Merge pull request #122 from Omikhleia/docs-manual-revamp

User manual revamp

classes/resilient/book.lua

@@ -61,7 +61,8 @@ function class:_init (options)
   self:loadPackage("markdown")
   self:loadPackage("djot")
   -- Once Djot is loaded, we can register custom pre-defined symbols
-  self.packages["markdown.commands"]:registerSymbol("_BIBLIOGRAPHY_", true, function (opts)
+  local mdc = self.packages["markdown.commands"]
+  mdc:registerSymbol("_BIBLIOGRAPHY_", true, function (opts)
     if not self.packages.bibtex then
       SU.warn("Bibliography support is not available")
       return {}
@@ -70,6 +71,32 @@ function class:_init (options)
       createCommand("printbibliography", opts)
     }
   end)
+  -- Our Djot/Markdown support already provides a _TOC_ symbol.
+  -- Here we can also provide _LISTOFFIGURES_, _LISTOFTABLES_, _LISTOFLISTINGS_.
+  -- And for the sake of consistency, we can also provide _TABLEOFCONTENTS_.
+  -- It is not exactly the same as _TOC_, which does additional things when used
+  -- outside resilient, with fallback to to SILE's default implementation, but it
+  -- is doesn't hurt to provide it here.
+  local extras = { "listoffigures", "listoftables", "listoflistings", "tableofcontents" }
+  for _, sym in ipairs(extras) do
+    mdc:registerSymbol("_" .. sym:upper() .. "_", true, function (opts)
+      return {
+        createCommand(sym, opts)
+      }
+    end)
+  end
+  -- Our Djot/Markdown support provides an undocumented _FANCYTOC_ symbol.
+  -- The reason why it is undocumented is that module fancytoc.sile is not a
+  -- dependency of markdown.sile.
+  -- On the other hand, resilient.sile has all needed dependencies.
+  -- So eventually we'll remove the _FANCYTOC_ symbol from markdown.sile.
+  -- No issue with re-registering it here, and we'll be ready for that.
+  mdc:registerSymbol("_FANCYTOC_", true, function (opts)
+    return {
+      createCommand("use", { module = "packages.fancytoc" }),
+      createCommand("fancytableofcontents", opts),
+    }
+  end)
 
   -- Override document.parindent default to this author's taste
   SILE.settings:set("document.parindent", "1.25em")

examples/manual-appendices/biblio.dj

@@ -0,0 +1,29 @@
+# Selected bibliography
+
+```=sile
+% For now, we use SIL language, and hack several things.
+% Eventually we'll get to a higher level of abstraction.
+%
+\use[module=packages.bibtex]
+\begin[size=10pt]{font}
+\set[parameter=document.parskip, value=4pt]
+\set[parameter=linebreak.emergencyStretch,value=1em]
+\set[parameter=linebreak.tolerance,value=2000]
+\lua{
+local class = SILE.documentState.documentClass
+class:registerCommand("bibLink", function (options, content)
+  SILE.call("href", { src = options.src }, {
+    SU.ast.createCommand("url", {}, {
+      SU.ast.createCommand("font", { family="Symbola", size="0.9em" }, { luautf8.char("0x1F517") })
+    })
+  })
+end)
+}
+\set[parameter=document.lskip,value=3em]
+\set[parameter=document.parindent,value=-3em]
+\set[parameter=current.parindent,value=-3em]
+
+\printbibliography[cited=false]
+
+\end{font}
+```

examples/manual-appendices/resume-class.dj

@@ -0,0 +1,46 @@
+# A naive _curriculum vitae_ class
+
+The *resilient.resume* class provides a minimalist (read, naive) way to make a modern-looking _résumé_ (CV) with SILE.
+It's a side project of the _re·sil·ient_ collection, born as an experiment to see how the styling paradigm of the collection behaves in a different context.
+It might have some rough edges, but it's a good starting point which could be improved upon.[^resume-improvements]
+
+ - Fonts
+
+    - You should select, early in your document, the main font to be used.
+      This class ideally works best with a font family that has: a thin style, an italic style, a light-weight (300) bold italic, a bold (600) regular. Lato, for instance, is such a font.
+    - Dingbat symbols rely on the Symbola font. You can change it by redefining the `resume-dingbats` style.
+
+  - Colors should not be abused in a CV, so this class proposes only three different colors.
+
+    - Two tints of gray for your first and last name, job title and headline.
+
+    - A nice tint of blue (#4080bf) for various sectioning and display elements. You can change it by redefining the `resume-color` style.[^resume-names]
+
+  - Page layout
+
+    - The first page does not have a header, but on subsequent pages the header repeats your full name.
+      The rationale is that your name shall be visible on each page, as the HR people get hundreds of CVs and
+      can easily get lost in them.
+    - The footer is shown side-by-side with the page folio, and contains your contact information. As for
+      the header, the rationale is that your contacts should be repeated. You wouldn’t want not to be
+      contacted just because the HR people lost the initial page, right?
+    - The folio includes the number of pages in your CV. As said, they
+      get to see hundreds of CV. Be nice ensuring they have no ordering issue when handling a printed
+      copy to managers, and do not miss any page.
+
+
+The commands are pretty simple and straightforward in this first version, so you can refer
+to the sample CV included in our example repository.
+
+:::
+[![](examples/resume-sample.pdf){width="48%" page=1}]{custom-style="ShadowFramed"}
+[![](examples/resume-sample.pdf){width="48%" page=2}]{custom-style="ShadowFramed"}
+:::
+^ A sample CV for a famous detective.
+
+
+[^resume-improvements]: This author has not checked extensively how other CV tools work.
+Maybe there is soome JSON or YAML formats commonly used, and it could be interesting to support them, and extend the class with more capabilities.
+Readers are encouraged to contribute to the effort.
+
+[^resume-names]: Likewise, your first and last names correspond to the `resume-firstname` and `resume-lastname` styles respectively.

examples/manual-classes/audience.dj

@@ -0,0 +1,65 @@
+{#resilient-classes-audience}
+# Target audience
+
+If you author your content in Djot or Markdown, most of the information you need to write your book is covered in the _Markdown and Djot to PDF with SILE_ user guide.
+There are just a few additional features specific to Djot, which are detailed below.
+
+On the other hand, if you are using the SIL language, you will need more in-depth information about the commands and constructs available in the _re·sil·ient_ classes.
+In most cases, this is the only scenario where the following chapters will be relevant to you.
+
+## Add-ons for Djot authors
+
+### Tables of Contents
+
+The *resilient.book* class provides several predefined Djot symbols for use in your documents.
+Each of these symbols must stand alone in its own paragraph.
+Attributes on the symbol are passed through, e.g. `:_TOC_:{depth=3}`.
+
+{variant=Simple}
+: `:_TOC_:` or `:_TABLEOFCONTENTS_:`
+
+  Insert a table of contents.
+
+  Supported attributes:
+
+   - `depth` (default 3) controls the depth of the content added to the table.
+   - `start` (default 0) controls at which level the table starts.
+   - `linking` (default true) controls whether the table entries are active links to the relevant sections.
+
+  ![](./manicule.svg){height="0.60em"} See section [](#packages-tableofcontents) in part [](#resilient-packages) for advanced information.
+
+: `:_FANCYTOC_:`
+
+  Insert a table of contents with a fancy style.
+
+  Supported attributes:
+
+   - `start` (default 0) controls at which level the table starts.
+
+  ![](./manicule.svg){height="0.60em"} See section [](#packages-fancytoc) in part [](#resilient-packages) for advanced information.
+
+: `:_LISTOFFIGURES_:`
+
+  Insert a list of figures.
+
+: `:_LISTOFTABLES_:`
+
+  Insert a list of tables.
+
+: `:_LISTOFLISTINGS_:`
+
+  Insert a list of listings.
+
+Note that these symbols do not automatically generate a heading or title.
+If a title is needed, you must add it manually using the appropriate heading level or styled element.
+
+### Bibliographies
+
+The *resilient.book* class also provides a predefined Djot symbol for inserting bibliographies (references).
+
+{variant=Simple}
+: `:_BIBLIOGRAPHY_:`
+
+  Insert a bibliography.
+
+  ![](./manicule.svg){height="0.60em"} See chapter [](#using-bibliographies) in part [](#master-document) for more information.