From e70fa509673c32977a1e1f0545373229198c8aa8 Mon Sep 17 00:00:00 2001 From: Omikhleia Date: Sat, 27 May 2023 18:50:19 +0200 Subject: [PATCH 1/6] feat(packages): Add document class styling in autodoc --- packages/autodoc/init.lua | 30 ++++++++++++++++++++++++------ 1 file changed, 24 insertions(+), 6 deletions(-) diff --git a/packages/autodoc/init.lua b/packages/autodoc/init.lua index afbd501e5..1d722e5ad 100644 --- a/packages/autodoc/init.lua +++ b/packages/autodoc/init.lua @@ -13,7 +13,8 @@ local theme = { setting = "#42280e", -- some kind of dark brown bracketed = "#656565", -- some grey package = "#172557", -- saturated space blue - note = "#525257" -- some asphalt grey hue + note = "#525257", -- some asphalt grey hue + class = "#6a2c54" -- some dark shaded magenta } local colorWrapper = function (ctype, content) @@ -170,6 +171,12 @@ function package:registerCommands () end) end) + self:registerCommand("autodoc:class:style", function (_, content) + SILE.call("font", { weight = 700 }, function() + colorWrapper("class", content) + end) + end) + self:registerCommand("autodoc:code:style", function (options, content) -- options.type is used to distinguish the type of code element and style -- it accordingly: "ast", "setting", "environment" shall select the font @@ -293,7 +300,19 @@ function package:registerCommands () -- We cannot really check package name to exist! SILE.call("autodoc:package:style", {}, { name }) - end, "Outputs a package name in code, checking its validity.") + end, "Outputs a package name.") + + -- Documenting a class name + + self:registerCommand("autodoc:class", function (_, content) + if type(content) ~= "table" then SU.error("Expected a table content") end + if #content ~= 1 then SU.error("Expected a single element") end + local name = type(content[1] == "string") and content[1] + if not name then SU.error("Unexpected class name") end + -- We cannot really check class name to exist! + + SILE.call("autodoc:class:style", {}, { name }) + end, "Outputs a class name.") -- Homogenizing the appearance of blocks of code @@ -409,13 +428,12 @@ The \autodoc:command{\autodoc:parameter} commands takes either a parameter name, The \autodoc:environment{autodoc:codeblock} environment allows typesetting a block of code in a consistent way. This is not a true verbatim environment, and you still have to escape SILE’s special characters within it (unless calling commands is what you really intend doing there, obviously). -For convenience, the package also provides a \code{raw} handler going by the same name, where you do not -have to escape the special characters (backslashes, braces, percents). +For convenience, the package also provides a \code{raw} handler going by the same name, where you do not have to escape the special characters (backslashes, braces, percents). -The \autodoc:command{\autodoc:example} marks its content as an example, possibly typeset in a different choice -of font. +The \autodoc:command{\autodoc:example} marks its content as an example, possibly typeset in a different choice of font. The \autodoc:command{\autodoc:note} outputs its content as a note, in a dedicated framed and indented block. +The \autodoc:command{\autodoc:package} and \autodoc:command{\autodoc:class} commands are used to format a package and class name. \end{document} ]] From 26ee26087b5db634607bf471775baf261562c3bf Mon Sep 17 00:00:00 2001 From: Omikhleia Date: Sat, 27 May 2023 18:53:28 +0200 Subject: [PATCH 2/6] docs(manual,packages): Use autodoc for consistent document class name styling That is, use `\autodoc:class`. Also some `\autodoc:package` were missing (and one had a typo). --- documentation/c02-gettingstarted.sil | 6 +++--- documentation/c03-input.sil | 2 +- documentation/c04-useful.sil | 14 +++++++------- documentation/c06-macroscommands.sil | 6 +++--- documentation/c07-settings.sil | 2 +- documentation/c08-language.sil | 8 ++++---- documentation/c09-concepts.sil | 8 ++++---- documentation/c10-classdesign.sil | 24 ++++++++++++------------ documentation/c11-xmlproc.sil | 6 +++--- documentation/c12-tricks.sil | 6 +++--- packages/folio/init.lua | 2 +- packages/specimen/init.lua | 2 +- 12 files changed, 43 insertions(+), 43 deletions(-) diff --git a/documentation/c02-gettingstarted.sil b/documentation/c02-gettingstarted.sil index b3b627ed3..e1a210fe6 100644 --- a/documentation/c02-gettingstarted.sil +++ b/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} diff --git a/documentation/c03-input.sil b/documentation/c03-input.sil index a1332e808..051635cb4 100644 --- a/documentation/c03-input.sil +++ b/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} diff --git a/documentation/c04-useful.sil b/documentation/c04-useful.sil index 16c18409a..e81c9aced 100644 --- a/documentation/c04-useful.sil +++ b/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} @@ -168,7 +168,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.} diff --git a/documentation/c06-macroscommands.sil b/documentation/c06-macroscommands.sil index 879372b4d..7b1840612 100644 --- a/documentation/c06-macroscommands.sil +++ b/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} diff --git a/documentation/c07-settings.sil b/documentation/c07-settings.sil index 0154f9c06..f38579b11 100644 --- a/documentation/c07-settings.sil +++ b/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 diff --git a/documentation/c08-language.sil b/documentation/c08-language.sil index ebbb74fb7..35044ae60 100644 --- a/documentation/c08-language.sil +++ b/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} diff --git a/documentation/c09-concepts.sil b/documentation/c09-concepts.sil index 94e102843..2fc07200b 100644 --- a/documentation/c09-concepts.sil +++ b/documentation/c09-concepts.sil @@ -196,7 +196,7 @@ SILE.typesetter:pushVglue({ height = l }) Adding boxes yourself is a little more complicated, because boxes need to know how to display themselves on the page. To facilitate this, they normally store a \code{value} and an \code{outputYourself} member function. For instance, -the \code{image} package does something very simple: it adds a horizontal +the \autodoc:package{image} package does something very simple: it adds a horizontal box to the node queue which knows the width and height of the image, the source, and instructions to the output engine to display the image: @@ -240,9 +240,9 @@ where the frames should be physically placed on the page. Here is how we will go about it. We need to start with a page break, because SILE will not appreciate you changing the page layout after it’s started to determine how to put text onto that page.\footnote{You can use -the \code{frametricks} package to get around this limitation—split the current +the \autodoc:package{frametricks} package to get around this limitation—split the current frame and start fiddling around with the positions of the new frames that -\code{frametricks} created for you.} How do we get to the start of a new +\autodoc:package{frametricks} created for you.} How do we get to the start of a new page? Remember that the \autodoc:command{\eject} (another word for \autodoc:command{\break} in vertical mode) only adds a penalty to the end of the output queue; page breaking is triggered when we leave horizontal mode, and the way to do that is \autodoc:command{\par}. @@ -285,7 +285,7 @@ except with three additional features: \end{itemize} \end{autodoc:note} -Next we declare the left and right column frames. The \code{book} class +Next we declare the left and right column frames. The \autodoc:class{book} class gives us some frames already, one of which, \code{content}, defines a typeblock with a decent size and positioning on the page. We will use the boundaries of this frame to declare our columns: the left diff --git a/documentation/c10-classdesign.sil b/documentation/c10-classdesign.sil index 8f3800ce6..6038fdf11 100644 --- a/documentation/c10-classdesign.sil +++ b/documentation/c10-classdesign.sil @@ -218,8 +218,8 @@ Document classes live somewhere in the \code{classes/} subdirectory of either wh \subsection{Implementing a bare class} -A minimum working class inherits from the \strong{base} class. -Most of the time, however, you will prefer inheriting at least from the \strong{plain} class, which already provides a lot of things users will expect, including most of the basic commands presented early in this manual. +A minimum working class inherits from the \autodoc:class{base} class. +Most of the time, however, you will prefer inheriting at least from the \autodoc:class{plain} class, which already provides a lot of things users will expect, including most of the basic commands presented early in this manual. Let’s assume this is the case, and simply create a file \code{classes/myclass.lua} with the following content. \begin[type=autodoc:codeblock]{raw} @@ -292,7 +292,7 @@ replicates the layout of the Hartley & Marks edition of Robert Bringhurst’s \em{The Elements of Typographical Style}. We are designing a book-like class, and so we will inherit from SILE’s -standard \strong{book} class found in \code{classes/book.lua}. +standard \autodoc:class{book} class found in \code{classes/book.lua}. Let’s briefly have a look at \code{book.lua} to see how it works.\footnote{% Note that the official SILE classes have some extra tooling to handle legacy class models trying to inherit from them. You don’t need those deprecation shims in your own classes when following these examples.} @@ -335,9 +335,9 @@ Initially the height of the footnotes is zero (and so the typeblock takes up the its bottom is fixed and therefore its top will be adjusted, and the bottom of the main typeblock frame will also be correspondingly adjusted. The folio frame (which holds the page number) lives below the footnotes, and the running headers live above the \code{content} frame. -Normally, as in the \strong{plain} class and anything inheriting from it, +Normally, as in the \autodoc:class{plain} class and anything inheriting from it, this would be enough to populate the pages’ frameset. -Instead the \code{book} class includes its own extension to the class with a callback \code{_init()} function which loads the \code{masters} package and generates a master frameset using the default frameset defined above. +Instead the \autodoc:class{book} class includes its own extension to the class with a callback \code{_init()} function which loads the \autodoc:package{masters} package and generates a master frameset using the default frameset defined above. \begin[type=autodoc:codeblock]{raw} function book:_init (options) @@ -353,14 +353,14 @@ function book:_init (options) end \end{raw} -Next, we use the \code{twoside} package to mirror our right-page master into a left-page master: +Next, we use the \autodoc:package{twoside} package to mirror our right-page master into a left-page master: \begin[type=autodoc:codeblock]{raw} self:loadPackage("twoside", { oddPageMaster = "right", evenPageMaster = "left" }) self:mirrorMaster("right", "left") \end{raw} -The \strong{book} class also loads the table of contents package which sets up commands for sectioning,and declares various things that need to be done at the start and end of each page. +The \autodoc:class{book} class also loads the table of contents package which sets up commands for sectioning,and declares various things that need to be done at the start and end of each page. Since we will be inheriting from the book class, we will have all these definitions already available to us. All we need to do is set up our new class, and then define what is different about it. Here is how we set up the inheritance: @@ -397,13 +397,13 @@ bringhurst.defaultFrameset = { } \end{raw} -Note that we’ve deliberately copied the frame definitions for the folio and footnote frames from the \strong{book} class, but if we had tried to reuse the \code{runningHead} frame definition it would have been too high because the typeblock is higher on the page than the standard \strong{book} class, and the running heads are defined relative to them. +Note that we’ve deliberately copied the frame definitions for the folio and footnote frames from the \autodoc:class{book} class, but if we had tried to reuse the \code{runningHead} frame definition it would have been too high because the typeblock is higher on the page than the standard \autodoc:class{book} class, and the running heads are defined relative to them. So, we needed to change the definition the running header frame to bring them down a bit lower. If all we want to do in our new class is to create a different page shape, this is all we need. -The \code{_init()} function inherited from the book class will take care of setting these frames up with mirrored masters. +The \code{_init()} function inherited from \autodoc:class{book} class will take care of setting these frames up with mirrored masters. -If we had wanted to load additional packages into our class as, say, the \strong{bible} class does, +If we had wanted to load additional packages into our class as, say, the \autodoc:class{bible} class does, we would need to define our own \code{_init()} function and call our parent class’s \code{_init()} function as well. For example to load the \autodoc:package{infonode} package into our class, we could add this function: @@ -445,9 +445,9 @@ We will not cover it here, but class authors may also provide their own hook loc \end{itemize} For an example, we will check out the \autodoc:package{tableofcontents} package for the hooks it sets, -but also the \autodoc:command[check=false]{\tocentry} command it registers that gets called manually in the \strong{book} class. +but also the \autodoc:command[check=false]{\tocentry} command it registers that gets called manually in the \autodoc:class{book} class. Let’s demonstrate roughly how the that package works. -We’ll be using the \code{infonodes} package to collect the information about which pages contain table of content items. +We’ll be using the \autodoc:package{infonode} package to collect the information about which pages contain table of content items. First, we set up our infonodes by creating a command that can be called by sectioning commands. In other words, \autodoc:command[check=false]{\chapter}, \autodoc:command[check=false]{\section}, etc., should call \autodoc:command[check=false]{\tocentry} to store the page reference for this section. diff --git a/documentation/c11-xmlproc.sil b/documentation/c11-xmlproc.sil index d7a5c4b7e..7ef32f267 100644 --- a/documentation/c11-xmlproc.sil +++ b/documentation/c11-xmlproc.sil @@ -7,14 +7,14 @@ DocBook is an XML format for structured technical documentation. DocBook itself doesn’t encode any presentation information about how its various tags should be rendered on a page, and so we shall have to make all the presentation decisions for ourself. Since DocDook itself doesn’t specify anything about presentation such as paper size, you may need to supply values either on the command line or using a preamble. -When you use the \code{-c docbook} command line option to SILE, SILE will use the \code{docbook} class in spite of any document declaration. +When you use the \code{-c docbook} command line option to SILE, SILE will use the \autodoc:class{docbook} class in spite of any document declaration. In addition, options such as paper size could be set; for example, \code{-O papersize=legal}. The class initalization for DocBoox isn’t too fancy; it just loads up a couple packages that will get used later. \begin{autodoc:note} Much of the example code in this chapter is in SIL format using macros. -The actual \code{docbook} class currently uses Lua functions to specify these commands. +The actual \autodoc:class{docbook} class currently uses Lua functions to specify these commands. The functionality is the same, but the Lua syntax is more flexible and recommended for most use cases. The SILE \autodoc:command{\define} macros shown here can still be used in a preamble file if desired. \end{autodoc:note} @@ -110,7 +110,7 @@ So in reality we actually define an abstract \code{countedThing} method and defi \section{Sectioning} -DocBook sectioning is a little different to the SILE \code{book} class. +DocBook sectioning is a little different to the SILE \autodoc:class{book} class. \code{
} tags can be nested; to start a subsection, you place another \code{
} tag inside the current \code{
}. So in order to know what level we are currently on, we need a stack. We also need to keep track of what section number we are on at \em{each} level. For instance, with the expected section numbers and titles in XML comments: diff --git a/documentation/c12-tricks.sil b/documentation/c12-tricks.sil index 9383f254a..49c5eaa60 100644 --- a/documentation/c12-tricks.sil +++ b/documentation/c12-tricks.sil @@ -6,7 +6,7 @@ We’ll conclude our tour of SILE by looking at some tricky situations which req \section{Parallel text} The example \url{https://sile-typesetter.org/examples/parallel.sil} contains a rendering of Chapter 1 of Matthew’s Gospel in English and Greek. -It uses the \strong{diglot} class to align the two texts side-by-side. +It uses the \autodoc:class{diglot} class to align the two texts side-by-side. The latter provides the \autodoc:command[check=false]{\left} and \autodoc:command[check=false]{\right} commands to start entering text on the left column or the right column respectively, and the \autodoc:command[check=false]{\sync} command to ensure that the two columns are in sync with each other. It’s an instructive example of what can be done in a SILE class, so we will take it apart and see how it works. @@ -329,7 +329,7 @@ We haven’t used \code{SILE.call} here because it performs all its operations o If we wanted to make things cleaner, we could swap typesetters by assigning \code{discovery.innerTypesetter} to \code{SILE.typesetter} and then calling ordinary commands, rather than doing the settings and glue insertion “by hand”. \end{autodoc:note} -In the future it may make sense for there to be a standard \code{sidenotes} package in SILE, but it has been instructive to see a couple of “non-standard”examples to understand how the internals of SILE can be leveraged to create such a package. +In the future it may make sense for there to be a standard \autodoc:package{sidenotes} package in SILE, but it has been instructive to see a couple of “non-standard”examples to understand how the internals of SILE can be leveraged to create such a package. Your homework is to create one! \section{SILE as a library} @@ -397,7 +397,7 @@ Running SILE with the \code{--debug \em{facility}} switch will turn on debugging \item{\code{versions} gives a report on the versions of libraries and fonts in use. Please include this information when reporting bugs in SILE!} \item{Any package or other area of SILE’s operation may define their own debugging tags; - the \code{insertions} package does this, as do the Japanese and Uyghur language support systems (\code{--debug uyghur}). + the \autodoc:package{insertions} package does this, as do the Japanese and Uyghur language support systems (\code{--debug uyghur}). Often the debug flag is the name of the package or the function.} \end{itemize} diff --git a/packages/folio/init.lua b/packages/folio/init.lua index 8d3edc88f..85e4c00e7 100644 --- a/packages/folio/init.lua +++ b/packages/folio/init.lua @@ -78,7 +78,7 @@ end package.documentation= [[ \begin{document} -The \autodoc:package{folio} package (which is automatically loaded by the \code{plain} class, and therefore by nearly every SILE class) controls the output of folios—the old-time typesetter word for page numbers. +The \autodoc:package{folio} package (which is automatically loaded by the \autodoc:class{plain} class, and therefore by nearly every SILE class) controls the output of folios—the old-time typesetter word for page numbers. It provides four commands to users: diff --git a/packages/specimen/init.lua b/packages/specimen/init.lua index df8ac4ede..7665782e4 100644 --- a/packages/specimen/init.lua +++ b/packages/specimen/init.lua @@ -64,7 +64,7 @@ package.documentation = [[ \use[module=packages.specimen] SILE has found itself becoming well used by type designers, who often want to create specimen documents to show off their new fonts. This package provides a few commands to help create test documents. -(The \code{fontproof} class, available from the package manager, contains many more tools for creating specimens.) +(The \autodoc:class{fontproof} class, available from the package manager, contains many more tools for creating specimens.) The \autodoc:command{\repertoire} command prints out every glyph in the font, in a simple table. The \autodoc:command{\pangrams} command prints out a few pangrams for the Latin script. Finally, \autodoc:command{\set-to-width[width=]{}} will process each line of content, changing the font size so that the output is a constant width. From 9bb3ed32f7a519f3c455a8e57ea085a49c009d87 Mon Sep 17 00:00:00 2001 From: Omikhleia Date: Sat, 27 May 2023 19:00:07 +0200 Subject: [PATCH 3/6] docs(manual): Enable autodoc color highlighting --- documentation/sile.sil | 1 + 1 file changed, 1 insertion(+) diff --git a/documentation/sile.sil b/documentation/sile.sil index 70b1d5ba9..9389fa992 100644 --- a/documentation/sile.sil +++ b/documentation/sile.sil @@ -7,6 +7,7 @@ % and little resources for fine-checking and tuning, we prefer (possibly large) underfull lines % to ugly overfull ones: \set[parameter=linebreak.emergencyStretch,value=20%lw] +\set[parameter=autodoc.highlighting, value=true] \font[size=11pt,family=Gentium Book Basic] \nofolios \pdf:metadata[key=Title, value=The SILE Book] From c0416d726667400d57b1c507d928e3b23cf0e4d3 Mon Sep 17 00:00:00 2001 From: Omikhleia Date: Sat, 27 May 2023 21:02:27 +0200 Subject: [PATCH 4/6] docs(manual): Expand on vertical spacing and fills See #577 --- documentation/c04-useful.sil | 34 +++++++++++++++++++++++++++++----- 1 file changed, 29 insertions(+), 5 deletions(-) diff --git a/documentation/c04-useful.sil b/documentation/c04-useful.sil index e81c9aced..c4ffacd3c 100644 --- a/documentation/c04-useful.sil +++ b/documentation/c04-useful.sil @@ -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=]} 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} From 1c38ce70c54e7de05d6c8c4c2a5356445c4f0e16 Mon Sep 17 00:00:00 2001 From: Omikhleia Date: Sun, 28 May 2023 17:14:28 +0200 Subject: [PATCH 5/6] docs(manual): Break lines at sentences in chap. 9 It makes maintenance and change reviews simpler. --- documentation/c09-concepts.sil | 150 +++++++++++---------------------- 1 file changed, 51 insertions(+), 99 deletions(-) diff --git a/documentation/c09-concepts.sil b/documentation/c09-concepts.sil index 2fc07200b..e62b2d422 100644 --- a/documentation/c09-concepts.sil +++ b/documentation/c09-concepts.sil @@ -10,8 +10,7 @@ we will also explain how to interact with these components at the Lua level.} \section{Measurements and lengths} -Before dabbling into more advanced topics, let’s introduce “measurements” and “lengths” in SILE, -the two available Lua constructs for representing dimensions. +Before dabbling into more advanced topics, let’s introduce “measurements” and “lengths” in SILE, the two available Lua constructs for representing dimensions. Measurements are specified in terms of \code{SILE.measurement} objects. It is a basic construct with an amount and a unit. Let us illustrate two common ways for creating such an object in Lua (from a string, with same syntax as in command parameters; or from a Lua table). @@ -97,12 +96,9 @@ local vglue = SILE.nodefactory.vglue({ height = l }) S\lower[height=0.5ex]{I}L\kern[width=-.2em]\raise[height=0.6ex]{\font[features=+smcp]{e}}}} \define[command=SILEglue]{\font[family=Gentium Plus]{% S\lower[height=0.5ex]{I}L\glue[width=-.2em]\raise[height=0.6ex]{\font[features=+smcp]{e}}}} -\autodoc:command{\kern}’s are a type of \autodoc:command{\glue}, only different in that -while a \autodoc:command{\glue} can be broken at the end of a line, a \autodoc:command{\kern} -can’t. Hearkening back to our \SILEkern example from the \em{Macros and -Commands} chapter, consider that example, repeated enough times to cause a -linebreak, but with \autodoc:command{\glue}’s everywhere \autodoc:command{\kern}’s are used -instead: +\autodoc:command{\kern}’s are a type of \autodoc:command{\glue}, only different in that while a \autodoc:command{\glue} can be broken at the end of a line, a \autodoc:command{\kern} +can’t. +Hearkening back to our \SILEkern example from the \em{Macros and Commands} chapter, consider that example, repeated enough times to cause a linebreak, but with \autodoc:command{\glue}’s everywhere \autodoc:command{\kern}’s are used instead: \begin{autodoc:example}% \SILEglue\SILEglue\SILEglue\SILEglue\SILEglue\SILEglue\SILEglue\SILEglue% @@ -115,10 +111,8 @@ instead: \SILEglue\SILEglue\SILEglue\SILEglue\SILEglue\SILEglue\SILEglue% \end{autodoc:example} \par -Note end of lines where \SILEglue is broken -between its ‘L’ and ‘\raise[height=0.6ex]{\font[family=Gentium Plus,features=+smcp]{e}}’. -Instead, if we typeset the same line using \autodoc:command{\kern}’s as we had -originally: +Note end of lines where \SILEglue is broken between its ‘L’ and ‘\raise[height=0.6ex]{\font[family=Gentium Plus,features=+smcp]{e}}’. +Instead, if we typeset the same line using \autodoc:command{\kern}’s as we had originally: \begin{autodoc:example}% \SILEkern\SILEkern\SILEkern\SILEkern\SILEkern\SILEkern\SILEkern\SILEkern% @@ -131,8 +125,7 @@ originally: \SILEkern\SILEkern\SILEkern\SILEkern\SILEkern\SILEkern\SILEkern% \end{autodoc:example} -The line just continues on right off the page. Why this is a useful feature is -more obvious if there are spaces between them: +The line just continues on right off the page. Why this is a useful feature is more obvious if there are spaces between them: \begin{autodoc:example}% Glues: @@ -148,57 +141,37 @@ Kerns: \section{The typesetter} -SILE’s typesetting is organised by the \code{SILE.typesetter} object. It -maintains two queues of material that it is still working on: the node queue and -the output queue. Material in these queues is content that has been parsed but -not yet rendered to the canvas and can still be manipulated. The node queue -(\code{SILE.typesetter.state.nodes}) contains new horizontal boxes and glue -that have not yet been broken up into lines. The output queue -(\code{SILE.typesetter.state.outputQueue}) consists of vertical material -(lines) which have not yet been broken up into pages. Line breaking and page -breaking happen when the typesetter moves between horizontal and vertical mode. - -As new content is parsed it is added to the node queue in as small chunks as -possible. These chunks must remain together no matter where they end up on -a line. This might include individual symbols, syllables, or objects such as -images. As soon as new content which requires a vertical break is encountered, -the node queue is processed to derive any missing shaping information about -each node, then the sequence of node is broken up into lines. Once all the -“horizontal mode” nodes are broken into lines and those lines are added to the -output queue, the other new vertical content can be processed. At any point you -can force the current queue of horizontal content (the node queue) to be shaped -into lines and added to the vertical output queue by calling the function -\code{SILE.typesetter:leaveHmode()}. This is handy when for writing custom -functions, but it is a fairly low level control. (It is unlikely to be -useful while writing a document.) A related but higher level command, -\autodoc:command{\par}, is more frequently used when writing a document and embedded in -the content. The \autodoc:command{\par} command first calls -\code{SILE.typesetter:leaveHmode()}, then inserts a vertical skip according to -the \autodoc:setting{document.parskip} setting, then goes on to reset a number of -settings that are typically paragraph-related such as hanging indents. - -When writing a custom command, if you want to manually add a vertical space to -the output, first ensure that the material in the current paragraph has been all -properly boxed-up and moved onto the output queue by calling -\code{SILE.typesetter:leaveHmode()}, then add your desired glue to the output -queue. +SILE’s typesetting is organised by the \code{SILE.typesetter} object. +It maintains two queues of material that it is still working on: the node queue and the output queue. +Material in these queues is content that has been parsed but not yet rendered to the canvas and can still be manipulated. +The node queue (\code{SILE.typesetter.state.nodes}) contains new horizontal boxes and glue +that have not yet been broken up into lines. +The output queue (\code{SILE.typesetter.state.outputQueue}) consists of vertical material +(lines) which have not yet been broken up into pages. +Line breaking and page breaking happen when the typesetter moves between horizontal and vertical mode. + +As new content is parsed it is added to the node queue in as small chunks as possible. +These chunks must remain together no matter where they end up on a line. +This might include individual symbols, syllables, or objects such as images. +As soon as new content which requires a vertical break is encountered, the node queue is processed to derive any missing shaping information about each node, then the sequence of node is broken up into lines. +Once all the “horizontal mode” nodes are broken into lines and those lines are added to the output queue, the other new vertical content can be processed. +At any point you can force the current queue of horizontal content (the node queue) to be shaped +into lines and added to the vertical output queue by calling the function \code{SILE.typesetter:leaveHmode()}. +This is handy when for writing custom functions, but it is a fairly low level control. (It is unlikely to be useful while writing a document.) +A related but higher level command, \autodoc:command{\par}, is more frequently used when writing a document and embedded in the content. The \autodoc:command{\par} command first calls \code{SILE.typesetter:leaveHmode()}, then inserts a vertical skip according to the \autodoc:setting{document.parskip} setting, then goes on to reset a number of settings that are typically paragraph-related such as hanging indents. +When writing a custom command, if you want to manually add a vertical space to the output, first ensure that the material in the current paragraph has been all properly boxed-up and moved onto the output queue by calling \code{SILE.typesetter:leaveHmode()} or \code{SILE.call("par")}, then add your desired glue to the output queue. This is exactly what the \autodoc:command{\skip} and similar commands do. -Adding boxes and glue to the typesetter’s queues is -such a common operation that the typesetter has some utility methods to construct -the nodes and add them for you: +Adding boxes and glue to the typesetter’s queues is such a common operation that the typesetter has some utility methods to construct the nodes and add them for you: \begin[type=autodoc:codeblock]{raw} SILE.typesetter:leaveHmode() SILE.typesetter:pushVglue({ height = l }) \end{raw} -Adding boxes yourself is a little more complicated, because boxes need to -know how to display themselves on the page. To facilitate this, they normally -store a \code{value} and an \code{outputYourself} member function. For instance, -the \autodoc:package{image} package does something very simple: it adds a horizontal -box to the node queue which knows the width and height of the image, the source, -and instructions to the output engine to display the image: +Adding boxes yourself is a little more complicated, because boxes need to know how to display themselves on the page. +To facilitate this, they normally store a \code{value} and an \code{outputYourself} member function. +For instance, the \autodoc:package{image} package does something very simple: it adds a horizontal box to the node queue which knows the width and height of the image, the source, and instructions to the output engine to display the image: \begin[type=autodoc:codeblock]{raw} SILE.typesetter:pushHbox({ @@ -215,57 +188,41 @@ SILE.typesetter:pushHbox({ end}); \end{raw} -Adding horizontal and vertical penalties to the typesetter’s queues is similarly -done with the \code{SILE.typesetter:pushPenalty(\{penalty = x\})} and -\code{SILE.typesetter:pushVpenalty(\{penalty = y\})} methods. +Adding horizontal and vertical penalties to the typesetter’s queues is similarly done with the \code{SILE.typesetter:pushPenalty(\{penalty = x\})} and \code{SILE.typesetter:pushVpenalty(\{penalty = y\})} methods. \section{Frames} As we have previously mentioned, SILE arranges text into frames on the page. -The overall layout of a page, including the apparent margins between content -and the page edge and other content regions, is controlled by defining the -position of the frame or frames into which the content will be flowed. +The overall layout of a page, including the apparent margins between content and the page edge and other content regions, is controlled by defining the position of the frame or frames into which the content will be flowed. -Normally those frames are defined by your document class, but you can actually -create your own frames on a per-page basis using the \autodoc:command{\pagetemplate} -and \autodoc:command{\frame} commands. There are very few situations in which you will -actually want to do this, but if you can understand this, it will help you -to understand how to define your own document classes. +Normally those frames are defined by your document class, but you can actually create your own frames on a per-page basis using the \autodoc:command{\pagetemplate} and \autodoc:command{\frame} commands. +There are very few situations in which you will actually want to do this, but if you can understand this, it will help you to understand how to define your own document classes. For instance, in a couple of page’s time, we’re going to implement a two-column layout. -SILE uses a \em{constraint solver} system to declare its frames, which means -that you can tell it how the frames relate to each other and it will compute -where the frames should be physically placed on the page. - -Here is how we will go about it. We need to start with a page break, because -SILE will not appreciate you changing the page layout after it’s started to -determine how to put text onto that page.\footnote{You can use -the \autodoc:package{frametricks} package to get around this limitation—split the current -frame and start fiddling around with the positions of the new frames that -\autodoc:package{frametricks} created for you.} How do we get to the start of a new -page? Remember that the \autodoc:command{\eject} (another word for \autodoc:command{\break} in -vertical mode) only adds a penalty to the end of the output queue; page breaking -is triggered when we leave horizontal mode, and the way to do that is \autodoc:command{\par}. +SILE uses a \em{constraint solver} system to declare its frames, which means that you can tell it how the frames relate to each other and it will compute where the frames should be physically placed on the page. + +Here is how we will go about it. +We need to start with a page break, because SILE will not appreciate you changing the page layout after it’s started to determine how to put text onto that page.\footnote{You can use the \autodoc:package{frametricks} package to get around this limitation—split the current frame and start fiddling around with the positions of the new frames that \autodoc:package{frametricks} created for you.} +How do we get to the start of a new page? +Remember that the \autodoc:command{\eject} (another word for \autodoc:command{\break} in vertical mode) only adds a penalty to the end of the output queue; + page breaking is triggered when we leave horizontal mode, and the way to do that is \autodoc:command{\par}. So we start with \autodoc:command{\eject\par} and then we will begin a \autodoc:command{\pagetemplate}. -Within \autodoc:command{\pagetemplate} we need to tell SILE which frame to begin typesetting -onto: +Within \autodoc:command{\pagetemplate} we need to tell SILE which frame to begin typesetting onto: \begin[type=autodoc:codeblock]{raw} \eject\par \begin[first-content-frame=leftCol]{pagetemplate} \end{raw} -Now we will declare our columns. But we’re actually going to start by declaring -the gutter first, because that’s something that we know and can define; we’re -going to stipulate that the gutter width will be 3\% of the page width: +Now we will declare our columns. +But we’re actually going to start by declaring the gutter first, because that’s something that we know and can define; we’re going to stipulate that the gutter width will be 3\% of the page width: \begin[type=autodoc:codeblock]{raw} \frame[id=gutter,width=3%pw] \end{raw} \begin{autodoc:note}% -Declarations of frame dimensions are like ordinary SILE \code{}s, -except with three additional features: +Declarations of frame dimensions are like ordinary SILE \code{}s, except with three additional features: \begin{itemize} \item{You can refer to properties of other frames using the \code{top()}, @@ -285,13 +242,10 @@ except with three additional features: \end{itemize} \end{autodoc:note} -Next we declare the left and right column frames. The \autodoc:class{book} class -gives us some frames already, one of which, \code{content}, defines a typeblock -with a decent size and positioning on the page. -We will use the boundaries of this frame to declare our columns: the left -margin of the left column is the left margin of the typeblock, and the right margin of -the right column is the right margin of the typeblock. But we also want -a few other parameters to ensure that: +Next we declare the left and right column frames. +The \autodoc:class{book} class gives us some frames already, one of which, \code{content}, defines a typeblock with a decent size and positioning on the page. +We will use the boundaries of this frame to declare our columns: the left margin of the left column is the left margin of the typeblock, and the right margin of the right column is the right margin of the typeblock. +But we also want a few other parameters to ensure that: \begin{itemize} \item{the gutter is placed between our two columns} @@ -328,10 +282,8 @@ Let’s do it. \showframe[id=rightCol] So there we have it: a two-column page layout. -In the next chapter we’ll use the knowledge of how to declare frames to -help us to create our own document class files. In the meantime, here is -some dummy text to demonstrate the fact that text does indeed flow between -the two columns naturally: +In the next chapter we’ll use the knowledge of how to declare frames to help us to create our own document class files. +In the meantime, here is some dummy text to demonstrate the fact that text does indeed flow between the two columns naturally: \lorem[words=500] \end{document} From 1722ea8a598e005b8aa7b014f06ba3ee737a1ca6 Mon Sep 17 00:00:00 2001 From: Omikhleia Date: Sun, 28 May 2023 17:34:29 +0200 Subject: [PATCH 6/6] docs(manual): Slightly rephrase details on "par" and leaveHmode() --- documentation/c09-concepts.sil | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/documentation/c09-concepts.sil b/documentation/c09-concepts.sil index e62b2d422..9265f1a18 100644 --- a/documentation/c09-concepts.sil +++ b/documentation/c09-concepts.sil @@ -157,11 +157,15 @@ As soon as new content which requires a vertical break is encountered, the node Once all the “horizontal mode” nodes are broken into lines and those lines are added to the output queue, the other new vertical content can be processed. At any point you can force the current queue of horizontal content (the node queue) to be shaped into lines and added to the vertical output queue by calling the function \code{SILE.typesetter:leaveHmode()}. -This is handy when for writing custom functions, but it is a fairly low level control. (It is unlikely to be useful while writing a document.) -A related but higher level command, \autodoc:command{\par}, is more frequently used when writing a document and embedded in the content. The \autodoc:command{\par} command first calls \code{SILE.typesetter:leaveHmode()}, then inserts a vertical skip according to the \autodoc:setting{document.parskip} setting, then goes on to reset a number of settings that are typically paragraph-related such as hanging indents. -When writing a custom command, if you want to manually add a vertical space to the output, first ensure that the material in the current paragraph has been all properly boxed-up and moved onto the output queue by calling \code{SILE.typesetter:leaveHmode()} or \code{SILE.call("par")}, then add your desired glue to the output queue. + +When writing a custom command, if you want to manually add a vertical space to the output, first ensure that the material in the current paragraph has been all properly boxed-up and moved onto the output queue by calling \code{SILE.typesetter:leaveHmode()}, then add your desired glue to the output queue. This is exactly what the \autodoc:command{\skip} and similar commands do. +It might be a good point to better explain here the actual difference between just leaving horizontal mode, and the related, but higher level, \autodoc:command{\par} command. +The latter is more frequently used when writing a document. +It first calls \code{SILE.typesetter:leaveHmode()}, but then also inserts a vertical skip according to the \autodoc:setting{document.parskip} setting, and goes on to reset a number of settings that are typically paragraph-related such as hanging indents. +When designing you own commands, there are therefore some cases when you may just need to call \code{SILE.typesetter:leaveHmode()} and handle everything else in your own code; and situations when invoking \code{SILE.call("par")} might be more adequate, resulting in an effective paragraph to be terminated. + Adding boxes and glue to the typesetter’s queues is such a common operation that the typesetter has some utility methods to construct the nodes and add them for you: \begin[type=autodoc:codeblock]{raw}