+.\" Copyright (c) 1990 The Regents of the University of California.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\" must display the following acknowledgement:
+.\" This product includes software developed by the University of
+.\" California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\" may be used to endorse or promote products derived from this software
+.\" without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" @(#)mdoc.samples.7 5.7 (Berkeley) 7/1/91
+.\"
+
+.\" This sampler invokes every macro in the package several
+.\" times and is garanteed to give a worst case performance
+.\" for an already extremely slow package.
+
+.Dd July 1, 1991
+.Os BSD 4.4
+.Dt MDOC.SAMPLES 7
+.Sh NAME
+.Nm mdoc.sample
+.Nd writing manual pages with
+.Nm -mdoc
+macro package
+.Sh SYNOPSIS
+.Nm man mdoc.sample
+.Sh DESCRIPTION
+A tutorial sampler for writing
+.Bx
+manual pages with the
+.Nm \-mdoc
+macro package, a
+.Em content Ns \-based
+formatting
+package for
+.Xr troff 1 .
+Its predecessor, the
+.Xr \-man 7
+package,
+addressed page structure leaving the
+manipulation of fonts and other
+typesetting details to the individual author.
+The
+.Nm \-mdoc
+package
+allows the author to ignore font considerations by
+using macros to label
+pieces of text according to content.
+In the context of manual pages, examples of content
+are a command name, a file pathname or a cross
+reference to another manual page; these
+items have value
+for both the author and the future user of the manual page.
+It is hoped the consistency gained
+across the manual set will provide easier
+translation to future documentation tools.
+.Pp
+Through out the
+.Ux
+manual pages, a manual entry
+is simply referred
+to as a man page, regardless of actual length and without
+sexist intention.
+.Sh TROFF IDIOSYNCRASIES
+The
+.Nm \-mdoc
+package attempts to simplify the process of writing a man page.
+Theoretically, one should not have to learn the dirty details of
+.Xr troff 1
+to use
+.Nm \-mdoc ;
+however, there are a few
+limitations which are unavoidable and best gotten out
+of the way. And, too, be forewarned, this package is
+.Em not
+fast.
+.Ss Macro Usage
+As in
+.Xr troff 1 ,
+a macro is called by placing a
+.Ql \&\.
+(dot character)
+at the beginning of
+a line followed by the two character name for the macro.
+Arguments may follow the macro separated by spaces.
+It is the dot character at the beginning of the line which causes
+.Xr troff 1
+to interpret the next two characters as a macro name.
+To place a
+.Ql \&\.
+(dot character)
+at the beginning of a line in some context other than
+a macro macro, precede the
+.Ql \&\.
+(dot) with a
+.Ql \e& .
+.Pp
+In general,
+.Xr troff 1
+macros accept up to nine arguments, any
+extra arguments are ignored.
+Most macros in
+.Nm \-mdoc
+accept nine arguments and,
+in limited cases, arguments may be continued or extended
+on the
+next line (See
+.Sx Extensions
+\-
+macro
+.Ql \&.Xo
+and
+.Ql \&.Xc ) .
+A few macros handle quoted aguments (see
+.Sx Passing Space Characters in an Argument
+below).
+Many
+.Nm \-mdoc
+macros 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
+.Ql \&\.
+(dot),
+and is
+.Em called
+when the argument is processed.
+It is in this manner that some macros are nested; for
+example
+the option macro,
+.Ql \&.Op ,
+may
+.Em call
+the flag and argument macros,
+.Ql \&.Fl
+and
+.Ql \&.Ar ,
+to specify an optional flag with an argument:
+.nr D 1
+.Bl -tag -width "\&.Op \&Fl s \&Ar bytes" -offset indent
+.It Op Fl s Ar bytes
+is produced by
+.Li \&.Op \&Fl s \&Ar bytes
+.El
+.Pp
+To prevent a two character
+string from being interpreted as a macro name, precede
+the string with the
+escape sequence
+.Ql \e& :
+.Bl -tag -width "[\&Fl s \&Ar bytes]" -offset indent
+.It Op \&Fl s \&Ar bytes
+is produced by
+.Li \&.Op \e&Fl s \e&Ar bytes
+.El
+.Pp
+.nr D 0
+Here the strings
+.Ql \&Fl
+and
+.Ql \&Ar
+were not interpreted as macros.
+Details on callable macros are presented in the
+sections
+.Sx CONTENT MACROS
+and
+.Sx PAGE LAYOUT MACROS.
+.Ss Passing Space Characters in an Argument
+Sometimes it is desirable to give as one argument a string
+containing one or more blank space characters. This may be necessary
+to defeat the nine argument limit or to specify arguments to macros
+which expect particular arrangement of items in the argument list.
+For example,
+the function macro
+.Ql \&.Fn
+expects the first argument to be the name of a function and any
+remaining arguments to be function parameters. As
+.Tn "ANSI C"
+stipulates the declaration of function parameters in the
+parenthesized parameter list, each parameter is guaranteed
+to be at minimum a two word string. For example,
+.Fa int foo .
+There are two possible ways to pass an argument which contains
+an imbedded space. Unfortunately, the most convient way
+of passing such a space between quotes was too expensive to implement for
+all the macros. It is however, implemented for the following macros which need
+it the most:
+.Pp
+.Bl -tag -width 4n -offset indent -compact
+.It Li \&Cd
+Configuration declaration (section 4 SYNOPSIS)
+.It Li \&Bl
+Begin list (for the width specifier).
+.It Li \&Em
+Emphasized text.
+.It Li \&Fn
+Functions (sections two and four).
+.It Li \&It
+List items.
+.It Li \&Li
+Literal text.
+.It Li \&Sy
+Symbolic text.
+.It Li \&%B
+Book titles.
+.It Li \&%J
+Journal names.
+.It Li \&%O
+Optional notes for a reference.
+.It Li \&%R
+Report title (in a reference).
+.It Li \&%T
+Title of article in a book or journal.
+.El
+.Pp
+One way of passing a string
+containing blank spaces is to use the hard or unpaddable space character
+.Ql \e\ ,
+that is, a blank space preceeded by the escape character
+.Ql \e .
+This method may be used with any macro but has the side effect
+of interfering with the adjustment of text
+over the length of a line.
+.Xr Troff
+sees the hard space as if it were any other printable character and
+cannot split the string into blank or newline separated pieces as one
+would expect. The method is useful for strings which are not expected
+to overlap a line boundary. For example:
+.Bl -tag -width "fetch(char *str)" -offset indent
+.It Fn fetch char\ *str
+is created by
+.Ql \&.Fn fetch char\e *str
+.It Fn fetch "char *str"
+can also be created by
+.Ql \&.Fn fetch "\\*q*char *str\\*q"
+.El
+.Pp
+If the
+.Ql \e
+or quotes
+were omitted,
+.Ql \&.Fn
+would see three arguments and
+the result would be:
+.Pp
+.Dl Fn fetch char *str
+.Pp
+For an example of what happens when the parameter list overlaps
+a newline boundary, see the
+.Sx BUGS
+section.
+.\" Note what happens if the parameter list overlaps a newline
+.\" boundary. For example, the next two examples are repeated several times
+.\" to make sure a line boundary is crossed:
+.\" .Bd -literal
+.\" \&.Fn struct\e\ dictionarytable\e\ *dictionarylookup struct\e\ dictionarytable\e\ *tab[]
+.\" .Ed
+.\" .Pp
+.\" produces, nudge nudge,
+.\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] ,
+.\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] ,
+.\" nudge
+.\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] .
+.\" .Pp
+.\" If double quotes are used, for example:
+.\" .Bd -literal
+.\" \&.Fn \*qstruct dictionarytable *dictionarylookup\*q \*qchar *h\*q \*qstruct dictionarytable *tab[]\*q
+.\" .Ed
+.\" .Pp
+.\" produces, nudge nudge,
+.\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" ,
+.\" nudge
+.\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" ,
+.\" nudge
+.\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" .
+.\" .Pp
+.\" Not a pretty sight...
+.\" In a paragraph, a long parameter containing unpaddable spaces as
+.\" in the former example will cause
+.\" .Xr troff
+.\" to break the line and spread
+.\" the remaining words out. The latter example will adjust nicely to
+.\" justified margins, but may break in between an argument and its
+.\" declaration. In
+.\" .Xr nroff
+.\" the right margin adjustment is normally ragged and the problem is
+.\" not as severe.
+.Ss Trailing Blank Space Characters
+.Xr Troff
+can be confused by blank space characters at the end of a line. It
+is wise preventative measure to globally remove all blank spaces
+from <blank-space><end-of-line> character sequences. Should the need
+arise to force a blank character at the end of a line,
+it may be forced with an unpaddable space and the
+.Ql \e&
+escape character.
+For example,
+.Ql string\e\ \e& .
+.Ss Escaping Special Characters
+Special characters
+like the newline character
+.Ql \en ,
+are handled by replacing the
+.Ql \e
+with
+.Ql \ee
+(e.g.
+.Ql \een )
+to preserve
+the backslash.
+.Sh THE ANATOMY OF A MAN PAGE (Getting Started)
+There are three basic groups of macros: specific header macros
+called only once at the very beginning of
+each manual page, page layout or structure macros
+which may be called many times, and content macros which also
+may be called many times.
+The body of a man page is easily constructed from a basic
+template found in the file:
+.Bd -literal -offset indent
+\&.\e" /usr/share/misc/man.tempate :
+\&.\e" The following six lines are required.
+\&.Dt DOCUMENT_TITLE [section number] [volume]
+\&.Os OPERATING_SYSTEM [version/release]
+\&.Dd Month day, year
+\&.Sh NAME
+\&.Sh SYNOPSIS
+\&.Sh DESCRIPTION
+\&.\e" The following requests should be uncommented and
+\&.\e" used where appropriate. This next request is
+\&.\e" for sections 2 and 3 function return values only.
+\&.\e" .Sh RETURN VALUES
+\&.\e" This next request is for sections 1, 6, 7 & 8 only
+\&.\e" .Sh ENVIRONMENT
+\&.\e" .Sh FILES
+\&.\e" .Sh EXAMPLES
+\&.\e" This next request is for sections 1, 6, 7 & 8 only
+\&.\e" (command return values (to shell) and
+\&.\e" fprintf/stderr type diagnostics)
+\&.\e" .Sh DIAGNOSTICS
+\&.\e" The next request is for sections 2 and 3 error
+\&.\e" and signal handling only.
+\&.\e" .Sh ERRORS
+\&.\e" .Sh SEE ALSO
+\&.\e" .Sh STANDARDS
+\&.\e" .Sh HISTORY
+\&.\e" .Sh AUTHORS
+\&.\e" .Sh BUGS
+.Ed
+.Pp
+The first items in the template are the macros
+.Pq Li \&.Dt , \&.Dd , \&.Os ;
+the document or man page title
+.Pq Em in upper case ,
+the section of the manual the page
+belongs to, the (document) date,
+and the operating system the man page is derived
+from. These macros identify the page,
+and are discussed below in
+.Sx TITLE MACROS .
+.Pp
+The remaining items in the template are section headers
+.Pq Li \&.Sh ;
+of which NAME, SYNOPSIS and DESCRIPTION
+are mandatory. The
+headers are
+discussed in
+.Sx PAGE LAYOUT MACROS,
+after
+presentation of
+.Sx CONTENT MACROS .
+Several content macros are used to demonstrate page layout macros;
+reading about content macros before page layout macros is
+recommended.
+.Sh TITLE MACROS
+Three header macros designate the document title or manual page title,
+the operating system,
+and the date of authorship.
+These macros are one called once at the very beginning of the document
+and are used to construct the headers and footers only.
+.Bl -tag -width 6n
+.It Li \&.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 section number may be 1,\ ...,\ 8,
+and if it is specified,
+the volume title may be omitted.
+A volume title may be arbitrary or one of the following:
+.\" .Cl
+.\" USD UNIX User's Supplementary Documents
+.\" .Cl
+.\" PS1 UNIX Programmers's Supplementary Documents
+.Pp
+.Bl -column SMM -offset indent -compact
+.It AMD UNIX Ancestral Manual Documents
+.It SMM UNIX System Manager's Manual
+.It URM UNIX Reference Manual
+.It PRM UNIX Programmers's Manual
+.El
+.Pp
+.\" .Cl
+.\" MMI UNIX Manual Master Index
+.\" .Cl
+.\" CON UNIX Contributed Software Manual
+.\" .Cl
+.\" LOC UNIX Local Manual
+.It 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
+was produced by:
+.Pp
+.Dl \&.Os BSD 4.4
+.It Li \&.Dd month day, year
+The date should be written formally:
+.Pp
+.Dl January 25, 1989
+.El
+.Sh CONTENT MACROS
+.Ss What's in a name...
+Content macro names are derived from the day to day
+informal language used to describe commands, subroutines and related
+files. Slightly
+different variations of this language are used to describe
+the three different aspects of writing a man page.
+First, there is the description of
+.Nm \-mdoc
+macro request usage.
+Second is the description of a
+.Ux
+command
+.Em with
+.Nm \-mdoc
+macros and third,
+the
+description a command to a user in the verbal sense;
+that is, discussion of a command in the text of a man page.
+.Pp
+In the first case,
+.Xr troff 1
+macros are themselves a type of command;
+the general syntax for a troff command is:
+.Bd -filled -offset indent
+\&.Va argument1 argument2 ... argument9
+.Ed
+.Pp
+The
+.Ql \&.Va
+is a macro command or request, and anything following it is an argument to
+be processed.
+In the second case,
+the description of a
+.Ux
+command using the content macros is a
+bit more involved;
+a typical SYNOPSIS command line might be displayed as:
+.Pp
+.Bd -filled -offset indent
+.Nm filter
+.Op Fl flag
+.Ar infile outfile
+.Ed
+.Pp
+Here,
+.Nm filter
+is the command name and the
+bracketed string
+.Fl flag
+is a
+.Em flag
+argument designated as optional by the option brackets.
+In
+.Nm \-mdoc
+terms,
+.Ar infile
+and
+.Ar outfile
+are
+called
+.Em arguments .
+The macros which formatted the above example:
+.Pp
+.Bd -literal -offset indent
+\&.Nm filter
+\&.Op \&Fl flag
+\&.Ar infile outfile
+.Ed
+.Pp
+In the third case, discussion of commands and command syntax
+includes both examples above, but may add more detail. The
+arguments
+.Ar infile
+and
+.Ar outfile
+from the example above might be refered to as
+.Em operands
+or
+.Em file arguments .
+Some command line argument lists are quite long:
+.\" .Bl -tag -width make -offset indent
+.Bl -tag -width make -offset indent
+.It Nm make
+.Op Fl eiknqrstv
+.Op Fl D Ar variable
+.Op Fl d Ar flags
+.Op Fl f Ar makefile
+.Op Fl I Ar directory
+.Op Fl j Ar max_jobs
+.Op Ar variable=value
+.br
+.Op Ar "target\ ..."
+.El
+.Pp
+Here one might talk about the command
+.Nm make
+and qualify the argument
+.Ar makefile ,
+as an argument to the flag,
+.Fl f ,
+or discuss the optional
+file
+operand
+.Ar target .
+In the verbal context, such detail can prevent confusion,
+however the
+.Nm \-mdoc
+package
+does not have a macro for an argument
+.Em to
+a flag.
+Instead the
+.Ql \&Ar
+argument macro is used for an operand or file argument like
+.Ar target
+as well as an argument to a flag like
+.Ar variable :
+.Bd -literal -offset indent
+\&.Nm make
+\&.Op Fl eiknqrstv
+\&.Op Fl D Ar variable
+\&.Op Fl d Ar flags
+\&.Op Fl f Ar makefile
+\&.Op Fl I Ar directory
+\&.Op Fl j Ar max_jobs
+\&.Op Ar variable=value
+\&.Op Ar target ...
+.Ed
+.Ss General Syntax
+All content macros share a similar
+syntax with a few minor deviations:
+.Ql \&.Ar ,
+.Ql \&.Fl ,
+.Ql \&.Nm ,
+and
+.Ql \&.Pa
+differ only when called without arguments;
+.Ql \&.Fn
+and
+.Ql \&.Xr
+impose an order on their argument lists
+and the
+.Em enclosure
+and
+.Em quoting
+macros
+have nesting limitations. All content macros
+are capable of handling punctuation.
+Any argument which may be tested for punctuation
+and contains a member of the mathematical, logical or
+quotation set:
+.Bd -literal -offset indent -compact
+{+,\-,/,*,%,<,>,<=,>=,=,==,&,`,',"}
+.Ed
+should have
+the character escaped with
+.Ql \e& .
+Typical syntax is shown in the first content macro displayed
+below,
+.Ql \&.Ad ,
+and the syntax for enclosure/quoting macros is shown in
+.Sx Enclosure and Quoting Macros .
+.Ss Address Macro
+The address macro constructs an address
+of the form addr1[,addr2[,addr3]].
+.Pp
+.Dl Usage: .Ad address ... \*(Pu
+.Bl -tag -width ".Ad f1 , f2 , f3 :" -compact -offset 14n
+.It Li \&.Ad addr1
+.Ad addr1
+.It Li \&.Ad addr1\ .
+.Ad addr1 .
+.It Li \&.Ad addr1\ , file2
+.Ad addr1 , file2
+.It Li \&.Ad f1\ , f2\ , f3\ :
+.Ad f1 , f2 , f3 :
+.It Li \&.Ad addr\ )\ )\ ,
+.Ad addr ) ) ,
+.El
+.Pp
+It is an error to call
+.Li \&.Ad
+without arguments.
+.Li \&.Ad
+is callable by other macros and may call other macros.
+.Ss Argument Macro
+The
+.Li \&.Ar
+argument macro may be used whenever
+a command line argument is referenced.
+.Pp
+.Dl Usage: .Ar argument ... \*(Pu
+.Bl -tag -width ".Ar file1 file2" -compact -offset 15n
+.It Li \&.Ar
+.Ar
+.It Li \&.Ar file1
+.Ar file1
+.It Li \&.Ar file1\ .
+.Ar file1 .
+.It Li \&.Ar file1 file2
+.Ar file1 file2
+.It Li \&.Ar f1 f2 f3\ :
+.Ar f1 f2 f3 :
+.It Li \&.Ar file\ )\ )\ ,
+.Ar file ) ) ,
+.El
+.Pp
+If
+.Li \&.Ar
+is called without arguments
+.Ql Ar
+is assumed. The
+.Li \&.Ar
+macro may call other macros, and may be
+called by other macros.
+.Ss Angle Bracket Quote/Enclosure
+Encloses a string or strings in between angle brackets. The macro
+.Ql \&.Aq
+encloses the remaining arguments on the macro command line, and the
+.Ql \&.Ao
+(angle open) and
+.Ql \&.Ac
+(angle close) macros may be used across one or more lines.
+.Pp
+.Dl Usage: .Aq string ... \*(Pu
+.Bl -tag -width ".Aq Pa ctype.h ) ," -compact -offset 14n
+.It Li \&.Aq
+.Aq
+.It Li \&.Aq string.
+.Aq string.
+.It Li \&.Aq string\ .
+.Aq string .
+.It Li \&.Aq stdio.h
+.Aq stdio.h
+.It Li \&.Aq \&Ar ctype.h\ )\ ,
+.Aq Ar ctype.h ) ,
+.El
+.Pp
+See
+.Sx Enclosure Macros
+for discussion and
+.Sx Options
+for examples of the open and close
+macros
+.Ql \&.Ac
+and
+.Ql \&.Ao .
+.Ql \&.Aq
+is callable by other macros and may call other macros.
+.Ss Bracket Quotes/Enclosure
+Bracket quotes should be used when the string being bracketed is
+.Em not
+an option string. The brackets for an option may be different
+than the default brackets. The macro
+.Ql \&.Bq
+encloses the remaining arguments on a macro command line and the
+macros
+.Ql \&.Bo
+and
+.Ql \&.Bc
+may be used across one or more lines.
+.Pp
+.Dl Usage: .Bq string ... \*(Pu
+.Pp
+The
+.Li \&.Bq
+macro exists for statements which use other macros:
+.Bq Em Greek , French .
+This was done with:
+.Pp
+.Dl Li \&.Bq \&Em Greek \&, French \&.
+.Pp
+It also could have been done using the prefix macro:
+.Pp
+.Dl Li ".Pf [ Em Greek , French ] ."
+.Pp
+See
+.Sx Enclosure Macros
+for discussion and
+.Sx Options
+for examples of the open and close
+macros
+.Ql \&.Bc
+and
+.Ql \&.Bo .
+The
+.Ql \&.Bq
+macro
+is callable and may call other macros.
+.Ss Configuration Declaration (section four only)
+The
+.Ql \&.Cd
+macro is used to demonstrate a
+.Xr config 8
+declaration for a device interface in a section four manual.
+This macro accepts quoted arguments (double quotes only).
+.Pp
+.Bl -tag -width "device le0 at scode?" -offset indent
+.It Cd "device le0 at scode?"
+produced by:
+.Ql ".Cd device le0 at scode?" .
+.El
+.Ss Command Modifier
+The command modifier is identical to the
+.Ql \&.Fl
+(flag) command with the exception
+the
+.Ql \&.Cm
+macro does not assert a dash
+in front of every argument. Traditionally flags are marked by the
+preceding dash, some commands or subsets of commands do not use them.
+Command modifiers may also be specified in conjunction with interactive
+commands such as editor commands.
+See
+.Sx Flags .
+.Ss Double Quote macro/Enclosure
+The
+.Ql \&.Dq
+double quote encloses
+any remaining strings on the command line with double quotes.
+Punctuation is
+placed after the end quote.
+The macros
+.Ql \&.Do
+and
+.Ql \&.Dc
+may be used across one or more lines.
+.Pp
+.Dl Usage: .Dq string ... \*(Pu
+.Bl -tag -width ".Dq Ar patternx ) ) ," -compact -offset 14n
+.It Li \&.Dq
+.Dq
+.It Li ".Dq string."
+.Dq string.
+.It Li ".Dq string abc ."
+.Dq string abc .
+.It Li ".Dq \'^[A-Z]\'"
+.Dq \'^[A-Z]\'
+.It Li \&.Dq \&Ar pattern\ )\ )\ ,
+.Dq Ar pattern ) ) ,
+.El
+.Pp
+If
+.Ql \&.Dq
+is called with no arguments
+.Dq
+is assumed. The
+.Ql \&.Dq
+macro may call or be called by
+other macros.
+See
+.Sx Enclosure Macros
+for discussion of
+.Ql \&.Dc
+and
+.Ql \&.Do
+macro types.
+.Ss Defined Variables
+A variable which is defined in an include file is specified
+by the macro
+.Ql \&.Dv .
+.Pp
+.Dl Usage: .Dv defined_variable ... \*(Pu
+.Bl -tag -width ".Dv MAXHOSTNAMELEN" -compact -offset 14n
+.It Li ".Dv MAXHOSTNAMELEN"
+.Dv MAXHOSTNAMELEN
+.It Li ".Dv TIOCGPGRP )"
+.Dv TIOCGPGRP )
+.El
+.Pp
+It is an error to call
+.Ql \&.Dv
+without arguments.
+.Ql \&.Dv
+may call other macros and
+may be called by other macros.
+.Ss Emphasis Macro
+Text may be stressed or emphasized with the
+.Ql \&.Em
+macro. The usual font for emphasis is italic.
+.Pp
+.Dl Usage: .Em argument ... \*(Pu
+.Bl -tag -width ".Em vide infra ) ) ," -compact -offset 14n
+.It Li ".Em does not"
+.Em does not
+.It Li ".Em exceed 1024 ."
+.Em exceed 1024 .
+.It Li ".Em vide infra ) ) ,"
+.Em vide infra ) ) ,
+.El
+.Pp
+The emphasis can be forced across several lines of text by using
+the
+.Ql \&.Bf
+macro discussed in
+.Sx Modes
+under
+.Sx PAGE LAYOUT .
+.\" .Pp
+.\" .Em
+.\" I'm certain the reason so many people desire an MBA from Harvard
+.\" is because they want to be successful philanthropists.
+.\" .Em
+.Pp
+The
+.Ql \&.Em
+macro
+is callable and may call other macros.
+It is an error to call
+.Ql \&.Em
+without arguments.
+.Ss Enclosure and Quoting Macros
+The concept of enclosure is similar to quoting.
+The object is to enclose a string or more between
+a pair of characters like quotes or parentheses.
+The terms quoting and enclosure are used
+interchangeably throughout this document. Many of the
+one line enclosure macros end
+end in small letter
+.Ql q
+to give a hint of quoting, but there are a few exceptions
+(the macros
+.Ql \&.En ,
+.Ql \&.Fn
+and
+.Ql \&.Op
+are also enclosure macros).
+For each enclosure macro
+there is also a pair of open and close macros which end
+in small letters
+.Ql o
+and
+.Ql c
+respectively. These can be used across one or more lines of text
+and while they cannot be nested, the one line quote macros
+can be used inside
+of them.
+For a good example of one these macros, see
+.Sx Options .
+.Pp
+.Bd -filled -offset indent
+.Bl -column "quote" "close" "open" "Enclose Stringx(in XX)" XXstringXX
+.Em " quote close open function result"
+\&.Aq, .Ac, .Ao Angle Bracket Enclosure <string>
+\&.Bq, .Bc, .Bo Bracket Enclosure [string]
+\&.Dq, .Dc, .Do Double Quote ``string''
+ .Ec, .Eo Enclose String (in XX) XXstringXX
+\&.Fn, .Fc, .Fo Function Enclosure function(string)
+\&.Op, .Oc, .Oo Option Enclosure [string]
+\&.Pq, .Pc, .Po Parenthesis Enclosure (string)
+\&.Qq, .Qc, .Qo Straight Double Quote "string"
+\&.Sq, .Sc, .So Single Quote `string'
+\& .Xc, .Xo Extend Argument \ \-\-
+.El
+.Ed
+.Pp
+The macros
+.Ql \&.Eo
+and
+.Ql \&.Ec
+allow a user to specify an open and close with the first argument as the
+opening or closing string respectively.
+.Ss Errno's (Section two only)
+The
+.Ql \&.Er
+errno macro specifies the error return value
+for section two library routines. The second example
+below shows
+.Ql \&.Er
+used with the
+.Ql \&.Bq
+macro, as it would be used in
+a section two manual page.
+.Pp
+.Dl Usage: .Er ERRNOTYPE ... \*(Pu
+.Bl -tag -width ".Bq Er ENOTDIR" -compact -offset 14n
+.It Li \&.Er ENOENT
+.Er ENOENT
+.It Li \&.Er ENOENT\ )\ ;
+.Er ENOENT ) ;
+.It Li \&.Bq \&Er ENOTDIR
+.Bq Er ENOTDIR
+.El
+.Pp
+It is an error to call
+.Ql \&.Er
+without arguments.
+The
+.Ql \&.Er
+macro
+is callable and may call other macros.
+.Ss Environment Variables
+The
+.Ql \&.Ev
+macro specifies a environment variable.
+.Pp
+.Dl Usage: .Ev argument ... \*(Pu
+.Bl -tag -width ".Ev PRINTER ) ) ," -compact -offset 14n
+.It Li \&.Ev DISPLAY
+.Ev DISPLAY
+.It Li \&.Ev PATH\ .
+.Ev PATH .
+.It Li \&.Ev PRINTER\ )\ )\ ,
+.Ev PRINTER ) ) ,
+.El
+.Pp
+It is an error to call
+.Ql \&.Ev
+without arguments.
+The
+.Ql \&.Ev
+macro
+is callable by other macros and may call other macros.
+.Ss Function Argument
+The
+.Ql \&.Fa
+macro is used to refer to function arguments (parameters)
+outside of the SYNOPSIS section of the manual or inside
+the SYNOPSIS section should a parameter list be too
+long for the
+.Ql \&.Fn
+macro and the enclosure macros
+.Ql \&.Fo
+and
+.Ql \&.Fc
+must be used.
+.Ql \&.Fa
+may also be used to refer to structure members.
+.Pp
+.Dl Usage: .Fa function_argument ... \*(Pu
+.Bl -tag -width ".Fa d_namlen\ )\ )\ ," -compact -offset 14n
+.It Li \&.Fa d_namlen\ )\ )\ ,
+.Fa d_namlen ) ) ,
+.It Li \&.Fa iov_len
+.Fa iov_len
+.El
+.Pp
+It is an error to call
+.Ql \&.Fa
+without arguments.
+.Ql \&.Fa
+is callable by other macros and may call other macros.
+.Ss Function Declaration
+The
+.Ql \&.Fd
+macro is used in the SYNOPSIS section with section two or three
+functions. The
+.Ql \&.Fd
+macro does not call other macros and is not callable by other
+macros.
+.Pp
+.Dl Usage: .Fd include_file (or defined variable)
+.Pp
+In the SYNOPSIS section a
+.Ql \&.Fd
+request causes a line break if a function has already been presented
+and a break has not occurred. This leaves a nice vertical space
+in between the previous function call and the declaration for the
+next function.
+.Ss Flags
+The
+.Ql \&.Fl
+macro handles command line flags. It prepends
+a dash,
+.Ql \- ,
+to the flag. For interactive command flags, which
+are not prepended with a dash, the
+.Ql \&.Cm
+(command modifier)
+macro is identical, but with out the dash.
+.Pp
+.Dl Usage: .Fl argument ... \*(Pu
+.Bl -tag -width ".Fl \-s \-t \-v" -compact -offset 14n
+.It Li \&.Fl
+.Fl
+.It Li \&.Fl cfv
+.Fl cfv
+.It Li \&.Fl cfv\ .
+.Fl cfv .
+.It Li \&.Fl s v t
+.Fl s v t
+.It Li \&.Fl -\ ,
+.Fl - ,
+.It Li \&.Fl xyz\ )\ ,
+.Fl xyz ) ,
+.El
+.Pp
+The
+.Ql \&.Fl
+macro without any arguments results
+in a dash representing stdin/stdout.
+Note that giving
+.Ql \&.Fl
+a single dash, will result in two dashes.
+The
+.Ql \&.Fl
+macro
+is callable and may call other macros.
+.Ss Functions (library routines)
+The .Fn macro is modeled on ANSI C conventions.
+.Bd -literal
+Usage: .Fn [type] function [[type] params ... \*(Pu]
+.Ed
+.Bl -tag -width ".Fn .int align. .const * char *sptrsxx" -compact
+.It Li "\&.Fn getchar"
+.Fn getchar
+.It Li "\&.Fn strlen ) ,"
+.Fn strlen ) ,
+.It Li \&.Fn "\\*qint align\\*q" "\\*qconst * char *sptrs\\*q" ,
+.Fn "int align" "const * char *sptrs" ,
+.El
+.Pp
+It is an error to call
+.Ql \&.Fn
+without any arguments.
+The
+.Ql \&.Fn
+macro
+is callable by other macros and may call other macros, but
+note that any call to another macro signals the end of
+the
+.Ql \&.Fn
+call (it will close-paren at that point).
+.Pp
+In the SYNOPSIS section, the function will always begin at
+the beginning of line. If there is more than one function
+presented in the SYNOPSIS section and a function type has not been
+given, a line break will occur, leaving a nice vertical space
+between the current function name and the one prior.
+At the moment,
+.Ql \&.Fn
+does not check its word boundaries
+against troff line lengths and may split across a newline
+ungracefully. This will be fixed in the near future.
+.Ss Function Type
+This macro is intended for the SYNOPSIS section. It may be used
+anywhere else in the manpage without problems, but its main purpose
+is to present the function type in kernel normal form for the SYNOPSIS
+of sections two and three
+(it causes a page break allowing the function name to appear
+on the next line).
+.Pp
+.Dl Usage: .Ft type ... \*(Pu
+.Pp
+.Bl -tag -width "\&.Ft struct stat" -offset 14n -compact
+.It Li \&.Ft struct stat
+.Ft struct stat
+.El
+.Pp
+The
+.Ql \&.Ft
+request is not callable by other macros.
+.Ss Interactive Commands
+The
+.Ql \&.Ic
+macro designates an interactive or internal command.
+.Pp
+.Dl Usage: .Li argument ... \*(Pu
+.Bl -tag -width ".Ic setenv , unsetenv" -compact -offset 14n
+.It Li \&.Ic :wq
+.Ic :wq
+.It Li \&.Ic do while {...}
+.Ic do while {...}
+.It Li \&.Ic setenv\ , unsetenv
+.Ic setenv , unsetenv
+.El
+.Pp
+It is an error to call
+.Ql \&.Ic
+without arguments.
+The
+.Ql \&.Ic
+macro may call other macros and is callable.
+.Ss Literals
+The
+.Ql \&.Li
+literal macro may be used for special characters,
+variable constants, anything which should be displayed as it
+would be typed.
+.Pp
+.Dl Usage: .Li argument ... \*(Pu
+.Bl -tag -width ".Li cntrl-D ) ," -compact -offset 14n
+.It Li \&.Li \een
+.Li \en
+.It Li \&.Li M1 M2 M3\ ;
+.Li M1 M2 M3 ;
+.It Li \&.Li cntrl-D\ )\ ,
+.Li cntrl-D ) ,
+.It Li \&.Li 1024\ ...
+.Li 1024 ...
+.El
+.Pp
+The
+.Ql \&.Li
+macro
+is callable by other macros and may call other macros.
+.Ss Name Macro
+The
+.Ql \&.Nm
+macro 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,
+.Ql \&.Nm
+regurgitates this initial name for the sole purpose
+of making less work for the author.
+Note:
+a section two
+or three document function name is addressed with the
+.Ql \&.Nm
+in the NAME section, and with
+.Ql \&.Fn
+in the SYNOPSIS
+and remaining sections.
+For interactive commands, such as the
+.Ql while
+command keyword in
+.Xr csh 1 ,
+the
+.Ql \&.Ic
+macro should be used.
+While the
+.Ql \&.Ic
+is nearly identical
+to
+.Ql \&.Nm ,
+it can not recall the first argument it was invoked with.
+.Pp
+.Dl Usage: .Nm argument ... \*(Pu
+.Bl -tag -width ".Nm mdoc.sample" -compact -offset 14n
+.It Li \&.Nm mdoc.sample
+.Nm mdoc.sample
+.It Li \&.Nm \-mdoc
+.Nm \-mdoc .
+.It Li \&.Nm foo\ )\ )\ ,
+.Nm foo ) ) ,
+.It Li \&.Nm
+.Nm
+.El
+.Pp
+The
+.Ql \&.Nm
+macro
+is callable by other macros and may call other macros.
+.Ss No\-Op or Normal Text Macro
+The macro
+.Li \&.No
+is
+a hack for words in a macro command line which should
+.Em not
+be formatted and follows the conventional syntax
+for content macros.
+.Ss No Space Macro
+The
+.Ql \&.Ns
+macro eliminates unwanted spaces in between macro requests.
+It is useful for old style argument lists where there is no space
+between the flag and argument:
+.Bl -tag -width ".Op Fl I Ns Ar directory" -offset indent
+.It Li ".Op Fl I Ns Ar directory"
+produces
+.Op Fl I Ns Ar directory
+.El
+.Pp
+Note: the
+.Ql \&.Ns
+macro always invokes the
+.Ql \&.No
+macro after eliminating the space unless another macro name
+follows it.
+The macro
+.Ql \&.Ns
+is callable and may call other macros.
+.Ss Options
+The
+.Ql \&.Op
+macro
+places option brackets around the any remaining arguments on the command
+line, and places any
+trailing punctuation outside the brackets. The macros
+.Ql \&.Oc
+and
+.Ql \&.Oo
+may be used across one or more lines.
+.Pp
+.Dl Usage: .Op options ... \*(Pu
+.Bl -tag -width ".Op Fl c Ar objfil Op Ar corfil ," -compact -offset indent
+.It Li \&.Op
+.Op
+.It Li ".Op Fl k"
+.Op Fl k
+.It Li ".Op Fl k ) ."
+.Op Fl k ) .
+.It Li ".Op Fl k Ar kookfile"
+.Op Fl k Ar kookfile
+.It Li ".Op Fl k Ar kookfile ,"
+.Op Fl k Ar kookfile ,
+.It Li ".Op Ar objfil Op Ar corfil"
+.Op Ar objfil Op Ar corfil
+.It Li ".Op Fl c Ar objfil Op Ar corfil ,"
+.Op Fl c Ar objfil Op Ar corfil ,
+.It Li \&.Op word1 word2
+.Op word1 word2
+.El
+.Pp
+The
+.Ql \&.Oc
+and
+.Ql \&.Oo
+macros:
+.Bd -literal -offset indent
+\&.Oo
+\&.Op \&Fl k \&Ar kilobytes
+\&.Op \&Fl i \&Ar interval
+\&.Op \&Fl c \&Ar count
+\&.Oc
+.Ed
+.Pp
+Produce:
+.Oo
+.Op Fl k Ar kilobytes
+.Op Fl i Ar interval
+.Op Fl c Ar count
+.Oc
+.Pp
+The macros
+.Ql \&.Op ,
+.Ql \&.Oc
+and
+.Ql \&.Oo
+are callable and may call other macros.
+.Ss Parenthesis Quote/Enclosure
+Macros
+.Li \&.Pq , \&.Pc
+and
+.Li \&.Po
+follow the conventions for a typical quoting macros,
+see
+.Sx Enclosure Macros
+and
+.Sx Options
+above.
+.Ss Pathnames
+The
+.Ql \&.Pa
+macro formats path or file names.
+.Pp
+.Dl Usage: .Pa pathname \*(Pu
+.Bl -tag -width ".Pa /tmp/fooXXXXX ) ." -compact -offset 14n
+.It Li \&.Pa /usr/share
+.Pa /usr/share
+.It Li \&.Pa /tmp/fooXXXXX\ )\ .
+.Pa /tmp/fooXXXXX ) .
+.El
+.Pp
+The
+.Ql \&.Pa
+macro
+is callable by other macros and may call other macros.
+.Ss Single Quotes/Enclosure
+See
+.Sx Enclosure Macros .
+See
+.Sx Double Quote/Enclosure
+above.
+The single quoting macro
+.Ql \&.Sq
+works in the identical manner as
+.Ql \&.Dq.
+.Ss Prefix Macro
+The
+.Ql \&.Pf
+macro
+is a short cut for combining
+two strings together, the first of which is
+in the default font, and the second a content
+specified string.
+.Pp
+.Bl -tag -width ".Pf ( Fa name2 " -offset 14n -compact
+.It Li ".Pf ( Fa name2"
+becomes
+.Pf ( Fa name2
+.El
+.Pp
+The
+.Ql \&.Pf
+macro is not callable, but may call other macros. The
+.Ql \&.Ns
+macro performs the analogus suffix function.
+.Ss Section Cross References
+The
+.Ql \&.Sx
+macro designates a reference to a section header
+within the same document. It is callable by other macros and may
+call other macros.
+.Pp
+.Bl -tag -width "Li \&.Sx FILES" -offset 14n
+.It Li \&.Sx FILES
+.Sx FILES
+.El
+.Ss References and Citations
+The following macros make a modest attempt to handle references.
+At best, the macros make it convientent to manually drop in a subset of
+refer style references.
+.Pp
+.Bl -tag -width 6n -offset indent -compact
+.It Li ".Rs"
+Reference Start. Causes a line break and begins collection
+of reference information until the
+reference end macro is read.
+.It Li ".Re"
+Reference End. The reference is printed.
+.It Li ".%A"
+Reference author name, one name per invocation.
+.It Li ".%B"
+Book title.
+.It Li ".%J"
+Journal title.
+.It Li ".%N"
+Issue number.
+.It Li ".%O"
+Optional information.
+.It Li ".%R"
+Report name.
+.It Li ".%T"
+Title of article.
+.It Li ".%V"
+Volume(s).
+.El
+.Pp
+The macros begining with
+.Ql %
+are not callable, but may call only the trade name macro which
+returns to its caller. The purpose is to allow trade names
+to be pretty printed in troff/ditroff output. WARNING: this
+has very few trade names defined at the moment and will print unknown
+trade names in the default font.
+.Ss Symbolic
+The symbolic emphasis macro is generally a boldface macro in
+either the symbolic sense or the traditional English usage.
+.Pp
+.Dl Usage: .Sy symbol ... \*(Pu
+.Bl -tag -width ".Sy Important Notice" -compact -offset 14n
+.It Li \&.Sy Important Notice
+.Sy Important Notice
+.El
+.Pp
+The
+.Ql \&.Sy
+macro
+is callable by other macros and may call other macros, except
+in the second form. Arguments to
+.Ql \&.Sy
+may be quoted.
+.Ss Variables
+Generic variable reference:
+.Pp
+.Dl Usage: .Va variable ... \*(Pu
+.Bl -tag -width ".Va char s ] ) ) ," -compact -offset 14n
+.It Li \&.Va count
+.Va count
+.It Li \&.Va settimer ,
+.Va settimer ,
+.It Li \&.Va int\ *prt\ )\ :
+.Va int\ *prt ) :
+.It Li \&.Va char\ s\ ]\ )\ )\ ,
+.Va char\ s ] ) ) ,
+.El
+.Pp
+It is an error to call
+.Ql \&.Va
+without any arguments.
+The
+.Ql \&.Va
+macro
+is callable by other macros and may call other macros.
+.Ss Cross References
+The
+.Ql \&.Xr
+macro 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.
+.Pp
+.Dl Usage: .Xr manpage [1,...,8] \*(Pu
+.Bl -tag -width ".Xr mdoc 7 ) ) ," -compact -offset 14n
+.It Li \&.Xr mdoc
+.Xr mdoc
+.It Li \&.Xr mdoc\ ,
+.Xr mdoc ,
+.It Li \&.Xr mdoc 7
+.Xr mdoc 7
+.It Li \&.Xr mdoc 7\ )\ )\ ,
+.Xr mdoc 7 ) ) ,
+.El
+.Pp
+The
+.Ql \&.Xr
+macro
+is callable by other macros and may call other macros.
+It is an error to call
+.Ql \&.Xr
+without
+any arguments.
+.Ss Extended Arguments
+The
+.Li \&.Xo
+and
+.Li \&.Xc
+maxros allow one to extend an argument list
+on a macro boundary. Argument lists cannot
+be extended within a macro
+which expects all of its arguments on one line such
+as
+.Ql \&.Op .
+.\" ---
+.Sh PAGE LAYOUT MACROS
+.Ss Section Headers
+The first three
+.Ql \&.Sh
+section header macros
+list below are required in every
+man page. The remaining section headers
+are recommended at the disgression of the author
+writing the manual page. The
+.Ql \&.Sh
+macro can take up to nine arguments. It may call
+other macros, but it may not be called by other macros.
+.Bl -tag -width ".Sh SYNOPSIS"
+.It \&.Sh NAME
+The
+.Ql \&.Sh NAME
+macro 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.
+The first is the
+.Ql \&.Nm
+name macro naming the subject of the man page.
+The second is the Name Description macro,
+.Ql \&.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.
+.It \&.Sh SYNOPSIS
+The SYNOPSIS section describes the typical usage of the
+subject of a man page. The macros required
+are either
+.Ql ".Nm" ,
+.Ql ".Cd" ,
+or
+.Ql ".Fn"
+(and possibly
+.Ql ".Fd" ,
+.Ql ".Ft"
+macros).
+The function name
+macro
+.Ql ".Fn"
+is required
+for manual page sections 2 and 3, the command and general
+name macro
+.Ql \&.Nm
+is required for sections 1, 5, 6, 7, 8.
+Section 4 manuals require a
+.Ql ".Nm" , ".Fd"
+or a
+.Ql ".Cd"
+configuration device usage macro.
+Several other macros may be necessary to produce
+the synopsis line as shown below:
+.Pp
+.Bd -filled -offset indent
+.Nm cat
+.Op Fl benstuv
+.Op Fl
+.Ar
+.Ed
+.Pp
+The following macros were used:
+.Pp
+.Dl \&.Nm cat
+.Dl \&.Op \&Fl benstuv
+.Dl \&.Op \&Fl
+.Dl \&.Ar
+.It \&.Sh DESCRIPTION
+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
+.Ql \&.Bl
+begin-list,
+.Ql \&.It
+list-item and
+.Ql \&.El
+end-list
+macros are used (see
+.Sx Lists and Columns
+below).
+.El
+.Pp
+The following
+.Ql \&.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.
+.Bl -tag -width SYNOPSIS
+.It \&.Sh ENVIRONMENT
+The ENVIRONMENT section should reveal any related
+environment
+variables and clues to their behaviour and/or usage.
+.It \&.Sh EXAMPLES
+There are several ways to create examples. See
+the EXAMPLES section below
+for details.
+.It \&.Sh FILES
+Files which are used or created by the man page subject
+should be listed via the
+.Ql \&.Pa
+macro in the FILES section.
+.It \&.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
+.Ql \&.Xr
+macro. At this time
+.Xr refer 1
+style references are not accommodated.
+.It \&.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.
+.It \&.Sh HISTORY
+Any command which does not adhere to any specific standards
+should be outlined historically in this section.
+.It \&.Sh AUTHORS
+Credits, if need be, should be placed here.
+.It \&.Sh DIAGNOSTICS
+Diagnostics from a command should be placed in this section.
+.It \&.Sh ERRORS
+Specific error handling, especially from library functions
+(man page sections 2 and 3) should go here. The
+.Ql \&.Er
+macro is used to specify an errno.
+.It \&.Sh BUGS
+Blatant problems with the topic go here...
+.El
+.Pp
+User specified
+.Ql \&.Sh
+sections may be added,
+for example, this section was set with:
+.Bd -literal -offset 14n
+\&.Sh PAGE LAYOUT MACROS
+.Ed
+.Ss Paragraphs and Line Spacing.
+.Bl -tag -width 6n
+.It \&.Pp
+The \&.Pp paragraph command may
+be used to specify a line space where necessary.
+The macro is not necessary after a
+.Ql \&.Sh
+or
+.Ql \&.Ss
+macro or before
+a
+.Ql \&.Bl
+macro.
+(The
+.Ql \&.Bl
+macro asserts a vertical distance unless the -compact flag is given).
+.El
+.\" .Pp
+.\" .Ds I
+.\" .Cw (ax+bx+c) \ is\ produced\ by\ \&
+.\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\&
+.\" .Cl Cx \t\t
+.\" .Li \&.Cx\ (
+.\" .Cx
+.\" .Cl Cx \t\t
+.\" .Li \&.Va ax
+.\" .Cx
+.\" .Cl Cx \t\t
+.\" .Li \&.Sy \+
+.\" .Cx
+.\" .Cl Cx \&(\&
+.\" .Va ax
+.\" .Cx +
+.\" .Va by
+.\" .Cx +
+.\" .Va c )
+.\" .Cx \t
+.\" .Em is produced by
+.\" .Cx \t
+.\" .Li \&.Va by
+.\" .Cx
+.\" .Cl Cx \t\t
+.\" .Li \&.Sy \+
+.\" .Cx
+.\" .Cl Cx \t\t
+.\" .Li \&.Va c )
+.\" .Cx
+.\" .Cl Cx \t\t
+.\" .Li \&.Cx
+.\" .Cx
+.\" .Cw
+.\" .De
+.\" .Pp
+.\" This example shows the same equation in a different format. The spaces
+.\" around the
+.\" .Li \&+
+.\" signs were forced with
+.\" .Li \e :
+.\" .Pp
+.\" .Ds I
+.\" .Cw (ax\ +\ bx\ +\ c) \ is\ produced\ by\ \&
+.\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\&
+.\" .Cl Cx \t\t
+.\" .Li \&.Cx\ (
+.\" .Cx
+.\" .Cl Cx \t\t
+.\" .Li \&.Va a
+.\" .Cx
+.\" .Cl Cx \t\t
+.\" .Li \&.Sy x
+.\" .Cx
+.\" .Cl Cx \t\t
+.\" .Li \&.Cx \e\ +\e\ \e&
+.\" .Cx
+.\" .Cl Cx \&(\&
+.\" .Va a
+.\" .Sy x
+.\" .Cx \ +\ \&
+.\" .Va b
+.\" .Sy y
+.\" .Cx \ +\ \&
+.\" .Va c )
+.\" .Cx \t
+.\" .Em is produced by
+.\" .Cl Cx \t\t
+.\" .Li \&.Va b
+.\" .Cx
+.\" .Cl Cx \t\t
+.\" .Li \&.Sy y
+.\" .Cx
+.\" .Cl Cx \t\t
+.\" .Li \&.Cx \e\ +\e\ \e&
+.\" .Cx
+.\" .Cl Cx \t\t
+.\" .Li \&.Va c )
+.\" .Cx
+.\" .Cl Cx \t\t
+.\" .Li \&.Cx
+.\" .Cx
+.\" .Cw
+.\" .De
+.\" .Pp
+.\" The incantation below was
+.\" lifted from the
+.\" .Xr adb 1
+.\" manual page:
+.\" .Pp
+.\" .Ds I
+.\" .Cw \&[?/]m_b1_e1_f1[?/]\& is\ produced\ by
+.\" .Cl Cx \t\t
+.\" .Li \&.Cx Op Sy ?/
+.\" .Cx
+.\" .Cl Cx \t\t
+.\" .Li \&.Nm m
+.\" .Cx
+.\" .Cl Cx Op Sy ?/
+.\" .Nm m
+.\" .Ad \ b1 e1 f1
+.\" .Op Sy ?/
+.\" .Cx \t
+.\" .Em is produced by
+.\" .Cx \t
+.\" .Li \&.Ar \e\ b1 e1 f1
+.\" .Cx
+.\" .Cl Cx \t\t
+.\" .Li \&.Op Sy ?/
+.\" .Cx
+.\" .Cl Cx \t\t
+.\" .Li \&.Cx
+.\" .Cx
+.\" .Cw
+.\" .De
+.\" .Pp
+.Ss Examples and Displays
+There are five types of displays, a quickie one line indented display
+.Ql \&.D1 ,
+a quickie one line literal display
+.Ql \&.Dl ,
+a block literal, block filled and block ragged which use
+the
+.Ql \&.Bd
+begin-display
+and
+.Ql \&.Ed
+end-display macros.
+.Pp
+.Bl -tag -width \&.D1
+.It Li \&.D1
+(D-one) Display one line of indented text.
+Arguments are checked to see if they are callable.
+.Bd -ragged -offset indent
+.Li \&.D1 \&Fl ldghfstru
+.Ed
+.Pp
+produces:
+.Pp
+.Dl Fl ldghfstru
+.It Li \&.Dl
+(D-ell)
+Display one line of indented
+.Em literal
+text. The
+.Ql \&.Dl
+example macro has been used throughout this
+file. It allows
+the indent (display) of one line of text.
+Its default font is set to
+constant width (literal) however
+.Ql \&.Dl
+does check arguments to see it they are callable.
+Macros called from
+.Li \&.Dl
+should be content macros; calling macros from
+the page layout section
+is redundant and may cause unpredictable errors.
+.Bd -ragged -offset indent
+.Li \&.Dl % ls -ldg /usr/local/bin
+.Ed
+.Pp
+produces:
+.Pp
+.Dl % ls -ldg /usr/local/bin
+.It Li \&.Bd
+Begin-display. The
+.Ql \&.Bd
+display must be ended with the
+.Ql \&.Ed
+macro. Displays may be nested within displays and
+lists.
+.Ql \&.Bd
+has the following syntax:
+.Pp
+.Dl ".Bd display-type [offset offset_value]"
+.Pp
+The display-type must be one of the following four types and
+may have an offset specifier for indentation:
+.Ql \&.Bd .
+.Pp
+.Bl -tag -width "literalxx" -compact
+.It Fl ragged
+Display a block of text as typed,
+right (and left) margin edges are left ragged.
+.It Fl filled
+Display a filled (formatted) block.
+The block of text is formatted (the edges are filled \-
+not left ragged).
+.It Fl literal
+Display a literal block, useful for source code or
+simple tabbed or spaced text.
+.It Fl file Ar file_name
+The file name following the
+.Fl file
+flag is read and displayed. Literal mode is
+asserted and tabs are set at 8 constant width character
+intervals, however any
+.Xr troff/ Ns Nm \-mdoc
+commands in file will be processed.
+.It Fl offset Ar string
+If
+.Fl offset
+is specified with one of the following strings, the string
+is interpreted to indicate the level of indentation for the
+forthcoming block of text:
+.Pp
+.Bl -tag -width "indent" -compact
+.It Ar left
+Align block on the current left margin,
+this is the default mode of
+.Ql \&.Bd .
+.It Ar center
+Supposedly center the block. At this time
+unfortunately, the block merely gets
+left aligned about an imaginary center margin.
+.It Ar indent
+Indents by one default indent value or tab. The default
+indent value is also used for the
+.Ql \&.D1
+display so one can be garanteed of the two types of displays
+lining up. This indent is nornally set to 6n or about two
+thirds of an inch (six constant width characters).
+.It Ar indent-two
+Indents two times the default indent value.
+.It Ar right
+This
+.Em left
+aligns the block about two inches from
+the right side of the page. This macro also needs
+work and perhaps may never be right in
+.Xr troff .
+.El
+.El
+.It ".Ed"
+End-display.
+.El
+.Ss Tagged Lists and Columns
+There are several types of lists which may be initiated with the
+.Ql ".Bl"
+begin-list macro. Items within the list
+are specified with the
+.Ql ".It"
+item macro and
+each list must end with the
+.Ql ".El"
+macro. Lists may be nested within themselves and within displays.
+Columns may be used inside of lists, but lists are unproven
+inside of columns.
+.Pp
+In addition, several list attributes may be specified such as
+the width of a tag, the list offset, and compactness specified
+(blank lines between items allowed or disallowed).
+The following list types are accepted by
+.Ql ".Bl":
+.Pp
+.Bl -ohang -compact
+.It Fl bullet
+.It Fl item
+.It Fl enum
+These three are the simplest types of lists. Once the
+.Ql ".Bl"
+macro has been given, items in the list are merely
+indicated by a line consisting solely of the
+.Ql ".It"
+macro. For example, the source text for a simple enumerated list
+would look like:
+.Bd -literal -offset indent-two
+\&.Bl -enum -compact
+\&.It
+\&Item one goes here.
+\&.It
+\&And item two here.
+\&.It
+\&Lastly item three goes here.
+\&.El
+.Ed
+.Pp
+The results:
+.Pp
+.Bl -enum -offset indent-two -compact
+.It
+Item one goes here.
+.It
+And item two here.
+.It
+Lastly item three goes here.
+.El
+.Pp
+A simple bullet list construction:
+.Bd -literal -offset indent-two
+\&.Bl -bullet -compact
+\&.It
+\&Bullet one goes here.
+\&.It
+\&Bullet two here.
+\&.El
+.Ed
+.Pp
+Produces:
+.Bl -bullet -offset indent-two -compact
+.It
+Bullet one goes here.
+.It
+Bullet two here.
+.El
+.Pp
+.It Fl tag
+.It Fl diag
+.It Fl hang
+.It Fl ohang
+.It Fl inset
+These list-types collect arguments specified with the
+.Ql \&.It
+macro and create a label which may be
+.Em inset
+into the forth coming text,
+.Em hanged
+(exdented) from the forth coming text,
+.Em overhanged
+set above the forth coming paragraph or
+.Em tagged
+(exdented and offset). This
+list was constructed with the
+.Ql Fl ohang
+list-type. The
+.Ql \&.It
+macro may call any callable macros for the inset, hang
+and tag list-types, but will not call macros for the
+diag type.
+Here is an example of inset labels:
+.Bl -inset -offset indent
+.It Em Tag
+The tagged list (also called a tagged paragraph) is the
+most common type of list used in the Berkeley manuals.
+.It Em Diag
+Diag lists create section four diagnostic lists
+and are similar to inset lists except callable
+macros are ignored.
+.It Em Hang
+Hanged labels are a matter of taste.
+.It Em Ohang
+Over hanging labels are nice when space is constrained.
+.It Em Inset
+Inset labels are useful for controlling blocks of
+paragraphs and are valuable for converting
+.Nm \-mdoc
+manuals to other formats.
+.El
+.Pp
+Here is the source text which produced the above example:
+.Bd -literal -offset indent
+\&.Bl -inset -offset indent
+\&.It Em Tag
+\&The tagged list (also called a tagged paragraph) is the
+\&most common type of list used in the Berkeley manuals.
+\&.It Em Diag
+\&Diag lists create section four diagnostic lists
+\&and are similar to inset lists except callable
+\¯os are ignored.
+\&.It Em Hang
+\&Hanged labels are a matter of taste.
+\&.It Em Ohang
+\&Over hanging labels are nice when space is constrained.
+\&.It Em Inset
+\&Inset labels are useful for controlling blocks of
+\¶graphs and are valuable for converting
+\&.Nm \-mdoc
+\&manuals to other formats.
+\&.El
+.Ed
+.Pp
+Here is a hanged list with just one item:
+.Bl -hang -offset indent
+.It Em Hanged
+labels appear similar to tagged lists when the
+label is smaller than the label width.
+.It Em Longer hanged list labels
+blend in to the paragraph unlike
+tagged paragraph labels.
+.El
+.Pp
+And the unfomatted text which created it:
+.Bd -literal -offset indent
+\&.Bl -hang -offset indent
+\&.It Em Hanged
+\&labels appear similar to tagged lists when the
+\&label is smaller than the label width.
+\&.It Em Longer hanged list labels
+\&blend in to the paragraph unlike
+\&tagged paragraph labels.
+\&.El
+.Ed
+.Pp
+The tagged list which follows uses an optional width specifier to controll
+the width of the tag.
+.Pp
+.Bl -tag -width "PAGEIN 10" -compact -offset indent
+.It SL 10
+sleep time of the process (seconds blocked)
+.It PAGEIN 10
+number of disk i/o's resulting from references
+by the process to pages not loaded in core.
+.It UID 10
+numerical user-id of process owner
+.It PPID 10
+numerical id of parent of process process priority
+(non-positive when in non-interruptible wait)
+.El
+.Pp
+The raw text:
+.Bd -literal -offset indent
+\&.Bl -tag -width "PAGEIN 10" -compact -offset indent
+\&.It SL 10
+\&sleep time of the process (seconds blocked)
+\&.It PAGEIN 10
+\&number of disk i/o's resulting from references
+\&by the process to pages not loaded in core.
+\&.It UID 10
+\&numerical user-id of process owner
+\&.It PPID 10
+\&numerical id of parent of process process priority
+\&(non-positive when in non-interruptible wait)
+\&.El
+.Ed
+.Pp
+Acceptable width specifiers:
+.Bl -tag -width Ar -offset indent
+.It Fl width Ar "\&Fl"
+sets the width to the default width for a flag. All callable
+macros have a default width value. The
+.Ql \&.Fl ,
+value is presently
+set to ten constant width characters or about five sixth of
+an inch.
+.It Fl width Ar "24n"
+sets the width to 24 constant width characters or about two
+inches. The
+.Ql n
+is absolutely necessary for the scaling to work correctly.
+.It Fl width Ar "ENAMETOOLONG"
+sets width to the constant width length of the
+string given.
+.It Fl width Ar "\\*qint mkfifo\\*q"
+again, the width is set to the constant width of the string
+given.
+.El
+.Pp
+If a width is not specified for the tag list type, the first
+time
+.Ql \&.It
+is invoked, an attempt is made to determine an appropriate
+width. If the first argument to
+.Ql ".It"
+is a callable macro, the default width for that macro will be used
+as if the macro name had been supplied as the width. However,
+if another item in the list is given with a different callable
+macro name, a new and nested list is assumed. Here is an involved
+example of a self nesting list:
+.Sh DIAGNOSTICS
+The debugging facilities for
+.Nm \-mdoc
+are limited, but can help detect subtle errors such
+as the collision of an argument name with an internal
+register or macro name. (A what?)
+A register is an arithmetic storage class for
+.Xr troff
+with a one or two character name.
+All registers internal to
+.Nm \-mdoc
+for
+.Xr troff
+and
+.Xr ditroff
+are two characters and
+of the form <uppercase><lowercase> such as
+.Ql \&Ar ,
+<lowercase><uppercase> as
+.Ql \&aR
+or
+<upper or lower letter><digit> as
+.Ql \&C\&1 .
+And adding to the muddle,
+.Xr troff
+has its own internal registers all of which are either
+two lowercase characters or a dot plus a letter or meta-character
+character.
+In one of the introduction examples, it was shown how to
+prevent the interpretation of a macro name with the escape sequence
+.Ql \e& .
+This is sufficient for the internal register names also.
+.Pp
+.\" Every callable macro name has a corresponding register
+.\" of the same name (<Uppercase><lowercase>).
+.\" There are also specific registers which have
+.\" been used for stacks and arrays and are listed in the
+.\" .Sx Appendix .
+.\" .Bd -ragged -offset 4n
+.\" [A-Z][a-z] registers corresponding to macro names (example ``Ar'')
+.\" [a-z][A-Z] registers corresponding to macro names (example ``aR'')
+.\" C[0-9] argument types (example C1)
+.\" O[0-9] offset stack (displays)
+.\" h[0-9] horizontal spacing stack (lists)
+.\" o[0-9] offset (stack) (lists)
+.\" t[0-9] tag stack (lists)
+.\" v[0-9] vertical spacing stack (lists)
+.\" w[0-9] width tag/label stack
+.\" .Ed
+.\" .Pp
+If a non-escaped register name is given in the argument list of a request
+unpredictable behaviour will occur. In general, anytime huge portions
+of text do not appear where expected in the output, or small strings
+such as list tags disappear, chances are there is a misunderstanding
+about an argument type in the argument list.
+Your mother never intended for you to remember this evil stuff - so here
+is a way to find out whether or not your arguments are valid: The
+.Ql \&.Db
+(debug)
+macro displays the interpretation of the argument list for most
+macros. Macros such as the
+.Ql \&.Pp
+(paragraph)
+macro do not contain debugging information. All of the callable macros do,
+and it is strongly advised whenever in doubt,
+turn on the
+.Ql \&.Db
+macro.
+.Pp
+.Dl Usage: \&.Db [on | off]
+.Pp
+An example of a portion of text with
+the debug macro placed above and below an
+artificially created problem (a flag argument
+.Ql \&aC
+which should be
+.Ql \e&aC
+in order to work):
+.Bd -literal -offset indent
+\&.Db on
+\&.Op Fl aC Ar file )
+\&.Db off
+.Ed
+.Pp
+The resulting output:
+.Bd -literal -offset indent
+DEBUGGING ON
+DEBUG(argv) MACRO: `.Op' Line #: 2
+ Argc: 1 Argv: `Fl' Length: 2
+ Space: `' Class: Executable
+ Argc: 2 Argv: `aC' Length: 2
+ Space: `' Class: Executable
+ Argc: 3 Argv: `Ar' Length: 2
+ Space: `' Class: Executable
+ Argc: 4 Argv: `file' Length: 4
+ Space: ` ' Class: String
+ Argc: 5 Argv: `)' Length: 1
+ Space: ` ' Class: Closing Punctuation or suffix
+ MACRO REQUEST: .Op Fl aC Ar file )
+DEBUGGING OFF
+.Ed
+.Pp
+The first line of information tells the name of the calling
+macro, here
+.Ql \&.Op ,
+and the line number it appears on. If one or more files are involved
+(especially if text from another file is included) the line number
+may be bogus. If there is only one file, it should be accurate.
+The second line gives the argument count, the argument
+.Pq Ql \&Fl
+and its length. If the length of an argument is two characters, the
+argument is tested to see if it is executable (unfortunately, any
+register which contains a non-zero value appears executable).
+The third line gives the space allotted for a class, and the
+class type. The problem here is the argument aC should not be
+executable. The four types of classes are string, executable, closing
+punctuation and opening punctuation. The last line shows the entire
+argument list as it was read. In this next example, the offending
+.Ql \&aC
+is escaped:
+.Bd -literal -offset indent
+\&.Db on
+\&.Em An escaped \e&aC
+\&.Db off
+.Ed
+.Bd -literal -offset indent
+DEBUGGING ON
+DEBUG(fargv) MACRO: `.Em' Line #: 2
+ Argc: 1 Argv: `An' Length: 2
+ Space: ` ' Class: String
+ Argc: 2 Argv: `escaped' Length: 7
+ Space: ` ' Class: String
+ Argc: 3 Argv: `aC' Length: 2
+ Space: ` ' Class: String
+ MACRO REQUEST: .Em An escaped &aC
+DEBUGGING OFF
+.Ed
+.Pp
+The argument
+.Ql \e&aC
+shows up with the same length of 2 as the
+.Ql \e&
+sequence produces a zero width, but a register
+named
+.Ql \e&aC
+was not found and the type classified as string.
+.Pp
+Other diagnostics consist of usage statements and are self explanatory.
+.Sh FILES
+.Bl -tag -width /usr/share/man0/template.doc -compact
+.It Pa /usr/share/tmac/tmac.doc
+manual macro package
+.It Pa /usr/share/man0/template.doc
+template for writing a man page
+.El
+.Sh HISTORY
+4.4 BSD
+.Sh SEE ALSO
+.Xr mdoc 7 ,
+.Xr man 1 ,
+.Xr troff 1
+.Sh BUGS
+Undesirable hyphenation on the dash of a flag
+argument is not yet resolved, and causes
+occasional mishaps in the DESCRIPTION section.
+(line break on the hyphen).
+.Pp
+Predefined strings are not declared in documentation.
+.Pp
+Section 3f has not been added to the header routines.
+.Pp
+.Ql \&.Nm
+font should be changed in NAME section.
+.Pp
+.Ql \&.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.
+.Pp
+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.
+.Pp
+The list and display macros to not do any keeps
+and certainly should be able to.
projects / unix-history / commitdiff