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

You could also use matching braces to enclose \verb’s argument, provided the latter does not contain unmatched braces. E.g.,

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

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.

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

5.1.1  Changing the verbatim escape character

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

\verbescapechar\@ 

makes ‘@’ the verbatim escape.

5.2  Inserting files verbatim

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

5.4  Verbatim style

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). E.g.,

.verbatim        {color: darkgreen} 

makes all verbatim text dark green.

5.5  Syntax-highlighting of program code

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

\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))))))

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

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). E.g., the style sheet for this document uses:

.scheme             {color: brown} /* background punctuation */ 
.scheme  .keyword   {color: black; 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, e.g.,

\scmbuiltin{cons car cdr} 

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} 

5.5.1  Using SLaTeX commands

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. E.g.,

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

5.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 (sec. 5.3).

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