The MTeX File Format

## mtex(7)

### NAME

> mtex - LaTeX-like file format for describing man pages

### TABLE OF CONTENTS

> - Introduction
> - Input Characters
> - Comments
> - Paragraphs
> - Typeface Commands
> - The Manpage Command
> - The Section Command
> - Environments
> - The Verbatim Environment
> - The Flushleft Environment
> - The List Environments
> - Output-specific Environments
> - Anchors and Links
> - Examples
> - M3Build Support
> - Makefile Support
> - Diagnostics
> - Bugs
> - See Also

### INTRODUCTION

> This document describes mtex, a file format suitable for describing formatted man pages. The programs mtex2html(1), mtex2man(1), and mtex2tex(1) are filters that convert mtex documents into HTML-, man-, and LaTeX-formatted documents suitable for viewing with a World-Wide Web browser such as Netscape(1), with nroff(1)/troff(1) (using the man(7) or man.nopage(7) macro packages), and with latex(1)/xdvi(1) respectively.

> The mtex file format is loosely based on LaTeX, but it contains far fewer commands and is somewhat fragile. Like LaTeX, mtex commands are introduced by the `\` (backslash) character, and command arguments are delimited by curly braces `{ }`. Mtex also uses `\begin` and `\end` commands to bracket environments. Some commands have multiple arguments, in which case the arguments are specified like this:

>       \cmd{arg1}{arg2}...{argN}

> In such cases, the arguments may be separated by arbitrary whitespace. Unlike LaTeX, braces are not used in mtex to delimit scopes; they are used only to delimit arguments.

> Except where noted below, the filter programs parse mtex files as a sequence of whitespace-separated tokens. The programs for viewing the resulting output files automatically fill paragraphs, so how the input is divided into lines is generally unimportant. There are a few exceptions to this rule. For example, certain commands must start at the beginning of a line, and text within the `verbatim` environment is not "filled" or justified.

> The mtex commands may be divided into two groups: running commands and line commands. The running commands may appear anywhere in running text. The line commands must appear at the start of a new line, and they generally cause a line break in the output.

> The running commands are:

> - the typeface-changing commands: `\bf`, `\it`, `\tt`;
> - the hypertext commands: `\link`, `\anchor`; and
> - the line-breaking command: `\newline`.

> The line commands are:

> - the command to declare a man page: `\manpage`;
> - the command to start a new section: `\section`;
> - the commands for bracketing environments: `\begin`, `\end`; and
> - the command for starting a new list item: `\item`

### INPUT CHARACTERS

> Any character is legal in an mtex file, but five characters are special.

> Commands in mtex begin with a '`\`' (backslash) character, and have arguments enclosed by `{` braces `}`. The backslash character is also used to escape other characters, as described below. Hence, these three characters are special. Braces that do not delimit arguments may appear in your input. However, to include a closing brace in the argument to a command, you must escape it as described below.

> As in TeX, double-quotes are indicated by pairs of single quotes: the input ```hello''` produces "hello". Hence each of the single quote characters is special. Stand-alone single quote characters may appear in your input (for example, as an apostrophe in a conjunction or possessive). However, to produce two consecutive single quote characters like ```this''`, you must escape the characters as described below.

> Each of the five special characters may be escaped with the backslash character itself:

> - `\\` produces backslash (`\`)
> - `\{` produces left brace (`{`)
> - `\}` produces right brace (`}`)
> - `\`` produces single left quote (```)
> - `\'` produces single right quote (`'`)

> The escape for the left brace character is not strictly necessary; it is provided only for symmetry.

> You are advised not to use the double-quote character in your input, since there is no way to reliably specify this character in nroff input. In particular, double-quote is known not to work in the arguments of the `\manpage` and `\section` commands. Use ```` and `''` wherever possible.

> For each output format, certain additional characters are special. For example, in HTML, the "`<`" character is special; to produce it in an HTML file for viewing, you would have to write "`&lt;`". Each of the filter programs translates the characters that are special for its output format automatically, so mtex2html(1) will in fact convert the input "`a < b`" to produce "`a &lt; b`" in the HTML output.

> To include one of the output-specific characters in the output without translating it, you can escape the character with a `\` (backslash). However, since such escape sequences are output-specific, they are only allowed in the output-specific environments described below.

### COMMENTS

> Lines beginning with the `%` (percent) character start comments in the input file. All characters from the percent character up to and including the first newline character are ignored.

> To include a percent character in your output, simply make sure that it does not appear at the start of an input line.

### PARAGRAPHS

> Paragraphs in the input are separated by one or more consecutive blank lines. Both mtex2html(1) and mtex2man(1) produce a single blank line in the output at the start of a new paragraph; mtex2tex(1) indents the first line of the new paragraph without skipping a line.

### TYPEFACE COMMANDS

> The mtex format includes commands for typesetting short bits of text in a bold, italic, or `typewriter` typeface:

> - `\bf{<Text>}` typesets `<Text>` in bold face
> - `\it{<Text>}` typesets `<Text>` in italics
> - `\tt{<Text>}` typesets `<Text>` in `typewriter font`

> The syntax of these commands is slightly different from standard TeX, since the arguments are expected to be short, and only one alternative typeface should be used at a time.

> Typeface commands may be nested, but the output will probably not be what you expect. For example, the input `\it{one \bf{bold} word}` will most likely set the words "one" and "word" in an italic typeface, but the word "bold" in a bold roman typeface, not a bold italic typeface.

> Typeface commands may appear in running text, but it is an unchecked error to include them in arguments to the `\manpage` and `\section` commands, since these commands automatically typeset their arguments in an output-dependent way.

### THE MANPAGE COMMAND

> Every mtex manpage should begin with the manpage command. It has the format:

>       \manpage{<PageTitle>}{<Name>}{<Section>}

> The `<PageTitle>` is the nominal title for this page, and is used in HTML output only. The `<Name>` value should be the name of the command or routine, and `<Section>` should be the section of the manual in which this man page appears. For example, the source for this manpage begins with the line:

>       \manpage{The MTeX File Format}{mtex}{7}

> The `\manpage` command must start on its own line, and no other non-whitespace characters may appear after its last argument on the same line. Any blank lines after it are ignored. The arguments should not include typeface commands.

### THE SECTION COMMAND

> New man page sections are introduced with the `\section` command, which has the form:

>       \section{<Text>}

> The `<Text>` will be typeset as a section title, indicated by typeface, font size, or indentation level. The `\section` command must start on its own line, and no other non-whitespace characters may appear after its argument on the same line. Only `\link` and `\anchor` commands may be used within the `<Text>` argument.

### ENVIRONMENTS

> An environment is a syntactic scope for formatting multiple input lines in a certain way. For example, the lines in a verbatim environment are formatted in a fixed-width font without being filled or justified.

> The lines of an environment are delimited by a matching `\begin`-`\end` pair, like this:

>       \begin{<EnvType>}
>       ...
>       \end{<EnvType>}

> Environments may be nested, but matching `\begin` and `\end` lines must have matching `<EnvType>` arguments. The legal `<EnvType>` values are verbatim; flushleft; the list environments itemize, enumerate, and description; and the output-specific environments html, roff, and tex.

> Both the `\begin` and `\end` commands must start on their own lines, and neither may be followed by any non-whitespace characters.

### THE VERBATIM ENVIRONMENT

> Text within the verbatim environment is typeset in a fixed-width font and is not filled. This means that whitespace within this environment is significant. Moreover, no characters within this environment are special, so in particular, all commands are ignored; special characters need not be escaped by a preceding backslash.

> Regardless of whether there are blank lines before and/or after the verbatim environment, the verbatim text will be preceeded and followed by a blank line in the formated output.

### THE FLUSHLEFT ENVIRONMENT

> Normally, the lines of a paragraph are filled automatically by the programs that process the output produced by the mtex filters. To produce ragged-right text in which you specify the line break positions manually, use the flushleft environment together with the `\newline` command.

> Within the flushleft environment, `\newline` starts a new line of output flush with the current left margin. Only whitespace characters are allowed to follow this command on its line. It is an error for `\newline` to occur outside the scope of a flushleft environment.

> For example, the input:

>       \begin{flushleft}
>       Systems Research Center\newline
>       131 Lytton Avenue\newline
>       Palo Alto, CA 94301
>       \end{flushleft}

> produces

> Systems Research Center
> 131 Lytton Avenue
> Palo Alto, CA 94301

### THE LIST ENVIRONMENTS

> Mtex provides three list environments for formatting a list of items: itemize, enumerate, and description. Items within the itemize environment are set off by tick marks, those within the enumerate environment are set off by cardinal numbers, and those within the description environment are set off by a user-supplied string.

> Items within the three list environment are denoted by the `\item` command. In the itemize and enumerate environments, this command has no arguments, but in the description environment, it has a single argument which is the description string. Typeface changes are allowed within this argument, as are the other running commands, but the backslash escape sequence "`\\`" should not be used in this argument.

> Paragraph breaks may be used between and within items to produce blank lines in the formatted output. However, since the text of items within the itemize and enumerate environments is expected to immediately follow the tick mark or cardinal tag, you are advised not to follow the zero-argument `\item` command with a paragraph break.

> List environments may be nested arbitrarily, but the introduction of a new list environment indents the output, so nestings more than three deep are not advised.

> The following example captures many of the possible ways in which the list environments can be used. The input:

>       \begin{description}
>       \item{The \it{itemize} environment}
>       The \it{itemize} environment yields itemized lists:
>       \begin{itemize}
>       \item indented
>       \item set off by tick marks
>       \end{itemize}

>       \item{The \it{enumerate} environment}
>       The items within \it{enumerate} are numbered:
>       \begin{enumerate}
>       \item start your manpage with \tt{\\manpage}
>       \item then, use \tt{\\section} for the sections
>       \end{enumerate}
>       The numbers are produced automatically.

>       \item{The \it{description} environment}
>       In the \it{description} environment, each item is
>       labeled with a user-supplied string.

>       Notice that blank lines within an item produce
>       paragraph breaks in the formatted output.
>       \end{description}

> produces:

> The itemize environment
>   The itemize environment yields itemized lists:
>   - indented
>   - set off by tick marks

> The enumerate environment
>   The items within enumerate are numbered:
>   1. start your manpage with `\manpage`
>   2. then, use `\section` for the sections
>   The numbers are produced automatically.

> The description environment
>   In the description environment, each item is labeled with a user-supplied string.

>   Notice that blank lines within an item produce paragraph breaks in the formatted output.

### OUTPUT-SPECIFIC ENVIRONMENTS

> The html, roff, and tex environments can be used to include text for one particular output format. Text within the html environment is only processed by the mtex2html(1) filter, text within the roff environment is only processed by the mtex2man(1) filter, and text within the tex environment is only processed by the mtex2tex(1) filter.

> The special characters particular to an output format are converted in each of these environments. If you want to include any of them literally, you must escape them. For example, the following code includes an inlined image in the HTML file produced by mtex2html(1), but is ignored by the other filters:

>       \begin{html}
>       \<IMG SRC="image.gif"\>
>       \end{html}

> Notice how the `<` and `>` characters are escaped in this example, since those two characters are special for HTML. Each of the man pages for the filter programs has a section listing the characters that are special for its output format.

### ANCHORS AND LINKS

> You can create anchor locations using the `\anchor` command, and links to other documents or to anchors in the current document using the `\link` command. Both of these commands are running commands and may appear anywhere in the input.

> The syntax of the anchor command is:

>       \anchor{<Name>}{<Text>}

> This associates an anchor named `<Name>` with the text `<Text>`. The `<Text>` argument may contain other running commands, such as the typeface commands.

> The syntax of the link command is:

>       \link{<Anchor>}{<Text>}

> This makes the text `<Text>` a link to the anchor `<Anchor>`. The `<Anchor>` argument may be any legal HTML anchor, as described in The Beginner's Guide to HTML. If you want the link to point to an anchor within the same document, `<Anchor>` should start with the `#` (pound-sign) character.

> Here is an example of a file with an anchor and a link to that local anchor:

>       \section{\anchor{DescSect}{Description}}
>       Here is the description section text...

>       Later in the file, here is a link to
>       the \link{#DescSect}{description} section.

>       Here is a non-local link to the
>       \link{http://src-www.pa.dec.com/src.home.html}
>       {SRC Home Page}.

> Notice in the second `\link` example how we've taken advantage of the fact that command arguments may be separated by arbitrary amounts of whitespace.

### EXAMPLES

> Here is the mtex source for the quake(1L) man page:

>       \manpage{quake}{quake}{1L}

>       \section{NAME}
>       quake - a system for compiling Modula-3 program descriptions

>       \section{SYNOPSIS}
>       \bf{quake} [-nV] [definitions | files ...]

>       \section{DESCRIPTION}
>       Quake is a simple, specialized language and its interpreter
>       drawing on elements of the C language, the Bourne shell, and
>       the C pre-processor. It was designed to be a component of
>       m3build(1)-the replacement for m3make (q.v.). Building a
>       complete, general-purpose language was not one of the goals.

>       For a full description, see URL:

>       \link{http://www.research.digital.com/SRC/modula-3/html/quake/quake.html}
>       {http://www.research.digital.com/SRC/modula-3/html/quake/quake.html}

>       \section{SEE ALSO}
>       m3build(1)

>       \section{AUTHOR}
>       Stephen Harrison

> Here is the mtex source of a slightly more complicated man page --- the mtex2html(1) man page itself:

>       \manpage{mtex2html Man Page}{mtex2html}{1}

>       \section{NAME}

>       mtex2html - translate mtex(7) files to HTML format

>       \section{SYNTAX}

>       \bf{mtex2html}

>       \section{DESCRIPTION}

>       \it{mtex2html} is a filter that reads a file in \link{mtex.7.html}
>       {mtex(7)} format from its standard input, and writes an
>       \link{http://www.ncsa.uiuc.edu/General/Internet/WWW/HTMLPrimer.html}{HTML
>       (HyperText Markup Language)} file to standard output suitable for viewing
>       with xmosaic(1).

>       \it{mtex2html} is written entirely in LIM (see lim(1)).

>       \section{SPECIAL CHARACTERS}

>       There are three special characters for the HTML output format. Here
>       are the characters and the strings they are translated to by
>       mtex2html(1):

>       \begin{flushleft}
>       ``\tt{<}'' becomes ``\tt{&lt;}''\newline
>       ``\tt{>}'' becomes ``\tt{&gt;}''\newline
>       ``\tt{&}'' becomes ``\tt{&amp;}''
>       \end{flushleft}

>       To prevent these characters from being translated within the
>       scope of an \it{html} environment, you must escape them with a
>       \tt{\\} (backslash) character.

>       \section{DIAGNOSTICS}

>       See the \link{mtex.7.html#Diagnostics}{Diagnostics} section of the
>       \link{mtex.7.html}{mtex(7)} manpage for a complete description.

>       \section{SEE ALSO}

>       \link{mtex.7.html}{mtex(7)},
>       \link{mtex2man.1.html}{mtex2man(1)},
>       \link{mtex2tex.1.html}{mtex2tex(1)},
>       xmosaic(1)
>       \begin{roff}

>       This man page is also available as a hypertext document under
>       Mosaic at URL
>       \tt{http://src-www.pa.dec.com/SRC/man/DS/mtex2html.1.html}.
>       \end{roff}

>       \section{AUTHOR OF PROGRAM AND DOCUMENTATION}

>       \link{http://src-www.pa.dec.com/SRC/people/Allan_Heydon/bio.html}
>       {Allan Heydon} (\tt{heydon@src.dec.com})

> Note the use of the roff environment in the SEE ALSO section. The text within this environment will not appear in the HTML file produced by the mtex2html(1) filter program.

### M3BUILD SUPPORT

> To build and install HTML- and man-formatted output files automatically using m3build(1), just add the following lines to your m3makefile:

>       import("mtex")
>       Mtex(<title>, <section>)

> You should have one `Mtex` line for each man page; you should have exactly one `import("mtex")` line (and it must appear before the `Mtex` lines).

> Each `Mtex` line runs mtex2html(1) and mtex2man(1) on the file named "<title>.<section>.mtex" in your source directory. The corresponding derived files are called "<title>.<section>.html" and "<title>.<section>". For example, the lines:

>       import("mtex")
>       Mtex("Juno", 1)

> cause the file "Juno.1.mtex" to be used as a source to produce the derived files "Juno.1.html" and "Juno.1". When you ship your package, the man-formatted man pages are installed as per the `ManExport` function, and the HTML-formatted pages are installed in a site-specific subdirectory of the default HTML export directory. At SRC, they are installed in:

>       /proj/www/SRC/man/<BuildDir>

> where "<BuildDir>" is the name of the build directory, such as "DS" or "AOSF".

### MAKEFILE SUPPORT

> To build HTML-, man-, and LaTeX-formatted output files automatically using make(1), you can add the following line to your Makefile:

>       include /proj/cra/pkg/mtex/mtex.makestub

> This includes the dependency rules specified in the `mtex.makestub` file, whose contents are:

>       .SUFFIXES: .txt .tex .man .html .mtex

>       .mtex.html: ; mtex2html < $? > $@
>       .mtex.man:  ; mtex2man < $? > $@
>       .mtex.tex:  ; mtex2tex < $? > $@
>       .man.txt:   ; nroff -man.nopage $? > $@

> This file specifies rules for building the HTML-, man-, and LaTeX-formatted manpages using the mtex2html(1), mtex2man(1), and mtex2tex(1) filter programs. The last line uses nroff(1) to produce an ASCII version of the manpage from the man-formatted version.

> This makefile stub defines rules for converting ".`mtex`" files to ".`html`", ".`man`", ".`tex`", and ".`txt`" files. Typically, your filename will include a section number, so the mtex source file will have the form "<name>.<sect>.`mtex`". With the above rules, you'll get files of the form "<name>.<sect>.`html`" and "<name>.<sect>.`man`". The former is fine to ship, but the latter is not, since the ".man" extension is extraneous. Tim Mann has discovered some make(1) magic for shipping the files correctly (this is only known to work with the version of make(1) running on OSF/1).

> First, you'll need to define variables for naming the man pages. Since man pages for different sections are shipped to different places, you'll have to divide your package's man pages by section. Here's an example for the mtex man pages:

>     MAN1_DOCS = mtextohtml.1 mtextoman.1 mtextotex.1
>     MAN7_DOCS = mtex.7
>     MAN_DOCS  = $(MAN1_DOCS) $(MAN7_DOCS)
>     HTML_DOCS = $(MAN_DOCS/$/.html)

> The magic in the definition of `HTML_DOCS` expands to a list of files of the form "<name>.<sect>.`html`". Now, the line for building all of the documents is:

>     docs: $(HTML_DOCS) $(MAN_DOCS/$/.man)

> The magic at the end of this line expands to a list of files of the form "<name>.<sect>.`man`". Hence, typing "`make` `docs`" produces a set of ".`html`" and ".`man`" files.

> All that remains now is to ship the files to correct places with the correct names. At SRC, the roff-formated man pages are shipped to the directory

>       /proj/man/<arch>/man<sect>/

> where <arch> is either "`alpha`" or "`mips`", and <sect> is the manual section number. The HTML-formatted man pages are shipped to the directory

>       /proj/www/SRC/man/<arch>/

> where <arch> is either "`AOSF`" or "`DS`". Here is a typical shippackage(1) line:

>     ship: tidy
>             shippackage $(PACKAGE)\
>               -l /proj/www/SRC/man/AOSF $(HTML_DOCS)\
>               -l /proj/man/alpha/man1 $(MAN1_DOCS/*/&=&.man)\
>               -l /proj/man/alpha/man7 $(MAN7_DOCS/*/&=&.man)

> The make magic in the lines for shipping the roff-formatted man pages expands to a list of expressions of the form "<name>.<sect>=<name>.<sect>.`man`". This causes the link to be made to the ".`man`" file in the current directory, but for the shipped link to have the name "<name>.<sect>", as required.

### DIAGNOSTICS

> All of the filter programs use the same core program to do their processing, so they all have the same diagnostics.

> If there are any errors in the input, the filter prints a descriptive error message followed by the line of the filter program at which the program aborted together with the number of characters read and written at the time of failure. In this case, the process exits with Unix exit code 2. If there were no errors, the process exits with Unix exit code 0.

> Each error message gives a line number and a description of the error. The possible error messages and their meanings are:

> - `command must appear at start of line`

>   One of the line commands `\manpage`, `\section`, `\begin`, `\end` or `\item` on the indicated line does not appear at the start the a line.

> - `command not followed by left brace`

>   The command on the indicated line is a known command, but it has at least one argument. The command name must be followed immediately by a left brace (`{`) character.

> - `no text allowed after command on this line`

>   Either the `\newline` command or one of the line commands `\manpage`, `\section`, `\begin`, or `\end` on the indicated line has a non-whitespace character after its last argument on the same line as that argument.

> - `command illegal in argument begun on line <X>`

>   One of the commands `\manpage`, `\section`, `\begin`, `\end`, `\item`, or `\newline` on the indicated line appears within a command argument. The opening left brace of the argument is on line number `<X>`. You may have simply left out the closing right brace. Only the running commands `\bf`, `\it`, `\tt`, `\link`, and `\anchor` are allowed to appear in command arguments.

> - `command illegal in list environment`

>   The `\manpage` and `\section` commands must appear at top-level; they are not allowed to appear within one of the list environments.

> - `syntax error in \<cmd>`

>   A syntax error occurred while parsing the named `<cmd>` starting on the specified line. Most likely this is due to a missing argument or to an incorrect curly brace. Command syntax is described in the Introduction section above.

> - `unrecognized command or special character "\<cmd>"`

>   A `\` (backslash) character on the specified line is followed by the characters `<cmd>` that are neither a command, one of the five escape characters listed in the Input Characters section, nor one of the special characters for this output format.

> - `illegal output-specific quoted character "\<char>"`

>   The quoted character `<char>` is special for this output format, but does not appear inside the corresponding output-specific environment.

> - `unrecognized \begin/\end argument`

>   The argument to the `\begin` or `\end` command on the specified line is not one of: `verbatim`, `flushleft`, `itemize`, `enumerate`, `description`, `html`, `roff`, or `tex`.

> - `not expecting \end`

>   An `\end` command was encountered for which there is no matching `\begin`, or which is contained within the argument to a command.

> - `expecting \end{<env>}`

>   The most recent `\begin` command introduced the environment `<env>`, but the `\end` command on the specified line closes a different environment.

> - `no matching \end for \begin`

>   End-of-file was reached before an `\end` command was found that matches the `\begin` command on the specified line.

> - `no matching right brace for \<cmd>`

>   A matching right brace could not be found for one of the arguments to the command `<cmd>`. In this case, the line number given is that on which the command begins.

> - `\newline not in flushleft environment`

>   The `\newline` command is only allowed to appear in the scope of a flushleft environment.

> - `\item should not have an argument in itemize/enumerate environment`

>   The `\item` command on the specified line has an argument, yet it should not because it appears within either an `itemize` or `enumerate` environment.

> - `\item must have an argument in description environment`

>   The `\item` command on the specified line has no argument, yet it should because it appears within a `description` environment.

> - `\item not in list environment`

>   The `\item` command on the specified line does not appear in a list environment.

### BUGS

> There are no provisions for distinguishing between dashes, hyphens, and minus signs.

> The `"` (double-quote) and `\` (backslash) characters should work in all circumstances. They don't due to difficulties with nroff(1) and the man(7) macros.

### SEE ALSO

> mtex2html(1), mtex2man(1), mtex2tex(1)
> make(1), latex(1), xdvi(1), xmosaic(1)
> nroff(1), troff(1), man(7), man.nopage(7)

### AUTHOR OF DOCUMENTATION

> Allan Heydon (`heydon@src.dec.com`)

>     Last modified on Tue Nov  7 10:41:29 PST 1995 by heydon