diff --git a/classes/resilient/book.lua b/classes/resilient/book.lua index 8505c8d..7cebdac 100644 --- a/classes/resilient/book.lua +++ b/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") diff --git a/examples/images/book-backcover.svg b/examples/images/book-backcover.svg new file mode 100644 index 0000000..8e076c7 --- /dev/null +++ b/examples/images/book-backcover.svg @@ -0,0 +1,210 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/examples/images/book-frontcover.svg b/examples/images/book-frontcover.svg new file mode 100644 index 0000000..7dca204 --- /dev/null +++ b/examples/images/book-frontcover.svg @@ -0,0 +1,123 @@ + + + + + + + + + + + + + + + + + + + + + + + diff --git a/examples/images/book-layout.svg b/examples/images/book-layout.svg new file mode 100644 index 0000000..b08e32a --- /dev/null +++ b/examples/images/book-layout.svg @@ -0,0 +1,451 @@ + + + + diff --git a/examples/images/book-parts-chapters.svg b/examples/images/book-parts-chapters.svg new file mode 100644 index 0000000..955a33d --- /dev/null +++ b/examples/images/book-parts-chapters.svg @@ -0,0 +1,293 @@ + + + + diff --git a/examples/images/book-workflow.svg b/examples/images/book-workflow.svg new file mode 100644 index 0000000..5ec0d36 --- /dev/null +++ b/examples/images/book-workflow.svg @@ -0,0 +1,435 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/examples/images/dore-perrault.jpg b/examples/images/dore-perrault.jpg new file mode 100644 index 0000000..6390923 Binary files /dev/null and b/examples/images/dore-perrault.jpg differ diff --git a/examples/images/layout-fuzzy.svg b/examples/images/layout-fuzzy.svg new file mode 100644 index 0000000..be83ecb --- /dev/null +++ b/examples/images/layout-fuzzy.svg @@ -0,0 +1,135 @@ + + + + diff --git a/examples/manual-appendices/biblio.dj b/examples/manual-appendices/biblio.dj new file mode 100644 index 0000000..84fa813 --- /dev/null +++ b/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} +``` diff --git a/examples/manual-appendices/resume-class.dj b/examples/manual-appendices/resume-class.dj new file mode 100644 index 0000000..d79c40b --- /dev/null +++ b/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. diff --git a/examples/manual-classes/audience.dj b/examples/manual-classes/audience.dj new file mode 100644 index 0000000..e94c1bf --- /dev/null +++ b/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. diff --git a/examples/manual-classes/book.dj b/examples/manual-classes/book.dj new file mode 100644 index 0000000..c1b09db --- /dev/null +++ b/examples/manual-classes/book.dj @@ -0,0 +1,205 @@ +# Deep dive into the resilient book class + +The design of the `resilient.book` class was started as an attempt at gradually tuning the default book class from SILE to this author’s needs and taste. +It eventually evolved into a full redesign on different grounds. +This very document uses it, so you can see it in real action. + +## Class options + +In addition to the class options provided by SILE, the class also supports the following options: + +{variant=Simple} +: `layout` + + Specifies the default (global) page layout. See part [](#page-layout). + +: `offset` + + Specifies the binding offset. See part [](#page-layout). + +: `headers` + + Specifies how running headers are used: + + - `none`: No running headers. + - `technical` (default): Chapter and section titles go in the even and odd running headers, respectively. + - `novel`: Chapter titles go in the odd running headers, and the title of the book, if set, goes in the even running headers.[^book-title] + +: `resolution` + + Specifies the global resolution in DPI (dots per inch). + Some add-on packages may use it in order to compute the size of generated images, etc. + + + +[^book-title]: The low-level command to set the book title is `\autodoc:command{\book-title{}}`{=sile} + +## Standard sectioning commands + +The class supports the following standard sectioning commands, from the highest division level to the lowest: `\autodoc:command{\part}`{=sile}, `\autodoc:command{\chapter}`{=sile}, `\autodoc:command{\section}`{=sile}, `\autodoc:command{\subsection}`{=sile}, `\autodoc:command{\subsubsection}`{=sile}. + +All sectioning commands obey styles (relying on the **resilient.styles** and **resilient.sectioning** packages), which notably imply that they have a lot of customization possibilities. +In the following pages, the described behaviors apply to the default configuration and styling, out-of-the-box. + +All the sections accepts the `\autodoc:parameter{numbering=false}`{=sile} option, if you want them unnumbered, and the `\autodoc:parameter{toc=false}`{=sile} option, if you do not want them to appear in the table of contents. +When they do, they correspond to “level 0” (parts) up to “level 4” (subsubsections). + +Remember a good advice—“Writers that think they need more than five levels should instead consider restructuring their document in a manner that does not require this level of nested sectioning. Increased section granularity can actually begin to detract from document clarity.” + +| Style | Description | +|:-------------------------------------------------|:-------------| +| `sectioning-base` | (Paragraph style inherited by all sectioning commands.) | +| `sectioning-⟨section type⟩` | (Sectioning) style applied to that sectioning command. | +^ Styles used for sectioning commands. + +By default, parts disable page numbering and running headers on their page. +Chapters have page numbering enabled on their first page and make sure no header shown is shown on that page. +Both start on an odd page[^odd-page], and the previous even page, if inserted blank, is shown without page number and header. +Parts and chapters reset the footnote counter. +Depending on the `headers` class option (see above), chapter and section titles go in running headers, unless customized otherwise. + +[^odd-page]: Again, as almost everything depending on styles, this can be customized. + +Notably, the class also defines a few commands currenty used as hooks in some of the above sectioning styles. + +| Command | Description | +|:-------------------------------------------------|:-------------| +| `\sectioning:part:hook` | Clears all page headers, disable the folios globally, resets the footnote counter and the chapter counter. | +| `\sectioning:chapter:hook` | Clears the header on the current page, re-enables folios, resets the footnote counter and adds the chapter title to the even running headers (see further below). | +| `\sectioning:section:hook` | Adds the section title to the odd running headers (see further below), with its counter preprended to it. | +^ Predefined command hooks used by sectioning commands. + +## Captioned environments + +The class provides three environnments, `\autodoc:environment{figure}`{=sile}, `\autodoc:environment{table}`{=sile}, and `\autodoc:environment{listing}`{=sile}, for captioned figures, tables, and listings, respectively. +They can contain arbitrary contents and a `\autodoc:command[check=false]{\caption{}}`{=sile} element. +The latter, when present, is extracted and displayed below the contents. +By default, the figure and table environments show their contents centered, with a numbered caption. +The listing environment does not center its content, but otherwise behaves the same. +Each of them has its own distinct counter. +The figure environment is (normally) intended to be used around an illustration. + +| Style | Description | +|:-------------------------------------------------|:-------------| +| `figure` | Style applied to the figure content (not including the caption). | +| `figure-caption` | (Sectioning) style applied to the figure caption. | +^ Styles used for figures. + +The table environment is (normally) intended to be used around… tables, you would have guessed it. + +| Style | Description | +|:-------------------------------------------------|:-------------| +| `table` | Style applied to the table content (not including the caption). | +| `table-caption` | (Sectioning) style applied to the table caption. | +^ Styles used for tables. + +The listing environment is (normally) intended to be used around blocks of code, or similar. +Note that the commmand does not switch to verbatim mode, it is up to you to do so if needed. + +| Style | Description | +|:-------------------------------------------------|:-------------| +| `listing` | Style applied to the listing content (not including the caption). | +| `listing-caption` | (Sectioning) style applied to the listing caption. | +^ Styles used for listings. + +The caption styles are actually sectioning styles, and the captions are inserted into the table of contents at level 5, 6 and 7 respectively. +It implies that one has the possibility to have them shown in the TOC, if passing a sufficient `\autodoc:parameter{depth}`{=sile} value to the `\autodoc:command{\tableofcontents}`{=sile} command. +While some authors may appreciate that, other, most likely, prefer having them in separate lists. +The following convenience commands are provided to that effect. + +| Command | Description | +|:-------------------------------------------------|:-------------| +| `\autodoc:command{\listoffigures}`{=sile} | Outputs the list of figures. | +| `\autodoc:command{\listoftables}`{=sile} | Outputs the list of tables. | +| `\autodoc:command{\listoflistings}`{=sile} | Outputs the list of listings. | +^ Commands for lists of figures and tables. + +But basically, they are just simple calls to `\autodoc:command{\tableofcontents}`{=sile} with the appropriate options to start at the corresponding TOC level and display only that level. +The only noteworthy advantage is that they check the styles in order to find out which level is concerned, so they may apply even if TOC levels are customized differently. + +As a final but important note, despite their name, the figure and table environments are not “floating” objects in the sense that this concept has in LaTeX. +In other terms, they are always inserted where declared in the page, without attempt to possibly move their material to some other position or a later page. + +## Headers & Footers + +Page numbers (folios) and running headers are by default flushed left or right depending on the page they are on, rather than centered. +This is defined via paragraph styles, so it can actually be customized at convenience. +The default styles also include an inheritance to a common “base” style (suitable for selecting the font size, etc.). +Nothing mandates it, but if you want to redefine these styles, we recommend keeping an appropriate style hierarchy, rather than stacking all definitions in a single style. +Well-thought, it can simplify the task for other later customizations. + +| Style | Description | +|:-------------------------------------------------|:-------------| +| `folio-base` | (Style inherited by the other folio styles.) | +| `header-base` | (Style inherited by the other header styles.) | +| `folio-even` | (Paragraph) style applied to the folio on even pages. | +| `folio-odd` | (Paragraph) style applied to the folio on odd pages. | +| `header-even` | (Paragraph) style applied to the header on even pages. | +| `header-odd` | (Paragraph) style applied to the header on odd pages. | +^ Styles used for folios and headers. + +The class also defines two commands for manipulating the page headers. + +| Command | Description | +|:-------------------------------------------------|:-------------| +| `\autodoc:command{\even-running-header{}}`{=sile} | Registers the content to be used in even running headers. | +| `\autodoc:command{\odd-running-header{}}`{=sile} | Registers the content to be used in odd running headers. | +| `\autodoc:command{\even-tracked-header{}}`{=sile} | Registers the content to be used in even running headers, tracked. | +| `\autodoc:command{\odd-tracked-header{}}`{=sile} | Registers the content to be used in odd running headers, tracked. | +^ Commands for manipulating page headers. + +The “tracked” variants ensure the content is tracked per page (using “info nodes”), which is usually what you want for section headers. +The other versions do not introduce info nodes, are intended to be used with direct content (such as a document title) or content already tracked elsewhere. + +Page headers rely on the functionality provided by the **resilient.headers** package, +so the `\autodoc:command{\noheaders}`{=sile}, `\autodoc:command{\noheaderthispage}`{=sile} and `\autodoc:command{\headers}`{=sile} commands are available, as well as `\autodoc:command{\header:rule}`{=sile}. + +## Block-indented quotes + +The class provides the `\autodoc:environment{blockquote}`{=sile} environment to typeset simple block-indented paragraphs. +Indented quotes can be nested. + +The environment relies on the same-named style for its styling and on the `\autodoc:setting{book.blockquote.margin}`{=sile} setting for its indentation (defaults to 2em). + +The environment also accepts a `\autodoc:parameter{variant}`{=sile} option, to switch to an alternate style, assumed to be named `blockquote-⟨variant⟩`. + +## Additional book divisions + +The class supports the standard `\autodoc:command{\frontmatter}`{=sile}, `\autodoc:command{\mainmatter}`{=sile} and `\autodoc:command{\backmatter}`{=sile} commands to switch between the different higher-level divisions of the document. +Obviously, these commands can only occur once in the document, and in the order given above. +They start a new page, and influence the style of folios. + +| Style | Description | +|:-------------------------------------------------|:-------------| +| `folio-frontmatter` | Numbering style applied to folios in the front matter. | +| `folio-mainmatter` | Numbering style applied to folios in the main matter. | +| `folio-backmatter` | Numbering style applied to folios in the back matter. | +^ Styles used for folios in different document divisions. + +Books not using these divisions assume “main” matter by default. +In the “front” and “back” matter divisions, parts and chapters are never numbered. +Note that this is not a configurable style decision, but the very definition of these divisions. +In the main matter, they are numbered by default, although this can be changed either on the sectioning command itself, or globally with adequate styles. + +The class also supports the `\autodoc:command{\appendix}`{=sile} command, which can only be invoke once, either in the main matter or in the back matter. +After that, the chapter counter is reset and chapters now use appendix sectioning styles. +By default, these styles derive from the chapter styles, with the numbering changed to uppercase letters, and the prefix text to “Appendix”. +Note that appendices are numbered even in the back matter, by default, according to common practice. +Again, this can be changed on the sectioning command itself, or globally with adequate styles. + +## Other features + +The footnotes are based on the **resilient.footnotes** package and therefore have the extra features proposed in this implementation, notably the `\autodoc:command{\footnote:rule}`{=sile} command and the possibility to specify an explicit `\autodoc:parameter{mark}`{=sile} on footnote calls. + +The table of contents relies on the **resilient.tableofcontents** package. One can therefore change many styling and appearance aspects to create a custom table of contents. + +Cross-references are supported via the **labelrefs** package, henceforth the `\autodoc:command{\label}`{=sile}, `\autodoc:command{\ref}`{=sile} and `\autodoc:command{\pageref}`{=sile} commands are available. + +A few layout-related commands are also provided. + +The `\autodoc:command{\layout[layout=]}`{=sile} command inserts a page break if needed, and changes the page layout from that point. +An optional `\autodoc:parameter{offset=}`{=sile} may be specified to also alter the binding offset. +By default, the global offset (that is, as possibly defined via the corresponding class option) is used. + +Mostly intended for documentation, the `\autodoc:command{\showlayout[layout=, papersize=]}`{=sile} command outputs an image representing the selected page layout and paper size. +Optional parameters are `\autodoc:parameter{offset=}`{=sile} for the binding offset (0, that is no offset, by default), `\autodoc:parameter{ratio=}`{=sile} for the image down-scaling (dividing the paper size by the specified amount, 6.5 by default), and `\autodoc:parameter{rough=}`{=sile} (false by default). diff --git a/examples/manual-classes/classes.sil b/examples/manual-classes/classes.sil deleted file mode 100644 index 3588edb..0000000 --- a/examples/manual-classes/classes.sil +++ /dev/null @@ -1,441 +0,0 @@ -\begin{document} -\chapter{The resilient book class} - -The design of the \strong{resilient.book} class was started as an attempt at gradually tuning the -default book class from SILE to this author’s needs and taste. It eventually -evolved into a full redesign on different grounds. This very document uses it, -so you can see it in real action. - -\section{Class options} - -In addition to the class options provided by SILE, the class also supports the following options: - -\begin{defn} -\term{layout} -\desc{Specifies the default (global) page layout. See part \ref[marker=page-layout].} -\end{defn} - -\begin{defn} -\term{offset} -\desc{Specifies the binding offset. See part \ref[marker=page-layout].} -\end{defn} - -\begin{defn} -\term{headers} -\desc{Specifies how running headers are used: -\begin{itemize} -\item{\code{none}: No running headers.} -\item{\code{technical} (default): Chapter and section titles go in the even and odd running headers, respectively.} -\item{\code{novel}: Chapter titles go in the odd running headers, and the title of the book, if set, goes in the even running headers.\footnote{The low-level command to set the book title is \autodoc:command{\book-title{}.}}} -\end{itemize}} -\end{defn} - -\begin{defn} -\term{resolution} -\desc{Specifies the global resolution in DPI (dots per inch). Some add-on packages may use it in order to -compute the size of generated images, etc.} -\end{defn} - -\section{Standard sectioning commands} - -The class supports the following sectioning commands, from the highest -division level to the lowest: \autodoc:command{\part}, \autodoc:command{\chapter}, -\autodoc:command{\section}, \autodoc:command{\subsection}, \autodoc:command{\subsubsection}. - -All sectioning commands obey styles (relying on the -\autodoc:package{resilient.styles} and \autodoc:package{resilient.sectioning} packages), which notably -imply that they have a lot of customization possibilities. -In the following pages, the described behaviors apply to the default -configuration and styling, out-of-the-box. - -All the sections accepts the \autodoc:parameter{numbering=false} option, if you want -them unnumbered, and the \autodoc:parameter{toc=false} option, if you do not want them -to appear in the table of contents. When they do, they correspond to “level 0” -(parts) up to “level 4” (subsubsections). - -Remember a good advice—“Writers that think they need more than five levels should -instead consider restructuring their document in a manner that does not require -this level of nested sectioning. Increased section granularity can actually begin -to detract from document clarity.” - -\define[command=ptable:cell:hook]{\raggedright{\noindent\style:font[size=0.9em]{\process}}}% -% FIXME Maybe the class should load ptable and override the hook to actually supported -% styles, that would be both convenient and consistent. -\begin{table} -\begin[cols=40%fw 50%fw, header=true]{ptable} - \begin[background=#eee]{row} - \cell[valign=top]{Style} - \cell[valign=top]{Description} - \end{row} - \begin{row} - \cell[valign=top]{\code{sectioning-base}} - \cell[valign=top]{(Paragraph style inherited by all sectioning commands.)} - \end{row} - \begin{row} - \cell[valign=top]{\code{sectioning-⟨\em{section type}⟩}} - \cell[valign=top]{(Sectioning) style applied to that sectioning command.} - \end{row} -\end{ptable} -\caption{Styles used for sectioning commands.} -\end{table} - -By default, parts disable page numbering and running headers on their page. -Chapters have page numbering enabled on their first page and make sure -no header shown is shown on that page. Both start on an odd page\footnote{Again, -as almost everything depending on styles, this can be customized.}, and the previous -even page, if inserted blank, is shown without page number and header. Parts and chapters -reset the footnote counter. -Depending on the `headers` class option (see above), chapter and section titles go in running -headers, unless customized otherwise. - -Notably, the class also defines a few commands currenty used as hooks in some of the -above sectioning styles. - -\begin{table} -\begin[cols=40%fw 50%fw, header=true]{ptable} - \begin[background=#eee]{row} - \cell[valign=top]{Command} - \cell[valign=top]{Description} - \end{row} - \begin{row} - \cell[valign=top]{\autodoc:command{\sectioning:part:hook}} - \cell[valign=top]{Clears all page headers, disable the folios globally, - resets the footnote counter and the chapter counter.} - \end{row} - \begin{row} - \cell[valign=top]{\autodoc:command{\sectioning:chapter:hook}} - \cell[valign=top]{Clears the header on the current page, re-enables folios, resets - the footnote counter and adds the chapter title to the even running headers (see further below).} - \end{row} - \begin{row} - \cell[valign=top]{\autodoc:command{\sectioning:section:hook}} - \cell[valign=top]{Adds the section title to the odd running headers (see further below), with its - counter preprended to it.} - \end{row} -\end{ptable} -\caption{Predefined command hooks used by sectioning commands.} -\end{table} - -\section{Captioned environments} - -The class provides three environnments, \autodoc:environment{figure}, \autodoc:environment{table}, and \autodoc:environment{listing}, for captioned figures, tables, and listings, respectively. -They can contain arbitrary contents and a \autodoc:command[check=false]{\caption{}} element. -The latter, when present, is extracted and displayed below the contents. -By default, the figure and table environments show their contents centered, with a numbered caption. -The listing environment does not center its content, but otherwise behaves the same. -Each of them has its own distinct counter. -The figure environment is (normally) intended to be used around an illustration. - -\begin{table} -\begin[cols=40%fw 50%fw, header=true]{ptable} - \begin[background=#eee]{row} - \cell[valign=top]{Style} - \cell[valign=top]{Description} - \end{row} - \begin{row} - \cell[valign=top]{\code{figure}} - \cell[valign=top]{Style applied to the figure content (not including the caption).} - \end{row} - \begin{row} - \cell[valign=top]{\code{figure-caption}} - \cell[valign=top]{(Sectioning) style applied to the figure caption.} - \end{row} -\end{ptable} -\caption{Styles used for figures.} -\end{table} - -The table environment is (normally) intended to be used around… tables, you would -have guessed it. - -\begin{table} -\begin[cols=40%fw 50%fw, header=true]{ptable} - \begin[background=#eee]{row} - \cell[valign=top]{Style} - \cell[valign=top]{Description} - \end{row} - \begin{row} - \cell[valign=top]{\code{table}} - \cell[valign=top]{Style applied to the table content (not including the caption).} - \end{row} - \begin{row} - \cell[valign=top]{\code{table-caption}} - \cell[valign=top]{(Sectioning) style applied to the table caption.} - \end{row} -\end{ptable} -\caption{Styles used for tables.} -\end{table} - -The listing environment is (normally) intended to be used around blocks of code, or similar. -Note that the commmand does not switch to verbatim mode, it is up to you to do so if needed. - -\begin{table} -\begin[cols=40%fw 50%fw, header=true]{ptable} - \begin[background=#eee]{row} - \cell[valign=top]{Style} - \cell[valign=top]{Description} - \end{row} - \begin{row} - \cell[valign=top]{\code{listing}} - \cell[valign=top]{Style applied to the listing content (not including the caption).} - \end{row} - \begin{row} - \cell[valign=top]{\code{listing-caption}} - \cell[valign=top]{(Sectioning) style applied to the listing caption.} - \end{row} -\end{ptable} -\caption{Styles used for listings.} -\end{table} - - -The caption styles are actually sectioning styles, and the captions are inserted into the table of contents at level 5, 6 and 7 respectively. -It implies that one has the possibility to have them shown in the TOC, if passing a sufficient \autodoc:parameter{depth} value to the \autodoc:command{\tableofcontents} command. -While some authors may appreciate that, other, most likely, prefer having them in separate lists. -The following convenience commands are provided to that effect. - -\begin{table} -\begin[cols=40%fw 50%fw, header=true]{ptable} - \begin[background=#eee]{row} - \cell[valign=top]{Command} - \cell[valign=top]{Description} - \end{row} - \begin{row} - \cell[valign=top]{\autodoc:command{\listoffigures}} - \cell[valign=top]{Outputs the list of figures.} - \end{row} - \begin{row} - \cell[valign=top]{\autodoc:command{\listoftables}} - \cell[valign=top]{Outputs the list of tables.} - \end{row} - \begin{row} - \cell[valign=top]{\autodoc:command{\listoflistings}} - \cell[valign=top]{Outputs the list of listings.} - \end{row} -\end{ptable} -\caption{Commands for lists of figures and tables.} -\end{table} - -But basically, they are just simple calls to \autodoc:command{\tableofcontents} with the -appropriate options to start at the corresponding TOC level and display only that level. -The only noteworthy advantage is that they check the styles in order to find out which -level is concerned, so they may apply even if TOC levels are customized differently. - -As a final but important note, despite their name, the figure and table environments -are not “floating” objects in the sense that this concept has in LaTeX. In other terms, -they are always inserted where declared in the page, without attempt to possibly move -their material to some other position or a later page. - -\section{Headers & Footers} - -Page numbers (folios) and running headers are by default flushed left or right depending -on the page they are on, rather than centered. This is defined via paragraph styles, so it -can actually be customized at convenience. The default styles also include an inheritance -to a common “base” style (suitable for selecting the font size, etc.). Nothing mandates -it, but if you want to redefine these styles, we recommend keeping an appropriate -style hierarchy, rather than stacking all definitions in a single style. Well-thought, -it can simplify the task for other later customizations. - -\begin{table} -\begin[cols=40%fw 50%fw, header=true]{ptable} - \begin[background=#eee]{row} - \cell[valign=top]{Style} - \cell[valign=top]{Description} - \end{row} - \begin{row} - \cell[valign=top]{\code{folio-base}} - \cell[valign=top]{(Style inherited by the other folio styles.)} - \end{row} - \begin{row} - \cell[valign=top]{\code{header-base}} - \cell[valign=top]{(Style inherited by the other header styles.)} - \end{row} - \begin{row} - \cell[valign=top]{\code{folio-even}} - \cell[valign=top]{(Paragraph) style applied to the folio on even pages.} - \end{row} - \begin{row} - \cell[valign=top]{\code{folio-odd}} - \cell[valign=top]{(Paragraph) style applied to the folio on odd pages.} - \end{row} - \begin{row} - \cell[valign=top]{\code{header-even}} - \cell[valign=top]{(Paragraph) style applied to the header on even pages.} - \end{row} - \begin{row} - \cell[valign=top]{\code{header-odd}} - \cell[valign=top]{(Paragraph) style applied to the header on odd pages.} - \end{row} -\end{ptable} -\caption{Styles used for folios and headers.} -\end{table} - -The class also defines two commands for manipulating the page headers. - -\begin{table} -\begin[cols=45%fw 45%fw, header=true]{ptable} - \begin[background=#eee]{row} - \cell[valign=top]{Command} - \cell[valign=top]{Description} - \end{row} - \begin{row} - \cell[valign=top]{\autodoc:command{\even-running-header{}}} - \cell[valign=top]{Registers the content to be used in even running headers.} - \end{row} - \begin{row} - \cell[valign=top]{\autodoc:command{\odd-running-header{}}} - \cell[valign=top]{Registers the content to be used in odd running headers.} - \end{row} - \begin{row} - \cell[valign=top]{\autodoc:command{\even-tracked-header{}}} - \cell[valign=top]{Registers the content to be used in even running headers, tracked.} - \end{row} - \begin{row} - \cell[valign=top]{\autodoc:command{\odd-tracked-header{}}} - \cell[valign=top]{Registers the content to be used in odd running headers, tracked.} - \end{row} -\end{ptable} -\caption{Commands for manipulating page headers.} -\end{table} - -The “tracked” variants ensure the content is tracked per page (using “info nodes”), which is usually what you want for section headers. -The other versions do not introduce info nodes, are intended to be used with direct content (such as a document title) or content already tracked elsewhere. - -Page headers rely on the functionality provided by the \autodoc:package{resilient.headers} package, -so the \autodoc:command{\noheaders}, \autodoc:command{\noheaderthispage} and \autodoc:command{\headers} -commands are available, as well as \autodoc:command{\header:rule}. - -\section{Block-indented quotes} - -The class provides the \autodoc:environment{blockquote} environment to typeset simple block-indented -paragraphs. -Indented quotes can be nested. - -The environment relies on the same-named style for its styling and on the \autodoc:setting{book.blockquote.margin} setting for its indentation (defaults to 2em). - -The environment also accepts a \autodoc:parameter{variant} option, to switch to an alternate style, assumed to be named \code{blockquote-⟨\em{variant}⟩}. - -\section{Additional book divisions} - -The class supports the standard \autodoc:command{\frontmatter}, \autodoc:command{\mainmatter} and \autodoc:command{\backmatter} commands to switch between the different higher-level divisions of the document. -Obviously, these commands can only occur once in the document, and in the order given above. -They start a new page, and influence the style of folios. - -\begin{table} - \begin[cols=40%fw 50%fw, header=true]{ptable} - \begin[background=#eee]{row} - \cell[valign=top]{Style} - \cell[valign=top]{Description} - \end{row} - \begin{row} - \cell[valign=top]{\code{folio-frontmatter}} - \cell[valign=top]{Numbering style applied to folios in the front matter.} - \end{row} - \begin{row} - \cell[valign=top]{\code{folio-mainmatter}} - \cell[valign=top]{Numbering style applied to folios in the main matter.} - \end{row} - \begin{row} - \cell[valign=top]{\code{folio-backmatter}} - \cell[valign=top]{Numbering style applied to folios in the back matter.} - \end{row} - \end{ptable} - \caption{Styles used for folios in different document divisions.} -\end{table} - -Books not using these divisions assume “main” matter by default. -In the “front” and “back” matter divisions, parts and chapters are never numbered. -Not that this is not a configurable style decision, but the very definition of these divisions. -In the main matter, they are numbered by default, although this can be changed either on the sectioning command itself, or globally with adequate styles. - -The class also supports the \autodoc:command{\appendix} command, which can only be invoke once, either in the main matter or in the back matter. -After that, the chapter counter is reset and chapters now use appendix sectioning styles. -By default, these styles derive from the chapter styles, with the numbering changed to uppercase letters, and the prefix text to “Appendix”. -Note that appendices are numbered even in the back matter, by default, according to common practice. -Again, this can be changed on the sectioning command itself, or globally with adequate styles. - -\section{Other features} - -The footnotes are based on the \autodoc:package{resilient.footnotes} package and therefore have the -extra features proposed in this implementation, notably the \autodoc:command{\footnote:rule} -command and the possibility to specify an explicit \autodoc:parameter{mark} on footnote calls. - -The table of contents relies on the \autodoc:package{resilient.tableofcontents} package. One can -therefore change many styling and appearance aspects to create a custom table of contents. - -Cross-references are supported via the \autodoc:package{labelrefs} package, henceforth -the \autodoc:command{\label}, \autodoc:command{\ref} and \autodoc:command{\pageref} commands are -available. - -\medskip -A few layout-related commands are also provided. - -The \autodoc:command{\layout[layout=]} command inserts a page break if needed, and changes the page layout from that point. -An optional \autodoc:parameter{offset=} may be specified to also alter the binding offset. -By default, the global offset (that is, as possibly defined via the corresponding class option) is used. - -Mostly intended for documentation, the \autodoc:command{\showlayout[layout=, papersize=]} command outputs an image representing the selected page layout and paper size. -Optional parameters are \autodoc:parameter{offset=} for the binding offset (0, that is no offset, by default), \autodoc:parameter{ratio=} for the image down-scaling (dividing the paper size by the specified amount, 6.5 by default), and \autodoc:parameter{rough=} (false by default). - -\chapter{A \em{curriculum vitae} class} - -The \strong{resilient.resume} class provides a minimalist (read, naive) way to make a modern \em{résumé} (CV) with SILE. - -\smallskip -\begin{itemize} -\item{Fonts} -\begin{itemize} - \item{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.} - \item{Dingbat symbols rely on the Symbola font. You can change it by redefining the \code{resume-dingbats} - style.} - \end{itemize} - \item{Colors should not be abused in a CV, so this class proposes only three different colors.} - \begin{itemize} - \item{Two tints of gray for your first and last name, job title and headline.} - \item{A nice tint of blue (#4080bf) for various sectioning and display elements. You can change it - by redefining the \code{resume-color} style.\footnote{Likewise, your first and last names - correspond to the \code{resume-firstname} and \code{resume-lastname} styles respectively.}} - \end{itemize} - \item{Page layout} - \begin{itemize} - \item{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.} - \item{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?} - \item{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.} - \end{itemize} -\end{itemize} - -\smallskip - -The commands are pretty simple and straightforward in this first version, so you can refer -to the sample CV included in our example repository. - -\begin{figure} -\framebox[padding=0, shadow=true, shadowcolor=220]{\img[width=45%fw, src=examples/resume-sample.pdf, page=1]}% -\kern[width=3pt]% -\framebox[padding=0, shadow=true, shadowcolor=220]{\img[width=45%fw, src=examples/resume-sample.pdf, page=2]} -\caption{A sample CV for a famous detective.} -\end{figure} - -%\chapter{XML TEI P4 print dictionaries} -% -% This class is a book-like class for (XML) TEI dictionaries. -% -% It just defines the appropriate page masters, sectioning hooks -%and loads all needed packages. The hard work processing the -%XML content is done in the \autodoc:package{teidict} package. -% -%This author does not intend to discuss it in full here. -%To see it in action, you can refer to our small example in -%\href[src=https://github.com/Omikhleia/omikhleia-sile-packages/tree/main/examples]{our -%repository}\footnote{\url{https://github.com/Omikhleia/omikhleia-sile-packages/tree/main/examples}}. -%For a more complex project using the same tools, you may also check -%the \href[src=https://omikhleia.github.io/sindict/]{sindict -%repository}\footnote{\url{https://omikhleia.github.io/sindict/}}. - -\end{document} diff --git a/examples/manual-front.dj b/examples/manual-front.dj new file mode 100644 index 0000000..b0aff9e --- /dev/null +++ b/examples/manual-front.dj @@ -0,0 +1,35 @@ +``` =sile +% Some initial and dirt hacks... +\footnote:rule +% This is a quick but bad implementation. We ought to have used properly defined styles. +\define[command=admon]{% +\novbreak +\smallskip% +\novbreak +\set[parameter=document.parindent, value=0]{% +\roughbox[enlarge=true, singlestroke=true, preserve=true, +padding=2%fw, bordercolor=#59b24c, fillcolor=230, shadowcolor=#96A8C7, shadow=false]{% +% Beware, wrap color around the parbox so it stays in horizontal mode +% In the parbox it could lead to a blank line (we'd need to fix this...) +% Colors aren't settings so they propagate to the parbox, whatever settings logic it has. +\color[color=100]{\parbox[width=96%lw]{\set[parameter=document.parindent, value=0]\font[size=9pt]{\process}\par}}% +}}% +\medskip}% +\define[command=ShadowFramed]{% +\framebox[padding=0, shadow=true, shadowcolor=220]{\process}} +``` + +{.unnumbered .notoc} +# Contents + +:_TOC_: + +{.unnumbered .notoc} +## Figures + +:_LISTOFFIGURES_: + +{.unnumbered .notoc} +## Tables + +:_LISTOFTABLES_: diff --git a/examples/manual-front.sil b/examples/manual-front.sil deleted file mode 100644 index 637d5f3..0000000 --- a/examples/manual-front.sil +++ /dev/null @@ -1,29 +0,0 @@ -\begin{document} -\footnote:rule -\define[command=admon]{% This is a quick but bad implementation. We ought to have used a style. -\novbreak -\smallskip% -\novbreak -\set[parameter=document.parindent, value=0]{% -\roughbox[enlarge=true, singlestroke=true, preserve=true, -padding=2%fw, bordercolor=#59b24c, fillcolor=230, shadowcolor=#96A8C7, shadow=false]{% -\parbox[width=96%lw]{\set[parameter=document.parindent, value=0]\font[size=9pt]\color[color=100]{\process}\par}% -}}% -\medskip} - -% -% There we go for the content. -% -\chapter[numbering=false, toc=false]{Contents} -\noheaders - -\tableofcontents - -\section[numbering=false, toc=false]{Figures} - -\listoffigures - -\section[numbering=false, toc=false]{Tables} - -\listoftables -\end{document} diff --git a/examples/manual-intro/goals.dj b/examples/manual-intro/goals.dj new file mode 100644 index 0000000..d55b37a --- /dev/null +++ b/examples/manual-intro/goals.dj @@ -0,0 +1,32 @@ +{.none .pagebreak} +--- + +![Making a _re·sil·ient_ book.](./images/book-workflow.svg){width="99%"} + +# What is _re·sil·ient_? + +{rule="0.4pt"} +> Type and typography---what you do and how you do it---are both science and art. +^ James Felici,\ +_The Complete Manual of Typography._ + +The _re·sil·ient_ module for the SILE digital typesetting system is a comprehensive collection of advanced components and tools designed to streamline the production of high-quality books and documents. + +Its core philosophy is to enable typesetting an entire book---"from front cover to back cover"---using text files mostly written in lightweight markup languages such as Djot or Markdown, enhanced with powerful syntax extensions. + +At the heart of _re·sil·ient_ is a robust “book” document class that offers a wealth of features, including a wide array of page layouts, full support for cross-references, advanced figure and table environments with captions, and other essential book elements, and highly configurable components, such as the table of contents, headers, footers, footnotes, and sectioning environments. + +Complementing the document class is an innovative styling paradigm. +It provides a consistent, unified approach to managing style decisions across your project, abstracting complexity while maintaining flexibility. + +The _re·sil·ient_ collection also simplifies the process of organizing and compiling large projects with its master document capabilities. +These allow you to combine multiple chapters into a cohesive book and to structure your content with remarkable flexibility. + +From cover design to page layout, fine typography to polished output, _re·sil·ient_ embodies the philosophy of making the creation of beautiful books as intuitive and efficient as possible. + +Whether you are an experienced typesetter, a seasoned SILE user, or just a newcomer, this module equips you with the tools to achieve professional results with ease. + +{.none .pagebreak} +--- + +![The _re·sil·ient_ ecosystem at a glance (simplified).](./examples/resilient-ecosystem.dot){width="99%fw"} diff --git a/examples/manual-intro/howto.dj b/examples/manual-intro/howto.dj index 6633307..933d62e 100644 --- a/examples/manual-intro/howto.dj +++ b/examples/manual-intro/howto.dj @@ -1,34 +1,27 @@ +# How to use this manual -{.none .pagebreak} ---- +{rule="0.4pt"} +> In a well-made book, where designer, compositor and printer have all done their jobs, no matter how many thousands of lines and pages, the letters are alive. +> They dance in their seats. Sometimes they rise and dance in the margins and aisles. +^ Robert Bringhurst,\ + _The Elements of Typographic Style._ -![The resilient ecosystem at a glance (simplified).](./examples/resilient-ecosystem.dot){width="99%fw"} +Your are ready to typeset some work---ideally, the _perfect book_ of your dreams---and towards that aim, you consider using the present collection of classes and packages. +That's a very good start! Let us guide you through the process. -{.unnumbered} -# How to use this manual +## Installing the _re·sil·ient_ modules -```=sile -\begin[rule=0.4pt]{epigraph} -In a well-made book, where designer, compositor and printer have all done their jobs, -no matter how many thousands of lines and pages, the letters are alive. -They dance in their seats. Sometimes they rise and dance in the margins and aisles. -\source{Robert Bringhurst,\break\em{The Elements of Typographic Style}.} -\end{epigraph} -``` - -Your are ready to typeset some work---ideally, the _perfect book_ of your -dreams---and towards that aim, you consider using the present collection -of classes and packages. -That's a very good start! Let us guide you through the process. +Wait, you have not installed the SILE software or the _re·sil·ient_ modules yet? + +![](./manicule.svg){height="0.60em"} See chapter [](#installation) and come back here when you are ready. -{.unnumbered} ## Picking a mark-up language Obviously, you first need to pick a mark-up language for your content. -If you are reading this document, you probably already browsed through the SILE Manual and consider using its SIL language. +If you are reading this document, you probably already browsed through _The SILE Book_ and consider using its SIL language. You might do so, indeed---but please note that Markdown and Djot are acceptable options too. -If you properly installed the resilient collection, then the *[markdown.sile](https://github.com/Omikhleia/markdown.sile)* module is installed too. +If you properly installed the _re·sil·ient_ collection, then the *[markdown.sile](https://github.com/Omikhleia/markdown.sile)* module is installed too. When used with this collection, it's leveraged with additional capabilities. On the other hand, if you are not already experienced with the SIL language and your content is reasonably simple, this author would recommend to seriously consider Markdown or Djot (with even a preference for Djot when possible). @@ -36,7 +29,6 @@ Not only are they simpler and lightweight, but they are also more portable, with ![](./manicule.svg){height="0.60em"} Check the _Markdown and Djot to PDF with SILE_ user guide. -{.unnumbered} ## Assembling your content Now, let's consider you have some input content ready, as an assortment of files, possibly in different mark-up languages: @@ -51,7 +43,6 @@ Truly, the resilient "master document format" aims at simplifying and streamlini ![](./manicule.svg){height="0.60em"} Read part [](#master-document){.section}. -{.unnumbered} ## Styling your book You have chosen a paper size for your book, and are using one of our classes, say the *resilient.book* class. @@ -64,16 +55,16 @@ You may want now to customize the document styles according to your needs. ![](./manicule.svg){height="0.60em"} Read part [](#styling-paradigm){.section}. -{.unnumbered} ## Going further -In composing your book, you may need some of the cool packages provided here. +In composing your book, you may need more details about the available document classes and their capabilities. -![](./manicule.svg){height="0.60em"} Read part [](#resilient-packages){.section}. +![](./manicule.svg){height="0.60em"} Read part [](#resilient-classes){.section}. -Likewise, you may need more details about the available document classes and their capabilities. +Likewise, you may need more low-level details regarding some of the cool components provided by the _re·sil·ient_ collection. +These sections are not for the faint of heart, but they are there for you when you need them. -![](./manicule.svg){height="0.60em"} Read part [](#resilient-classes){.section}. +![](./manicule.svg){height="0.60em"} Read part [](#resilient-packages){.section}. {.pendant} --- diff --git a/examples/manual-intro/installation.dj b/examples/manual-intro/installation.dj new file mode 100644 index 0000000..711c13b --- /dev/null +++ b/examples/manual-intro/installation.dj @@ -0,0 +1,63 @@ +{#installation} +# Installing the _re·sil·ient_ modules + +Usually, a guide of this kind would immediately start with some "Getting Started" section, with a step-by-step guide to install the software. +This author is well aware of that fact. +But you only need to read this chapter if you never installed _re·sil·ient_ before, and will never read it again once you have done so. +So, it's not that bad to have it here only, after some introductory material, is it? + +## Standard installation + +This module collection requires SILE v0.15 or upper. +See the [SILE website](https://sile-typesetter.org/) for installation instructions. +Installation relies on the *luarocks* package manager. +See its own installation instructions on the [LuaRocks website](https://luarocks.org/). +Then, to install the latest official version: + +{custom-style=CodeBlock} +::: + ```bash +luarocks install resilient.sile +``` +::: + +Refer to the SILE manual for more detailed 3rd-party package installation information and configuration options. +In particular, depending on the SILE distribution you use, you may want need to explicitly target the version of Lua that SILE was built with. + +Other than that, the installation should be straightforward, and _re·sil·ient_ then comes with all the necessary dependencies automatically. + +{#recommended-additional-software} +## Recommended additional software + +This module also notably installs, as dependencies, the following collections (so you don't have to install them separately): + + - the [*embedders.sile*](https://github.com/Omikhleia/embedders.sile) collection, a general framework for embedding images from textual representations, performing their on-the-fly conversion, + - the [*printoptions.sile*](https://github.com/Omikhleia/embedders.sile) collection, a general framework for rasterizing vector images and rescaling raster images. + +However, these require additional software to be installed on your host system, to invoke the necessary conversion commands. +Depending on the features you plan to use, you may need to ensure the following software is installed. +All of these are optional if you don't plan to use the corresponding features. + + - Dependencies for *embedders.sile* are only required if you plan to include some specific types of text-based images in your documents. + + - *lilypond* for music notation, if you plan to include music scores in your documents. + - *graphviz* for DOT graph rendering, if you plan to include graphs in your documents. + - *ghostscript* for PDF image conversion. + + - Dependencies for *printoptions.sile* are only required if you plan to go to print with your documents, and your printer has specific requirements or expectations.[^printer-expectations] + + - **inkscape** for SVG image conversion, if you plan to rasterize vector images in your documents. + - **graphicsmagick** for image conversion, if you plan to minimize the size of your raster images. + +As with anything that relies on invoking external programs on your host system, please be aware of potential security concerns. +Be cautious with the source of the elements you include in your documents! + +{custom-style=admon} +::: +Thank you for your attention, gentle reader. +We wish you a very pleasant journey through the rest of this manual. +Don't hesitate to provide feedback and help us pushing this collection forward. +::: + +[^printer-expectations]: Typically, this author regularly uses the print services of [Lulu.com](https://www.lulu.com/), which has specific requirements for the images in the PDF files you submit. +(This author is not affiliated with Lulu.com in any way, and this mention is not an endorsement of their services.) diff --git a/examples/manual-layouts/layouts-general.dj b/examples/manual-layouts/layouts-general.dj new file mode 100644 index 0000000..7783354 --- /dev/null +++ b/examples/manual-layouts/layouts-general.dj @@ -0,0 +1,78 @@ +# Choosing a page layout + +The layout of a book is a crucial aspect of its design. +It is not only about the size of the paper, but also about the proportions of the text block, the margins, and the headers and footers. +You do not want, surely, to guess the adequate proportions by yourself, do you? + +Neither do you want to spend hours trying to figure out how to set up a good page layout. +This is where _re·sil·ient_ comes to the rescue... + +![A "regular" book layout---Where blocks go?](images/book-layout.svg){width="70%"} + +## The layout class option + +Paper sizes for printed works varied a lot across time. +Frequent ratios nowadays are 1:√2 (such as the ISO paper sizes, e.g. A5, 14.8 × 21 cm) or 2:3 (such as US trade, 6 × 9 in), though there are still plenty of other page formats in use (e.g. French pocket books often come in 10 × 17 cm or 10 × 18 cm format.) + +The relation between the page size and the main text block also varied a lot, depending on the aesthetic tastes of authors and designers. + +The resilient document classes provide a `layout=⟨string⟩` class option for selecting some fairly usual page layouts. +They are shown further below for comparison, applied to the US trade and A5 formats, though their historical use may have favored a different paper size. + +## Thriving for harmony + +The secret law of page harmony relies on using elegant proportions. +When designing your _perfect book,_ just after having decided on a paper size, you will want to pick a great page layout. + +SILE already offers several ways for designing your own page masters. +However, the syntax is not particularly easy, and users might not know what it takes to use good values for print-quality books. + +The rationale for providing predefined layouts in the resilient collection is to address that point, with a curated choice of classic page layouts, available off-the-shelf. + +## On headers and footers + +It has to be noted that these common layouts rarely detailed where headers or folios were to be placed. +Most typography books are silent on the topic, or stay rather vague, stating obvious generalities—such as the headers and footers having to be, bear with me, "close to the text block." + +This author, therefore, decided to be a typographer on his own, regarding that matter, and used a golden ratio to place the header and footer areas in their margin space. + +## On the binding offset or gutter + +The “gutter” is a typographical term referring to an _additional_ margin added to interior pages to compensate for the part of the page made unusable by the binding process. +Unfortunately, it cannot really be automated, as it usually depends on many internal and external factors—notably, the number of pages, the thickness of the selected paper, and the printer’s binding process. + +The resilient document classes provide the `offset=⟨dimen⟩` class option. +When used, it shifts the text block by the given amount.[^layout-offset] + +Books of less than 60 pages do not normally need to include such a gutter, but with a higher page count, you may have to consider using it, appropriately tuned with an _ad hoc_ value. +Be aware, however, that outer margins will be reduced by the same amount. +If you intend to use them for annotations, be very careful here. + +::: +``` =sile +% Quite a huge offset here in the example to make it visible. +\showlayout[layout=ateliers demiluxe, + papersize=6in x 9in] \raise[height=0.5in]{→} \showlayout[layout=ateliers demiluxe, papersize=6in x 9in, offset=0.20in] +``` +::: +^ Shifting a layout with a binding offset. + +The offset is usually specified in fixed inches or millimeters, as it doesn’t depend on the paper size. +It is near to impossible to make a general recommendation here, without knowing more details regarding the type of book and the binding process.[^layout-binding] +As a rule of thumb, a good practice is usually to check that the inner margins including the offset are not getting much bigger than the outer margins. +Otherwise, it might imply you picked an inappropriate page layout in the first place. +Above 60 pages, you might thus start with an offset of `0.125in` and adjust by test and trial. Between 150 and 400 pages, you might need to reach `0.25in`, or more… + +[^layout-offset]: Please note that it applies to page masters derived from a resilient layout. +If you designed your own page templates with SILE’s low-level constructs, you are fully responsible for taking a binding offset into account there. + +[^layout-binding]: Some printing services even offer coil binding. +Those coils are going to eat a whole lot of the inner margin! + +{.pagebreak .none} +--- + +{custom-style=center} +::: +![](images/layout-fuzzy.svg){width="80%"} +::: diff --git a/examples/manual-layouts/layouts-predefined.dj b/examples/manual-layouts/layouts-predefined.dj new file mode 100644 index 0000000..a293f33 --- /dev/null +++ b/examples/manual-layouts/layouts-predefined.dj @@ -0,0 +1,190 @@ +# Off-the-shelf page layouts + +## French layouts or “Canon des ateliers” + +This canon normally applies a 4/10, 5/10, 6/10, 7/10 progression rule to distribute the white space around the text block (“règle du 10/12^e^”). + +In the standard definition, the 4/10 and 6/10 ratios are used for the inner and outer margins; and the 5/10 and 7/10 ratios for the top and bottom margins, but using the same base space value (i.e. taken from the horizontal direction). + +A variant (“règle du 10^e^”) uses only the 4/10 and 6/10 ratios, but vertically applies to the text block height the same proportion rules as in the horizontal direction. + +There are other variants, such as one using the values of the inner and outer margins for the top and bottom margins, leading to pretty dense pages. + +Thus, we have to support several ways of computing and distributing the margins. +Is it complex enough? Wait, the canon has no less than three different proportion rules for the text block.[^layout-ateliers] + +[^layout-ateliers]: This author, being French, will only note that we apparently like to make things more complex than they ought to be. + +For regular material (“imprimé courant”), the width of the text block takes 3/4 of the page width. +So we have the standard `ateliers regular` (= `ateliers`) using the 10/12^e^ rule, and `ateliers regular 10e` for the 10^e^ rule variant. + +::: +``` =sile +\showlayout[layout=ateliers, + papersize=6in x 9in] \showlayout[layout=ateliers, + papersize=a5]\quad\showlayout[layout=ateliers regular 10e, + papersize=6in x 9in] \showlayout[layout=ateliers regular 10e, papersize=a5] +``` +::: +^ Canon des ateliers — regular. + +In the demi-luxe variant, the width of the text block takes 2/3 of the page. +Here again, we show the standard `ateliers demiluxe` and the `ateliers demiluxe 10e` variant. + +::: +``` =sile +\showlayout[layout=ateliers demiluxe, + papersize=6in x 9in] \showlayout[layout=ateliers demiluxe, + papersize=a5]\quad\showlayout[layout=ateliers demiluxe 10e, + papersize=6in x 9in] \showlayout[layout=ateliers demiluxe 10e, papersize=a5] +``` +::: +^ Canon des ateliers — demiluxe. + +In the “de luxe” variant, the width of the text block takes 5/8 of the page. +As you would have guessed, these are the standard `ateliers deluxe` and its `ateliers deluxe 10e` variant. + +::: +``` =sile +\showlayout[layout=ateliers deluxe, + papersize=6in x 9in] \showlayout[layout=ateliers deluxe, + papersize=a5]\quad\showlayout[layout=ateliers deluxe 10e, + papersize=6in x 9in] \showlayout[layout=ateliers deluxe 10e, papersize=a5] +``` +::: +^ Canon des ateliers — deluxe. + +## Ratio-based layouts + +Ratio-based methods are also known as the Van de Graaf canon, after the latter rediscovered and documented them in the 1940s. +They are also sometimes referred to as the “secret canon” used in many medieval manuscripts and incunabula. + +The proposed historical layouts are `honnecourt` and `vencentinus`. + +In the 13^th^ century, the architect Villard de Honnecourt came up with what he considered a “harmonious” and pleasing design (esp. +for 2:3 pages), using a 1/9 ratio and a text block area in the same proportions as the page, with a matching diagonal. + +::: +``` =sile +\showlayout[layout=honnecourt, papersize=6in x 9in] \showlayout[layout=honnecourt, papersize=a5] +``` +::: +^ Honnecourt’s historical layout. + +In the 15^th^ century, Marcus Vencentinus used a similar method, but with a 1/6 ratio, for a prayer book. +It has a wide outer margin and footer area, leaving enough place for annotations and marginal comments. + +::: +``` =sile +\showlayout[layout=vencentinus, papersize=6in x 9in] \showlayout[layout=vencentinus, papersize=a5] +``` +::: +^ Vencentinus’ historical layout. + +The rather quite large footer area in such layouts is based on the idea that books are held by the lower margin. + +These methods are based on regular divisions of the page, mere arithmetical operations which may be generalized for any page dimention _W_ × _H_, with a ratio _N_ and a constant _v_. +In the Honnecourt and Vencentinus’ canons, _v_=2, but other values are possible. + +In a method he described on the French _Typographie_ mailing list in 2002, Olivier Randier suggested that the _H/W_ ratio +was usually giving excellent results for most standard page sizes, including the ISO ones. +Following these “modern” findings, this class provides the fairly compact `division 12` (1/12 ratio), `division 9` (1/9 ratio, alias `division` as it is the most usual and pleasant layout), and `division 6` (1/6 ratio). + +::: +``` =sile +\showlayout[layout=division 12, + papersize=6in x 9in] \showlayout[layout=division 12, + papersize=a5]\quad\showlayout[layout=division 9, + papersize=6in x 9in] \showlayout[layout=division 9, papersize=a5] + +\smallskip +\showlayout[layout=division 6, + papersize=6in x 9in] \showlayout[layout=division 6, papersize=a5] +``` +::: +^ Divisions by 12, 9, 6 — modern layouts. + +Some of these layouts do not leave much available room for marginal notes. +The layout syntax supports other values than the standard ones, as `division ⟨N⟩` (based on the _H/W_ page ratio for the _v_ constant), or `division ⟨N⟩ ⟨v⟩`. + +## The golden canon of Tschichold + +Jan Tschichold (1902--1974) considered a "golden canon of page construction", where the text block is placed onto the page in such a way as its diagonal coincides with the page relevant diagonal, and the circle inscribed within the text block is tangent to the page sides. +It is provided here as `canonical`. + +::: +``` =sile +\showlayout[layout=canonical, papersize=6in x 9in] \showlayout[layout=canonical, papersize=a5] +``` +::: +^ Jan Tschichold's canonical layout. + +## Non-standard layouts + +{.notoc} +### A layout with wide margins + +Most of the common layouts presented above do not have both a dense text block and wide enough outer margins for annotations. +The experimental proposal below, dubbed `marginal`, is partly ratio-based (`marginal ⟨N⟩`, with 8 as default, i.e. a 1/8 ratio for inner margins), with some hard-coded choices and a dose of golden ratio in the mix. +The formula is somewhat empirical, but this author finds it decently looking for a critical text apparatus with an important amount of maginal notes. + +::: +``` =sile +\showlayout[layout=marginal, papersize=6in x 9in] \showlayout[layout=marginal, papersize=a5] +``` +::: +^ A “marginal” page layout. + +As can be seen, the header frame also goes past the text block, englobing the margin area. + +{.notoc} +### A poor man’s centered layout + +In passing, the `none` layout uses margins of 1/6^th^ of the page dimensions. +It just exists because it’s the base component for other layouts. + +::: +``` =sile +\showlayout[layout=none, papersize=6in x 9in] \showlayout[layout=none, papersize=a5] +``` +::: +^ This is not really a layout. + +{.notoc} +### An explicit page layout + +Some users may think they know better and want to define their own page layout. +This author thinks it is a bad idea, but it’s your choice, after all. +The `geometry` layout allows explicitly setting the page margins, as either a pair of dimensions (`geometry ⟨vert⟩ ⟨horiz⟩`) or as a quadruplet of dimensions (`geometry ⟨head⟩ ⟨inner⟩ ⟨foot⟩ ⟨outer⟩`). + +::: +``` =sile +\showlayout[layout=geometry 0.75in 1in 0.75in 2in, papersize=6in x 9in] +``` +::: +^ Be my guests — arbitrary margins. + +## Summary table + +| Layout option | Description | +|:--------------------------------|:-----------------------------------------------------| +| `ateliers` = `ateliers regular` | Ateliers, “courant en 10/12^e^” | +| `ateliers regular 10e` | Ateliers, “courant en 10^e^” | +| `ateliers demiluxe` | Ateliers, “demi-luxe en 10/12^e^” | +| `ateliers demiluxe 10e` | Ateliers, “demi-luxe en 10^e^” | +| `ateliers deluxe` | Ateliers, “de luxe en 10/12^e^” | +| `ateliers deluxe 10e` | Ateliers, “de luxe en 10^e^” | +| `honnecourt` = `division 9 2` | Honnecourt’s historical layout | +| `vencentinus` = `division 6 2` | Vencentinus’ historical layout | +| `division 12` | Division by 12, _H/W_ ratio | +| `division` = `division 9` | Division by 9, _H/W_ ratio | +| `division 6` | Division by 6, _H/W_ ratio | +| `division N` | Division by _N_, _H/W_ ratio | +| `division N v` | Division by _N_, _v_ ratio | +| `canonical` | Tschichold’s golden canon | +| `marginal` = `marginal 8` | Wide outer margin, other at 1/8^th^ | +| `marginal N` | Wide outer margin, other at 1/_N_ ^th^ | +| `none` | Centered with margins at 1/6^th^ | +| `geometry V H` | Vertical margin, horizontal margin | +| `geometry H I F O` | Head margin, inner margin, foot margin, outer margin | +^ Off-the-shelf layouts at a glance. diff --git a/examples/manual-layouts/layouts.sil b/examples/manual-layouts/layouts.sil deleted file mode 100644 index 0b39daf..0000000 --- a/examples/manual-layouts/layouts.sil +++ /dev/null @@ -1,341 +0,0 @@ -\begin{document} -\chapter{Choosing a page layout} - -\section{The layout class option} - -Paper sizes for printed works varied a lot across time. -Frequent ratios nowadays are 1:√2 (such as the ISO paper sizes, e.g. A5, 14,8 × 21 cm) -or 2:3 (such as US trade, 6 × 9 in), though there are still plenty of other page formats -in use (e.g. French pocket books often come in 10 × 17 cm or 10 × 18 cm format.) - -The relation between the page size and the main text block also varied a lot, -depending on the aesthetic tastes of authors and designers. - -The resilient document classes provide a \autodoc:parameter{layout=} class -option for selecting some fairly usual page layouts. -They are shown further below for comparison, applied to the US trade and A5 formats, -though their historical use may have favored a different paper size. - -\section{Thriving for harmony} - -The secret law of page harmony relies on using elegant proportions. -When designing your \em{perfect book}, just after having decided on a paper -size, you will want to pick a great page layout. - -SILE already offers several ways for designing your own page masters. However, -the syntax is not particularly easy, and users might not know what it takes -to use good values for print-quality books. - -The rationale for providing predefined layouts in the resilient collection -is to address that point, with a curated choice of classic page layouts, -available off-the-shelf. - -\section{On headers and footers} - -It has to be noted that these common layouts rarely detailed where headers or -folios were to be placed. Most typography books are silent on the topic, -or stay rather vague, stating obvious generalities—such as the headers and -footers having to be, bear with me, “close to the text block”. - -This author, therefore, decided to be a typographer on his own, regarding -that matter, and used a golden ratio to place the header and footer areas -in their margin space. - -\section{On the binding offset or gutter} - -The “gutter” is a typographical term referring to an \em{additional} margin -added to interior pages to compensate for the part of the page made unusable by -the binding process. Unfortunately, it cannot really be automated, as it -usually depends on many internal and external factors—notably, the number of pages, -the thickness of the selected paper, and the printer’s binding process. - -The resilient document classes provide the \autodoc:parameter{offset=} -class option. -When used, it shifts the text block by the given amount.\footnote{Please note that -it applies to page masters derived from a resilient layout. -If you designed your own page templates with SILE’s low-level constructs, -you are fully responsible for taking a binding offset into account there.} - -Books of less than 60 pages do not normally need to include such a gutter, -but with a higher page count, you may have to consider using it, -appropriately tuned with an \em{ad hoc} value. -Be aware, however, that outer margins will be reduced by the same amount. -If you intend to use them for annotations, be very careful here. - -% Quite a huge offset here in the example to make it visible. -\begin{figure} -\showlayout[layout=ateliers demiluxe, - papersize=6in x 9in] \raise[height=0.5in]{→} \showlayout[layout=ateliers demiluxe, papersize=6in x 9in, offset=0.20in] -\caption{Shifting a layout with a binding offset.} -\end{figure} - -The offset is usually specified in fixed inches or millimeters, as it doesn’t depend on the paper size. -It is near to impossible to make a general recommendation here, without knowing more details regarding the type of book and the binding process.\footnote{Some printing services even offer coil binding. Those coils are going to eat a whole lot of the inner margin!} -As a rule of thumb, a good practice is usually to check that the inner margins including the offset are not getting much bigger than the outer margins. Otherwise, it might imply you picked an inappropriate page layout in the first place. -Above 60 pages, you might thus start with an offset of \code{0.125in} and adjust by test and trial. Between 150 and 400 pages, you might need to reach \code{0.25in}, or more… - -\chapter{Off-the-shelf page layouts} - -\section{French layouts or “Canon des ateliers”} - -This canon normally applies a 4/10, 5/10, 6/10, 7/10 progression rule to distribute -the white space around the text block (“règle du 10/12\textsuperscript{e}”). - -In the standard definition, the 4/10 and 6/10 ratios are used for the -inner and outer margins; and the 5/10 and 7/10 ratios for the top and -bottom margins, but using the same base space value (i.e. taken from the -horizontal direction). - -A variant uses only the 4/10 and 6/10 ratios, but vertically applies to the -text block height the same proportion rules as in the horizontal direction -(“règle du 10\textsuperscript{e}”). - -There are other variants, such as one using the values of the inner and outer -margins for the top and bottom margins, leading to pretty dense pages. - -Thus, we have to support several ways of computing and distributing the -margins. Is it complex enough? Wait, the canon has no less than three different -proportion rules for the text block.\footnote{This author, being French, -will only note that we apparently like to make things more complex than -they ought to be.} - -For regular material (“imprimé courant”), the width of the text block takes 3/4 -of the page width. -So here we have the standard \code{ateliers} (= \code{ateliers regular}) using -the default 10/12\textsuperscript{e} rule and the 10\textsuperscript{e} rule variant -(\code{ateliers regular 10e}). - -\begin{figure} -\showlayout[layout=ateliers, - papersize=6in x 9in] \showlayout[layout=ateliers, - papersize=a5]\quad\showlayout[layout=ateliers regular 10e, - papersize=6in x 9in] \showlayout[layout=ateliers regular 10e, papersize=a5] -\caption{Canon des ateliers — regular.} -\end{figure} - -In the demi-luxe variant, the width of the text block takes 2/3 of the -page. Here again, we show the standard \code{ateliers demiluxe} -and the \code{ateliers demiluxe 10e} variant. - -\begin{figure} -\showlayout[layout=ateliers demiluxe, - papersize=6in x 9in] \showlayout[layout=ateliers demiluxe, - papersize=a5]\quad\showlayout[layout=ateliers demiluxe 10e, - papersize=6in x 9in] \showlayout[layout=ateliers demiluxe 10e, papersize=a5] -\caption{Canon des ateliers — demiluxe.} -\end{figure} - -In the “de luxe” variant, the width of the text block takes 5/8 of the -page. -As you would have guessed, these are the standard \code{ateliers deluxe} and -its \code{ateliers deluxe 10e} variant. - -\begin{figure} -\showlayout[layout=ateliers deluxe, - papersize=6in x 9in] \showlayout[layout=ateliers deluxe, - papersize=a5]\quad\showlayout[layout=ateliers deluxe 10e, - papersize=6in x 9in] \showlayout[layout=ateliers deluxe 10e, papersize=a5] -\caption{Canon des ateliers — deluxe.} -\end{figure} - -\section{Ratio-based layouts} - -Ratio-based methods are also known as the Van de Graaf canon, after the latter -rediscovered and documented them in the 1940s. -They are also sometimes referred to as the “secret canon” used in many medieval -manuscripts and incunabula. - -The proposed historical layouts are \code{honnecourt} and \code{vencentinus}. - -In the 13\textsuperscript{th} century, the architect Villard de Honnecourt -came up with what he considered a “harmonious” and pleasing design (esp. -for 2:3 pages), using a 1/9 ratio and a text block area in the same proportions -as the page, with a matching diagonal. - -\begin{figure} -\showlayout[layout=honnecourt, papersize=6in x 9in] \showlayout[layout=honnecourt, papersize=a5] -\caption{Honnecourt’s historical layout.} -\end{figure} - -In the 15\textsuperscript{th} century, Marcus Vencentinus used a similar -method, but with a 1/6 ratio, for a prayer book. It has a wide outer margin -and footer area, leaving enough place for annotations and marginal comments. - -\begin{figure} -\showlayout[layout=vencentinus, papersize=6in x 9in] \showlayout[layout=vencentinus, papersize=a5] -\caption{Vencentinus’ historical layout.} -\end{figure} - -The rather quite large footer area in such layouts is based on the idea that -books are held by the lower margin. - -These methods are based on regular divisions of the page, mere arithmetical operations -which may be generalized for any page dimention \em{W} × \em{H}, with a ratio \em{N} -and a constant \em{v}. In the Honnecourt and Vencentinus’ canons, \em{v}=2, -but other values are possible. - -In a method he described on the French \em{Typographie} -mailing list in 2002, Olivier Randier suggested that the \em{H/W} ratio -was usually giving excellent results for most standard page sizes, including the ISO -ones. -Following these “modern” findings, this class provides the fairly compact \code{division 12} -(1/12 ratio), \code{division 9} (1/9 ratio, alias \code{division} as it is the most usual and -pleasant layout), and \code{division 6} (1/6 ratio). - -\begin{figure} -\showlayout[layout=division 12, - papersize=6in x 9in] \showlayout[layout=division 12, - papersize=a5]\quad\showlayout[layout=division 9, - papersize=6in x 9in] \showlayout[layout=division 9, papersize=a5] - -\smallskip -\showlayout[layout=division 6, - papersize=6in x 9in] \showlayout[layout=division 6, papersize=a5] -\caption{Divisions by 12, 9, 6 — modern layouts} -\end{figure} - -It’s easy to check that some of these layouts do not leave much available room -for marginal notes. Note that the layout syntax supports other values -than the “standard” ones, as \code{division ⟨N⟩} (based on the \em{H/W} page -ratio for the \em{v} constant), or \code{division ⟨N⟩ ⟨v⟩}. - -\section{The golden canon of Tschichold} - -Jan Tschichold (1902–1974) considered a “golden canon of page construction”, -where the text block is placed onto the page in such a way as its diagonal coincides -with the page relevant diagonal, and the circle inscribed within the text block is tangent -to the page sides. It is provided here as \code{canonical}. - -\begin{figure} -\showlayout[layout=canonical, papersize=6in x 9in] \showlayout[layout=canonical, papersize=a5] -\caption{Jan Tschichold’s canonical layout.} -\end{figure} - -\section{Non-standard layouts} - -\subsection{A layout with wide margins} - -Most of the common layouts presented above do not have both a dense text block and wide -enough outer margins for annotations. The experimental proposal below, dubbed \code{marginal}, -is partly ratio-based (\code{marginal ⟨N⟩}, with 8 as default, i.e. a 1/8 ratio for -inner margins), with some hard-coded choices and a dose of golden ratio in the mix. -The formula is somewhat empirical, but this author finds it decently looking for a -critical text apparatus with an important amount of maginal notes. - -\begin{figure} -\showlayout[layout=marginal, papersize=6in x 9in] \showlayout[layout=marginal, papersize=a5] -\caption{A “marginal” page layout.} -\end{figure} - -As can be seen, the header frame also goes past the text block, englobing the margin area. - -\subsection{A poor man’s centered layout} - -In passing, the \code{none} layout uses margins of 1/6\textsuperscript{th} of the page dimensions. -It just exists because it’s the base component for other layouts. - -\begin{figure} -\showlayout[layout=none, papersize=6in x 9in] \showlayout[layout=none, papersize=a5] -\caption{This is not really a layout.} -\end{figure} - -\subsection{An explicit page layout} - -Some users may think they know better and want to define their own page layout. -This author thinks it is a bad idea, but it’s your choice, after all. -The \code{geometry} layout allows explicitly setting the page margins, as either a pair of dimensions (\code{geometry ⟨vert⟩ ⟨horiz⟩}) or as a quadruplet of dimensions (\code{geometry ⟨head⟩ ⟨inner⟩ ⟨foot⟩ ⟨outer⟩}). - -\begin{figure} -\showlayout[layout=geometry 0.75in 1in 0.75in 2in, papersize=6in x 9in] -\caption{Be my guests — arbitrary margins.} -\end{figure} - -\section{Summary table} - -\begin{table} -\begin[cols=40%fw 59%fw, header=true]{ptable} - \begin[background=#eee]{row} - \cell[valign=top,halign=left]{Layout option} - \cell[valign=top,halign=left]{Description} - \end{row} - \begin{row} - \cell[valign=top,halign=left]{\code{ateliers} = \code{ateliers regular}} - \cell[valign=top,halign=left]{Ateliers, “courant en 10/12\textsuperscript{e}”} - \end{row} - \begin{row} - \cell[valign=top,halign=left]{\code{ateliers regular 10e}} - \cell[valign=top,halign=left]{Ateliers, “courant en 10\textsuperscript{e}”} - \end{row} - \begin{row} - \cell[valign=top,halign=left]{\code{ateliers demiluxe}} - \cell[valign=top,halign=left]{Ateliers, “demi-luxe en 10/12\textsuperscript{e}”} - \end{row} - \begin{row} - \cell[valign=top,halign=left]{\code{ateliers demiluxe 10e}} - \cell[valign=top,halign=left]{Ateliers, “demi-luxe en 10\textsuperscript{e}”} - \end{row} - \begin{row} - \cell[valign=top,halign=left]{\code{ateliers deluxe}} - \cell[valign=top,halign=left]{Ateliers, “de luxe en 10/12\textsuperscript{e}”} - \end{row} - \begin{row} - \cell[valign=top,halign=left]{\code{ateliers deluxe 10e}} - \cell[valign=top,halign=left]{Ateliers, “de luxe en 10\textsuperscript{e}”} - \end{row} - \begin{row} - \cell[valign=top,halign=left]{\code{honnecourt} = \code{division 9 2}} - \cell[valign=top,halign=left]{Honnecourt’s historical layout} - \end{row} - \begin{row} - \cell[valign=top,halign=left]{\code{vencentinus} = \code{division 6 2}} - \cell[valign=top,halign=left]{Vencentinus’ historical layout} - \end{row} - \begin{row} - \cell[valign=top,halign=left]{\code{division 12}} - \cell[valign=top,halign=left]{Division by 12, \em{H/W} ratio} - \end{row} - \begin{row} - \cell[valign=top,halign=left]{\code{division} = \code{division 9}} - \cell[valign=top,halign=left]{Division by 9, \em{H/W} ratio} - \end{row} - \begin{row} - \cell[valign=top,halign=left]{\code{division 6}} - \cell[valign=top,halign=left]{Division by 6, \em{H/W} ratio} - \end{row} - \begin{row} - \cell[valign=top,halign=left]{\code{division N}} - \cell[valign=top,halign=left]{Division by \em{N}, \em{H/W} ratio} - \end{row} - \begin{row} - \cell[valign=top,halign=left]{\code{division N v}} - \cell[valign=top,halign=left]{Division by \em{N}, \em{v} ratio} - \end{row} - \begin{row} - \cell[valign=top,halign=left]{\code{canonical}} - \cell[valign=top,halign=left]{Tschichold’s golden canon} - \end{row} - \begin{row} - \cell[valign=top,halign=left]{\code{marginal} = \code{marginal 8}} - \cell[valign=top,halign=left]{Wide outer margin, other at 1/8\textsuperscript{th}} - \end{row} - \begin{row} - \cell[valign=top,halign=left]{\code{marginal N}} - \cell[valign=top,halign=left]{Wide outer margin, other at 1/\em{N\kern[width=0.1em]}\textsuperscript{th}} - \end{row} - \begin{row} - \cell[valign=top,halign=left]{\code{none}} - \cell[valign=top,halign=left]{Centered with margins at 1/6\textsuperscript{th}} - \end{row} - \begin{row} - \cell[valign=top,halign=left]{\code{geometry V H}} - \cell[valign=top,halign=left]{Vertical margin, horizontal margin} - \end{row} - \begin{row} - \cell[valign=top,halign=left]{\code{geometry H I F O}} - \cell[valign=top,halign=left]{Head margin, inner margin, foot margin, outer margin} - \end{row} -\end{ptable} -\caption{Off-the-shelf layouts at a glance.} -\end{table} - -\end{document} diff --git a/examples/manual-masterdoc/bibliographies.dj b/examples/manual-masterdoc/bibliographies.dj index f126a0b..5400d77 100644 --- a/examples/manual-masterdoc/bibliographies.dj +++ b/examples/manual-masterdoc/bibliographies.dj @@ -1,3 +1,4 @@ +{#using-bibliographies} # Using bibliographies For scholarly works, you may want to include bibliographic references in your book. @@ -36,7 +37,7 @@ Refer to _The SILE Book_ for more information on how to do this. ## Printing the bibliography -The **resilient.book** class registers a Djot symbol, `_BIBLIOGRAPHY_`, which you can use in a standalone paragraph to print the bibliography.[^bibliography-symbol] +The *resilient.book* class registers a Djot symbol, `_BIBLIOGRAPHY_`, which you can use in a standalone paragraph to print the bibliography.[^bibliography-symbol] Attributes are passed through to the underlying implementation. For example, to print all the bibliography including uncited references, you can use: @@ -50,8 +51,10 @@ This allows you to start fresh for subsequent uses (e.g., in a different chapter ## Citing references -This is not covered here. -Refer to the _Markdown and Djot to PDF with SILE_ user guide, or to _The SILE Book_ for more information on how to cite references depending on the format you are using to author your content. +The most basic form of citation, in documents authored in Djot or Markdown, is `[@key]`, where `key` is the citation key in your bibliography file. + +There are more advanced forms of citation with locators, such as `[@key, page 26]` to include a page number. +For a more detailed explanation regarding how to cite references and the supported bibliography formats, refer to the _Markdown and Djot to PDF with SILE_ user guide [@willis:sile-markdown-djot], or to _The SILE Book_ [@cozens:sile] depending on the format you are using to author your content. [^bibliography-symbol]: Obviously, this needs to be used in a Djot content file. diff --git a/examples/manual-masterdoc/bookdivisions.dj b/examples/manual-masterdoc/bookdivisions.dj index ca0b931..b4a35c0 100644 --- a/examples/manual-masterdoc/bookdivisions.dj +++ b/examples/manual-masterdoc/bookdivisions.dj @@ -1,7 +1,7 @@ # More book divisions -In §[](#masterdoc-content-basic), we explored how to declare a simple book consisting of chapters or parts. -For books with chapters only: +In the previous chapters, we explored how to declare a simple book consisting of chapters or parts. +As seen, the syntax for books with chapters only is: ```yaml @@ -10,17 +10,11 @@ content: ⟨...⟩ ``` -Or for books with parts: - -```yaml -content: - parts: - ⟨...⟩ -``` +And likewise, for books with parts, with the `parts` key instead of `chapters`. ## Front, main and back divisions -Actually, the above examples are simplified versions of a book's structure. +Actually, the above examples are simplified versions of a book's internal structure. They are equivalent to the following full syntax: ```yaml @@ -31,10 +25,10 @@ content: That is, your content is assumed to be part of the main matter by default. Some books, however, require a more complex structure, dividing content into front matter, main matter, and back matter. -This is particularly common in academic works, where the front matter might include a preface, dedication, and table of contents. -![Internal book divisions](images/book-divisions.svg){width="65%lw"} +![Internal book divisions.](images/book-divisions.svg){width="65%"} +In such books, the front matter might include a preface, dedication, and table of contents. The back matter is more variable, but for instance, it might include an index, bibliography, or glossary. Each division begins on an odd-numbered page. @@ -116,9 +110,9 @@ Or with a book with a part containing both chapters and appendices: content: mainmatter: parts: - - caption: Backmatter part + - caption: Some part chapters: - - caption: Backmatter chapter + - caption: Some chapter appendices: - - caption: Backmatter appendix + - caption: Some appendix ``` diff --git a/examples/manual-masterdoc/bookmatters.dj b/examples/manual-masterdoc/bookmatters.dj index 684d88b..6a0ed25 100644 --- a/examples/manual-masterdoc/bookmatters.dj +++ b/examples/manual-masterdoc/bookmatters.dj @@ -41,8 +41,9 @@ The aim of the resilient master document is to provide a default set of conventi - At the end of the book, some _end-papers_ occur. On the recto one may find the title, the publisher, sometimes the ISBN is barcode form, and possibly other important mentions --- In some countries, the legal deposit is required to be printed there, etc. This page is also known as an _impressum,_ and its verso is (generally) left blank. -![A resilient book structure](images/book-anatomy.svg){width="65%lw"} +![A resilient book structure.](images/book-anatomy.svg){width="65%"} +{#bookmatters:templates-customization} ## Customizing the title and endpaper pages All theses pages are actually implemented as a set of "Djot templates" (`.djt` files) that you can override.[^bookmatters:templates] @@ -109,6 +110,8 @@ Yet, when going to print, you may need to have them removed. Once you have declared a back cover image, you will notice it automatically contains the ISBN of your book in an overlay at its bottom-right, if you defined it in your metadata. (If you didn't, this space is nevertheless reserved.) +![Structure of the back cover.](images/book-backcover.svg){width="65%"} + The back cover can also contain additional content, such as a description of the book. Let's therefore go on with our possibilities. @@ -166,7 +169,9 @@ book: In most cases, the text on the front cover of a book is part of the overall cover design, with its own typography and layout incorporated into the image. If this applies to you, no further steps are needed beyond the options previously discussed. -However, if you're in a situation where the cover design is not yet finalized or the image lacks text, you can customize the front cover using a "Djot template." +![Structure of the front cover.](images/book-frontcover.svg){width="65%"} + +However, if you're in a situation where the cover design is not yet finalized or the image lacks text, you can use a templated overlay. The text will be automatically typeset in either white or black, based on the background color, to ensure optimal contrast. ```yaml @@ -178,6 +183,9 @@ book: template: cover ``` +The provided `cover` template uses your metadata to typeset the title, author, and possibly other information. +You can write and use your own template, as already explained in §[](#bookmatters:templates-customization). + ## Other options The master document handler also accepts a `cropmarks=true` option, which can be useful when you print your book on larger sheets of paper. diff --git a/examples/manual-masterdoc/masterdoc.dj b/examples/manual-masterdoc/masterdoc.dj index 8115296..b2f27be 100644 --- a/examples/manual-masterdoc/masterdoc.dj +++ b/examples/manual-masterdoc/masterdoc.dj @@ -21,7 +21,7 @@ sile -u inputters.silm mybook.silm ``` The format consists in a simple description of the book properties and content, expressed in [YAML](https://en.wikipedia.org/wiki/YAML), a lightweight human-readable data-representation language. -Here is an example, showing most of the elements. +Here is an example, showing most of the basic elements. ```yaml masterfile: 1.0 @@ -68,75 +68,212 @@ The `masterfile` entry is a number corresponding to a version, for compatibility ## The metadata section +[^:icon-pdf-metadata:]: ^:U+25C6:^ + +[^:icon-running-headers:]: ^:U+25CB:^ + +[^:icon-back-cover:]: ^:U+25CF:^ + The `metadata` object contains several general document properties. +All these properties are optional, but some are used in specific contexts when available: + + - Properties marked :icon-pdf-metadata: are automatically used as PDF metadata. + + - Properties marked :icon-running-headers: may be used in running headers (depending on the document class and its options, see further below). + + - Properties marked :icon-back-cover: are used on the back cover, if enabled. + +{variant="Simple"} +: `title` :icon-pdf-metadata: :icon-running-headers: + + The title of your book (string). + +: `subtitle` + + The subtitle of your book (string). + +: `subject` :icon-pdf-metadata: + + The subject of the book (string). + +: `keywords` :icon-pdf-metadata: + + Keywords for the book (string or array of strings). + +: `authors` :icon-pdf-metadata: + + The author(s) of the book (string or array of strings). + +: `translators` + + The translator(s) of the book (string or array of strings). + +: `publisher` + + The publisher of the book (string). + +: `pubdate` - - The `title`, `authors`, `subject` and `keywords` will automatically be used as PDF metadata. + The publication date of the book (date, such as `2023-07-14`). - - As denoted by the plural, `authors`, `translators` and `keywords` may consist in a list of strings, but they also accept a single string. +: `isbn` :icon-back-cover: - - The `title` may be used in running headers (possibly, depending on the document class and its options). + The ISBN of the book (string). -All properties are passed as metadata made available to the content files. +: `url` + + The URL of the book (string) when applicable. + +: `copyright` + + The copyright notice of the book (string). + +: `legal` + + The legal notice of the book (string). + +All properties are made available to the content files. In the current implementation, this is only effective with Djot documents, wherein the medatada are exposed as Djot symbols (e.g. `:title:`, `:authors:`, and so on). -For convenience, for authors and translators, the symbols `:author:` and `:translator:`{.nobreak} are also exposed, and contain the first entry. +For convenience, the singular forms `:author:` and `:translator:` are also exposed, and contain the first entry. +The publication date is also expanded in Djot as `:pubdate-year:`, `:pubdate-month:`, and `:pubdate-day:` to access the components separately. +Book matters (cover, title page, etc.), covered in a further chapter, may also use these metadata. ## The font section -The `font` object defines the _default_ font, as a font `family` and a `size`. +The `font` object defines the default main font to use in the book. - - The `family` is either a font name (as a string) or an array of font names. - In the latter case, the first font is used as default font and the others are declared as "font fallbacks", would some characters be unavailable. - - The `size`, as expected, is the default font size, usually expressed in points. +{variant="Simple"} +: `family` + + The main font family to use, as a string or an array of strings. + In the latter case, the first font is used as default font and the others are declared as "font fallbacks", would some characters be unavailable. + +: `size` + + The default font size, usually expressed in points (e.g. `12pt`). ## The SILE configuration section -The `sile` object provides intructions for processing the master document with SILE. +The `sile` object provides intructions for processing the master document with, guess what, the SILE typesetting engine. + +### Configuration options + +The `options` are to be understood as document class options. (As such, they can notably be overridden from the command line when invoking SILE.) +The optional `class` key specifies the document class to use. + +It defaults to `resilient.book`. +Usually you will not need to set it, as the default choice is already a good one, and there is no guarantee that other classes will support the same level of features. +The other options depend on that document class. +Using the *resilient.book* class, the following options are available: + +{variant="Simple"} +: `papersize` + + The paper size to use, as a known paper size (`letter`, `a4`, etc.) or custom dimensions (e.g. `6in x 9in`). + Default is `a4`. + +: `layout` + + The global page layout (see part [](#page-layout)). + Default is `division`. + +: `offset` + + The binding offset (see part [](#page-layout)). + +: `headers` + + What goes in the running headers depends on this option. + The accepted values are listed below. + + {variant="Simple"} + : `none` - - The `options` are to be understood as document class options. - (As such, they can notably be overridden from the command line when invoking SILE.) + No running headers. - - If you don't specify a `class` then *resilient.book* is assumed. + : `technical` (default) - - Other supported options are `papersize`, and, with the resilient book class, `layout`, `offset`, `headers` and `resolution`. + Chapter and section titles go in the even and odd running headers, respectively. -- The `settings` can be used to globally set some SILE parameters. + : `novel` -- The `packages` object lists extra packages that SILE must use. - It can be used to load add-on packages needed by your content but not already provided by the document class and its supporting packages. + Chapter titles go in the odd running headers, and the title of the book, if set, goes in the even running headers. +: `resolution` + + The global resolution in DPI (dots per inch). + Some add-on packages may use it in order to compute the size of generated images, transform external images, etc. + +### Configuration settings + +The `settings` can be used to globally set some SILE parameters. +A few usual suggestions are listed below for convenience, but please refer to _The SILE Book_ for standard parameters and parts +[](#resilient-packages)--[](#resilient-classes) in this manual for resilient-specific parameters. + +{variant="Simple"} +: `textsubsuper.fake` (boolean) + + Whether to use fake superscript and subscript glyphs (raised and scaled) or native ones, when available. + It highly depends on the font and the quality of its superscript and subscript glyphs, so you will have to test it. + +: `typesetter.italicCorrection` (boolean) + + Whether to apply an italic correction heuristic when text switches between italic and upright. + The recommended value is `true`, but you may want to keep it disabled with certain choices of fonts. + +### Extra packages + +The `packages` object lists extra packages that SILE must use. +It can be used to load add-on packages needed by your content but not already provided by the document class and its supporting packages. +As far as the resilient collection is concerned, a few notable suggestions are listed below. + + - **resilient.poetry** for poetry typesetting. + - **printoptions** for advanced print options & tools for professional printers. + {#masterdoc-content-basic} ## Up to the content -Last but not least, the `chapters` array (or `parts`, see further below) lists the files to include in the work. -In its simplest form, it consists in an ordered list of file names. +Last but not least, after the important but mundane sections, it is time to organize the actual content of your book. + +![From files to chapters and parts.](images/book-parts-chapters.svg){width="65%"} + +For the sake of simplicity, let's consider you have a bunch of files in Djot or Markdown, each representing a chapter---that, is files all starting with a level 1 heading. +We'll consider more complex structures later. + +In the simplest case, chapters consists in an ordered list of file names. These files may be of any type supported by SILE, the document class or loaded packages.[^masterdoc-nesting] ```yaml -chapters: - - chap1.md - - chap2.dj +content: + chapters: + - chap1.md + - chap2.dj ``` This is actually a convenience short form for the fuller syntax. ```yaml -chapters: - - file: chap1.md - - file: chap2.dj +content: + chapters: + - file: chap1.md + - file: chap2.dj ``` In this structured form, other fields are accepted, for enforcing the input format (which can be useful if the extension is non-standard) and the options passed to the input handler. +Refer to the documentation of that handler to know which options are available. ```yaml -chapters: - - file: chap1.txt - format: markdown - options: - smart: false # disable smart typography support in Markdown +content + chapters: + - file: chap1.txt + format: markdown + options: + smart: false # disable smart typography support ``` There is another structured form which just takes a "caption" string. -To be honest, it's mostly provided as a quick convenience placeholder. +It's mostly provided as a quick convenience placeholder. +This author uses it when drafting a book, to quickly sketch its structure before adding the actual content. ```yaml chapters: @@ -148,18 +285,68 @@ All structured forms accept a `content` entry, which is again a list of files to With Djot, Markdown or other formats supporting this feature,[^masterdoc-sil-nesting] the headings in these files are then _shifted_. ```yaml -chapters: - - file: chap1.dj # Level 1 headings = chapters, etc. - content: - - file: sect.dj # Level 1 headings = sections, etc. +content: + chapters: + - file: chap1.dj # Level 1 headings = chapters, etc. + content: + - file: sect.dj # Level 1 headings = sections, etc. +``` + +So let's now consider a more complex structure, with several "parts." +With document classes supporting parts, it allows using them, starting at that level. + +```yaml +content: + parts: + - file: part1.dj + content: + - chap1.dj ``` -We earlier mentioned the `parts` keywords. -With document classes supporting parts, such as **resilient.book**, it allows using them, starting at that level.[^masterdoc-astute] +Each document file, here, begins with a level 1 heading. +But the book now starts with a part, and the chapters are included in it, with their headings shifted accordingly. +Would you want to split your sections in several files, as if they were independent (also starting with a level 1 heading), you can nest them in the same way, and they will be included, appropriately shifted, in the chapters. +And so on for deeper levels. + +In the next chapters, we will see even more complex structures, with front, main and back matters, appendices, and more. +But for now, you have all the basics to start assembling your book. [^masterdoc-nesting]: In particular, you may include a master document in another. In that case, though, only the declared extra packages and the content files are used. [^masterdoc-sil-nesting]: Not available for SIL documents. -[^masterdoc-astute]: Astute readers will realize that the `chapters` structure is just a convenience facility. +## Abusing the master document format + +The master document format is quite flexible and adaptable to various use cases. + +However, it's primarily a "high-level" description of a book's structure, leaving the specifics of the content files entirely up to you. +For better or worse, it's fairly easy to abuse. + +You can use low-level commands in SIL or Lua, and break all reasonable expectations. +But even without going that far, let's consider the following example. + +```yaml +content: + parts: + - content: + - introduction.dj + - caption: Part 2 + content: + - chapter1.dj +``` + +The introduction is in an anonymous part. +Its headers are therefore offset, as explained above, aren't they? +And you end up with a chapter preceeding the first part. +This is sometimes very practical, but the "true" way to do it would be a front matter division. +We will see that in a moment, but mentioning such a trick is still worth it. It may have its uses in certain cases. + +Similarly, if a chapter-level file in your master document doesn't begin with a level 1 title, it will be included as is, +and semantically, it belongs to the _previous_ part or chapter. +In other words, you can divide your content any way you like, and do some fancy things with it. +The master document format is only a tool and a guide, not a straitjacket. + +> "I have spoken. +> This is the way." +^ _The Mandalorian_ (Series). diff --git a/examples/manual-packages/audience.dj b/examples/manual-packages/audience.dj new file mode 100644 index 0000000..23d48fb --- /dev/null +++ b/examples/manual-packages/audience.dj @@ -0,0 +1,13 @@ +{#resilient-packages-audience} +# Target audience + +This part goes even deeper into advanced topics than the previous one. +The following chapters provide internal documentation for the packages included in the _re·sil·ient_ collection. + +Authors working in Djot or Markdown will rarely need this level of detail, except when the _Markdown and Djot to PDF with SILE_ manual indicates that a construct passes its argument to the underlying implementation. +In such cases, these chapters may be useful for understanding the capabilities of the underlying packages. + +For SIL users, however, this section offers valuable insights into the direct use of these packages. +The SIL language is the focus here, with an assumption of deeper knowledge of SILE, meaning that casual readers may find this section less accessible than the rest of this manual. + +This is also of interest to developers exploring the internals of the _re·sil·ient_ components and seeking to extend or modify their functionality. diff --git a/examples/manual-packages/packages.dj b/examples/manual-packages/packages.dj new file mode 100644 index 0000000..7f09265 --- /dev/null +++ b/examples/manual-packages/packages.dj @@ -0,0 +1,273 @@ +# Typography packages + +## Superscripts & subscripts + +{custom-style=admon} +This package is part of the *textsubsuper.sile* collection. + +``` =sile +\package-documentation{textsubsuper} +``` + +## Strut rules + +{custom-style=admon} +This package is part of the *ptable.sile* collection. + +``` =sile +\package-documentation{struts} +``` + +## Smart quotations marks + +{custom-style=admon} +This package is part of the *smartquotes.sile* collection. + +``` =sile +\package-documentation{smartquotes} +``` + +## Shorthands & abbreviations + +``` =sile +\package-documentation{resilient.abbr} +``` + +# Boxes & Tables + +## Boxed paragraphs + +{custom-style=admon} +This package is part of the *ptable.sile* collection. + +``` =sile +\package-documentation{parbox} +``` + +## Flexible tables + +{custom-style=admon} +This package is part of the *ptable.sile* collection. + +``` =sile +\package-documentation{ptable} +``` + +## Fancy box frames + +{custom-style=admon} +This package is part of the *ptable.sile* collection. + +``` =sile +\package-documentation{framebox} +``` + +# Graphic-related packages + +## Printer’s ornaments & pendants + +{custom-style=admon} +This package is part of the *couyards.sile* collection. + +``` =sile +\package-documentation{couyards} +``` + +## EAN-13 barcodes for ISBN etc. + +{custom-style=admon} +This package is part of the *barcodes.sile* collection. + +``` =sile +\package-documentation{barcodes.ean13} +``` + +## QR codes + +{custom-style=admon} +This package is part of the *qrcode.sile* collection. + +``` =sile +\package-documentation{qrcode} +``` + +## Textual image formatters + +{custom-style=admon} +This package is part of the *embedders.sile* collection. + +``` =sile +\package-documentation{embedders} +``` + +### Graphs with the Graphviz DOT language + +``` =sile +\embedder-documentation{dot} +``` + +### Musical scores with LilyPond + +``` =sile +\embedder-documentation{lilypond} +``` + +## Pie charts + +{custom-style=admon} +This package is part of the *piecharts.sile* collection. + +``` =sile +\package-documentation{piecharts} +``` + +# Book parts and utilities + +## Cross-references + +{custom-style=admon} +This package is part of the *labelrefs.sile* collection. + +``` =sile +\package-documentation{labelrefs} +``` + +{#packages-tableofcontents} +## Enhanced table of contents + +``` =sile +\package-documentation{resilient.tableofcontents} +``` + +{#packages-fancytoc} +## Fancy alternative table of contents + +{custom-style=admon} +This package is part of the *fancytoc.sile* collection. + +``` =sile +\package-documentation{fancytoc} +``` + +Here it is at work for the current document with default parameters. +Since our book class supports parts at level 0, we get the parts +and chapters. + +``` =sile +\fancytableofcontents +\bigskip +``` + +And here it is stating at level 1, i.e. chapters and sections. + +``` =sile +\fancytableofcontents[start=1] +``` + +## Enhanced footnotes + +``` =sile +\package-documentation{resilient.footnotes} +``` + +## Page headers revisited + +``` =sile +\package-documentation{resilient.headers} +``` + +# Print-related packages + +## Printing options & tools for professional printers + +{custom-style=admon} +This package is part of the *printoptions.sile* collection. + +``` =sile +\package-documentation{printoptions} +``` + +# Specialized environments + +## Epigraphs + +``` =sile +\package-documentation{resilient.epigraph} +``` + +## Enhanced bullet lists and enumerations + +``` =sile +\package-documentation{resilient.lists} +``` + +## Poetry, verses & scansion + +``` =sile +\package-documentation{resilient.poetry} +``` + +## Verbatim content + +``` =sile +\package-documentation{resilient.verbatim} +``` + +## Definition items + +``` =sile +\package-documentation{resilient.defn} +``` + +# Other input formats + +## Djot + +{custom-style=admon} +This package is part of the *markdown.sile* collection. + +``` =sile +\package-documentation{djot} +``` + +## Markdown + +{custom-style=admon} +This package is part of the *markdown.sile* collection. + +``` =sile +\package-documentation{markdown} +``` + +## Pandoc AST + +{custom-style=admon} +This package is part of the *markdown.sile* collection. + +``` =sile +\package-documentation{pandocast} +``` + +# Technical packages + +These packages are not intended to be used alone, but provide utilities +for other packages. They are therefore mainly aimed at package and +class writers. + +## Style specification support + +``` =sile +\package-documentation{resilient.styles} +``` + +## Abstraction for sectioning commands + +``` =sile +\package-documentation{resilient.sectioning} +``` + +## Helper multi-liners for character styles + +``` =sile +\package-documentation{resilient.liners} +``` diff --git a/examples/manual-packages/packages.sil b/examples/manual-packages/packages.sil deleted file mode 100644 index 2fdf7bc..0000000 --- a/examples/manual-packages/packages.sil +++ /dev/null @@ -1,234 +0,0 @@ -\begin{document} -%\section{End-user packages provided independently} -% -%\subsection{colophon: shaped & decorated paragraphs} -% -%(No yet migrated) - -%\package-documentation{colophon} - -%%% -%%% TYPOGRAPHY -%%% -\chapter{Typography packages} - -\section{Superscripts & subscripts} - -\admon{This package is part of the \strong{textsubsuper.sile} collection.} - -\package-documentation{textsubsuper} - -\section{Strut rules} - -\admon{This package is part of the \strong{ptable.sile} collection.} - -\package-documentation{struts} - -\section{Smart quotations marks} - -\admon{This package is part of the \strong{smartquotes.sile} collection.} - -\package-documentation{smartquotes} - -\section{Shorthands & abbreviations} - -\package-documentation{resilient.abbr} - -%%% -%%% BOXES AND TABLES -%%% -\chapter{Boxes & Tables} - -\section{Boxed paragraphs} - -\admon{This package is part of the \strong{ptable.sile} collection.} - -\package-documentation{parbox} - -\section{Flexible tables} - -\admon{This package is part of the \strong{ptable.sile} collection.} - -\package-documentation{ptable} - -\section{Fancy box frames} - -\admon{This package is part of the \strong{ptable.sile} collection.} - -\package-documentation{framebox} - -%%% -%%% GRAPHICS -%%% -\chapter{Graphic-related packages} - -\section{Printer’s ornaments & pendants} - -\admon{This package is part of the \strong{couyards.sile} collection.} - -\package-documentation{couyards} - -\section{EAN-13 barcodes for ISBN etc.} - -\admon{This package is part of the \strong{barcodes.sile} collection.} - -\package-documentation{barcodes.ean13} - -\section{QR codes} - -\admon{This package is part of the \strong{qrcode.sile} collection.} - -\package-documentation{qrcode} - -\section{Textual image formatters} - -\admon{This package is part of the \strong{embedders.sile} collection.} - -\package-documentation{embedders} - -\subsection{Graphs with the Graphviz DOT language} - -\embedder-documentation{dot} - -\subsection{Musical scores with LilyPond} - -\embedder-documentation{lilypond} - -\section{Pie charts} - -\admon{This package is part of the \strong{piecharts.sile} collection.} - -\package-documentation{piecharts} - -%%% -%%% Book parts and tools -%%% -\chapter{Book parts and utilities} - -\section{Cross-references} - -\admon{This package is part of the \strong{labelrefs.sile} collection.} - -\package-documentation{labelrefs} - -\section{Enhanced table of contents} - -\package-documentation{resilient.tableofcontents} - -\section{Fancy alternative table of contents} - -\admon{This package is part of the \strong{fancytoc.sile} collection.} - -\package-documentation{fancytoc} - -Here it is at work for the current document with default parameters. -Since our book class supports parts at level 0, we get the parts -and chapters. - -\fancytableofcontents - -\bigskip -And here it is stating at level 1, i.e. chapters and sections. - -\fancytableofcontents[start=1] - -\section{Enhanced footnotes} - -\package-documentation{resilient.footnotes} - -\section{Page headers revisited} - -\package-documentation{resilient.headers} - -%%% -%%% PRINTING -%%% -\chapter{Print-related packages} - -\section{Printing options & tools for professional printers} - -\admon{This package is part of the \strong{printoptions.sile} collection.} - -\package-documentation{printoptions} - -%%% -%%% SPECIALIZED ENVS -%%% -\chapter{Specialized environments} - -\section{Epigraphs} - -\package-documentation{resilient.epigraph} - -\section{Enhanced bullet lists and enumerations} - -\package-documentation{resilient.lists} - -\section{Poetry, verses & scansion} - -\package-documentation{resilient.poetry} - -\section{Verbatim content} - -\package-documentation{resilient.verbatim} - -\section{Definition items} - -\package-documentation{resilient.defn} - -%%% -%%% INPUT FORMATS -%%% -\chapter{Other input formats} - -\section{Markdown} - -\admon{This package is part of the \strong{markdown.sile} collection.} - -\package-documentation{markdown} - -\section{Pandoc AST} - -\admon{This package is part of the \strong{markdown.sile} collection.} - -\package-documentation{pandocast} - -\section{Djot} - -\admon{This package is part of the \strong{markdown.sile} collection.} - -\package-documentation{djot} - -%%% -%%% TECHNICAL PACKAGES -%%% -\chapter{Technical packages} - -These packages are not intended to be used alone, but provide utilities -for other packages. They are therefore mainly aimed at package and -class writers. - -\section{Style specification support} - -\package-documentation{resilient.styles} - -\section{Abstraction for sectioning commands} - -\package-documentation{resilient.sectioning} - -\section{Helper multi-liners for character styles} - -\package-documentation{resilient.liners} - -%\section{Specialized packages} -% -%\subsection{(teidict) XML TEI P4 print dictionaries} -% -% (Now separate) -%\package-documentation[src=packages/teidict] -% -%\subsection{teiabbr: localized abbreviations for TEI dictionaries} -% -%\package-documentation[src=packages/teiabbr] -% -\end{document} diff --git a/examples/manual-parts/part-appendices.dj b/examples/manual-parts/part-appendices.dj new file mode 100644 index 0000000..c27f221 --- /dev/null +++ b/examples/manual-parts/part-appendices.dj @@ -0,0 +1,6 @@ +# Appendices + +![At the end of the book: the journey is yours.[^dore1873]](images/dore-perrault.jpg){ width="99%" } + +{mark="†"} +[^dore1873]: Gustave Doré, _Contes de Perrault,_ 1862. diff --git a/examples/manual-parts/part-intro.dj b/examples/manual-parts/part-intro.dj index 2c99217..d865844 100644 --- a/examples/manual-parts/part-intro.dj +++ b/examples/manual-parts/part-intro.dj @@ -1,4 +1,4 @@ -# Introduction to re·sil·ient +# Introduction to _re·sil·ient_ ![Printers in 1568.[^meggs1998]](images/printer_1568.png){ width="50%pw" } diff --git a/examples/manual-styling/advanced/dropcap.md b/examples/manual-styling/advanced/dropcap.dj similarity index 93% rename from examples/manual-styling/advanced/dropcap.md rename to examples/manual-styling/advanced/dropcap.dj index 28856fb..ce303e9 100644 --- a/examples/manual-styling/advanced/dropcap.md +++ b/examples/manual-styling/advanced/dropcap.dj @@ -1,7 +1,7 @@ ## Styling initial capitals Initial capitals (also known as drop caps) are a typographic feature where the first letter of a paragraph is enlarged and styled differently from the rest of the text. -The **resilient.book** class defines two commands for this purpose: `initial-joined` and `initial-unjoined`. +The *resilient.book* class defines two commands for this purpose: `initial-joined` and `initial-unjoined`. The former should be used when the initial capital is part of the first word of the paragraph, and the latter when it is a separate character. In Markdown or Djot, you may use one or the other directly as a style (although they are rather pseudo-styles, strictly speaking). diff --git a/examples/manual-styling/advanced/eqno.md b/examples/manual-styling/advanced/eqno.dj similarity index 100% rename from examples/manual-styling/advanced/eqno.md rename to examples/manual-styling/advanced/eqno.dj diff --git a/examples/manual-styling/advanced/folio.md b/examples/manual-styling/advanced/folio.dj similarity index 94% rename from examples/manual-styling/advanced/folio.md rename to examples/manual-styling/advanced/folio.dj index 1f45152..f34041e 100644 --- a/examples/manual-styling/advanced/folio.md +++ b/examples/manual-styling/advanced/folio.dj @@ -1,6 +1,6 @@ ## Styling page numbers -In two-side documents, such as the **resilient.book** class, dedicated paragraph styles +In two-side documents, such as the *resilient.book* class, dedicated paragraph styles are used for odd and even pages. The _default_ definitions just take care the alignment, and defer other styling decisions to a common parent style. diff --git a/examples/manual-styling/advanced/footnotes.md b/examples/manual-styling/advanced/footnotes.dj similarity index 100% rename from examples/manual-styling/advanced/footnotes.md rename to examples/manual-styling/advanced/footnotes.dj diff --git a/examples/manual-styling/advanced/intro.md b/examples/manual-styling/advanced/intro.dj similarity index 100% rename from examples/manual-styling/advanced/intro.md rename to examples/manual-styling/advanced/intro.dj diff --git a/examples/manual-styling/advanced/liststyles.md b/examples/manual-styling/advanced/liststyles.dj similarity index 94% rename from examples/manual-styling/advanced/liststyles.md rename to examples/manual-styling/advanced/liststyles.dj index bdb615c..7b88a78 100644 --- a/examples/manual-styling/advanced/liststyles.md +++ b/examples/manual-styling/advanced/liststyles.dj @@ -1,6 +1,6 @@ ## Styling lists -The **resilient.lists** package, as noted in its documentation, uses +The *resilient.lists* package, as noted in its documentation, uses different sets of styles for the `itemize` and the `enumerate` environments. diff --git a/examples/manual-styling/advanced/other.md b/examples/manual-styling/advanced/other.dj similarity index 53% rename from examples/manual-styling/advanced/other.md rename to examples/manual-styling/advanced/other.dj index 49fd540..2113653 100644 --- a/examples/manual-styling/advanced/other.md +++ b/examples/manual-styling/advanced/other.dj @@ -6,9 +6,9 @@ You should therefore read their documentation to learn about them, and look at a Readers experienced with SILE’s standard packages also have to be aware that the latter sometimes define hooks, initially intended for users to possibly re-implement in order to override some internal formatting logic. Obviously, in the context of a resilient-compatible class, some of these are already overriden to rely on the styling paradigm presented here. -For instance, the (standard) **url** package provides a `urlstyle` hook command. While you could override it---that is, redefine that command---, please note that this is what the resilient classes already do, so as to delegate the decision to a style conveniently called `urlstyle` too.[^other-sile-hooks] +For instance, the (standard) *url* package provides a `urlstyle` hook command. While you could override it---that is, redefine that command---, please note that this is what the resilient classes already do, so as to delegate the decision to a style conveniently called `urlstyle` too.[^other-sile-hooks] -[^other-sile-hooks]: The same principle actually applies to page numbers, relying on the standard **folio** package. The latter provides a `foliostyle` hook, which the resilient styling system overrides with its own clever logic. -Likewise, the `math:numberstyle` hook from the **math** package is also redefined, to rely on the `eqno` style for display math equation numbers (and actually, if it exist and is non-emppty, to the `eqno-⟨counter⟩` style specific to the counter in question, by default `equation`), as described in the previous section. +[^other-sile-hooks]: The same principle actually applies to page numbers, relying on the standard *folio* package. The latter provides a `foliostyle` hook, which the resilient styling system overrides with its own clever logic. +Likewise, the `math:numberstyle` hook from the *math* package is also redefined, to rely on the `eqno` style for display math equation numbers (and actually, if it exist and is non-emppty, to the `eqno-⟨counter⟩` style specific to the counter in question, by default `equation`), as described in the previous section. In other terms, even for standard SILE packages, we may already have provided a style-aware version of their original customization hooks. diff --git a/examples/manual-styling/advanced/toclevels.md b/examples/manual-styling/advanced/toclevels.dj similarity index 94% rename from examples/manual-styling/advanced/toclevels.md rename to examples/manual-styling/advanced/toclevels.dj index 780094b..7f37ae7 100644 --- a/examples/manual-styling/advanced/toclevels.md +++ b/examples/manual-styling/advanced/toclevels.dj @@ -9,9 +9,9 @@ consider: - How page references are formatted. [^toc-fancy]: This section applies to the "standard" table of contents, -as produced with the `\tableofcontents` command from the **resilient.tableofcontents** +as produced with the `\tableofcontents` command from the *resilient.tableofcontents* package. -Specific implementations such as **fancytoc** may use their own +Specific implementations such as *fancytoc* may use their own styling rules. ### Global setup diff --git a/examples/manual-styling/basics/character.md b/examples/manual-styling/basics/character.dj similarity index 96% rename from examples/manual-styling/basics/character.md rename to examples/manual-styling/basics/character.dj index 8d4cae5..694c97d 100644 --- a/examples/manual-styling/basics/character.md +++ b/examples/manual-styling/basics/character.dj @@ -19,7 +19,7 @@ A regular character style obeys to the following specification The ⟨font specification⟩ is an object which can contain any of the usual elements, as used in the SILE `\font` command. -The ⟨color specification⟩ follows the same syntax as defined in the SILE **color** package. +The ⟨color specification⟩ follows the same syntax as defined in the SILE *color* package. As an example, the following style results in a blue italic superscript in the Libertinus Serif font. @@ -35,12 +35,14 @@ my-custom-style-name: position: "super" ``` -#### Properties {.unnumbered} +{.unnumbered} +#### Properties The "properties" might be extended in a future revision; for now they support a position element, to specify a superscript or subscript formatting, and a text case element. The "normal" values may be used to override a parent style definition, when style inheritance is used. -#### Decorations {.unnumbered} +{.unnumbered} +#### Decorations The ⟨decoration specification⟩ is an object which can contain any of the following elements. @@ -70,7 +72,7 @@ It defaults to "solid" and "zizag" respectively. The "thickness" defaults to `0.5pt`. For instance, the `md-mark` style overrides the Markdown or Djot default rendering of the "highlight" syntax. -Let's ==mark some text== for the sake of demonstration, with the following style definition: +Let's {=mark some text=} for the sake of demonstration, with the following style definition: ```yaml md-mark: @@ -116,7 +118,8 @@ Some packages, however, accept negative "before kern" values for specific use cases. See, for instance, the section devoted to footnote markers. -#### Note on units {.unnumbered} +{.unnumbered} +#### Note on units As a rule of thumb, the "kern" widths can include stretch and shrink values (e.g. `10pt plus 2pt minus 1pt`). Be aware, however, that diff --git a/examples/manual-styling/basics/concepts.md b/examples/manual-styling/basics/concepts.dj similarity index 98% rename from examples/manual-styling/basics/concepts.md rename to examples/manual-styling/basics/concepts.dj index 8c243ce..da6439f 100644 --- a/examples/manual-styling/basics/concepts.md +++ b/examples/manual-styling/basics/concepts.dj @@ -53,7 +53,8 @@ and different vertical skips here or there? The styling paradigm offers a powerful generic abstraction towards that goal. -### An opinionated note on alternatives {.unnumbered .notoc} +{.unnumbered .notoc} +### An opinionated note on alternatives If you ever used (La)TeX, one possible way is to provide "hooks" that the user can change. At places, SILE follows that approach too---either via commands that diff --git a/examples/manual-styling/basics/definitions.md b/examples/manual-styling/basics/definitions.dj similarity index 100% rename from examples/manual-styling/basics/definitions.md rename to examples/manual-styling/basics/definitions.dj diff --git a/examples/manual-styling/basics/lists.md b/examples/manual-styling/basics/lists.dj similarity index 100% rename from examples/manual-styling/basics/lists.md rename to examples/manual-styling/basics/lists.dj diff --git a/examples/manual-styling/basics/paragraph.md b/examples/manual-styling/basics/paragraph.dj similarity index 92% rename from examples/manual-styling/basics/paragraph.md rename to examples/manual-styling/basics/paragraph.dj index 19f961a..30746b9 100644 --- a/examples/manual-styling/basics/paragraph.md +++ b/examples/manual-styling/basics/paragraph.dj @@ -29,6 +29,7 @@ there will be applied. The specification additionnaly provides: - The alignment of the paragraph block (center, left, right or justify---the latter is the default but may be useful to overwrite an inherited alignment). - Rules applying before the paragraph block: + - The amount of vertical space before the content, as a variable length or a named skip (such as `bigskip`, `medskip`, `smallskip`). - Whether paragraph indentation is applied to the first paragraph (defaults @@ -36,7 +37,9 @@ there will be applied. The specification additionnaly provides: for section titles not to be indented. - Whether a page break may occur before the block (defaults to `true`). - - Rules applying after the paragraph block + + - Rules applying after the paragraph block + - The amount of vertical space after the content, as a variable length or a named skip (such as `bigskip`, `medskip`, `smallskip`). - Whether paragraph indentation is applied to the next paragraph after the @@ -51,7 +54,8 @@ there will be applied. The specification additionnaly provides: the first paragraph indentation after a section title. The French convention, however, is to always indent regular paragraphs, even after a section title. -::: {custom-style="admon"} +{custom-style="admon"} +::: This version of the specification does not provide any way to configure the margins (left and right text block indents), internal skips, and other low-level paragraph formatting options (paragraph indent, etc.)[^styles-par-margins] @@ -59,8 +63,8 @@ low-level paragraph formatting options (paragraph indent, etc.)[^styles-par-marg [^styles-par-margins]: This might be considered in a future revision, but note that it may also be addressed by defining extra alignment options. -The **resilient.book** class, for instance, defines its own `block` alignment option -(used in block quotes, see further); the **resilient.verbatim** packages defines and `obeylines` alignment, etc. +The *resilient.book* class, for instance, defines its own `block` alignment option +(used in block quotes, see further); the *resilient.verbatim* packages defines and `obeylines` alignment, etc. Please note that changing an existing character style into a paragraph style does not imply that the content is magically turned into paragraphs. @@ -68,12 +72,13 @@ When classes or packages expect a character style at some point, only that part of the style definition is used. Classes and packages are responsible for applying the paragraph part too, depending on context. -### Note on consecutive skips {.unnumbered} +{.unnumbered} +### Note on consecutive skips Consider a "block quote" paragraph style, where you would expect some vertical spaces both above and below a quotation---say, small skips---to make it more distinct from the surrounding text. -The **resilient.book** class, for instance, provides the following default +The *resilient.book* class, for instance, provides the following default style definition. ```yaml diff --git a/examples/manual-styling/basics/sectioning.md b/examples/manual-styling/basics/sectioning.dj similarity index 89% rename from examples/manual-styling/basics/sectioning.md rename to examples/manual-styling/basics/sectioning.dj index 32d9c70..f0846ae 100644 --- a/examples/manual-styling/basics/sectioning.md +++ b/examples/manual-styling/basics/sectioning.dj @@ -30,8 +30,7 @@ With these first assumptions in mind, let’s summarize the requirements: to page headers, and so on.—The list of possibilities could be long here and very dependent on the kind of structure one considers, and it would be boresome to invent a syntax covering all potential needs, so some sort of “hook” has at least to be provided (more on that later). -- The main numbering, when used, may need some text strings prepended or appended to it, - (e.g. "Chapter 1.") + - The main numbering, when used, may need some text strings prepended or appended to it (e.g. "Chapter 1."), - When added to page headers (or in similar contexts), as per the supporting class design, one may want the section number to appear or not, and to be possibly formatted in a different way than in the ToC or in the main text flow. @@ -68,15 +67,12 @@ inheritance mechanism provided by the styles also allows one to reuse existing base specifications. In this author’s opinion, it is quite flexible and clear. The two last options, however, may require a clarification. -The `numberstyle` specification defines which number style should be used for -the section number, depending on the context where it appears (main text flow, -running headers and cross-references).^[In this version, the -numbering in the table of contents is handled with a different mechanism, -as a part of the ToC styles. Whether there is a need to reconcile these -solutions might be considered in a future revision.] +The `numberstyle` specification defines which number style should be used for the section number, depending on the context where it appears (main text flow, running headers and cross-references).[^toc-numbering-incertain] Note that if a given context is absent, the section number will not be displayed. -This might be sufficient to disable inherited numbering in some contexts, but -in these cases, you can just leave the `main` number style present but empty. +This might be sufficient to disable inherited numbering in some contexts, but in these cases, you can just leave the `main` number style present but empty. + +[^toc-numbering-incertain]: In this version, the numbering in the table of contents is handled with a different mechanism, as a part of the ToC styles. +Whether there is a need to reconcile these solutions might be considered in a future revision. For the "main" number style, some sections may expect the number to be on its own standalone line rather than just before the section title.—Chapters and parts, diff --git a/examples/manual-styling/basics/toc.md b/examples/manual-styling/basics/toc.dj similarity index 100% rename from examples/manual-styling/basics/toc.md rename to examples/manual-styling/basics/toc.dj diff --git a/examples/resilient-ecosystem.dot b/examples/resilient-ecosystem.dot index 9bc24cb..5062de8 100644 --- a/examples/resilient-ecosystem.dot +++ b/examples/resilient-ecosystem.dot @@ -25,6 +25,11 @@ digraph omikhleia { textsubsuper [shape=component,style=filled,fillcolor=aliceblue] } + subgraph cluster_qrcode { + label = "qrcode.sile"; + + qrcode [shape=component,style=filled,fillcolor=mintcream] + } subgraph cluster_labelrefs { label = "labelrefs.sile"; @@ -40,10 +45,8 @@ digraph omikhleia { cbase [shape=component,style=filled,fillcolor=snow,label="resilient.base"] book [shape=component,style=filled,fillcolor=mintcream,label="resilient.book"] - resume [shape=component,style=filled,fillcolor=mintcream,label="resilient.resume"] book -> cbase - resume -> cbase } subgraph cluster_resilient_pkg { label = "packages"; @@ -56,41 +59,45 @@ digraph omikhleia { sectioning [shape=component,style=filled,fillcolor=seashell,label="resilient.sectioning"] styles [shape=component,style=filled,fillcolor=seashell,label="resilient.styles"] + bookmatters [shape=component,style=filled,fillcolor=seashell,label="resilient.bookmatters"] lists [shape=component,style=filled,fillcolor=aliceblue,label="resilient.lists"] poetry [shape=component,style=filled,fillcolor=mintcream,label="resilient.poetry"] epigraph [shape=component,style=filled,fillcolor=mintcream,label="resilient.epigraph"] abbr [shape=component,style=filled,fillcolor=mintcream,label="resilient.abbr"] + defn [shape=component,style=filled,fillcolor=mintcream,label="resilient.defn"] + verbatim [shape=component,style=filled,fillcolor=mintcream,label="resilient.verbatim"] + liners [shape=component,style=filled,fillcolor=mintcream,label="resilient.liners"] cbase -> styles pbase -> styles styles -> textsubsuper + bookmatters -> qrcode book -> tableofcontents book -> footnotes book -> headers book -> sectioning book -> labelrefs - book -> struts - - resume -> lists - resume -> headers - resume -> ptable - resume -> labelrefs + book -> lists epigraph -> pbase footnotes -> pbase lists -> pbase poetry -> pbase sectioning -> pbase - tableofcontents ->pbase + tableofcontents -> pbase + defn -> pbase + verbatim -> pbase + liners -> pbase } subgraph cluster_resilient_ins { label = "inputters"; - silm [shape=component,style=filled,fillcolor=lemonchiffon,label="inputters.silm"] + silm [shape=component,style=filled,fillcolor=lemonchiffon,label="silm"] silm -> book [style=dashed] + silm -> bookmatters } } @@ -104,9 +111,9 @@ digraph omikhleia { subgraph cluster_markdown { label = "markdown.sile"; - markdown [shape=component,style=filled,fillcolor=aliceblue] - djot [shape=component,style=filled,fillcolor=mintcream] - pandocast [shape=component,style=filled,fillcolor=mintcream] + markdown [shape=component,style=filled,fillcolor=lemonchiffon] + djot [shape=component,style=filled,fillcolor=lemonchiffon] + pandocast [shape=component,style=filled,fillcolor=lemonchiffon] markcmd [shape=component,style=filled,fillcolor=aliceblue,label="markdown.commands"] markdown -> markcmd @@ -114,17 +121,12 @@ digraph omikhleia { pandocast -> markcmd book -> markdown + book -> djot markcmd -> ptable markcmd -> embedders markcmd -> smartquotes } - subgraph cluster_printoptions { - label = "printoptions.sile"; - - printoptions [shape=component,style=filled,fillcolor=mintcream] - } - subgraph cluster_fancytoc { label = "fancytoc.sile"; @@ -145,9 +147,10 @@ digraph omikhleia { barcodes [shape=component,style=filled,fillcolor=mintcream,label="barcodes.ean13"] } - subgraph cluster_qrcode { - label = "qrcode.sile"; +subgraph cluster_printoptions { + label = "printoptions.sile"; - qrcode [shape=component,style=filled,fillcolor=mintcream] + printoptions [shape=component,style=filled,fillcolor=mintcream] + silm -> barcodes } } diff --git a/examples/sile-resilient-manual-styles.yml b/examples/sile-resilient-manual-styles.yml index bf98f72..de77b5f 100644 --- a/examples/sile-resilient-manual-styles.yml +++ b/examples/sile-resilient-manual-styles.yml @@ -147,6 +147,14 @@ defn-desc: before: vbreak: false +defn-desc-Simple: + inherit: "defn-desc" + style: + font: + weight: + paragraph: + align: "noparindent" + defn-term: inherit: "defn-base" origin: "resilient.defn" @@ -159,6 +167,14 @@ defn-term: before: skip: "smallskip" +defn-term-Simple: + inherit: "defn-term" + style: + font: + weight: + paragraph: + align: "noparindent" + dropcap: origin: "resilient.book" style: @@ -717,8 +733,6 @@ sectioning-appendix-main-number: origin: "resilient.book" style: numbering: - before: - text: "Appendix " display: "ALPHA" sectioning-appendix-ref-number: diff --git a/examples/sile-resilient-manual.silm b/examples/sile-resilient-manual.silm index ea1c253..7478305 100644 --- a/examples/sile-resilient-manual.silm +++ b/examples/sile-resilient-manual.silm @@ -9,7 +9,7 @@ metadata: - book authors: Didier Willis publisher: Omikhleia - pubdate: 2025-01-15 + pubdate: 2025-01-31 url: https://github.com/Omikhleia/resilient.sile copyright: © 2021–2025, Didier Willis. legal: | @@ -43,16 +43,23 @@ sile: packages: - autodoc-resilient # REQUIRED FOR RESILIENT, do not use regular autodoc - lorem +bibliography: + style: chicago-author-date + language: en-US + files: + - typography.bib content: frontmatter: parts: - content: - - manual-front.sil + - manual-front.dj mainmatter: parts: - file: manual-parts/part-intro.dj content: + - manual-intro/goals.dj - manual-intro/howto.dj + - manual-intro/installation.dj - file: manual-parts/part-masterdoc.dj content: - manual-masterdoc/masterdoc.dj @@ -61,29 +68,38 @@ content: - manual-masterdoc/bibliographies.dj - file: manual-parts/part-layouts.dj content: - - manual-layouts/layouts.sil + - manual-layouts/layouts-general.dj + - manual-layouts/layouts-predefined.dj - file: manual-parts/part-styling.dj content: - - manual-styling/basics/concepts.md - - manual-styling/basics/definitions.md - - manual-styling/basics/character.md - - manual-styling/basics/lists.md - - manual-styling/basics/paragraph.md - - manual-styling/basics/toc.md - - manual-styling/basics/sectioning.md - - manual-styling/advanced/intro.md - - manual-styling/advanced/folio.md - - manual-styling/advanced/footnotes.md - - manual-styling/advanced/toclevels.md - - manual-styling/advanced/liststyles.md - - manual-styling/advanced/eqno.md - - manual-styling/advanced/dropcap.md - - manual-styling/advanced/other.md - # unfinished - # - manual-styling/captioned.md - - file: manual-parts/part-packages.dj - content: - - manual-packages/packages.sil + - manual-styling/basics/concepts.dj + - manual-styling/basics/definitions.dj + - manual-styling/basics/character.dj + - manual-styling/basics/lists.dj + - manual-styling/basics/paragraph.dj + - manual-styling/basics/toc.dj + - manual-styling/basics/sectioning.dj + - manual-styling/advanced/intro.dj + - manual-styling/advanced/folio.dj + - manual-styling/advanced/footnotes.dj + - manual-styling/advanced/toclevels.dj + - manual-styling/advanced/liststyles.dj + - manual-styling/advanced/eqno.dj + - manual-styling/advanced/dropcap.dj + - manual-styling/advanced/other.dj + # Not written yet... + # - manual-styling/advanced/captioned.dj - file: manual-parts/part-classes.dj content: - - manual-classes/classes.sil + - manual-classes/audience.dj + - manual-classes/book.dj + - file: manual-parts/part-packages.dj + content: + - manual-packages/audience.dj + - manual-packages/packages.dj + backmatter: + parts: + - file: manual-parts/part-appendices.dj + appendices: + - manual-appendices/biblio.dj + - manual-appendices/resume-class.dj diff --git a/examples/typography.bib b/examples/typography.bib new file mode 100644 index 0000000..9a0d261 --- /dev/null +++ b/examples/typography.bib @@ -0,0 +1,125 @@ +-- Major books on typography + +@book{bringhurst2002, + title = {The Elements of Typographic Style}, + author = {Bringhurst, Robert}, + date = {2012}, + edition = {4}, + publisher = {Hartley & Marks Publishers}, + isbn = {978-0881792119}, +} + +@book{bringhurst2023, + title = {Principes élémentaires de la typographie. Une histoire des styles}, + author = {Bringhurst, Robert}, + translator = {Chambon, Perrine and Kopylov, Marc and Lebastard, Jeanne}, + date = {2023}, + publisher = {Éditions B42}, + isbn = {978-2490077656}, +} + +@book{lacroux2011, + title = {Orthotypographie. Orthographe & Typographie françaises, dictionnaire raisonné}, + author = {Lacroux, Jean-Pierre}, + date = {2007}, + volumes = {2}, + url = {http://www.orthotypographie.fr/}, +} + +@book{tschichold1975, + title = {Ausgewählte Aufsätze über Fragen der Gestalt des Buches und der Typographie}, + author = {Tschichold, Jan}, + origdate = {1975}, + date = {1987}, + publisher = {Birkhäuser-Verlag}, + isbn = {978-3034878005}, +} + +@book{tschichold1991, + title = {The Form of the Book: Essays on the Morality of Good Design}, + author = {Tschichold, Jan}, + date = {1991}, + publisher = {Hartley & Marks}, + isbn = {978-0881791167} +} + +@book{tschichold1994, + title = {Livre et typographie: Essais choisis}, + author = {Tschichold, Jan}, + origdate = {1994}, + date = {2018}, + publisher = {Éditions Allia}, + isbn = {979-1030408577}, +} + +@book{hochuli2015, + title = {Le détail en typographie. La lettre, l’interlettrage, le mot, l’espacement, la ligne, l’interlignage, la colonne}, + author = {Hochuli, Jost}, + translator = {Guégan, Victor and Malherbet, Pierre}, + date = {2015}, + publisher = {Éditions B42}, + isbn = {978-2917855577}, +} + +-- Minor books and articles on typography or digital typesetting + +@book{duplan1986, + title = {Maquette et mise en page}, + author = {Duplan, Pierre and Jauneau, Roger}, + date = {1986}, + publisher = {Éditions du Moniteur}, + isbn = {978-2281310511}, +} + +@article{kohm2003, + title = {Étude comparative de différents modèles d’empagement}, + author = {Kohm, Markus}, + journal = {Cahiers GUTenberg}, + volume = {42}, + date = {2003}, + pages = {4-25}, + url = {http://www.numdam.org/item/CG_2003___42_4_0.pdf}, +} + +@article{hurtig:empagement, + title = {Méthodes d’empagement: Les tracés régulateurs}, + author = {Hurtig, Alain}, + url = {http://www.alain.les-hurtig.org/varia/empagement.html}, +} + +-- SILE-related publications + +@book{cozens:sile, + title = {The SILE Book}, + author = {Cozens, Simon and Maclennan, Caleb and Nicole, Olivier and Willis, Didier}, + origdate = {2014}, + date = {2024}, + url = {https://sile-typesetter.org/}, +} + +@book{willis:sile-resilient, + title = {The re·sil·ient collection of classes & packages for SILE: User Guide}, + author = {Willis, Didier}, + year = {2021–}, + date = {2025}, + origdate = {2021}, + url = {https://www.calameo.com/books/0073493380301d2d84340}, +} + +@book{willis:sile-markdown-djot, + title = {Markdown and Djot to PDF with SILE: Ultimate Guide & Showcase Document}, + author = {Willis, Didier}, + date = {2025}, + origdate = {2022}, + url = {https://www.calameo.com/books/007349338f6a46a6b6fb5}, +} + +@book{willis:sile-maths, + title = {SILE and the Hydra of Maths. Showcase & Critical Assessment 2024}, + author = {Willis, Didier}, + date = {2024}, + publisher = {Omikhleia}, + url = {https://drive.google.com/file/d/1kGHIHUU9dsAsMBrGYotPUO0XyDLwD-CF}, +} + +-- EOF diff --git a/packages/resilient/styles/init.lua b/packages/resilient/styles/init.lua index 7e8ce5d..d387acd 100644 --- a/packages/resilient/styles/init.lua +++ b/packages/resilient/styles/init.lua @@ -265,10 +265,36 @@ function package.freezeStyles (_) SU.debug("resilient.styles", "Freezing styles") end +-- FIXME refactor these two functions +-- It works, but it's messy and we could certainly handle it when resolving the style +-- and applyng inheritance, rather at the last moment. +local function propertyValueIfNotNull (prop) + if tostring(prop) == "yaml.null" then + -- Don't crash on null values (a special table with tinyyaml). + -- And be friendly with them (they cancel style inheritance). + return nil + end + if type(prop) == "table" then + SU.error("Unexpected table value for property") + end + return prop +end +local function shallowNonNullOptions (options) + -- When passing options to SILE commands, we want to avoid passing null + -- values from YAML style files. + local copy = {} + for k, v in pairs(options) do + if propertyValueIfNotNull(v) then + copy[k] = v + end + end + return copy +end + function package:registerCommands () self:registerCommand("style:font", function (options, content) local size = tonumber(options.size) - local opts = pl.tablex.copy(options) -- shallow copy + local opts = shallowNonNullOptions(options) if size then SU.warn("Attempt using a font style with old relative font size '"..options.size..[[' This feature will be deprecated when the new styling paradigm is completed. @@ -279,17 +305,6 @@ function package:registerCommands () SILE.call("font", opts, content) end, "Applies a font, with additional support for relative sizes.") - local function propertyValueIfNotNull (prop) - if tostring(prop) == "yaml.null" then - -- Don't crash on null values (a special table with tinyyaml). - -- And be friendly with them (they cancel style inheritance). - return nil - end - if type(prop) == "table" then - SU.error("Unexpected table value for property") - end - return prop - end -- Very naive cascading... local function characterStyle (style, content, options) options = options or {} @@ -312,16 +327,18 @@ function package:registerCommands () end end if style.decoration then - if style.decoration.line then - local lineCommand = SILE.scratch.styles.decorations[style.decoration.line] + local lineValue = propertyValueIfNotNull(style.decoration.line) + if lineValue then + local lineCommand = SILE.scratch.styles.decorations[lineValue] if not lineCommand then - SU.error("Invalid style decoration line '"..style.decoration.line.."'") + SU.error("Invalid style decoration line '" .. lineValue .. "'") end - content = createCommand(lineCommand, style.decoration, content) + content = createCommand(lineCommand, shallowNonNullOptions(style.decoration), content) end end - if style.color then - content = createCommand("color", { color = style.color }, content) + local colorValue = propertyValueIfNotNull(style.color) + if colorValue then + content = createCommand("color", { color = colorValue }, content) end if style.font and SU.boolean(options.font, true) then content = createCommand("style:font", style.font, content) @@ -360,7 +377,7 @@ function package:registerCommands () end local styleForAlignment = function (style, content, breakafter) - if style.paragraph and style.paragraph.align then + if style.paragraph and style.paragraph.align then -- FIXME: Code smell, re-tested below if style.paragraph.align then local alignCommand = SILE.scratch.styles.alignments[style.paragraph.align] if not alignCommand then @@ -484,7 +501,7 @@ function package:registerCommands () vglue = cloneStyleSkip(vglue, name) -- Not sure here whether it should be an explicit glue or not, -- but it seems so to me... - SILE.typesetter:pushExplicitVglue(vglue) + SILE.typesetter:pushVglue(vglue) end if novbreak then SILE.call("novbreak") end end diff --git a/rockspecs/resilient.sile-2.7.0-1.rockspec b/rockspecs/resilient.sile-2.7.0-1.rockspec index be1f0fc..4f8d55a 100644 --- a/rockspecs/resilient.sile-2.7.0-1.rockspec +++ b/rockspecs/resilient.sile-2.7.0-1.rockspec @@ -23,10 +23,10 @@ dependencies = { "labelrefs.sile >= 0.1.0", "printoptions.sile >= 1.2.0", "piecharts.sile >= 0.3.0", - "ptable.sile >= 3.1.0", + "ptable.sile >= 3.1.1", "qrcode.sile >= 1.1.0", "textsubsuper.sile >= 1.2.0", - "markdown.sile >= 2.3.1", + "markdown.sile >= 2.3.2", "silex.sile >= 0.8.0, < 1.0", } build = {