8  Verbatim text

TeX2page recognizes a slightly enhanced version of LaTeX’s \verb command. Recall that LaTeX’s \verb’s argument is enclosed within a pair of identical characters (not whitespace or *), and this argument is printed verbatim. This is useful for typesetting things like fragments of computer code. E.g.,

A \verb|cons|-cell has two components: a \verb+car+ and 
a \verb&cdr&. 

is converted to

A cons-cell has two components: a car and a cdr.

The TeX2page version of \verb adds a couple more features:

(i) You can use matching braces to enclose its argument, provided the latter does not contain unmatched braces. E.g.,

The command \verb{\section{Imagining a Conscious Robot}}
typesets ‘\verb{Imagining a Conscious Robot}’ as a section
title.
is converted to

The command \section{Imagining a Conscious Robot} typesets ‘Imagining a Conscious Robot’ as a section title.

(ii) If \verb’s argument commences with a newline, it is set as a display. E.g.,

\verb{
(define compose
  (lambda (f g)
    (lambda aa
      (f (apply g aa)))))
}
produces

(define compose
  (lambda (f g)
    (lambda aa
      (f (apply g aa)))))
Note that such displays faithfully typeset all the whitespace of the text, including linebreaks and indentation.

As in LaTeX, if a * immediately follows \verb, any spaces in \verb’s argument text are highlighted as something that is visible. This allows you to easily count spaces or tell if there is trailing space on a line.

\verb*{three   spaces}
produces

three···spaces

Commands within verbatim

Often you want to use TeX​ ​commands in special spots within verbatim text, especially displayed verbatim material. For this reason, the character ‘|’ is allowed as an escape character if the verbatim text is enclosed within braces.

As an example, let’s say you’ve defined an \evalsto macro to use in cases where you want to say a program expression evaluates to a result. A possible definition is:

\def\evalsto{::==}
You could use \evalsto inside a verbatim display as follows:

\verb{ 
(cons 1 2) |evalsto (1 . 2) 
} 

This will produce

(cons 1 2) ::== (1 . 2)
Some standard commands that can be used inside braced verbatim are: || to insert the escape character itself; and |{ and |} to insert the occasional non-matching brace.

Changing the verbatim escape character

You can use the Eplain and TeX2page macro \verbatimescapechar to postulate a character other than ‘|’ as the verbatim escape. E.g.,

\verbatimescapechar\@
makes ‘@’ the verbatim escape.

Other common verbatim macros

TeX2page also understands LaTeX’s {verbatim} and {verbatim*} environments, Eplain’s \verbatim, the \path macro from path.sty, and the {Verbatim} and {Verbatim*} environments from fancyvrb.sty.

It recognizes fancyvrb’s \DefineShortVerb and OPmac’s \activettchar. Setting \DefineShortVerb{\`} or \activettchar` lets you write \verb`\c@de_fr&gm%#t$` as simply `\c@de_fr&gm%#t$`, as in AsciiDoc. Setting \DefineShortVerb{\|} or \activettchar| lets you write |\c@de_fr&gm%#t$|, as in manmac.

It also recognizes manmac’s \begintt ... \endtt, but note that by default, TeX2page’s \begintt sets everything within it verbatim. If you want it to be truly manmac-like, i.e., with | as the escape character and \] producing visible space, you should set \tthook to something suitable:

\def\tthook{\catcode`\|=0 
  \def\|{char`\|}% 
  \def\ {·}} 

If you also have \activettchar`, then set \tthook before you set \activettchar.

Inserting files verbatim

You can insert files verbatim with the command \verbatiminput (from LaTeX’s verbatim.sty) or with Eplain’s \listing. Usage:

\verbatiminput{program.lisp}

Writing to files

The command \verbwrite, used like \verb, does not typeset its enclosed text but outputs it verbatim into a text file. The text file has by default the same basename as the document, but with extension .txt.

To specify another text file, use \verbwritefile. E.g.,

\verbwritefile notes-to-myself.txt    % or
\verbwritefile{notes-to-myself.txt}
This will cause subsequent calls to \verbwrite upto the next \verbwritefile or end of document (whichever comes first) to send text into the file notes‑to‑myself.txt. \verbwritefile deletes any pre-existing contents of its argument file.

TeX2page also recognizes the TeX​ ​command \write, which takes two arguments: an output stream number and a TeX​ ​expression to be output. Recall that TeX​ ​allows only the numbers 0–15 for output streams that can be associated with files; numbers outside this range are deemed to represent standard output.

However: TeX2page follows modern TeX​ ​implementation practice in treating the output stream 18 specially. \write18{oscommand}, instead of writing oscommand to standard output, will execute it as an operating-system command! This is not standard TeX​ ​behavior, but most modern TeXs enable this feature with a command-line option that is either ‑shell‑escape or ‑‑enable‑write18 (use ‑‑help on your TeX​ ​executable(s) to find out).

Verbatim style

The verbatim commands (\verb, \path and \verbatiminput, etc.)​ ​introduced above use a style class called verbatim. You can affect the appearance of your verbatim text by defining a style for verbatim in a style sheet (p. 7). E.g.,

.verbatim        {color: hsl(205,100%,16%)}
sets all verbatim text in Prussian blue.

Syntax-highlighting of program code

The commands \scm and \scminput are variants of \verb and \verbatiminput. They are useful for producing syntax-highlighted Lisp code in the HTML file. E.g.,

\scm{
(defun factorial (n)
  (when *debug*
    (format t "Calling factorial ~a~%" n))
  (if (= n 0) 1 ;the base case
      (* n (factorial (1- n)))))
}
produces

(defun factorial (n)
  (when *debug*
    (format t "Calling factorial ~a~%" n))
  (if (= n 0) 1 ;the base case
      (* n (factorial (1- n)))))

(Your browser needs to support style sheets for the syntax-highlighting to show.)

Seven categories of code text are distinguished:

(i) background punctuation;

(ii) self-evaluating atoms (numbers, booleans, characters, strings);

(iii) syntactic keywords;

(iv) builtin variables;

(v) global or special variables, viz., identifiers that begin and end with an asterisk;

(vi) other variables; and

(vii) comments.

To distinguish between the categories of Lisp code text, TeX2page uses a style class called scheme with six subclasses, viz., selfeval, keyword, builtin, global, variable, and comment. You can set the color property (and other properties like font‑weight and font‑style) of these classes in a style sheet (p. 7). The default settings are:

.scheme             {color: hsl(280,33%,30%)} /* background punctuation */
.scheme  .selfeval  {color: hsl(120,100%,20%); font-style: normal}
.scheme  .keyword   {color: hsl(0,100%,20%);   font-style: normal; font-weight: bold}
.scheme  .builtin   {color: hsl(0,100%,20%);   font-style: normal}
.scheme  .global    {color: hsl(300,100%,20%); font-style: normal}
.scheme  .variable  {color: hsl(240,100%,20%); font-style: normal}
.scheme  .comment   {color: hsl(180,100%,20%); font-style: oblique}
TeX2page initially only recognizes some well-known syntactic keywords, global variables, and self-evaluators. It does not recognize builtins as apart from the general run of variables. Users who want builtins distinguished can use \scmbuiltin, e.g.,

\scmbuiltin{cons car cdr}

Users who do not want to distinguish Common Lisp–style global (“special”) variables as a separate category from other variables should give the style class .global the same properties as .variable, e.g.,

.scheme .global {color: hsl(240,100%,20%}

Users can add their own keywords with \scmkeyword. E.g.,

\scmkeyword{define-class unwind-protect}

By default, tokens that don’t fall in any of the other categories are set as variables. However, \scmvariable can be used to explicitly identify as variables those tokens that are currently treated as non-variables (e.g., keywords or self-evaluators). E.g.,

\scmvariable{and 42 +i}

Using SLaTeX​ ​commands

TeX2page also syntax-highlights Lisp code introduced using the SLaTeX​ ​commands, chiefly \scheme and {schemedisplay}. SLaTeX​ ​users know that these commands typeset code in the DVI output using fonts (rather than color) for highlighting. For the HTML, TeX2page will use color.

A minor point is that SLaTeX’s commands allow TeX commands inside Lisp comments. This is useful if you want to highlight mentions of Lisp code inside Lisp comments. To get the same effect with TeX2page, use the \TZPslatexcomments flag (p. 6).

Documenting your code

You can use TeX2page to do a form of literate programming, i.e., combining your documentation with your code. The command \scmdribble, which is used like \scm, will not only display the enclosed code, but also send it to the external file named by the most recent \verbwritefile.

To specify code that should go into the external file but should not be displayed, simply use \verbwrite instead of \scmdribble.