Merge 1722ea8 into d9db529

documentation/c02-gettingstarted.sil

@@ -310,7 +310,7 @@ You can use \code{--output -} to write the output directly to the system IO stre
 
 In \url{https://sile-typesetter.org/examples/docbook.xml}, you will find a typical DocBook 5.0 article.
 Normally turning DocBook to print involves a complicated dance of XSLT processors, format object processors, and/or strange LaTeX packages.
-But SILE can read XML files directly, and comes with a \code{docbook} class, which tells SILE how to render (admittedly, a subset of) the DocBook tags onto a page.
+But SILE can read XML files directly, and comes with a \autodoc:class{docbook} class, which tells SILE how to render (admittedly, a subset of) the DocBook tags onto a page.
 
 Hence, turning \code{docbook.xml} into \code{docbook.pdf} is as simple as:
 
@@ -322,9 +322,9 @@ Loading docbook
 \end{terminal}
 
 The \code{-c} flag sets the default class, a necessary step because DocBook XML files do not come wrapped in a tag that specifies a SILE class.
-The \code{docbook} class will provide the commands necessary to process the tags typically found in DocBook files.
+The \autodoc:class{docbook} class will provide the commands necessary to process the tags typically found in DocBook files.
 
-In Chapter 9, we’ll look at how the \code{docbook} class works, and how you can define processing expectations for other XML formats.
+In Chapter 9, we’ll look at how the \autodoc:class{docbook} class works, and how you can define processing expectations for other XML formats.
 
 \section{Running SILE remotely as a CI job}
 

documentation/c03-input.sil

@@ -142,7 +142,7 @@ So if you type \code{affluent fishing}, then, depending on your font, your outpu
     ‘\autodoc:example{affluent fishing}’.
 If you specifically want to break up the ligatures, insert empty groups (using the grouping characters \code{\{} and \code{\}}) in the middle of the possible ligatures:
     \code{af\{\}f\{\}luent f\{\}ishing}: ‘\autodoc:example{af{}f{}luent f{}ishing}’.
-See the section on the \code{features} package for more information on how to control the display of ligatures and other font features.
+See the section on the \autodoc:package{features} package for more information on how to control the display of ligatures and other font features.
 
 \section{Commands}
 

documentation/c04-useful.sil

@@ -83,7 +83,7 @@ The full list of attributes to the \autodoc:command{\font} command are:
 
 It’s quite fiddly to be always changing font specifications manually;
     later we’ll see some ways to automate the process.
-SILE’s \code{plain} class notably provides the \autodoc:command{\em{…}} command as a shortcut for \autodoc:command{\font[style=italic]{…}}, and the \autodoc:command{\strong{…}} command as a a shortcut for \autodoc:command{\font[weight=700]{…}}.
+SILE’s \autodoc:class{plain} class notably provides the \autodoc:command{\em{…}} command as a shortcut for \autodoc:command{\font[style=italic]{…}}, and the \autodoc:command{\strong{…}} command as a a shortcut for \autodoc:command{\font[weight=700]{…}}.
 
 Note for parameters that accept multiple values, values may be separated with commas.
 Be sure to wrap the value in quotes so the commas don't get parsed as new parameters.
@@ -94,22 +94,22 @@ For example \autodoc:command{\font[variations="wght=150,wdth=122"]} can be used
 \section{Document structure}
 
 SILE provides a number of different \em{class}es of document (similar to LaTeX classes).
-By default, you get the \code{plain} class, which has very little support for structured documents.
-There is also the \code{book} class, which adds support for right and left page masters, running headers, footnotes, and chapter, section and subsection headings.
+By default, you get the \autodoc:class{plain} class, which has very little support for structured documents.
+There is also the \autodoc:class{book} class, which adds support for right and left page masters, running headers, footnotes, and chapter, section and subsection headings.
 
-To use the commands in this section, you will need to request the \code{book} class by specifying, in your \code{\\begin\{document\}} command, the \autodoc:parameter{class=book} parameter;
+To use the commands in this section, you will need to request the \autodoc:class{book} class by specifying, in your \code{\\begin\{document\}} command, the \autodoc:parameter{class=book} parameter;
     for example, the document you are currently reading begins with the command \code{\\begin[class=book]\{document\}}.
 
 \subsection{Chapters and sections}
 
-If you choose the book class, you can divide your document into different sections using the commands \autodoc:command{\chapter{…}}, \autodoc:command{\section{…}}, and \autodoc:command{\subsection{…}}.
+If you choose the \autodoc:class{book} class, you can divide your document into different sections using the commands \autodoc:command{\chapter{…}}, \autodoc:command{\section{…}}, and \autodoc:command{\subsection{…}}.
 The argument to each command is the name of the chapter or section, respectively.
 Chapters will be opened on a new right-hand page, and the chapter name will form the left running header.
 Additionally, the section name and number will form the right running header.
 
 \begin{autodoc:note}
 Chapters, sections and subsections will be automatically numbered starting from 1.
-To alter the numbering, see the documentation for the \code{counters} package in the next chapter.
+To alter the numbering, see the documentation for the \autodoc:package{counters} package in the next chapter.
 To produce an unnumbered chapter, provide the parameter \autodoc:parameter{numbering=false}.
 \end{autodoc:note}
 
@@ -122,7 +122,7 @@ Footnotes can be added to a book with the \autodoc:command{\footnote{…}} comma
 The argument to the command will be set as a footnote at the bottom of the page.
 Footnotes are automatically numbered from 1 at the start of each chapter.
 
-\section{Indentation and spacing}
+\section{Paragraph indentation}
 
 Paragraphs in SILE normally begin with an indentation (by default, 20 points in width).
 To turn this off, you can use the \autodoc:command{\noindent} command at the start of a paragraph.
@@ -131,16 +131,40 @@ A \autodoc:command{\noindent} can be cancelled by following it with an \autodoc:
 You can completely turn off indentation for the whole of the document by changing its size to zero.
 We’ll see how to change the size of the indentation in the settings chapter, but the easiest way to set it to zero for the whole of the document (rather than for just one paragraph) is to issue the command \autodoc:command{\neverindent}.
 
-To increase the vertical space between paragraphs or other elements, the commands \autodoc:command{\smallskip}, \autodoc:command{\medskip} and \autodoc:command{\bigskip} are available to add a 3pt, 6pt, and 12pt gap, respectively.
-There will be a \autodoc:command{\bigskip} after this paragraph.
+\section{Horizontal spacing}
 
-\bigskip%
 There are also commands to increase the horizontal space in a line;
-    from the smallest to the largest, \autodoc:command{\thinspace} (1/6th of an em), \autodoc:command{\enspace} (1 en), \autodoc:command{\quad} (1 em), and \autodoc:command{\quad} (2em).
+    from the smallest to the largest, \autodoc:command{\thinspace} (1/6th of an em), \autodoc:command{\enspace} (1 en), \autodoc:command{\quad} (1 em), and \autodoc:command{\qquad} (2em).
 
 If you want to add a very long stretchy space, you can use the command \autodoc:command{\hfill}.
 Doing this in conjunction with a line break will cause the line before the break to be flush left, like this.\cr{}The command \autodoc:command{\cr} is a shortcut for \autodoc:command{\hfill\break}.
 
+\section{Vertical spacing}
+
+To increase the vertical space between paragraphs or other elements, the commands \autodoc:command{\smallskip}, \autodoc:command{\medskip} and \autodoc:command{\bigskip} are available to add a 3pt, 6pt, and 12pt gap, respectively.
+There will be a \autodoc:command{\bigskip} after this paragraph.
+
+\bigskip%
+Besides this predefined skips, you can also use \autodoc:command{\skip[height=<dimension>]} to add a vertical space of a given height.
+
+If you want to add a very long stretchy vertical space, you can use the command \autodoc:command{\vfill}.
+
+When playing with vertical spaces, there is however a few additional considerations to take into account.
+Without entering into the details, they are usually ignored at the beginning of a frame.
+Would you want to enforce them there, you therefore need to have some initial content.
+An empty \autodoc:command{\hbox} can do the trick.
+Additionally, there are cases where SILE automaticall inserts a \autodoc:command{\vfill} command at the end of a frame, so you may need to ensure you terminated a paragraph and introduced your own frame break in order to avoid it.
+The following example illustrates both techniques.
+
+\begin[type=autodoc:codeblock]{raw}
+\hbox{}% This is an empty initial line
+\skip[height=2cm]
+A paragraph around 2 centimeters below the top of the frame.
+\vfill
+A paragraph pushed at the bottom of the frame.\par
+\break
+\end{raw}
+
 \section{Text alignment}
 
 \begin{raggedright}
@@ -168,7 +192,7 @@ This paragraph is centered on the page.
 
 SILE automatically determines line and page breaks.
 In later chapters we will introduce some \em{settings} which can be used to tweak this process.
-However, SILE’s \code{plain} class also provides some commands to help the process on its way.
+However, SILE’s \autodoc:class{plain} class also provides some commands to help the process on its way.
 
 The following four commands can be used to control line breaks (when used \em{within} a paragraph), as well as page breaks (when used \em{between} paragraphs):%
 \footnote{The names are similar to those used in (La)TeX, but their semantics differ slightly.}

documentation/c06-macroscommands.sil

@@ -25,7 +25,7 @@ To typeset
 this logo, we need to ask \SILE to: typeset an ‘S’; typeset an ‘I’ lowered by
 a certain amount (half an ex, as it happens); typeset an ‘L’; walk backwards
 along the line a tiny bit; typeset a smaller-sized ‘E’ raised by a certain
-amount, using the \code{features} package to choose a small capital ‘E’.
+amount, using the \autodoc:package{features} package to choose a small capital ‘E’.
 
 In \SILE code, that looks like:
 
@@ -65,7 +65,7 @@ L%
 \end{raw}
 
 We are using the built-in SILE command \autodoc:command{\define}.
-\autodoc:command{\define} takes an option called \code{command};
+\autodoc:command{\define} takes an option called \autodoc:parameter{command};
 its value is the name of the command we are defining.
 The content of the \autodoc:command{\define} command is a series of SILE instructions to be executed when the command is used.
 
@@ -92,7 +92,7 @@ of any text up until the nearest comma, semicolon, or closing square bracket.
 
 Now let’s move on to the next level. Sometimes you will want to create
 commands which are not simply replacements, but which have arguments of their
-own. As an example, let’s say we use the \code{color} package to turn a bit of
+own. As an example, let’s say we use the \autodoc:package{color} package to turn a bit of
 text red \color[color=red]{like this}. The usual way to do that is to say
 
 \begin[type=autodoc:codeblock]{raw}

documentation/c07-settings.sil

@@ -254,7 +254,7 @@ Now we can finally complete our implementation of centering:
 \set[parameter=typesetter.parfillskip,value=0pt]
 
 And this is (more or less) how the \autodoc:environment{center} environment is defined in
-the \code{plain} class: we make the margins able to expand but the spaces not able
+the \autodoc:class{plain} class: we make the margins able to expand but the spaces not able
 to expand; we turn off indenting at the start of the paragraph, and we turn
 off the filling glue at the end of the paragraph.
 \par

documentation/c08-language.sil

@@ -70,7 +70,7 @@ direction joined by a hyphen.
 
 Each frame has its own writing direction. By default, this is \code{LTR-TTB}.
 Normally you would set the writing direction once, in the master frames of
-your document class. One easy way to do this in the \code{plain} document
+your document class. One easy way to do this in the \autodoc:class{plain} document
 class is to pass the \autodoc:parameter{direction} parameter to the
 \code{\\begin\{document\}} command. For example, Mongolian is written top
 to bottom with text lines moving from the left to the right of the page,
@@ -116,7 +116,7 @@ are available; if not, work through the resources at
 \section{Localization}
 
 A small handful of strings may be programatically added to documents depending on language, context, and options.
-For example by default in English the \code{book} class will prepend “Chapter ” before chapter numbers output by the \autodoc:command{\chapter} command.
+For example by default in English the \autodoc:class{book} class will prepend “Chapter ” before chapter numbers output by the \autodoc:command{\chapter} command.
 These localized strings are managed internally using the Fluent localization system.%
 \footnote{See Project Fluent (\url{https://projectfluent.org}) for details on the data format and uses.}
 Some default localizations are provided for a handful of languages, but it is quite likely SILE will not (yet) have your language.
@@ -202,8 +202,8 @@ correct space. The size of these spaces is determined by
 
 SILE aims to conform with the W3G document “Requirements for Japanese Text Layout”\footnote{\url{https://www.w3.org/TR/jlreq/}} which describes the typographic conventions for Japanese (and also Chinese) text.
 Breaking rules \em{(kinzoku shori)} and intercharacter spacing is fully supported on selecting the Japanese language.
-The easiest way to set up the other elements of Japanese typesetting such as the \em{hanmen} grid and optional vertical typesetting support is by using the \code{jplain} or \code{jbook} classes.
-For other languages with similar layout requirements, more generic \code{tplain} and \code{tbook} classes are available that setup the layout elements without also setting the default language and font to Japanese specific values.
+The easiest way to set up the other elements of Japanese typesetting such as the \em{hanmen} grid and optional vertical typesetting support is by using the \autodoc:class{jplain} or \autodoc:class{jbook} classes.
+For other languages with similar layout requirements, more generic \autodoc:class{tplain} and \autodoc:class{tbook} classes are available that setup the layout elements without also setting the default language and font to Japanese specific values.
 These are also good condidates to use as base classes and extend for more language-specific classes.
 
 \package-documentation{hanmenkyoshi}