.\" Copyright (c) 1990 The Regents of the University of California.
.\" %sccs.include.redist.man%
.\" @(#)mdoc.samples.7 5.3 (Berkeley) %G%
.\" This sampler invokes every macro in the package several
.\" times and is garanteed to give a worst case performance
.\" for an already slow package.
.Nd detailed samples utilizing
A fairly complete sampler of how the
Although this is a content based formatting package, and
theoretically one should not have to learn
to use it, there are a few
limitations 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
a macro (request) is called by placing a
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
to interpret the next two characters as a request.
at the beginning of a line in some context other than
a macro request, precede the
In this macro package, some macros may be given the
name of another macro as an argument. In this case
the argument, although the name of a macro,
with the remaining arguments.
It is in this manner that some requests are nested, such
The only requests which check to see if the first argument
.Cw \&.Cx\ Complex\ Expressions
.Cl \&.Cl\ Column Line Entry \&.Dp Display Examples (tagged paragraph)
.Cl \&.Cx\ Complex\ Expressions \&.Op\ Option Request
.Cl \&.Dl\ Display (one) Line \&.Sq Single Quotes
.Cl \&.Dq\ Double Quotes \&.Tp Tagged Paragraphs
The eligible first arguments are:
.Cw \&.Cx\ Complex\ Expressions
.Cl \&.Ad Addresses \&.Fn Functions
.Cl \&.Ar Arguments \&.Ic Interactive Commands
.Cl \&.Cl Column Entries \&.Li Literals
.Cl \&.Cm Command Modifiers \&.Nm Names, subjects
.Cl \&.Cw Column Widths \&.Op Options
.Cl \&.Cx Complex Expressions \&.Pa Pathnames
.Cl \&.Em Emphasis \&.Sy Symbolic
.Cl \&.Er Errno's \&.Tp Tagged Paragraphs
.Cl \&.Ev Environment \&.Va Variables
.Cl \&.Fl Flags \&.Xr Cross References
Requests which cannot be called, or call any other macro:
.Cw \&.Cx\ Complex\ Expressions
.Cl \&.Di Display Indent \&.Dw Display Tag Width
.Cl \&.De Display End \&.Pp Paragraph Start
.Cl \&.Df Display Filled \&.Tw Tagged Paragraph Tag Width
.Cl \&.Df Display unfilled
is unusual that it can call more than one request on the same
.Ss Passing Space Characters in an Argument
to a macro request which contains spaces, the space must be preceded
to escape special interpretation:
For critical spaces at the end of a line, as might be needed
is a good guarantee the space will not be stripped (e.g.
A blank space at the end of a line is otherwise an open invitation
.Ss Escaping Special Characters
like the newline character
are handled by replacing the
Three header macros designate the document title or manual page title,
and the date of authorship (if not derived from
These macros are one called once at the very beginning of the document
and are used to construct the headers and footers only.
.Tp Li \&.Dt DOCUMENT_TITLE section# [volume]
The document title is the
subject of the man page and must be in CAPITALS due to troff
The section number may be 1,...,8,
the volume title may be omitted.
A volume title may be arbitrary or one of the following:
.\" USD UNIX User's Supplementary Documents
.\" PS1 UNIX Programmers's Supplementary Documents
.Cl AMD UNIX Ancestral Manual Documents
.Cl SMM UNIX System Manager's Manual
.Cl URM UNIX Reference Manual
.Cl PRM UNIX Programmers's Manual
.\" MMI UNIX Manual Master Index
.\" CON UNIX Contributed Software Manual
.\" LOC UNIX Local Manual
.Tp Li \&.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
.Tp Li \&.Dd month day, year
The date should be written formally:
.\" is not a standard SCCS id-key. ??
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
which expect a specific format.
The other requests can handle up to 9 arguments
and will format punctuation properly as
long as the punctuation is placed in the last
arguments. 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
{+,\-,/,*,%,<,>,<=,>=,=,==,&,`,',"}
The address request constructs and address
of the form addr1[,addr2[,addr3]].
.Dl \&.Ad Usage: .Ad address ... \*(Pu
.Dw \&.Ad\ f1\ ,\ f2\ ,\ f3\ :
.Dp Li \&.Ad addr1\ , file2
.Dp Li \&.Ad f1\ , f2\ , f3\ :
.Dp Li \&.Ad addr\ )\ )\ ,
The request may be called by
argument request may be used whenever
a command line argument is referenced.
.Dl Usage: .Ar argument ... \*(Pu
.Dp Li \&.Ar file\ )\ )\ ,
is called with no arguments
request cannot call other macros, but may
request for an example of using
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
.Dl Usage: .Dq string ... \*(Pu
.Dw \&.Dq\ fools\ and\ follies
.Dp Li \&.Dq fools and follies
.Dp Li \&.Dq Ar pattern\ )\ )\ ,
is called with no arguments
request may call or be called by
Neither request can nest with in itself, but
can be nested with in each other.
A portion of text may be stressed or emphasized with the .Em
request. The font used is commonly italic.
.Dl Usage: .Em argument ... \*(Pu
.Dw \&.Em\ vide\ infra\ )\ )\ ,
.Dp Li \&.Em exceed 1024\ .
.Dp Li \&.Em vide infra\ )\ )\ ,
The request cannot call other macros, but
.Ss Errno's (Section's two and three only)
errno request specifies the error return value
for section two and three library routines. The second example
request, as it would be used in the error
section of a section two manual page.
.Dl Usage: .Er ERRNOTYPE ... \*(Pu
.Dp Li \&.Op \&Er ENOTDIR
The request cannot call other macros, but
.Ss Environment Variables
request specifies a environment variable.
.Dl Usage: .Ev argument ... \*(Pu
.Dw \&.Ev\ PRINTER\ )\ )\ ,
.Dp Li \&.Ev PRINTER\ )\ )\ ,
The request cannot call other macros, but
request handles command line flags. It prepends
to the flag. For interactive command flags, which
are not prepended with a dash, the
request is identical, but with out the dash.
stands for command modifier.
.Dl Usage: .Fl argument ... \*(Pu
request without any arguments results
in a dash sign representing stdin/stdout.
a single dash, will result in two dashes.
The request cannot call other macros, but
.Ss Functions (library routines)
The .Fn request is modeled on ANSI C conventions. It
may fail on old style parameter lists.
Usage: .Fn [type\e\ ] function [[type\e\ ] params ... \*(Pu
.Dw \&.Fn\ void\e\ push\ int\e\ p\ int\e\ *ptr,
.Dp Li \&.Fn strlen\ )\ ,
.Dp Li \&.Fn strcpy char\e\ *dst char\e\ *src
.Fn strcpy char\ *dst char\ *src
.Dp Li \&.Fn int\e\ align int\e\ word
.Dp Li \&.Fn void\e\ push int\e\ p int\e\ *ptr\ ,
.Fn void\ push int\ p int\ *ptr ,
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
request cannot execute any macro
names given as the first argument.
literal request may be used for special characters,
variable constants, anything which should be displayed as it
.Dl Usage: .Li argument ... \*(Pu
.Dp Li \&.Li cntrl-D\ )\ ,
The request cannot call other macros, but
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
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
can continue to be used for any other sections.
For interactive commands, such as the
it can not recall the first argument it was invoked with.
.Dl Usage: .Nm argument ... \*(Pu
.Dp Li \&.Nm foo\ )\ )\ ,
request cannot call other macros, but
request formats path or file names. It has two
different behaviours. In any section of the man page
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.
.Dl Usage: .Pa pathname \*(Pu
.Dw \&.Pa\ /tmp/fooXXXXX\ )\ .
.Dp Li \&.Pa /tmp/fooXXXXX\ )\ .
From within section FILES, use the
requests to format the pathnames
request cannot call other macros, but
above. The single quoting request
works in the same manner as
The symbolic request is really a boldface request.
The need for this macro has not been established,
it is included 'just in case'.
.Dl Usage: .Sy symbol ... \*(Pu
.Dw \&.Sy\ something\ bold
.Dp Li \&.Sy something bold
request cannot call other macros, but can be called
Generic variable reference:
.Dl Usage: .Va variable ... \*(Pu
.Dw \&.Va\ char\ s\ ]\ )\ )\ ,
.Dp Li \&.Va int\ *prt\ )\ :
.Dp Li \&.Va char\ s\ ]\ )\ )\ ,
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.
.Dl Usage: .Xr manpage [1,...,8] \*(Pu
.Dp Li \&.Xr mdoc 7\ )\ )\ ,
request cannot call other macros, but may be called
section header requests are required in every
request can take up to nine arguments.
request is mandatory. If not specified,
the headers, footers and page layout defaults
will not be set and things will be rather unpleasant.
The NAME section consists of at least three items.
name request naming the subject of the man page.
The second is the Name Description request,
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.
The SYNOPSIS section describes the typical usage of the
subject of a man page. The requests required
for manual page sections 2 and 3, the command and general
is required for the remaining sections 1, 4, 5, 6, 7, 8.
Several other requests may be necessary to produce
the synopsis line as shown below:
The following requests were used:
request has accepted as its first
argument the name of another macro
Upon discovering the first argument is callable,
calls it with the remaining arguments
and returns the formatted text in option brackets.
In most cases the first text in the DESCRIPTION section
is a brief paragraph on the command, function or file,
followed by a lexical list of options and respective
explanations. To create such a list, the
request is used in conjunction with text macros, such
the EXAMPLES section below).
for instance, in this manual page
.Dl Li \&.Sh PAGE LAYOUT MACROS
was used for this section.
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.
The ENVIRONMENT section should reveal any related
variables and clues to their behaviour and/or usage.
There are several ways to create examples. See
the EXAMPLES section below
Files which are used or created by the man page subject
request in the FILES section.
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
style references are not accommodated.
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.
Any command which does not adhere to any specific standards
should be outlined historically in this section.
Credits, if need be, should be placed here.
Diagnostics from a command should be placed in this section.
Specific error handling, especially from library functions
(man page sections 2 and 3) should go here. The
request is used to specify an errno.
Blatant problems with the topic go here...
.Ss Paragraphs and Line Spacing.
The \&.Pp paragraph command may
be used to specify a line space where necessary.
The request is not necessary after a
A complex expression is one combined of many
different elements of text. It is usually only necessary
in particularly nasty man pages, such as
where combinations of commands, addresses and symbols
When pieces of text are processed,
that a space character will be desired after each word
making it difficult to combine expressions where
different requests are used.
merely glues text together without spaces. Where
a space is required, it must be specified.
This first example shows how to construct a simple
expression with no spacing in between:
.Cw (ax+bx+c) \ is\ produced\ by\ \&
.\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\&
This example shows the same equation in a different format. The spaces
.Cw (ax\ +\ bx\ +\ c) \ is\ produced\ by\ \&
.\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\&
The incantation below was
.Cw \&[?/]m_b1_e1_f1[?/]\& is\ produced\ by
.Ss Examples and Displays
There are three types of displays, an indented one line display
a non\-filled block display
and a filled block display.
Display one line of indented text.
example request has been used throughout this
basic use is to indent (display) one line of text for quick
one line examples. Its default font is set to
checks the first argument to see if it is callable. It cannot process
more than nine arguments.
.Li \&.Dl % ls -ldg /usr/local/bin
.Dl % ls -ldg /usr/local/bin
Calling either the request
is redundant and may cause unpredictable errors.
Display a block of text as typed,
right margin edges are left ragged.
so they can be used outside and within
request must be ended with a
takes can be manipulated to indent
Align block on the current left margin,
this is the default mode of
if called without arguments.
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.
Indent from left margin default amount (usually
about a three quarters of an inch or eight
constant width characters).
This left aligns the block about two inches from
the right side of the page. It too, alas, needs
Display a filled (formatted) block. Identical to
except the block of text is formatted (the edges are
not left ragged). Takes the same modifers as
.Ss Tagged paragraphs and Columns
both require a begin and end. When
are called with arguments, they collect and
create the tag portion from
Anything after the tag is placed in
macro is essentially the same as
macro, but with a few added features.
These are discussed following the
.Dl \&.Ad, \&.Ar, \&.Cm, \&.Em, \&.Er, \&.Ev, \&.Fl, \&.Fn, \&.Ic,
.Dl \&.Li, \&.Nm, \&.Sy, \&.Va and \&.Xr.
request can be nested, and values for determining
the width of each tag are based on which macro
is calling, if it is calling one, or by specifying
The default width for an unknown tag type is set to just
about one and three quarter inches, or 20 characters in a
If the default width is unsatisfactory,
sets the width to the default flag width
set to ten constant width characters or about five sixth of
sets the width to 24 constant width characters or about two
is absolutely necessary for the scaling to work correctly.
.Dp Li \&.Tw ENAMETOOLONG
sets the width to the constant width length of the
.Dp Li \&.Tw int\e\ mkfifo
again, the width is set to the constant width of the string
given, and the space is protected with a preceding
This is the first call to
Since the first argument was callable
and different from the last one, the
A third nest (indent) using the
with no arguments stops the current nest
and exdents back to the previous level.
without arguments exdents. This will put
us back at the first level.
request. This request is followed
The above was created from:
This is the first call to
Since the first argument was callable and different from
the last one, the tag was indented.
A third nest (indent) using the
with no arguments stops the current nest
and exdents back to the previous level.
without argments exdents.
This will put us back at the first level.
request. This request is followed by the last call to
sleep time of the process (seconds blocked)
number of disk i/o's resulting from references by the process
to pages not loaded in core.
numerical user-id of process owner
numerical id of parent of process
process priority (non-positive when in non-interruptible wait)
sleep time of the process (seconds blocked)
number of disk i/o's resulting from references by the process
to pages not loaded in core.
numerical user-id of process owner
numerical id of parent of process
process priority (non-positive when in non-interruptible wait)
is to indent a small amount from the current margin before
processing the tag. This margin can be changed with the
which takes as its first argument either a numerical
argument (e.g. a scaled number like 24n) or a letter
forces a left margin, which is useful if something doesn't
quite fit (as in the example for the
macro in the TEXT MACRO section above).
is the default, 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
is called without arguments).
has been used to set the width of the tag.
It is identical to the request
The column request is made up of a width request,
and a column line request,
From one to four simple columns can be created
and all but the last column, are simple
single entry style columns.
The last (rightmost) column can overflow into
request takes at most three arguments
as width indicators. The number of columns is
always one more than given to
request should have its arguments
on the next line and the columns should be
separated by a tab character.
An example of two columns:
The requests used to format the
columns above (the jagged edges are from tabs which can
.Dl \&.Cl Macros Description
.Dl \&.Cl \e&.Tp List Request
.Dl \&.Cl \e&.Nm Name Request
There some problems with columns at the moment, while they
work well in nested lists, they are otherwise difficult
request ain't quite working perfectly.
is to place brackets around the given arguments, and place any
punctuation outside the brackets. In the case of
trailing punctuation on the same request line as the
should be placed outside the brackets.
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:
.Dw \&.Op\ Fl\ c\ Ar\ objfil\ Op\ Ar\ corfil\ ,
.Dp Li \&.Op Fl k Ar kookfile
.Dp Li \&.Op Fl k Ar kookfile\ ,
.Dp Li \&.Op Ar objfil Op Ar corfil
.Op Ar objfil Op Ar corfil
.Dp Li \&.Op Fl c Ar objfil Op Ar corfil\ ,
.Op Fl c Ar objfil Op Ar corfil ,
The punctuation on the second to last example is
improperly placed and should be fixed some day.
.\" .Pa /usr/share/tmac/tmac.doc.style site specific layout
.Dw /usr/share/man0/template.doc
.Dp Pa /usr/share/tmac/tmac.doc
.Dp Pa /usr/share/man0/template.doc
template for writing a man page
Punctuation may be broken on
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.
font should be changed in NAME section.
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 interpretation of characters from the
{+,\-,/,*,%,<,>,<=,>=,=,==,&}
character in an argument string which may be checked for punctuation.
This is a relatively rare occurrence, as a lot of checking is
projects / unix-history / blob