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: acarand acdr.
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
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.
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.
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.
You can insert files verbatim with the command
\verbatiminput (from LaTeX’s verbatim.sty) or with Eplain’s
\listing. Usage:
\verbatiminput{program.lisp}
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).
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.
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}
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).
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.