4  Verbatim text

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. 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: a car and a cdr.

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} types The 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.

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.

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.

4.1  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.

4.1.1  Changing the verbatim escape character

You can use the macro \verbescapechar to postulate a character other than `|' as the verbatim escape. Eg,

\verbescapechar\@

makes `@' the verbatim escape.

4.2  Inserting files verbatim

You can insert files verbatim with the command \verbinput. Usage:

\verbinput progam.scm

This displays the contents of the file program.scm ``as is''. Useful for listings.

4.3  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 \verbfilename. Eg,

\verbfilename notes-to-myself.txt

This will cause subsequent calls to \verbwrite upto the next \verbfilename or end of document (whichever comes first) to send text into the file notes-to-myself.txt.

4.4  Verbatim style

The verbatim commands \verb, \path and \verbinput 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 (sec 7). Eg,

.verbatim        {color: darkgreen}

makes all verbatim text dark green.

4.5  Syntax-highlighting of program code

The commands \scm and \scminput are variants of \verb and \verbinput. 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))))))

Six categories of code text are distinguished:

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

2. syntactic keywords;

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

4. other variables;

5. comments; and

6. background punctuation.

To distinguish between the categories of Scheme code text, TeX2page uses a style class called scheme with five subclasses, viz, selfeval, keyword, global, variable, and comment. You can set the color property (or perhaps other properties) of these classes in a style sheet. Eg, the style sheet for this document uses

.scheme             {color: brown} /* background punctuation */
.scheme  .keyword   {color: #cc0000; font-weight: bold}
.scheme  .variable  {color: navy}
.scheme  .global    {color: purple}
.scheme  .selfeval  {color: green}
.scheme  .comment   {color: teal}

Users can add their own keywords and constants with \scmkeyword and \scmconstant. Eg,

\scmkeyword{define-class unwind-protect}

4.6  Documenting your code

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 a code file. The code file has by default the same basename as the document, but with extension .scm.

To specify another code file, use \scmfilename. Eg,

\scmfilename factorial.lisp

This will cause subsequent \scmdribbled code upto the next \scmfilename or end of document (whichever comes first) to go into the file factorial.lisp.

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