mtex(7)

NAME

mtex - LaTeX-like file format for describing man pages

TABLE OF CONTENTS

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 Mosaic, nroff(1)/troff(1) (using the man(7) or man.nopage(7) macro packages), and 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 line commands are:

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:

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:

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.

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.

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:

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 Mon Jun 12 17:22:27 PDT 1995 by heydon