Merge pull request #1846 from alerque/manual-code

documentation/c08-language.sil

@@ -50,31 +50,19 @@ then in Urdu: \font[family=LateefGR,language=urd]{ههه}.
 
 \section{Direction}
 
-SILE is written to be \em{direction-agnostic,} which means that it has
-no fixed idea about which way text should flow on a page. Latin scripts
-are generally written left-to-right with individual lines starting from
-the top of the page and advancing towards the bottom. Japanese can be
-written in the same way, but traditionally is typeset down the page with
-lines of text moving from the right of the page to the left.
-
-To describe this, SILE uses the concept of a \em{writing direction,}
-which denotes the way each individual line appears on the page—left
-to right for Latin scripts, right to left for Arabic, Hebrew and so on,
-top to bottom for traditional Japanese—and a \em{page advance direction,}
-which denotes the way the lines “stack up”. Each of these directions can
-take one of four values: \code{LTR}, \code{RTL}, \code{TTB}, or \code{BTT}.
-A \em{direction specification} is made up of either a writing direction
-(\code{LTR} or \code{RTL}), in which case the page advance direction is
-understood to be \code{TTB}, or a writing direction and a page advance
-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 \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,
-so to create a Mongolian document, use:
+SILE is written to be \em{direction-agnostic,} which means that it has no fixed idea about which way text should flow on a page.
+Latin scripts are generally written left-to-right with individual lines starting from the top of the page and advancing towards the bottom.
+Japanese can be written in the same way, but traditionally is typeset down the page with lines of text moving from the right of the page to the left.
+
+To describe this, SILE uses the concept of a \em{writing direction,} which denotes the way each individual line appears on the page—left to right for Latin scripts, right to left for Arabic, Hebrew and so on, top to bottom for traditional Japanese—and a \em{page advance direction,} which denotes the way the lines “stack up”.
+Each of these directions can take one of four values: \code{LTR}, \code{RTL}, \code{TTB}, or \code{BTT}.
+A \em{direction specification} is made up of either a writing direction (\code{LTR} or \code{RTL}), in which case the page advance direction is understood to be \code{TTB}, or a writing direction and a page advance 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 \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, so to create a Mongolian document, use:
 
 \begin[type=autodoc:codeblock]{raw}
 \begin[direction=TTB-LTR]{document}
@@ -83,35 +71,27 @@ so to create a Mongolian document, use:
 \end{document}
 \end{raw}
 
-To change the writing direction for a single frame, use
-\autodoc:command{\thisframedirection[direction=<dir>]}.
+To change the writing direction for a single frame, use \autodoc:command{\thisframedirection[direction=<dir>]}.
 
-SILE uses the Unicode bidirectional algorithm to handle texts written in
-mixed directionalities. See \url{https://sile-typesetter.org/examples/i18n.sil}
-for an example which brings together multiple scripts and directionalities.
+SILE uses the Unicode bidirectional algorithm to handle texts written in mixed directionalities.
+See \url{https://sile-typesetter.org/examples/i18n.sil} for an example which brings together multiple scripts and directionalities.
 
 \section{Hyphenation}
 
-SILE hyphenates words based on its current language. (Language is set using the
-\autodoc:command{\font} command above.) SILE comes with support for hyphenating a wide
-variety of languages, and also aims to encode specific typesetting knowledge about
+SILE hyphenates words based on its current language.
+(Language is set using the \autodoc:command{\font} command above.)
+SILE comes with support for hyphenating a wide variety of languages, and also aims to encode specific typesetting knowledge about
 languages.
 
-The default hyphen character is “-”, which can be tweaked by the \autodoc:command{\font}
-parameter \autodoc:parameter{hyphenchar}. It accepts a Unicode character or Unicode codepoint
-in \code{[Uu]+<code>} or Hexadecimal \code{0[Xx]<code>} format—for instance,
-\autodoc:command{\font[family=Rachana,language=ml,hyphenchar=U+200C]}.
+The default hyphen character is “-”, which can be tweaked by the \autodoc:command{\font} parameter \autodoc:parameter{hyphenchar}.
+It accepts a Unicode character or Unicode codepoint in \code{[Uu]+<code>} or Hexadecimal \code{0[Xx]<code>} format—for instance, \autodoc:command{\font[family=Rachana,language=ml,hyphenchar=U+200C]}.
 
-SILE comes with a special “language” called \code{und}, which has no hyphenation
-patterns available. If you switch to this language, text will not be hyphenated.
-The command \autodoc:command{\nohyphenation{…}} is provided as a shortcut for
-\autodoc:command{\font[language=und]{…}}.
+SILE comes with a special “language” called \code{und}, which has no hyphenation patterns available.
+If you switch to this language, text will not be hyphenated.
+The command \autodoc:command{\nohyphenation{…}} is provided as a shortcut for \autodoc:command{\font[language=und]{…}}.
 
-The hyphenator uses the same algorithm as TeX and can use TeX hyphenation
-pattern files if they are converted to Lua format. To implement hyphenation
-for a new language, first check to see if TeX hyphenation dictionaries
-are available; if not, work through the resources at
-\url{http://tug.org/docs/liang/}.
+The hyphenator uses the same algorithm as TeX and can use TeX hyphenation pattern files if they are converted to Lua format.
+To implement hyphenation for a new language, first check to see if TeX hyphenation dictionaries are available; if not, work through the resources at \url{http://tug.org/docs/liang/}.
 
 \section{Localization}
 
@@ -148,17 +128,15 @@ A particularly common string to override might be the table of contents heading:
 
 \section{Support for specific languages}
 
-The following section shows some of the support features that SILE provides
-for specific languages apart from hyphenation and language-specific glyph
+The following section shows some of the support features that SILE provides for specific languages apart from hyphenation and language-specific glyph
 selection:
 
 \subsection{Amharic}
 
-SILE inserts word break opportunities after Ethiopic word spaces and full
-stops. Amharic can be typeset in two styles: with space surrounding
-punctuation or space after punctuation. You can set the setting
-\autodoc:setting[check=false]{languages.am.justification} to either \code{left}
-or \code{centered} to control which style is used. The default is \code{left}.
+SILE inserts word break opportunities after Ethiopic word spaces and full stops.
+Amharic can be typeset in two styles: with space surrounding punctuation or space after punctuation.
+You can set the setting \autodoc:setting[check=false]{languages.am.justification} to either \code{left} or \code{centered} to control which style is used.
+The default is \code{left}.
 
 \begin{autodoc:codeblock}
 \\font[family=Noto Sans Ethiopic,language=am]
@@ -189,14 +167,12 @@ on how to typeset this, you have options:
 
 \subsection{French}
 
-In French typesetting, there is normally a non-breakable space between text
-and “high” punctuation (a thin fixed space before question marks, exclamation
-marks, and semicolons, and an inter-word space before colons), and also spaces
-within “guillemets” (quotation marks). SILE will automatically apply the
-correct space. The size of these spaces is determined by
-\autodoc:setting[check=false]{languages.fr.thinspace},
-\autodoc:setting[check=false]{languages.fr.colonspace} and
-\autodoc:setting[check=false]{languages.fr.guillspace}.
+In French typesetting, there is normally a non-breakable space between text and “high” punctuation (a thin fixed space before question marks, exclamation marks, and semicolons, and an inter-word space before colons), and also spaces within “guillemets” (quotation marks).
+SILE will automatically apply the correct space.
+The size of these spaces is determined by
+	\autodoc:setting[check=false]{languages.fr.thinspace},
+	\autodoc:setting[check=false]{languages.fr.colonspace} and
+	\autodoc:setting[check=false]{languages.fr.guillspace}.
 
 \subsection{Japanese / Chinese}
 
@@ -218,10 +194,7 @@ SILE implements syllable-based line breaking for Burmese and Javanese text.
 
 \subsection{Uyghur}
 
-Uyghur is the only Arabic script based language which uses hyphenation,
-and SILE supports hyphenation. Because Arabic fonts aren’t normally designed
-with hyphenation in mind, you may need to tweak some settings to ensure that
-Uyghur is typeset correctly. As well as choosing the \code{hyphenchar} (see
-the hyphenation section above), the setting \autodoc:setting[check=false]{languages.ug.hyphenoffset}
-inserts a space between the text and the hyphen.
+Uyghur is the only Arabic script based language which uses hyphenation, and SILE supports hyphenation.
+Because Arabic fonts aren’t normally designed with hyphenation in mind, you may need to tweak some settings to ensure that Uyghur is typeset correctly.
+As well as choosing the \code{hyphenchar} (see the hyphenation section above), the setting \autodoc:setting[check=false]{languages.ug.hyphenoffset} inserts a space between the text and the hyphen.
 \end{document}

documentation/c09-concepts.sil

@@ -1,5 +1,4 @@
 \begin[class=book]{document}
-\include[src=documentation/macros.sil]
 \chapter{The Nitty Gritty}
 
 We are finally at the bottom of our delve into SILE’s commands and settings.

documentation/c11-xmlproc.sil

@@ -115,7 +115,7 @@ DocBook sectioning is a little different to the SILE \autodoc:class{book} class.
 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:
 
-\begin{verbatim}
+\begin[type=autodoc:codeblock]{raw}
   <section><title>A</title> : \autodoc:example{1. A}
     <section><title>B</title>: \autodoc:example{1.1 B}
     </section>
@@ -126,7 +126,7 @@ For instance, with the expected section numbers and titles in XML comments:
     <section><title>E</title>: \autodoc:example{1.3 E}
   </section>
   <section><title>F</title>: \autodoc:example{2. F}
-\end{verbatim}
+\end{raw}
 
 So, we will keep two variables: the current level, and the counters for all of the levels so far.
 Each time we enter a \code{section}, we increase the current level counter:

documentation/c12-tricks.sil

@@ -37,15 +37,15 @@ end
 
 Next we create two new typesetters, one for each column, and we tell each one how to find the other:
 
-\begin{verbatim}
+\begin[type=autodoc:codeblock]{raw}
 function diglot:_init (options)
   self.leftTypesetter = SILE.typesetters.base()
   self.rightTypesetter = SILE.typesetters.base()
   self.rightTypesetter.other = self.leftTypesetter
   self.leftTypesetter.other = self.rightTypesetter
   return plain._init(self)
 end
-\end{verbatim}
+\end{raw}
 
 Each column needs its own font, so we provide commands to store this information.
 The \autodoc:command[check=false]{\leftfont} and \autodoc:command[check=false]{\rightfont} macros simply store their options to be passed to the \autodoc:command[check=false]{\font} command every time \autodoc:command[check=false]{\left} and \autodoc:command[check=false]{\right} are called.

documentation/macros.sil

@@ -25,7 +25,7 @@
 \define[command=book:sectionfont]{\sectionsfont{\font[size=15pt]{\process}}}
 \define[command=book:subsectionfont]{\sectionsfont{\font[size=13pt]{\process}}}
 \define[command=code]{\font[family=Hack,size=0.8em,language=und,style=roman]{\process}}
-\define[command=verbatim:font]{\font[family=Hack,size=9pt]}
+\define[command=verbatim:font]{\font[family=Hack,size=8.5pt]}
 % Custom commands
 \define[command=terminal]{\verbatim{\set[parameter=document.lskip,value=36pt]\process\smallskip}}
 \define[command=changed]{

packages/autodoc/init.lua

@@ -317,32 +317,40 @@ function package:registerCommands ()
   -- Homogenizing the appearance of blocks of code
 
   self:registerCommand("autodoc:codeblock", function(_, content)
-      SILE.call("bigskip")
       SILE.settings:temporarily(function()
         -- Note: We avoid using the verbatim environment and simplify things a bit
         -- (and try to better enforce novbreak points of insertion)
         SILE.call("verbatim:font")
+        -- Rather than absolutizing 4 different values, just do it once and cache it
+        local ex = SILE.measurement("1ex"):absolute()
+        SILE.typesetter:leaveHmode()
         SILE.settings:set("typesetter.parseppattern", "\n")
         SILE.settings:set("typesetter.obeyspaces", true)
         SILE.settings:set("document.parindent", SILE.nodefactory.glue())
-        SILE.settings:set("document.parskip", SILE.nodefactory.vglue("1pt"))
-        SILE.settings:set("document.baselineskip", SILE.nodefactory.glue("1.2em"))
+        SILE.settings:set("document.parskip", SILE.nodefactory.vglue(0.3*ex))
+        SILE.settings:set("document.baselineskip", SILE.nodefactory.glue(2.3*ex))
         SILE.settings:set("document.spaceskip", SILE.length("1spc"))
         SILE.settings:set("shaper.variablespaces", false)
         SILE.settings:set("document.language", "und")
-        SILE.call("autodoc:line")
-        SILE.call("novbreak")
-        SILE.process(content)
-        SILE.call("novbreak")
         SILE.typesetter:leaveHmode()
+        SILE.call("color", { color = "#303040" }, function ()
+          SILE.call("bigskip")
+          SILE.call("autodoc:line")
+          SILE.typesetter:pushVglue(-0.6*ex)
+          SILE.call("novbreak")
+          SILE.process(content)
+          SILE.call("novbreak")
+          SILE.typesetter:pushVglue(1.4*ex)
+          SILE.call("autodoc:line")
+          SILE.call("smallskip")
+        end)
     end)
-    SILE.call("novbreak")
-    SILE.call("autodoc:line")
-    SILE.call("smallskip")
   end, "Outputs its content as a standardized block of code")
 
   self:registerCommand("autodoc:line", function(_, _)
+    SILE.call("novbreak")
     SILE.call("fullrule", { thickness = "0.5pt" })
+    SILE.call("novbreak")
   end, "Ouputs a line used for surrounding code blocks (somewhat internal)")
 
   self:registerCommand("autodoc:example", function(_, content)