NROFF(1)

NAME
nroff - text processing typesetter

SYNOPSIS
nroff [ options ] file [...]

DESCRIPTION
nroff is a text processor and formatter based on the design provided in "Software Tools" by Kernighan and Plauger. It has been modified to closely resemble the Unix(tm) nroff command. The text and commands found in the file(s) are processed to generate formatted text. Note that one (and only one) of the files can be "-" which reads input from stdin at that point. The output always goes to stdout which can be redirected by the shell. The -o option lets you redirect error output to the specified file rather than stderr. Debugging information always goes to the file "nroff.dbg" and is generally used only for program development.

OPTIONS
The following command line options are available:

-d  Set debug mode.

-h  Hold before exit (Atari TOS only).

-m<name>
    Process macro file tmac.<name>. Thus -man would cause the file tmac.an to be loaded. Note that files processed in this way should contain only macro definitions, no immediate output should be generated from this file (see ENVIRONMENT).

-o<file>
    Set error log file (default is stderr).

-raN
    Preset number register 'a' (single character) to N (decimal integer only).

-po<n>
    Shift output right n spaces (like .po).

-pn<n>
    Initial page number (like .pn).

-v  Prints the version information to stdout.

+<n>
    Causes output to start with page n.

-<n>
    Causes output to stop after page n.

-   Input from stdin.

ENVIRONMENT
nroff recognizes the following environment variables from the shell:

TMACDIR
    An alternate directory to find the files tmac.* ("." for example). The default is c:\lib\tmac under TOS and /usr/lib/tmac under Minix or Unix(tm).

TMPDIR
    An alternate directory to place any temporary files. The default is the current directory. Note that nroff does not currently use any temporary files.

COMMANDS
Commands typically are distinguished by a period in column one of the input followed by a two character abbreviation for the command funtion. The abbreviation may then be followed by an optional numeric or character argument. The numeric argument may be an absolute value such as setting the right margin to a particular column, or the argument may be preceded by a plus sign or a minus sign to indicate that the parameter should be modified relative to a previous setting. The following commands are recognized (those marked "extension" are requests added to the basic set provided by Unix(tm) nroff):

.ad Begin line adjustment. If fill mode is not on, adjustment is defered until it is back on. If a type indicator is present, the adjustment type is changed as follows:
         Indicator      Type
            l           adjust left margin only
            r           adjust right margin only
            c           center
         b or n         adjust both margins (default)
         absent         unchanged

.af Assign format to number register. The available formats are:
         Format    Numbering Sequence
           1       0,1,2,3,4,...
          001      000,001,002,...
           i       0,i,ii,iii,iv,v,...
           I       0,I,II,III,IV,V,...
           a       0,a,b,...,z,aa,ab,...zz,aaa,...
           A       0,A,B,...,Z,AA,AB,...ZZ,AAA,...
    The second format above indicates that the field width, i.e. number of digits, is specified by the number of digits in the format type.

.bd Ignored by nroff.

.bo Causes the following lines of text to appear in boldface. The optional argument specifies the number of lines to be typed in boldface. Boldface and underlining are mutually exclusive features. The appearance of a boldface command will cause any underlining to cease.

.bp Causes succeeding text to appear at the top of a new page. The optional argument specifies the page number for the new page. The initial value is one and the default value is one more than the previous page number.

.br Causes succeeding text to start on a new line at the current left margin. There is no numeric argument for this command.

.bs Enables or disables the appearance of backspaces in the output text. Underlining and boldface options are implemented by inserting character - backspace - character combinations into the output buffer. This is fine for devices which properly recognize the backspace character. Some printers, however, do not recognize backspaces, so the option is provided to overprint one line buffer with another. The first line buffer is terminated with just a carriage return rather than the carriage return - linefeed combination. A zero argument or no argument to the backspace command removes backspaces from the output. A non-zero argument leaves them in the output. The default is to remove backspaces.

.cc Changes the nroff command character to that specified by the character argument. If no argument is provided, the default is a period (.).

.ce Causes the next line of text to appear centered on the output. The optional argument specifies if more than one line is to be centered.

.cs Ignored by nroff.

.cu Causes the next line(s) of text to be continuously underlined. Unlike the underline command (see .ul) which underlines only alphanumerics, continuous underlining underlines all printable characters. The optional argument specifies the number of lines of text to underlined. Any normal underlining or boldface commands currently in effect will be terminated.

.c2 Changes the nroff no break character to that specified by the character argument. If no argument is provided, the default is a single quote.

.de Causes all text and commands following to be used to define a macro. The definition is terminated by a .en command or the default .. terminator. The first two characters of the argument following the .de command become the name of the new command. It should be noted that upper and lower case arguments are considered different. Thus, the commands .PP and .pp could define two different macros. Care should be exercised since existing commands may be redefined.

    A macro may contain up to nine arguments. In the macro definition, the placement of arguments is designated by the two character sequences, $1, $2, ... $9. When the macro is invoked, each argument of the macro command line is substituted for its corresponding designator in the expansion. The first argument of the macro command is substituted for the $1 in the expansion, the second argument for the $2, and so forth. Arguments are typically strings which do not contain blanks or tabs. If an argument is to contain blanks, then it should be surrounded by either single or double quotes.

.ds Define a string. To initiate the string with a blank or include blanks in the string, start it with a single or double quite. The string can contain other defined strings or number registers as well as normal text. Strings are stored on the macro name space.

.ec Changes the nroff escape character to that specified by the character argument. If no argument is provided, the default is a backslash.

.ef Specifies the text for the footer on even numbered pages. The format is the same as for the footer command (see .fo).

.eh Specifies the text for the header on even numbered pages. The format is the same as for the footer command (see .fo).

.en Designates the end of a macro definition.

.eo Turn the escape mechanism off.

.ex Exit nroff at this point in the processing. Ex forces all files closed and flushes the output.

.fi Causes the input text to be rearranged or filled to obtain the maximum word count possible between the previously set left and right margins. No argument is expected.

.fl Causes the output buffer to be flushed immediately.

.fo Specifies text to be used for a footer. The footer text contains three strings seperated by a delimiter character. The first non-blank character following the command is designated as the delimiter. The first text string is left justified to the current indentation value (specified by .in). The second string is centered between the current indentation value and the current right margin value (specified by .rm). The third string is right justified to the current right margin value. The absence of footer text will result in the footer being printed as one blank line. The presence of the page number character (set by .pc) in the footer text results in the current page number being inserted at that position. Multiple occurrances of the page number character are allowed.

.ft Changes the current font. The choices are R (Times Roman), I (Times Italic), B (Times Bold), S (math special), and P used to request the previous font. P resets the next previous font to be the one just changed, amounting to a swap.

.he Specifies text to be used for a header. The format is the same as for the footer (see .fo).

.if Execute a command if the condition is true. Format is:
         .if c command
         .if !c command
         .if N command
         .if !N command
         .if "str1"str2" command
         .if !"str1"str2" command
    Here c is a single letter: n (true if nroff), t (true if troff), e (true if even page), or o (true if odd page). N is a numerical experssion and can include operators +, -, *, /, % (mod), >, <, >=, <=, = (or ==), & (and), or : (or). If the result is greater than 0, the condition evaluates true. Numbers in the expression can be either constants or contents of number registers. Strings are tested using delimeter / or " only at this time. Note that "block" conditionals like:
         .if c \{\
         ...
         ...
         ...
    are not yet supported. Also the .ie/.el conditional is not yet supported.

.in Indents the left margin to the column value specified by the argument. The default left margin is set to zero.

.ju Causes blanks to be inserted between words in a line of output in order to align or justify the right margin. The default is to justify.

.lg Ignored by nroff.

.ll Sets the current line length. The default is eighty.

.ls Sets the line spacing to the value specified by the argument. The default is for single spacing.

.lt Set length of three-part titles. Line length and title length are independent. Indents do not apply to titles but page offsets do.

.m1 Specifies the number of lines in the header margin. This is the space from the physical top of page to and including the header text. A value of zero causes the header to not be printed. A value of one causes the header to appear at the physical top of page. Larger argument values cause the appropriate number of blank lines to appear before the header is printed.

.m2 Specifies the number of blank lines to be printed between the header line and the first line of the processed text.

.m3 Specifies the number of blank lines to be printed between the last line of processed text and the footer line.

.m4 Specifies the number of lines in the footer margin. This command affects the footer the same way the .m1 command affects the header.

.mc Margin character. The first argument is the character to use, the second is the distance to the right of the right margin to place the margin character. Useful for change bars. No arguments turns the capability off. Note that with this nroff, the margin character is always a single character only and this distance is prefered to be in inches (e.g. 0.2i). The default space is 0.2i (2 spaces).

.na Noadjust. Ajdustment is turned off; the right margin is ragged. The adjustment type for .ad is not changed. Output line filling still occurs if fill mode is on.

.ne Specifies a number of lines which should not be broken across a page boundary. If the number of lines remaining on a page is less than the value needed, then a new output page is started.

.nf Specifies that succeeding text should be printed without rearrangement, or with no fill. No argument is expected.

.nj Specifies that no attempt should be made to align or justify the right margin. No argument is expected.

.nr Causes the value of a number register to be set or modified. A total of twenty-six number registers are available designated \na through \nz (either upper or lower case is allowed). When the sequence \nc is imbedded in the text, the current value of number register c replaces the sequence, thus, such things as paragraph numbering can be accomplished with relative ease.

.of Specifies the text for the footer on odd numbered pages. The format is the same as the footer command (see .fo).

.oh Specifies the text for the header on odd numbered pages. The format is the same as the footer command (see .fo).

.pc Specifies the page number character to be used in headers and footers. The occurrance of this character in the header or footer text results in the current page number being printed. The default for this character is the percent sign (%).

.pl Specifies the page length or the number of lines per output page. The default is sixty-six.

.pm Print macros. The names and sizes of the macros are printed to stdout. This is useful when building a macro package to see how much of the total namespace is consumed by the package.

.pn Changes the page number of the current page and all subsequent pages to its argument. If no argument is given, the command is ignored.

.po Specifies a page offset value. This allows the formatted text to be shifted to the right by the number of spaces specified. This feature may also be invoked by a switch on the command line.

.ps Ignored by nroff.

.rr Removes a number register.

.so Causes input to be retrieved from the file specified by the command's character string argument. The contents of the new file are inserted into the output stream until an EOF is detected. Processing of the original file is then resumed. Command nesting is allowed.

.sp Specifies a number of blank lines to be output before printing the next line of text.

.ss Ignored by nroff.

.ti Temporarily alters the indentation or left margin value for a single succeeding input line.

.tl Specifies text to be used for a page title. The format is the same as for the header (see .he).

.ul Causes the next line(s) of text to be underlined. Unlike the .cu command, this command causes only alphanumerics to be underlined, skipping punctuation and white space. Underline and boldface are mutually exclusive.

The following nroff commands, normally available, are currently not implemented in this version: .fp, .mk, .rt, .vs, .sv, .os, .ns, .rs, .am, .as, .rm, .rn, .di, .da, .wh, .ch, .dt, .it, .em, .ta, .tc, .lc, .fc, .lg, .uf, .tr, .nh, .hy, .hc, .hw, .nm, .nn, .ie, .el, .ev, .rd, .ex, .nx, .pi, .tm, and .ig. +cc .

ESCAPE SEQUENCES
Escape sequences are used to access special characters (such as Greek letters) which may be outside the normal printable ASCII character set. The are also used to toggle certain actions such as font selection.

The escape sequences include:

\          backslash character
\          printable version of escape character
'          accute accent (equivalent to \(aa)
`          grave accent (equivalent to \(ga)
-          minus sign
.          period
<space>    a single, unpaddable space
           digit-width space
          16em space (zero space in nroff)
          112em space (zero space in nroff)
          non-printing zero-width character

          default hyphenation character
        special character named xx
,   interpolate string x or xx
         font change (c = R,I,B,S,P)
         interpolate number register x
	          horizontal tab

The Atari ST (TOS) version of nroff includes the following special characters. NOTE: THESE ARE NOT AVAILABLE UNDER Minix OR Unix(tm)!

©        copyright
®        registered
™        trademark
½        1/2
¼        1/4
        exponent 2
        exponent 3
        exponent n
´        acute
`        grave
°        degree
†        dagger
¢        cent
•        bullet
⊥        paragraph
ĝ        ring bell
↑        up arrow
↓        dn arrow
→        rt arrow
←        lf arrow
÷        divide
√        sq root
≡        ==
≥        >=
≤        <=
±        +-
≈        ~=
~        approx
¬        not
∈        memeber
∩        intersect
∪        union
α        alpha
β        beta
γ        gamma
δ        delta
σ        sigma
π        pi
μ        mu

PREDEFINED GENERAL NUMBER REGISTERS
The following number registers are available for both reading and writing. They are accessed with the \n(xx and \nx escape and can be set with .nr:
%           current page number
dw          current day of the week (1-7)
dy          current day of the month (1-31)
hh          current hours (0-23)
ln          current line number
mm          current minutes (0-59)
mo          current month (1-12)
ss          current seconds (0-59)
yr          last 2 digits of current year

The following number registers are available for reading only:
+cc .

NOTES
There are several missing features, notably diversions, traps, conditionals, all the hard stuff. This means you can't use some existing macro packages (yet, I hope). There is no complete -ms and -me packages as a result. The goal is to make this nroff work with all the SunOS macro packages sometime before Unix becomes obsolete!

If you make additions to this code, please mail the changes to me so I can make formal distributions.

BUGS
Undoubtedly more than I know about. Here are a few:

[GNO] This program uses recursion, which is Not a Good Thing on the IIgs. The current implementation has been compiled to use 6k of stack, which is entirely too much for a well behaved program of this size. Stack checking has been left activated, so if you run out of stack the worst you should get is an error message.

[GNO] The tmac.s macro package has not been reviewed recently and is not believed to be generally usable.

[GNO] The nroff(1), man(1), and ms(1) man pages don't completely follow the GNO style guidelines.

The ability to perform numerical calculations on registers is not implemented.

All dimensional units are in em's or inches only.

Lines with multiple string instances (i.e. \*(xx) don't seem to work.

Lines with font changes (e.g. for italics) use vt52 escape sequences to go to highlight mode. This should read termcap/terminfo to do it right.

Some interpolations don't work properly.

The code uses statically allocated arrays for macros, strings, and registers. This should be changed to dynamically allocated buffers or write to intermediate files on small memory systems (i.e. Minix).

FILES
/lib/tmac/tmac.*   predefined macros (see ENVIRONMENT)
nroff.dbg          debugging output
stderr             default error output stream
stdout             output stream

AUTHOR
Various bug fixes for GNO by Devin Reade <gdr@myrias.com>,
March 1997.
Adapted for Atari ST (TOS) and Minix by Bill Rosenkranz 11/89
net:    rosenkra@convex.com
CIS:    71460,17
GENIE:  W.ROSENKRANZ
Original author:
Stephen L. Browning
5723 North Parker Avenue
Indianapolis, Indiana 46220

HISTORY
Originally written in BDS C (by Stephen L. Browning?)
Adapted for standard C by W. N. Paul
Heavily hacked up to conform to the "real" nroff with numerous
additions by Bill Rosenkranz 11/89
Bug fixes (termcap) and Minix 1.5.5 compatibility by
Wim 'Blue Baron' van Dorst (wsincc@tuerc3.urc.tue.nl)

RECOMMENDATIONS
I envisioned this rather limited version as a way of formatting man pages for my Atari ST system. It works just fine for that. The man macro package is certainly adequate for that purpose. However, it would be nice to have more. I suggest you limit yourself to things which would port easily to other environments. All the man macros available here should port without effort to a more complete Unix(tm) environment.

nroff as it stands can certainly be useful. I recommend you don't use the commands marked "extension". Study the source for the man pages nroff(1), ms(7), and man(7) as well as the macro packages (tmac.an and tmac.s) and the examples to find out the quirks. Some things may not quite work like they do under Unix(tm), but it is fairly close for what is here.

REFERENCES
This document briefly describes the workings of nroff. It is certainly not the definitive work on text processing. I suggest you go out and get a good book (there are several on the market) or refer to the Unix(tm) manuals for more help. nroff is just like a compiler and is much more complicated than (say) the C language which only has a handful of rules and is much more thoroughly documented.

REQUEST SUMMARY
The following table summarizes the nroff requests currently available:
Request Form    Initial  Default  Notes   Explanation
--------------  -------  -------  ------- ----------------------
Font and Character Size Control
+ne 4
Page Control
+ne 4
Text Filling, Adjusting, and Centering
+ne 4
Vertical Spacing

+ne 4
Line Length and Indenting
+ne 4
Macros, Strings, Diversions, and Position Traps