Merge pull request #2191 from alerque/raw-verbatim

Add verbatim handler for raw, touchup docs

packages/verbatim/init.lua

@@ -39,14 +39,22 @@ function package:registerCommands ()
    end)
 end
 
+function package:registerRawHandlers ()
+   self:registerRawHandler("verbatim", function (options, content)
+      SILE.call("verbatim", options, { content[1] })
+   end)
+end
+
 package.documentation = [[
 \begin{document}
 The \autodoc:package{verbatim} package is useful when quoting pieces of computer code and other text for which formatting is significant.
 It changes SILE’s settings so that text is set ragged right, with no hyphenation, no indentation and regular spacing.
 It tells SILE to honor multiple spaces, and sets a monospaced font.
 
 \autodoc:note{Despite the name, \autodoc:environment{verbatim} does not alter the way that SILE sees special characters.
-You still need to escape backslashes and braces: to produce a backslash, you need to write \code{\\\\}.}
+You still need to escape backslashes and braces: to produce a backslash, you need to write \code{\\\\}.
+See the use of the \\autodoc:environment{raw} with a verbatim type handler for more literal verbatim behavior.
+}
 
 Here is some text set in the \autodoc:environment{verbatim} environment:
 
@@ -58,13 +66,30 @@ end
 \end{raw}
 
 If you want to specify what font the verbatim environment should use, you can redefine the \autodoc:command{\verbatim:font} command.
+Unless otherwise set, the default verbatim font will be \em{Hack}.
 For example you could change it from XML like this:
 
 \begin[type=autodoc:codeblock]{raw}
 <define command="verbatim:font">
    <font family="DejaVu Sans Mono" size="9pt"/>
 </define>
 \end{raw}
+
+This handles spaces, newlines, tabs and other similar whitespace literally in a way that SILE would otherwise have handled specially.
+If additionally you want to ignore nested SILE content (e.g. SIL commands in SIL) then you need to use a raw enviroment instead:
+
+\begin[type=autodoc:codeblock]{raw}
+\begin[type=verbatim]{raw}
+Sile commands like \em{emphasis} will not be intercepted.
+\end‌{raw}
+\end{raw}
+
+Displays as:
+
+\begin[type=verbatim]{raw}
+Sile commands like \em{emphasis} will not be intercepted.
+\end{raw}
+
 \end{document}
 ]]