The command \verb
is used for text that should be
set verbatim, such as fragments of computer code.
\verb
's argument is enclosed within a
pair of identical characters (that aren't whitespace,
{
, or *
). For example,
A \verb|cons|-cell has two components: a \verb+car+ and a \verb&cdr&.
is converted to
A
cons
-cell has two components: acar
and acdr
.
You could also use matching braces to enclose \verb
's
argument, provided the latter does not contain unmatched
braces. Eg,
The command \verb{\section{The Test of the Bow}} types \verb{The Test of the Bow} as a section title.
is converted to
The command
\section{The Test of the Bow}
typesThe Test of the Bow
as a section title.
If \verb
's argument commences with a newline, it is
set as a display. Eg,
\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.
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
''
The command \path
is similar to \verb
. The only
difference is that when the document is TeX'd, the text
specified by \path
can be broken across lines at `.
'
and `/
'. This is useful for long URLs and filenames.
TeX2page also understands LaTeX's {verbatim}
and {verbatim*}
environments, which set displayed
verbatim text with spaces and newlines as is.
{verbatim*}
differs from {verbatim}
in that
spaces are highlighted as something visible.
Note: Unfortunately, you cannot use
\verb
and \path
in LaTeX section headers.
While TeX2page itself has no problem
with this sort of construction, LaTeX will
cause error. Use \tt
instead, perhaps with some
other definitions for special characters. The
section macros provided in tex2page.tex
for
use with plain TeX do not have this problem.
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 macro \verbescapechar
to
postulate a character other than `|
' as the
verbatim escape. Eg,
\verbescapechar\@
makes `@
' the verbatim escape.
You can insert files verbatim with the command
\verbatiminput
. Usage:
\verbatiminput progam.scm % or \verbatiminput{program.scm}
This displays the contents of the file
program.scm
``as is''. Useful for listings.5
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
.6
To specify another text file, use \verbwritefile
.
Eg,
\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.
The verbatim commands \verb
, \path
and \verbatiminput
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 (section 4). Eg,
.verbatim {color: darkgreen}
makes all verbatim text dark green.
The commands \scm
and \scminput
are variants
of \verb
and \verbatiminput
. They are
useful for producing syntax-highlighted Scheme
code in the HTML file. Eg,
\scm{ (define fact "The factorial function" (lambda (n) (if (= n 0) 1 ;the base case (* n (fact (- n 1)))))) }
produces
(define fact "The factorial function" (lambda (n) (if (= n 0) 1 ;the base case (* n (fact (- n 1))))))
Seven categories of code text are distinguished: (1) self-evaluating atoms (numbers, booleans, characters, strings); (2) syntactic keywords; (3) builtin variables; (4) global or special variables, viz, identifiers that begin and end with an asterisk; (5) other variables; (6) comments; and (7) background punctuation.
To distinguish between the categories of Scheme 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 (or
perhaps other properties) of these classes in a style
sheet (section 4). Eg, the style sheet for
this document uses:
.scheme {color: brown} /* background punctuation */ .scheme .keyword {color: #990000; font-weight: bold} .scheme .builtin {color: #990000} .scheme .variable {color: navy} .scheme .global {color: purple} .scheme .selfeval {color: green} .scheme .comment {color: teal}
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
, eg,
\scmbuiltin{cons car cdr}
Users can add their own keywords with \scmkeyword
.
Eg,
\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 (eg, keywords or self-evaluators). Eg,
\scmvariable{and 42 +i}
TeX2page also syntax-highlights Scheme 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 Scheme comments. This is useful
if you want to highlight mentions of Scheme code inside
Scheme comments. To get the same effect with TeX2page,
declare \slatexlikecomments
before first use.
This
works with TeX2page's native \scm
too, not just
with the SLaTeX commands. Eg,
\scm{ (open-input-string ; in Scsh, use \scm{string->input-port} s) }
produces
(open-input-string ; in Scsh, use string->input-port
s)
\slatexlikecomments
is not an unmixed blessing,
however, as it restricts your Scheme comments to text
that is valid TeX. Use \noslatexlikecomments
to
go back to verbatim comments.
You can use TeX2page to do a form of literate
programming, ie, 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
(sec 5.3).
To specify code that should go into the external file but
should not be displayed, simply use
\verbwrite
instead of \scmdribble
.
5 For the DVI
output, you can use the definition for
\verbatiminput
in tex2page.tex
or, in LaTeX,
load the package verbatim.sty
. Note that the
latter only accepts a braced filename as argument.
tex2page.tex
will not overwrite the definition from
verbatim.sty
.
6
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{command}
,
instead of writing command
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
[8] or
--enable-write18
[36].