4.3BSD-Reno/share/man/cat7/mdoc.samples.0
MDOC.SAMPLES(7) UNIX Reference Manual MDOC.SAMPLES(7)
NNAAMMEE
mmddoocc..ssaammppllee - detailed samples utilizing the --mmddoocc macro package
SSYYNNOOPPSSIISS
mmaann mmddoocc..ssaammppllee
DDEESSCCRRIIPPTTIIOONN
A fairly complete sampler of how the --mmddoocc macro package is used.
TTRROOFFFF IIDDIIOOSSYYNNCCRRAASSIIEESS
Although this is a content based formatting package, and theoretically
one should not have to learn troff(1) to use it, there are a few limita-
tions which are unavoidable and best gotten out of the way. And, too, be
forewarned, this package is slow. Its purpose is to allow translation of
man pages from troff(1) to TeX(Coming Soon) and vice versa.
MMaaccrroo UUssaaggee
As in troff(1), a macro (request) is called by placing a . (dot charac-
ter) at the beginning of a line followed by the two character name for
the macro. Arguments may follow the request separated by spaces. It is
the dot character at the beginning of the line which causes troff(1) to
interpret the next two characters as a request. To place a . (dot char-
acter) at the beginning of a line in some context other than a macro re-
quest, precede the . (dot) with a \&. In this macro package, some mac-
ros may be given the name of another macro as an argument. In this case
the argument, although the name of a macro, is not preceded by a .
(dot), and will be executed with the remaining arguments. It is in this
manner that some requests are nested, such as the .Op request may _c_a_l_l
the flag request .Fl.
[--llss] is produced by .Op Fl ls
The only requests which check to see if the first argument is executable
are:
.Cl Column Line Entry .Dp Display Examples (tagged paragraph)
.Cx Complex Expressions .Op Option Request
.Dl Display (one) Line .Sq Single Quotes
.Dq Double Quotes .Tp Tagged Paragraphs
The eligible first arguments are:
.Ad Addresses .Fn Functions
.Ar Arguments .Ic Interactive Commands
.Cl Column Entries .Li Literals
.Cm Command Modifiers .Nm Names, subjects
.Cw Column Widths .Op Options
.Cx Complex Expressions .Pa Pathnames
.Em Emphasis .Sy Symbolic
.Er Errno's .Tp Tagged Paragraphs
.Ev Environment .Va Variables
.Fl Flags .Xr Cross References
Requests which cannot be called, or call any other macro:
.Di Display Indent .Dw Display Tag Width
.De Display End .Pp Paragraph Start
.Df Display Filled .Tw Tagged Paragraph Tag Width
.Df Display unfilled
The macro .Op is unusual that it can call more than one request on the
same line.
PPaassssiinngg SSppaaccee CChhaarraacctteerrss iinn aann AArrgguummeenntt
To pass an argument to a macro request which contains spaces, the space
must be preceded by a \ to escape special interpretation:
iinntt **ffeettcchh() is created by .Fn int\ *fetch
For critical spaces at the end of a line, as might be needed with the re-
quest .Cx, following the space with \& is a good guarantee the space will
not be stripped (e.g. \ \&). A blank space at the end of a line is oth-
erwise an open invitation to party for troff(1).
EEssccaappiinngg SSppeecciiaall CChhaarraacctteerrss
Special characters like the newline character \n, are handled by replac-
ing the \ with \e (e.g. \en) to preserve the backslash.
HHEEAADDEERR RREEQQUUEESSTTSS
Three header macros designate the document title or manual page title,
the operating system, and the date of authorship (if not derived from
sccs(1) or rcs(1)). These macros are one called once at the very begin-
ning of the document and are used to construct the headers and footers
only.
.Dt DOCUMENT_TITLE section# [volume]
The document title is the subject of the man page and
must be in CAPITALS due to troff limitations. The sec-
tion number may be 1,...,8, and if it is specified, the
volume title may be omitted. A volume title may be arbi-
trary or one of the following:
AMD UNIX Ancestral Manual Documents
SMM UNIX System Manager's Manual
URM UNIX Reference Manual
PRM UNIX Programmers's Manual
.Os operating_system release#
The name of the operating system should be the common
acronym, e.g. BSD or ATT. The release should be the
standard release nomenclature for the system specified,
e.g. 4.3, 4.3+tahoe, V.3, V.4. Unrecognized arguments are
displayed as given in the page footer. For instance, for
the footer on this page, the 4.4 Berkeley Distribution
was produced by:
.Os BSD 4.4
.Dd month day, year
The date should be written formally:
January 25, 1989
TTEEXXTT MMAACCRROOSS
The following macro requests have similar syntax; the exceptions being
the behaviour of the request if called without an argument, and the
behaviour of the requests .Fn, .Pa, and .Xr, which expect a specific for-
mat. The other requests can handle up to 9 arguments and will format
punctuation properly as long as the punctuation is placed in the last ar-
guments. Punctuation placed in the middle of a string of text arguments
will result in a out of place space character.
Any argument which may be tested for punctuation and contains a member of
the mathematical, logical or quotation set
{+,-,/,*,%,<,>,<=,>=,=,==,&,`,',"} should have the character escaped.
AAddddrreessss RReeqquueesstt
The address request constructs and address of the form
addr1[,addr2[,addr3]].
.Ad Usage: .Ad address ... [.,;:()[]]
.Ad addr1 _a_d_d_r_1
.Ad addr1 . _a_d_d_r_1.
.Ad addr1 , file2 _a_d_d_r_1, _f_i_l_e_2
.Ad f1 , f2 , f3 : _f_1, _f_2, _f_3:
.Ad addr ) ) , _a_d_d_r)),
It is an error to call .Ad without arguments. The request may be called
by .Cl, .Cx, .Dl, .Dp, .Op or .Tp.
AArrgguummeenntt RReeqquueesstt
The .Ar argument request may be used whenever a command line argument is
referenced.
Usage: .Ar argument ... [.,;:()[]]
.Ar [_f_i_l_e ...]
.Ar file1 _f_i_l_e_1
.Ar file1 . _f_i_l_e_1.
.Ar file1 file2 _f_i_l_e_1 _f_i_l_e_2
.Ar f1 f2 f3 : _f_1 _f_2 _f_3:
.Ar file ) ) , _f_i_l_e)),
If .Ar is called with no arguments [_f_i_l_e ...] is assumed. The .Ar request
cannot call other macros, but may be called by .Cl, .Cx, .Dl, .Dp, .Op or
.Tp. See the .Op request for an example of using .Ar in combination with
the .Fl request.
DDoouubbllee QQuuoottee RReeqquueesstt
The .Dq double quote request may be used to surround a string with double
quotes. Punctuation is placed after the edn quote. To place punctuation
in inside the quotes it must be escaped with \&.
Usage: .Dq string ... [.,;:()[]]
.Dq ``''
.Dq string ``string''
.Dq string . ``string''.
.Dq fools and follies ``fools and follies''
.Dq Ar pattern ) ) , ``_p_a_t_t_e_r_n'')),
If .Dq is called with no arguments ``'' is assumed. The .Dq request may
call or be called by .Cl, .Cx, .Dl, .Dp, .Op .Sq, or .Tp.
The .Sq provides single quotes in the same manner as .Dq. Neither re-
quest can nest with in itself, but .Dq and .Sq can be nested with in each
other.
EEmmpphhaassiiss RReeqquueesstt
A portion of text may be stressed or emphasized with the .Em request.
The font used is commonly italic.
Usage: .Em argument ... [.,;:()[]]
.Em does not _d_o_e_s _n_o_t
.Em exceed 1024 . _e_x_c_e_e_d _1_0_2_4.
.Em vide infra ) ) , _v_i_d_e _i_n_f_r_a)),
It is an error to call .Em without arguments. The request cannot call
other macros, but may be invoked by .Cl, .Cx, .Dl, .Dp, .Op or .Tp.
EErrrrnnoo''ss ((SSeeccttiioonn''ss ttwwoo aanndd tthhrreeee oonnllyy))
The .Er errno request specifies the error return value for section two
and three library routines. The second example below shows .Er used with
the .Op request, as it would be used in the error section of a section
two manual page.
Usage: .Er ERRNOTYPE ... [.,;:()[]]
.Er ENOENT ENOENT
.Op Er ENOTDIR [ENOTDIR]
It is an error to call .Er without arguments. The request cannot call
other macros, but may be invoked by .Cl, .Cx, .Dl, .Dp, .Op or .Tp.
EEnnvviirroonnmmeenntt VVaarriiaabblleess
The .Ev request specifies a environment variable.
Usage: .Ev argument ... [.,;:()[]]
.Ev DISPLAY DISPLAY
.Ev PATH . PATH.
.Ev PRINTER ) ) , PRINTER)),
It is an error to call .Ev without arguments. The request cannot call
other macros, but may be invoked by .Cl, .Cx, .Dl, .Dp, .Op or .Tp.
FFllaaggss
The .Fl request handles command line flags. It prepends a dash, -, to the
flag. For interactive command flags, which are not prepended with a dash,
the .Cm request is identical, but with out the dash. The .Cm stands for
command modifier.
Usage: .Fl argument ... [.,;:()[]]
.Fl --
.Fl cfv --ccffvv
.Fl cfv . --ccffvv.
.Fl s v t --ss --vv --tt
.Fl - , ----,
.Fl xyz ) , --xxyyzz),
The .Fl request without any arguments results in a dash sign representing
stdin/stdout. Note that giving .Fl a single dash, will result in two
dashes. The request cannot call other macros, but may be invoked by .Cl,
.Cx, .Dl, .Dp, .Op or .Tp.
FFuunnccttiioonnss ((lliibbrraarryy rroouuttiinneess))
The .Fn request is modeled on ANSI C conventions. It may fail on old
style parameter lists.
Usage: .Fn [type\ ] function [[type\ ] params ... [.,;:()[]]
.Fn getchar ggeettcchhaarr()
.Fn strlen ) , ssttrrlleenn()),
.Fn strcpy char\ *dst char\ *src ssttrrccppyy(_c_h_a_r *_d_s_t, _c_h_a_r *_s_r_c)
.Fn int\ align int\ word iinntt aalliiggnn(_i_n_t _w_o_r_d)
.Fn void\ push int\ p int\ *ptr ,
vvooiidd ppuusshh(_i_n_t _p, _i_n_t *_p_t_r),
It is an error to call .Fn without any arguments. At the moment, .Fn
does not check its word boundaries against troff line lengths. It may
split across a line ungracefully. This will be fixed in the near future.
In the examples above, arguments with more than one word escape the blank
spaces with a \. The .Fn request cannot execute any macro names given as
the first argument. It may be called by the .Cl, .Cx, .Dl, .Dp, .Op or
.Tp.
LLiitteerraallss
The .Li literal request may be used for special characters, variable con-
stants, anything which should be displayed as it would be typed.
Usage: .Li argument ... [.,;:()[]]
.Li \en \n
.Li M1 M2 M3 ; M1 M2 M3;
.Li cntrl-D ) , cntrl-D),
.Li 1024 ... 1024 ...
It is an error to call .Li without arguments. The request cannot call
other macros, but may be invoked by .Cl, .Cx, .Dl, .Dp, .Op or .Tp.
NNaammee RReeqquueesstt
The .Nm request is used for the document title or subject name. It has
the peculiarity of remembering the first argument it was called with,
which should always be the subject name of the page. When called without
arguments, .Nm regurgitates this initial name for the sole purpose of
making less work for the author. Beyond the NAME section of the man
page, a section two or three document function name is addressed with the
Fn request, while .Nm can continue to be used for any other sections.
For interactive commands, such as the while command keyword in csh(1),
the .Ic request should be used. While the .Ic is nearly identical to
.Nm, it can not recall the first argument it was invoked with.
Usage: .Nm argument ... [.,;:()[]]
.Nm mdoc.sample mmddoocc..ssaammppllee
.Nm -mdoc --mmddoocc.
.Nm foo ) ) , ffoooo)),
.Nm mmddoocc..ssaammppllee
The .Nm request cannot call other macros, but may be called by .Cl, .Cx,
.Dl, .Dp, .Op or .Tp.
PPaatthhnnaammeess
The .Pa request formats path or file names. It has two different
behaviours. In any section of the man page _e_x_c_e_p_t the section FILES, it
expects at most one path or file name, and any amount of punctuation. In
the section FILES, it is often desirable to have a column of pathnames
and a column of pathname descriptions.
Usage: .Pa pathname [.,;:()[]]
.Pa /usr/share /_u_s_r/_s_h_a_r_e
.Pa /tmp/fooXXXXX ) . /_t_m_p/_f_o_o_X_X_X_X_X).
From within section FILES, use the .Dw and .Dp requests to format the
pathnames and their descriptions. .Pa request cannot call other macros,
but may be called by .Cl, .Cx, .Dl, .Dp, .Op or .Tp.
SSiinnggllee QQuuootteess
See the request .Dq above. The single quoting request .Sq works in the
same manner as .Dq.
SSyymmbboolliicc
The symbolic request is really a boldface request. The need for this
macro has not been established, it is included 'just in case'.
Usage: .Sy symbol ... [.,;:()[]]
.Sy something bold ssoommeetthhiinngg bboolldd
The .Sy request cannot call other macros, but can be called by .Cl, .Cx,
.Dl, .Dp, .Op or .Tp.
VVaarriiaabblleess
Generic variable reference:
Usage: .Va variable ... [.,;:()[]]
.Va count
_c_o_u_n_t
.Va settimer,
_s_e_t_t_i_m_e_r,
.Va int *prt ) :
_i_n_t *_p_r_t):
.Va char s ] ) ) ,
_c_h_a_r _s])),
CCrroossss RReeffeerreenncceess
The .Xr request expects the first argument to be a manual page name, and
the second argument, if it exists, to be either a section page number or
punctuation. Any remaining arguments are assumed to be punctuation.
Usage: .Xr manpage [1,...,8] [.,;:()[]]
.Xr mdoc mdoc
.Xr mdoc , mdoc,
.Xr mdoc 7 mdoc(7)
.Xr mdoc 7 ) ) , mdoc(7))),
The .Xr request cannot call other macros, but may be called by .Cl, .Cx,
.Dl, .Dp, .Op or .Tp. It is an error to call .Xr without any arguments.
PPAAGGEE LLAAYYOOUUTT MMAACCRROOSS
SSeeccttiioonn HHeeaaddeerrss
Several .Sh section header requests are required in every man page. The
.Sh request can take up to nine arguments.
.Sh NAME The .Sh NAME request is mandatory. If not speci-
fied, the headers, footers and page layout defaults
will not be set and things will be rather un-
pleasant. The NAME section consists of at least
three items. The first is the .Nm name request
naming the subject of the man page. The second is
the Name Description request, .Nd, which separates
the subject name from the third item, which is the
description. The description should be the most
terse and lucid possible, as the space available is
small.
.Sh SYNOPSIS The SYNOPSIS section describes the typical usage of
the subject of a man page. The requests required
are either .Nm or .Fn. The function name request
.Fn is required for manual page sections 2 and 3,
the command and general name request .Nm is re-
quired for the remaining sections 1, 4, 5, 6, 7, 8.
Several other requests may be necessary to produce
the synopsis line as shown below:
ccaatt [--bbeennssttuuvv] [--] [_f_i_l_e ...]
The following requests were used:
.Nm cat
.Op Fl benstuv
.Op Fl
.Ar
Note, the .Op request has accepted as its first ar-
gument the name of another macro _F_l. Upon discov-
ering the first argument is callable, .Op calls it
with the remaining arguments and returns the for-
matted text in option brackets.
.Sh DESCRIPTION In most cases the first text in the DESCRIPTION
section is a brief paragraph on the command, func-
tion or file, followed by a lexical list of options
and respective explanations. To create such a list,
the .Tp request is used in conjunction with text
macros, such as the .Fl macro (see the EXAMPLES
section below).
Other user specified .Sh sections may be added, for instance, in this
manual page
.Sh PAGE LAYOUT MACROS
was used for this section.
The following .Sh section headers are part of the preferred manual page
layout and must be used appropriately to maintain consistency. They are
listed in the order in which they would be used.
.Sh ENVIRONMENT The ENVIRONMENT section should reveal any related
environment variables and clues to their behaviour
and/or usage.
.Sh EXAMPLES There are several ways to create examples. See the
EXAMPLES section below for details.
.Sh FILES Files which are used or created by the man page
subject should be listed via the .Pa request in the
FILES section.
.Sh SEE ALSO References to other material on the man page topic
and cross references to other relevant man pages
should be placed in the SEE ALSO section. Cross
references are specified using the .Xr request. At
this time refer(1) style references are not accom-
modated.
.Sh STANDARDS If the command, library function or file adheres to
a specific implementation such as POSIX 1003.1 or
ANSI C X3.159-1989 this should be noted here. If
the command does not adhere to any standard, its
history should be noted in the HISTORY section.
.Sh HISTORY Any command which does not adhere to any specific
standards should be outlined historically in this
section.
.Sh AUTHORS Credits, if need be, should be placed here.
.Sh DIAGNOSTICS Diagnostics from a command should be placed in this
section.
.Sh ERRORS Specific error handling, especially from library
functions (man page sections 2 and 3) should go
here. The .Er request is used to specify an errno.
.Sh BUGS Blatant problems with the topic go here...
PPaarraaggrraapphhss aanndd LLiinnee SSppaacciinngg..
.Pp The .Pp paragraph command may be used to specify a
line space where necessary. The request is not
necessary after a .Sh or .Ss request or before a
.Tp or .Dp request.
CCoommpplleexx EExxpprreessssiioonnss
A complex expression is one combined of many different elements of text.
It is usually only necessary in particularly nasty man pages, such as
adb(1) or ex(1), where combinations of commands, addresses and symbols
may be needed. When pieces of text are processed, troff(1) assumes that
a space character will be desired after each word making it difficult to
combine expressions where different requests are used. .Cx merely glues
text together without spaces. Where a space is required, it must be
specified. A few examples:
This first example shows how to construct a simple expression with no
spacing in between:
.Cx (
.Va ax
.Sy +
(_a_x+_b_y+_c) _i_s _p_r_o_d_u_c_e_d _b_y .Va by
.Sy +
.Va c)
.Cx
This example shows the same equation in a different format. The spaces
around the + signs were forced with \:
.Cx (
.Va a
.Sy x
.Cx \ +\ \&
(_axx + _byy + _c) _i_s _p_r_o_d_u_c_e_d _b_y .Va b
.Sy y
.Cx \ +\ \&
.Va c)
.Cx
The incantation below was lifted from the adb(1) manual page:
.Cx Op Sy ?/
.Nm m
[??//]mm _b_1 _e_1 _f_1[??//] _i_s _p_r_o_d_u_c_e_d _b_y .Ar \ b1 e1 f1
.Op Sy ?/
.Cx
EExxaammpplleess aanndd DDiissppllaayyss
There are three types of displays, an indented one line display .Dl, a
non-filled block display Ds and a filled block display.
.Dl Display one line of indented text. The .Dl example request has
been used throughout this file. It's basic use is to indent
(display) one line of text for quick one line examples. Its default
font is set to constant width, however, .Dl checks the first argu-
ment to see if it is callable. It cannot process more than nine ar-
guments.
.Dl % ls -ldg /usr/local/bin
produces:
% ls -ldg /usr/local/bin
.Dl Fl ldghfstru
produces:
--llddgghhffssttrruu
Calling either the request .Tp or .Dp from .Dl is redundant and may
cause unpredictable errors.
.Ds Display a block of text as typed, right margin edges are left
ragged. Nesting .Ds requests seems to work, so they can be used
outside and within tagged paragraphs. Each .Ds request must be end-
ed with a De request. .Ds takes can be manipulated to indent with
the L, C, R, and I flags.
L Align block on the current left margin, this is the de-
fault mode of .Ds if called without arguments.
C Supposedly center the block. At this time unfortunately,
the block merely gets left aligned about an imaginary
center margin. This will be fixed some time inthe near
future.
I Indent from left margin default amount (usually about a
three quarters of an inch or eight constant width charac-
ters).
R This left aligns the block about two inches from the
right side of the page. It too, alas, needs work.
.De Ends a .Ds request.
.Df Display a filled (formatted) block. Identical to .Ds, except the
block of text is formatted (the edges are not left ragged). Takes
the same modifers as Ds.
TTaaggggeedd ppaarraaggrraapphhss aanndd CCoolluummnnss
The commands .Tp and .Dp create tagged paragraph lists. Like the .Cx re-
quest, both require a begin and end. When .Tp or .Dp are called with ar-
guments, they collect and create the tag portion from the arguments.
Anything after the tag is placed in the paragraph portion. The .Dp macro
is essentially the same as the .Tp macro, but with a few added features.
These are discussed following the .Tp example. .Tp and .Dp can call
several macros, these are:
.Ad, .Ar, .Cm, .Em, .Er, .Ev, .Fl, .Fn, .Ic,
.Li, .Nm, .Sy, .Va and .Xr.
The .Tp request can be nested, and values for determining the width of
each tag are based on which macro .Tp is calling, if it is calling one,
or by specifying a width with the .Tw request. The default width for an
unknown tag type is set to just about one and three quarter inches, or 20
characters in a constant width font. If the default width is unsatisfac-
tory, .Tw can be used as follows:
.Tw Fl sets the width to the default flag width .Fl, which
is set to ten constant width characters or about
five sixth of an inch.
.Tw 24n sets the width to 24 constant width characters or
about two inches. The n is absolutely necessary
for the scaling to work correctly.
.Tw ENAMETOOLONG
sets the width to the constant width length of the
string given.
.Tw int\ mkfifo
again, the width is set to the constant width of
the string given, and the space is protected with a
preceding \.
A nesting .Tp Example:
NNaammee11 This is the first call to .Tp with .Nm.
NNaammee22 Another call with .Nm.
_V_a_r_i_a_b_l_e_1 An example of the .Va request with .Tp. Since the
first argument was callable and different from the
last one, the tag was indented.
_V_a_r_i_a_b_l_e_2 Another .Va example.
--FFllaagg11 A third nest (indent) using the .Fl re-
quest.
--FFllaagg22 Again the .Fl
A .Tp with no arguments stops the current nest and
exdents back to the previous level.
_V_a_r_i_a_b_l_e_3 Another call with the .Va request.
Again a .Tp without arguments exdents. This will put us back
at the first level.
NNaammee33 Another .Nm request. This request is followed by the last call
to .Tp without arguments.
The above was created from:
.Tp Nm Name1
This is the first call to
.Li .Tp
with
.Li .Nm .
.Tp Nm Name2
Another call with
.Li .Nm .
.Tp Va Variable1
An example of the
.Li .Va
request with
.Li .Tp .
Since the first argument was callable and different from
the last one, the tag was indented.
.Tp Va Variable2
Another
.Li .Va
example.
.Tp Fl Flag1
A third nest (indent) using the
.Li .Fl
request.
.Tp Fl Flag2
Again the
.Li .Fl
.Tp
A
.Li .Tp
with no arguments stops the current nest
and exdents back to the previous level.
.Tp Va Variable3
Another call with the
.Li .Va
request.
.Tp
Again a
.Li .Tp
without argments exdents.
This will put us back at the first level.
.Tp Nm Name3
Another
.Li .Nm
request. This request is followed by the last call to
.Li .Tp
without arguments.
.Tp
An example of .Dp:
SL 10 sleep time of the process (seconds blocked)
PAGEIN 10 number of disk i/o's resulting from references by the
process to pages not loaded in core.
UID 10 numerical user-id of process owner
PPID 10 numerical id of parent of process process priority
(non-positive when in non-interruptible wait)
The raw text:
.Dw PAGEIN 10
.Dp SL 10
sleep time of the process (seconds blocked)
.Dp PAGEIN 10
number of disk i/o's resulting from references by the process
to pages not loaded in core.
.Dp UID 10
numerical user-id of process owner
.Dp PPID 10
numerical id of parent of process
process priority (non-positive when in non-interruptible wait)
.Dp
The default behaviour of .Dp is to indent a small amount from the current
margin before processing the tag. This margin can be changed with the
request .Di which takes as its first argument either a numerical argument
(e.g. a scaled number like 24n) or a letter L or I. The L forces a left
margin, which is useful if something doesn't quite fit (as in the example
for the .Fn macro in the TEXT MACRO section above). The I is the de-
fault, but may be used for a return to the default if necessary. Like
all the tagged widths, the indents are pushed on a stack, and when that
stack (or level) is expired, the previous values are used (this happens
whenever a .Dp or .Tp is called without arguments). In this example, .Dw
has been used to set the width of the tag. It is identical to the re-
quest .Tw discussed above.
CCoolluummnnss
The column request is made up of a width request, .Cw, and a column line
request, .Cl. From one to four simple columns can be created and all but
the last column, are simple single entry style columns. The last (right-
most) column can overflow into a indented paragraph.
The .Cw request takes at most three arguments as width indicators. The
number of columns is always one more than given to .Cw. the .Cl request
should have its arguments on the next line and the columns should be
separated by a tab character.
An example of two columns:
Macros Description
.Tp List Request
.Nm Name Request
The requests used to format the columns above (the jagged edges are from
tabs which can also be represented by \t):
.Cw Macros
.Cl Macros Description
.Cl \&.Tp List Request
.Cl \&.Nm Name Request
.Cw
There some problems with columns at the moment, while they work well in
nested lists, they are otherwise difficult to offset via example.
OOppttiioonnss
The .Op request ain't quite working perfectly. The (eventual) goal of
.Op is to place brackets around the given arguments, and place any punc-
tuation outside the brackets. In the case of .Cx, trailing punctuation
on the same request line as the .Op should be placed outside the brack-
ets. The multiple macro calls are one of the reasons this request is so
moody. Is is the only macro which attempts to call other macros on the
request line. Its not doing too badly, just not perfect:
.Op []
.Op Fl k [--kk]
.Op Fl k ) . [--kk]).
.Op Fl k Ar kookfile [--kk _k_o_o_k_f_i_l_e]
.Op Fl k Ar kookfile , [--kk _k_o_o_k_f_i_l_e],
.Op Ar objfil Op Ar corfil [_o_b_j_f_i_l [_c_o_r_f_i_l]]
.Op Fl c Ar objfil Op Ar corfil , [--cc _o_b_j_f_i_l [_c_o_r_f_i_l],]
.Op word1 word2 [word1 word2]
The punctuation on the second to last example is improperly placed and
should be fixed some day.
FFIILLEESS
/_u_s_r/_s_h_a_r_e/_t_m_a_c/_t_m_a_c._d_o_c manual macro package
/_u_s_r/_s_h_a_r_e/_m_a_n_0/_t_e_m_p_l_a_t_e._d_o_c template for writing a man page
HHIISSTTOORRYY
4.4 BSD
SSEEEE AALLSSOO
mdoc.samples(7), man(1), troff(1)
BBUUGGSS
Punctuation may be broken on .Op again.
Undesirable hyphenation on the dash of a flag argument is not yet
resolved, and causes occasional mishaps in the DESCRIPTION section.
Predefined strings are not declared in documentation.
Section 3f has not been added to the header routines.
.Nm font should be changed in NAME section.
.Fn needs to have a check to prevent splitting up if the line length is
too short. Right now it separates the last parenthesis, and sometimes
looks ridiculous if a line is in fill mode.
The method used to prevent header and footer page breaks (other than the
initial header and footer) when using nroff seems to be putting out a
partially filled line at the bottom of the page leaving an unsightly
blank space.
The tagged paragraph, display and column requests to not do any keeps and
certainly should be able to.
Occasionally there maybe a problem with mathematical or logical interpre-
tation of characters from the set {+,-,/,*,%,<,>,<=,>=,=,==,&} found as
the second character in an argument string which may be checked for punc-
tuation. This is a relatively rare occurrence, as a lot of checking is
done to prevent it, but if it should happen escape the characters with
\&.