+MDOC.SAMPLES(7) BSD Reference Manual MDOC.SAMPLES(7)
+
+N\bNA\bAM\bME\bE
+ m\bmd\bdo\boc\bc.\b.s\bsa\bam\bmp\bpl\ble\bes\bs - tutorial sampler for writing BSD manuals with -\b-m\bmd\bdo\boc\bc
+
+S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
+ m\bma\ban\bn m\bmd\bdo\boc\bc.\b.s\bsa\bam\bmp\bpl\ble\bes\bs
+
+D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
+ A tutorial sampler for writing BSD manual pages with the -\b-m\bmd\bdo\boc\bc macro
+ package, a _\bc_\bo_\bn_\bt_\be_\bn_\bt-based and _\bd_\bo_\bm_\ba_\bi_\bn-based formatting package for
+ troff(1). Its predecessor, the -man(7) package, addressed page layout
+ leaving the manipulation of fonts and other typesetting details to the
+ individual author. In -\b-m\bmd\bdo\boc\bc, page layout macros make up the _\bp_\ba_\bg_\be
+ _\bs_\bt_\br_\bu_\bc_\bt_\bu_\br_\be _\bd_\bo_\bm_\ba_\bi_\bn which consists of macros for titles, section headers,
+ displays and lists. Essentially items which affect the physical position
+ of text on a formatted page. In addition to the page structure domain,
+ there are two more domains, the manual domain and the general text do-
+ main. The general text domain is defined as macros which perform tasks
+ such as quoting or emphasizing pieces of text. The manual domain is de-
+ fined as macros that are a subset of the day to day informal language
+ used to describe commands, routines and related BSD files. Macros in the
+ manual domain handle command names, command line arguments and options,
+ function names, function parameters, pathnames, variables, cross refer-
+ ences to other manual pages, and so on. These domain 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 transla-
+ tion to future documentation tools.
+
+ Through out the UNIX manual pages, a manual entry is simply referred to
+ as a man page, regardless of actual length and without sexist intention.
+
+G\bGE\bET\bTT\bTI\bIN\bNG\bG S\bST\bTA\bAR\bRT\bTE\bED\bD
+ Since a tutorial document is normally read when a person desires to use
+ the material immediately, the assumption has been made that the user of
+ this document may be impatient. The material presented in the remained
+ of this document is outlined as follows:
+
+ 1. TROFF IDIOSYNCRASIES
+ Macro Usage.
+ Passing Space Characters in an Argument.
+ Trailing Blank Space Characters (a warning).
+ Escaping Special Characters.
+
+ 2. THE ANATOMY OF A MAN PAGE
+ A manual page template.
+
+ 3. INTRODUCTION OF TITLE MACROS.
+
+ 4. INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS.
+ What's in a name....
+ General Syntax.
+
+ 5. MANUAL DOMAIN
+ Addresses.
+ Arguments.
+ Configuration Declarations (section four only).
+ Command Modifier .
+ Defined Variables.
+ Errno's (Section two only).
+ Environment Variables.
+ Function Argument.
+ Function Declaration.
+
+
+ Flags.
+ Functions (library routines).
+ Function Types.
+ Interactive Commands.
+ Literals.
+ Names.
+ Options.
+ Pathnames.
+ Variables.
+ Cross References.
+
+ 6. GENERAL TEXT DOMAIN
+ AT&T Macro.
+ BSD Macro.
+ UNIX Macro.
+ Emphasis Macro.
+ Enclosure/Quoting Macros
+ Angle Bracket Quote/Enclosure.
+ Bracket Quotes/Enclosure.
+ Double Quote macro/Enclosure.
+ Parenthesis Quote/Enclosure.
+ Single Quotes/Enclosure.
+ Prefix Macro.
+ Extended Arguments.
+ No-Op or Normal Text Macro.
+ No Space Macro.
+ Section Cross References.
+ Symbolic Macro.
+ References and Citations.
+ Trade Names (Acronyms and Type Names).
+
+ 7. PAGE STRUCTURE DOMAIN
+ Section Headers.
+ Paragraphs and Line Spacing.
+ Keeps.
+ Displays.
+ Lists and Columns.
+
+ 8. PREDEFINED STRINGS
+
+ 9. DIAGNOSTICS
+
+ 10. FORMATTING WITH GROFF, TROFF AND NROFF
+
+ 11. BUGS
+
+T\bTR\bRO\bOF\bFF\bF I\bID\bDI\bIO\bOS\bSY\bYN\bNC\bCR\bRA\bAS\bSI\bIE\bES\bS
+ The -\b-m\bmd\bdo\boc\bc package attempts to simplify the process of writing a man page.
+ Theoretically, one should not have to learn the dirty details of troff(1)
+ to use -\b-m\bmd\bdo\boc\bc; however, there are a few limitations which are unavoidable
+ and best gotten out of the way. And, too, be forewarned, this package is
+ _\bn_\bo_\bt fast.
+
+ M\bMa\bac\bcr\bro\bo U\bUs\bsa\bag\bge\be
+ As in troff(1), a macro is called by placing a `.' (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 char-
+ acter at the beginning of the line which causes troff(1) to interpret the
+ next two characters as a macro name. To place a `.' (dot character) at
+ the beginning of a line in some context other than a macro invocation,
+ precede the `.' (dot) with the `\&' escape sequence. The `\&' translates
+ literally to a zero width space, and is never displayed in the output.
+
+ In general, troff(1) macros accept up to nine arguments, any extra argu-
+ ments are ignored. Most macros in -\b-m\bmd\bdo\boc\bc accept nine arguments and, in
+ limited cases, arguments may be continued or extended on the next line
+ (See _\bE_\bx_\bt_\be_\bn_\bs_\bi_\bo_\bn_\bs). A few macros handle quoted arguments (see _\bP_\ba_\bs_\bs_\bi_\bn_\bg _\bS_\bp_\ba_\bc_\be
+ _\bC_\bh_\ba_\br_\ba_\bc_\bt_\be_\br_\bs _\bi_\bn _\ba_\bn _\bA_\br_\bg_\bu_\bm_\be_\bn_\bt below).
+
+ Most of the -\b-m\bmd\bdo\boc\bc general text domain and manual domain macros are spe-
+ cial in that their argument lists are _\bp_\ba_\br_\bs_\be_\bd for callable macro names.
+ This means an argument on the argument list which matches a general text
+ or manual domain macro name and is determined to be callable will be exe-
+ cuted or called when it is processed. In this case the argument, al-
+ though the name of a macro, is not preceded by a `.' (dot). It is in
+ this manner that many macros are nested; for example the option macro,
+ `.Op', may _\bc_\ba_\bl_\bl the flag and argument macros, `Fl' and `Ar', to specify
+ an optional flag with an argument:
+
+ [-\b-s\bs _\bb_\by_\bt_\be_\bs] is produced by .Op Fl s Ar bytes
+
+ To prevent a two character string from being interpreted as a macro name,
+ precede the string with the escape sequence `\&':
+
+ [Fl s Ar bytes] is produced by .Op \&Fl s \&Ar bytes
+
+ Here the strings `Fl' and `Ar' are not interpreted as macros. Macros
+ whose argument lists are parsed for callable arguments are referred to as
+ parsed and macros which may be called from an argument list are referred
+ to as callable through out this document and in the companion quick ref-
+ erence manual mdoc(7). This is a technical _\bf_\ba_\bu_\bx _\bp_\ba_\bs as almost all of the
+ macros in -\b-m\bmd\bdo\boc\bc are parsed, but as it was cumbersome to constantly refer
+ to macros as being callable and being able to call other macros, the term
+ parsed has been used.
+
+ P\bPa\bas\bss\bsi\bin\bng\bg S\bSp\bpa\bac\bce\be C\bCh\bha\bar\bra\bac\bct\bte\ber\brs\bs i\bin\bn a\ban\bn A\bAr\brg\bgu\bum\bme\ben\bnt\bt
+ 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 `.Fn' expects the first argument to be the name of a function and
+ any remaining arguments to be function parameters. As 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, _\bi_\bn_\bt _\bf_\bo_\bo.
+
+ There are two possible ways to pass an argument which contains an embed-
+ ded space. _\bI_\bm_\bp_\bl_\be_\bm_\be_\bn_\bt_\ba_\bt_\bi_\bo_\bn _\bn_\bo_\bt_\be: Unfortunately, the most convenient way
+ of passing spaces in between quotes by reassigning individual arguments
+ before parsing was fairly expensive speed wise and space wise to imple-
+ ment in all the macros for AT&T troff. It is not expensive for groff but
+ for the sake of portability, has been limited to the following macros
+ which need it the most:
+
+ Cd Configuration declaration (section 4 _\bS_\bY_\bN_\bO_\bP_\bS_\bI_\bS)
+ Bl Begin list (for the width specifier).
+ Em Emphasized text.
+ Fn Functions (sections two and four).
+ It List items.
+ Li Literal text.
+ Sy Symbolic text.
+ %B Book titles.
+ %J Journal names.
+ %O Optional notes for a reference.
+ %R Report title (in a reference).
+ %T Title of article in a book or journal.
+
+ One way of passing a string containing blank spaces is to use the hard or
+ unpaddable space character `\ ', that is, a blank space preceded by the
+ escape character `\'. 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. 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:
+
+ f\bfe\bet\btc\bch\bh(_\bc_\bh_\ba_\br _\b*_\bs_\bt_\br) is created by `.Fn fetch char\ *str'
+
+ f\bfe\bet\btc\bch\bh(_\bc_\bh_\ba_\br _\b*_\bs_\bt_\br) can also be created by `.Fn fetch "*char *str"'
+
+ If the `\' or quotes were omitted, `.Fn' would see three arguments and
+ the result would be:
+
+ f\bfe\bet\btc\bch\bh(_\bc_\bh_\ba_\br, _\b*_\bs_\bt_\br)
+
+ For an example of what happens when the parameter list overlaps a newline
+ boundary, see the _\bB_\bU_\bG_\bS section.
+
+ T\bTr\bra\bai\bil\bli\bin\bng\bg B\bBl\bla\ban\bnk\bk S\bSp\bpa\bac\bce\be C\bCh\bha\bar\bra\bac\bct\bte\ber\brs\bs
+ Troff can be confused by blank space characters at the end of a line. It
+ is a wise preventive 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 `\&' escape character. For example,
+ `string\ \&'.
+
+ E\bEs\bsc\bca\bap\bpi\bin\bng\bg S\bSp\bpe\bec\bci\bia\bal\bl C\bCh\bha\bar\bra\bac\bct\bte\ber\brs\bs
+ Special characters like the newline character `\n', are handled by re-
+ placing the `\' with `\e' (e.g. `\en') to preserve the backslash.
+
+T\bTH\bHE\bE A\bAN\bNA\bAT\bTO\bOM\bMY\bY O\bOF\bF A\bA M\bMA\bAN\bN P\bPA\bAG\bGE\bE
+ The body of a man page is easily constructed from a basic template found
+ in the file:
+
+ .\" /usr/share/misc/man.template:
+ .\" The following six lines are required.
+ .Dd Month day, year
+ .Os OPERATING_SYSTEM [version/release]
+ .Dt DOCUMENT_TITLE [section number] [volume]
+ .Sh NAME
+ .Sh SYNOPSIS
+ .Sh DESCRIPTION
+ .\" The following requests should be uncommented and
+ .\" used where appropriate. This next request is
+ .\" for sections 2 and 3 function return values only.
+ .\" .Sh RETURN VALUES
+ .\" This next request is for sections 1, 6, 7 & 8 only
+ .\" .Sh ENVIRONMENT
+ .\" .Sh FILES
+ .\" .Sh EXAMPLES
+ .\" This next request is for sections 1, 6, 7 & 8 only
+ .\" (command return values (to shell) and
+ .\" fprintf/stderr type diagnostics)
+ .\" .Sh DIAGNOSTICS
+ .\" The next request is for sections 2 and 3 error
+ .\" and signal handling only.
+ .\" .Sh ERRORS
+ .\" .Sh SEE ALSO
+ .\" .Sh STANDARDS
+ .\" .Sh HISTORY
+ .\" .Sh AUTHORS
+ .\" .Sh BUGS
+
+ The first items in the template are the macros (.Dd, .Os, .Dt); the docu-
+ ment date, the operating system the man page or subject source is devel-
+ oped or modified for, and the man page title (_\bi_\bn _\bu_\bp_\bp_\be_\br _\bc_\ba_\bs_\be) along with
+ the section of the manual the page belongs in. These macros identify the
+ page, and are discussed below in _\bT_\bI_\bT_\bL_\bE _\bM_\bA_\bC_\bR_\bO_\bS.
+
+ The remaining items in the template are section headers (.Sh); of which
+ _\bN_\bA_\bM_\bE, _\bS_\bY_\bN_\bO_\bP_\bS_\bI_\bS and _\bD_\bE_\bS_\bC_\bR_\bI_\bP_\bT_\bI_\bO_\bN are mandatory. The headers are discussed
+ in _\bP_\bA_\bG_\bE _\bS_\bT_\bR_\bU_\bC_\bT_\bU_\bR_\bE _\bD_\bO_\bM_\bA_\bI_\bN, after presentation of _\bM_\bA_\bN_\bU_\bA_\bL _\bD_\bO_\bM_\bA_\bI_\bN. Several
+ content macros are used to demonstrate page layout macros; reading about
+ content macros before page layout macros is recommended.
+
+T\bTI\bIT\bTL\bLE\bE M\bMA\bAC\bCR\bRO\bOS\bS
+ The title macros are the first portion of the page structure domain, but
+ are presented first and separate for someone who wishes to start writing
+ a man page yesterday. 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.
+
+ .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 omit-
+ ted. A volume title may be arbitrary or one of the following:
+
+ AMD UNIX Ancestral Manual Documents
+ SMM UNIX System Manager's Manual
+ URM UNIX Reference Manual
+ PRM UNIX Programmer's Manual
+
+ The default volume labeling is URM for sections 1, 6, and 7; SMM
+ for section 8; PRM for sections 2, 3, 4, and 5.
+
+ .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, a typical footer might be:
+
+ .Os BSD 4.3
+
+ or for a locally produced set
+
+ .Os CS Department
+
+ The Berkeley default, `.Os' without an argument, has been defined
+ as BSD Experimental in the site specific file
+ _\b/_\bu_\bs_\br_\b/_\bs_\br_\bc_\b/_\bs_\bh_\ba_\br_\be_\b/_\bt_\bm_\ba_\bc_\b/_\bd_\bo_\bc_\b-_\bc_\bo_\bm_\bm_\bo_\bn. It really should default to
+ LOCAL. Note, if the `.Os' macro is not present, the bottom left
+ corner of the page will be ugly.
+
+ .Dd month day, year
+ The date should be written formally:
+
+ January 25, 1989
+
+M\bMA\bAN\bNU\bUA\bAL\bL D\bDO\bOM\bMA\bAI\bIN\bN
+ W\bWh\bha\bat\bt'\b's\bs i\bin\bn a\ba n\bna\bam\bme\be.\b..\b..\b.
+ The manual domain 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 de-
+ scription of -\b-m\bmd\bdo\boc\bc macro request usage. Second is the description of a
+ UNIX command _\bw_\bi_\bt_\bh -\b-m\bmd\bdo\boc\bc 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.
+
+ In the first case, troff(1) macros are themselves a type of command; the
+ general syntax for a troff command is:
+
+ .Va argument1 argument2 ... argument9
+
+ The `.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 UNIX
+ command using the content macros is a bit more involved; a typical
+ _\bS_\bY_\bN_\bO_\bP_\bS_\bI_\bS command line might be displayed as:
+
+ f\bfi\bil\blt\bte\ber\br [-\b-f\bfl\bla\bag\bg] _\bi_\bn_\bf_\bi_\bl_\be _\bo_\bu_\bt_\bf_\bi_\bl_\be
+
+ Here, f\bfi\bil\blt\bte\ber\br is the command name and the bracketed string -\b-f\bfl\bla\bag\bg is a _\bf_\bl_\ba_\bg
+ argument designated as optional by the option brackets. In -\b-m\bmd\bdo\boc\bc terms,
+ _\bi_\bn_\bf_\bi_\bl_\be and _\bo_\bu_\bt_\bf_\bi_\bl_\be are called _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs. The macros which formatted the
+ above example:
+
+ .Nm filter
+ .Op Fl flag
+ .Ar infile outfile
+
+ In the third case, discussion of commands and command syntax includes
+ both examples above, but may add more detail. The arguments _\bi_\bn_\bf_\bi_\bl_\be and
+ _\bo_\bu_\bt_\bf_\bi_\bl_\be from the example above might be referred to as _\bo_\bp_\be_\br_\ba_\bn_\bd_\bs or _\bf_\bi_\bl_\be
+ _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs. Some command line argument lists are quite long:
+
+ m\bma\bak\bke\be [-\b-e\bei\bik\bkn\bnq\bqr\brs\bst\btv\bv] [-\b-D\bD _\bv_\ba_\br_\bi_\ba_\bb_\bl_\be] [-\b-d\bd _\bf_\bl_\ba_\bg_\bs] [-\b-f\bf _\bm_\ba_\bk_\be_\bf_\bi_\bl_\be]
+ [-\b-I\bI _\bd_\bi_\br_\be_\bc_\bt_\bo_\br_\by] [-\b-j\bj _\bm_\ba_\bx_\b__\bj_\bo_\bb_\bs] [_\bv_\ba_\br_\bi_\ba_\bb_\bl_\be_\b=_\bv_\ba_\bl_\bu_\be] [_\bt_\ba_\br_\bg_\be_\bt _\b._\b._\b.]
+
+ Here one might talk about the command m\bma\bak\bke\be and qualify the argument
+ _\bm_\ba_\bk_\be_\bf_\bi_\bl_\be, as an argument to the flag, -\b-f\bf, or discuss the optional file
+ operand _\bt_\ba_\br_\bg_\be_\bt. In the verbal context, such detail can prevent confusion,
+ however the -\b-m\bmd\bdo\boc\bc package does not have a macro for an argument _\bt_\bo a
+ flag. Instead the `Ar' argument macro is used for an operand or file ar-
+ gument like _\bt_\ba_\br_\bg_\be_\bt as well as an argument to a flag like _\bv_\ba_\br_\bi_\ba_\bb_\bl_\be. The
+ make command line was produced from:
+
+ .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
+ .Bk -words
+ .Op Ar target ...
+ .Ek
+
+ The `.Bk' and `.Ek' macros are explained in _\bK_\be_\be_\bp_\bs.
+
+ G\bGe\ben\bne\ber\bra\bal\bl S\bSy\byn\bnt\bta\bax\bx
+ The manual domain and general text domain macros share a similar syntax
+ with a few minor deviations: `.Ar', `.Fl', `.Nm', and `.Pa' differ only
+ when called without arguments; `.Fn' and `.Xr' impose an order on their
+ argument lists and the `.Op' and `.Fn' macros have nesting limitations.
+ All content macros are capable of recognizing and properly handling punc-
+ tuation, provided each punctuation character is separated by a leading
+ space. If an request is given:
+
+ .Li sptr, ptr),
+
+ The result is:
+
+ sptr, ptr),
+
+ The punctuation is not recognized and all is output in the literal font.
+ If the punctuation is separated by a leading white space:
+
+ .Li sptr , ptr ) ,
+
+ The result is:
+
+ sptr, ptr),
+
+ The punctuation is now recognized and is output in the default font dis-
+ tinguishing it from the strings in literal font.
+
+ To remove the special meaning from a punctuation character escape it with
+ `\&'. Troff is limited as a macro language, and has difficulty when pre-
+ sented with a string containing a member of the mathematical, logical or
+ quotation set:
+
+ {+,-,/,*,%,<,>,<=,>=,=,==,&,`,',"}
+
+ The problem is that troff may assume it is supposed to actually perform
+ the operation or evaluation suggested by the characters. To prevent the
+ accidental evaluation of these characters, escape them with `\&'. Typical
+ syntax is shown in the first content macro displayed below, `.Ad'.
+
+ A\bAd\bdd\bdr\bre\bes\bss\bs M\bMa\bac\bcr\bro\bo
+ The address macro identifies an address construct of the form ad-
+ dr1[,addr2[,addr3]].
+
+ Usage: .Ad address ... { . , ; : ( ) [ ]}
+ .Ad addr1 _\ba_\bd_\bd_\br_\b1
+ .Ad addr1 . _\ba_\bd_\bd_\br_\b1.
+ .Ad addr1 , file2 _\ba_\bd_\bd_\br_\b1, _\bf_\bi_\bl_\be_\b2
+ .Ad f1 , f2 , f3 : _\bf_\b1, _\bf_\b2, _\bf_\b3:
+ .Ad addr ) ) , _\ba_\bd_\bd_\br)),
+
+ It is an error to call .Ad without arguments. .Ad is callable by other
+ macros and is parsed.
+
+ A\bAr\brg\bgu\bum\bme\ben\bnt\bt M\bMa\bac\bcr\bro\bo
+ The .Ar argument macro may be used whenever a command line argument is
+ referenced.
+
+ Usage: .Ar argument ... { . , ; : ( ) [ ]}
+ .Ar _\bf_\bi_\bl_\be _\b._\b._\b.
+ .Ar file1 _\bf_\bi_\bl_\be_\b1
+ .Ar file1 . _\bf_\bi_\bl_\be_\b1.
+ .Ar file1 file2 _\bf_\bi_\bl_\be_\b1 _\bf_\bi_\bl_\be_\b2
+ .Ar f1 f2 f3 : _\bf_\b1 _\bf_\b2 _\bf_\b3:
+ .Ar file ) ) , _\bf_\bi_\bl_\be)),
+
+ If .Ar is called without arguments `_\bf_\bi_\bl_\be _\b._\b._\b.' is assumed. The .Ar macro
+ is parsed and is callable.
+
+ C\bCo\bon\bnf\bfi\big\bgu\bur\bra\bat\bti\bio\bon\bn D\bDe\bec\bcl\bla\bar\bra\bat\bti\bio\bon\bn (\b(s\bse\bec\bct\bti\bio\bon\bn f\bfo\bou\bur\br o\bon\bnl\bly\by)\b)
+ The `.Cd' macro is used to demonstrate a config(8) declaration for a de-
+ vice interface in a section four manual. This macro accepts quoted argu-
+ ments (double quotes only).
+
+ d\bde\bev\bvi\bic\bce\be l\ble\be0\b0 a\bat\bt s\bsc\bco\bod\bde\be?\b? produced by: `.Cd device le0 at scode?'.
+
+ C\bCo\bom\bmm\bma\ban\bnd\bd M\bMo\bod\bdi\bif\bfi\bie\ber\br
+ The command modifier is identical to the `.Fl' (flag) command with the
+ exception the `.Cm' macro does not assert a dash in front of every argu-
+ ment. Traditionally flags are marked by the preceding dash, some com-
+ mands or subsets of commands do not use them. Command modifiers may also
+ be specified in conjunction with interactive commands such as editor com-
+ mands. See _\bF_\bl_\ba_\bg_\bs.
+
+
+ D\bDe\bef\bfi\bin\bne\bed\bd V\bVa\bar\bri\bia\bab\bbl\ble\bes\bs
+ A variable which is defined in an include file is specified by the macro
+ `.Dv'.
+
+ Usage: .Dv defined_variable ... { . , ; : ( ) [ ]}
+ .Dv MAXHOSTNAMELEN MAXHOSTNAMELEN
+ .Dv TIOCGPGRP ) TIOCGPGRP)
+
+ It is an error to call `.Dv' without arguments. `.Dv' is parsed and is
+ callable.
+
+ E\bEr\brr\brn\bno\bo'\b's\bs (\b(S\bSe\bec\bct\bti\bio\bon\bn t\btw\bwo\bo o\bon\bnl\bly\by)\b)
+ The `.Er' errno macro specifies the error return value for section two
+ library routines. The second example below shows `.Er' used with the
+ `.Bq' general text domain macro, as it would be used in a section two
+ manual page.
+
+ Usage: .Er ERRNOTYPE ... { . , ; : ( ) [ ]}
+ .Er ENOENT ENOENT
+ .Er ENOENT ) ; ENOENT);
+ .Bq Er ENOTDIR [ENOTDIR]
+
+ It is an error to call `.Er' without arguments. The `.Er' macro is
+ parsed and is callable.
+
+ E\bEn\bnv\bvi\bir\bro\bon\bnm\bme\ben\bnt\bt V\bVa\bar\bri\bia\bab\bbl\ble\bes\bs
+ The `.Ev' macro 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 `.Ev' macro is
+ parsed and is callable.
+
+ F\bFu\bun\bnc\bct\bti\bio\bon\bn A\bAr\brg\bgu\bum\bme\ben\bnt\bt
+ The `.Fa' macro is used to refer to function arguments (parameters) out-
+ side of the _\bS_\bY_\bN_\bO_\bP_\bS_\bI_\bS section of the manual or inside the _\bS_\bY_\bN_\bO_\bP_\bS_\bI_\bS section
+ should a parameter list be too long for the `.Fn' macro and the enclosure
+ macros `.Fo' and `.Fc' must be used. `.Fa' may also be used to refer to
+ structure members.
+
+ Usage: .Fa function_argument ... { . , ; : ( ) [ ]}
+ .Fa d_namlen ) ) , _\bd_\b__\bn_\ba_\bm_\bl_\be_\bn)),
+ .Fa iov_len _\bi_\bo_\bv_\b__\bl_\be_\bn
+
+ It is an error to call `.Fa' without arguments. `.Fa' is parsed and is
+ callable.
+
+ F\bFu\bun\bnc\bct\bti\bio\bon\bn D\bDe\bec\bcl\bla\bar\bra\bat\bti\bio\bon\bn
+ The `.Fd' macro is used in the _\bS_\bY_\bN_\bO_\bP_\bS_\bI_\bS section with section two or three
+ functions. The `.Fd' macro does not call other macros and is not
+ callable by other macros.
+
+ Usage: .Fd include_file (or defined variable)
+
+ In the _\bS_\bY_\bN_\bO_\bP_\bS_\bI_\bS section a `.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 decla-
+ ration for the next function.
+
+ F\bFl\bla\bag\bgs\bs
+ The `.Fl' macro handles command line flags. It prepends a dash, `-', to
+ the flag. For interactive command flags, which are not prepended with a
+ dash, the `.Cm' (command modifier) macro is identical, but with out the
+ dash.
+
+ Usage: .Fl argument ... { . , ; : ( ) [ ]}
+ .Fl -\b-
+ .Fl cfv -\b-c\bcf\bfv\bv
+ .Fl cfv . -\b-c\bcf\bfv\bv.
+ .Fl s v t -\b-s\bs -\b-v\bv -\b-t\bt
+ .Fl - , -\b--\b-,
+ .Fl xyz ) , -\b-x\bxy\byz\bz),
+
+ The `.Fl' macro without any arguments results in a dash representing
+ stdin/stdout. Note that giving `.Fl' a single dash, will result in two
+ dashes. The `.Fl' macro is parsed and is callable.
+
+ F\bFu\bun\bnc\bct\bti\bio\bon\bns\bs (\b(l\bli\bib\bbr\bra\bar\bry\by r\bro\bou\but\bti\bin\bne\bes\bs)\b)
+ The .Fn macro is modeled on ANSI C conventions.
+
+ Usage: .Fn [type] function [[type] parameters ... { . , ; : ( ) [ ]}]
+ .Fn getchar g\bge\bet\btc\bch\bha\bar\br()
+ .Fn strlen ) , s\bst\btr\brl\ble\ben\bn()),
+ .Fn "int align" "const * char *sptrs", i\bin\bnt\bt a\bal\bli\big\bgn\bn(_\bc_\bo_\bn_\bs_\bt _\b* _\bc_\bh_\ba_\br _\b*_\bs_\bp_\bt_\br_\bs),
+
+ It is an error to call `.Fn' without any arguments. The `.Fn' macro is
+ parsed and is callable, note that any call to another macro signals the
+ end of the `.Fn' call (it will close-parenthesis at that point).
+
+ For functions that have more than eight parameters (and this is rare),
+ the macros `.Fo' (function open) and `.Fc' (function close) may be used
+ with `.Fa' (function argument) to get around the limitation. For example:
+
+ .Fo "int res_mkquery"
+ .Fa "int op"
+ .Fa "char *dname"
+ .Fa "int class"
+ .Fa "int type"
+ .Fa "char *data"
+ .Fa "int datalen"
+ .Fa "struct rrec *newrr"
+ .Fa "char *buf"
+ .Fa "int buflen"
+ .Fc
+
+ Produces:
+
+ i\bin\bnt\bt r\bre\bes\bs_\b_m\bmk\bkq\bqu\bue\ber\bry\by(_\bi_\bn_\bt _\bo_\bp, _\bc_\bh_\ba_\br _\b*_\bd_\bn_\ba_\bm_\be, _\bi_\bn_\bt _\bc_\bl_\ba_\bs_\bs, _\bi_\bn_\bt _\bt_\by_\bp_\be,
+ _\bc_\bh_\ba_\br _\b*_\bd_\ba_\bt_\ba, _\bi_\bn_\bt _\bd_\ba_\bt_\ba_\bl_\be_\bn, _\bs_\bt_\br_\bu_\bc_\bt _\br_\br_\be_\bc _\b*_\bn_\be_\bw_\br_\br, _\bc_\bh_\ba_\br _\b*_\bb_\bu_\bf, _\bi_\bn_\bt _\bb_\bu_\bf_\bl_\be_\bn)
+
+ The `.Fo' and `.Fc' macros are parsed and are callable. In the _\bS_\bY_\bN_\bO_\bP_\bS_\bI_\bS
+ section, the function will always begin at the beginning of line. If
+ there is more than one function presented in the _\bS_\bY_\bN_\bO_\bP_\bS_\bI_\bS 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, `.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.
+
+ F\bFu\bun\bnc\bct\bti\bio\bon\bn T\bTy\byp\bpe\be
+ This macro is intended for the _\bS_\bY_\bN_\bO_\bP_\bS_\bI_\bS section. It may be used anywhere
+ else in the man page without problems, but its main purpose is to present
+ the function type in kernel normal form for the _\bS_\bY_\bN_\bO_\bP_\bS_\bI_\bS of sections two
+ and three (it causes a page break allowing the function name to appear on
+ the next line).
+
+ Usage: .Ft type ... { . , ; : ( ) [ ]}
+
+ .Ft struct stat _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt
+
+ The `.Ft' request is not callable by other macros.
+
+ I\bIn\bnt\bte\ber\bra\bac\bct\bti\biv\bve\be C\bCo\bom\bmm\bma\ban\bnd\bds\bs
+ The `.Ic' macro designates an interactive or internal command.
+
+ Usage: .Li argument ... { . , ; : ( ) [ ]}
+ .Ic :wq :\b:w\bwq\bq
+ .Ic do while {...} d\bdo\bo w\bwh\bhi\bil\ble\be {\b{.\b..\b..\b.}\b}
+ .Ic setenv , unsetenv s\bse\bet\bte\ben\bnv\bv, u\bun\bns\bse\bet\bte\ben\bnv\bv
+
+ It is an error to call `.Ic' without arguments. The `.Ic' macro is
+ parsed and is callable.
+
+ L\bLi\bit\bte\ber\bra\bal\bls\bs
+ The `.Li' literal macro 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 ...
+
+ The `.Li' macro is parsed and is callable.
+
+ N\bNa\bam\bme\be M\bMa\bac\bcr\bro\bo
+ The `.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, `.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 `.Nm' in the _\bN_\bA_\bM_\bE section, and with
+ `.Fn' in the _\bS_\bY_\bN_\bO_\bP_\bS_\bI_\bS and remaining sections. For interactive commands,
+ such as the `while' command keyword in csh(1), the `.Ic' macro 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 m\bmd\bdo\boc\bc.\b.s\bsa\bam\bmp\bpl\ble\be
+ .Nm \-mdoc -\b-m\bmd\bdo\boc\bc.
+ .Nm foo ) ) , f\bfo\boo\bo)),
+ .Nm m\bmd\bdo\boc\bc.\b.s\bsa\bam\bmp\bpl\ble\bes\bs
+
+ The `.Nm' macro is parsed and is callable.
+
+ O\bOp\bpt\bti\bio\bon\bns\bs
+ The `.Op' macro places option brackets around the any remaining arguments
+ on the command line, and places any trailing punctuation outside the
+ brackets. The macros `.Oc' and `.Oo' may be used across one or more
+ lines.
+
+ Usage: .Op options ... { . , ; : ( ) [ ]}
+ .Op []
+ .Op Fl k [-\b-k\bk]
+ .Op Fl k ) . [-\b-k\bk]).
+ .Op Fl k Ar kookfile [-\b-k\bk _\bk_\bo_\bo_\bk_\bf_\bi_\bl_\be]
+ .Op Fl k Ar kookfile , [-\b-k\bk _\bk_\bo_\bo_\bk_\bf_\bi_\bl_\be],
+ .Op Ar objfil Op Ar corfil [_\bo_\bb_\bj_\bf_\bi_\bl [_\bc_\bo_\br_\bf_\bi_\bl]]
+ .Op Fl c Ar objfil Op Ar corfil , [-\b-c\bc _\bo_\bb_\bj_\bf_\bi_\bl [_\bc_\bo_\br_\bf_\bi_\bl]],
+ .Op word1 word2 [word1 word2]
+
+ The `.Oc' and `.Oo' macros:
+
+ .Oo
+ .Op Fl k Ar kilobytes
+ .Op Fl i Ar interval
+ .Op Fl c Ar count
+ .Oc
+
+ Produce: [[-\b-k\bk _\bk_\bi_\bl_\bo_\bb_\by_\bt_\be_\bs] [-\b-i\bi _\bi_\bn_\bt_\be_\br_\bv_\ba_\bl] [-\b-c\bc _\bc_\bo_\bu_\bn_\bt]]
+
+ The macros `.Op', `.Oc' and `.Oo' are parsed and are callable.
+
+ P\bPa\bat\bth\bhn\bna\bam\bme\bes\bs
+ The `.Pa' macro formats path or file names.
+
+ Usage: .Pa pathname { . , ; : ( ) [ ]}
+ .Pa /usr/share _\b/_\bu_\bs_\br_\b/_\bs_\bh_\ba_\br_\be
+ .Pa /tmp/fooXXXXX ) . _\b/_\bt_\bm_\bp_\b/_\bf_\bo_\bo_\bX_\bX_\bX_\bX_\bX).
+
+ The `.Pa' macro is parsed and is callable.
+
+ V\bVa\bar\bri\bia\bab\bbl\ble\bes\bs
+ Generic variable reference:
+
+ Usage: .Va variable ... { . , ; : ( ) [ ]}
+ .Va count _\bc_\bo_\bu_\bn_\bt
+ .Va settimer, _\bs_\be_\bt_\bt_\bi_\bm_\be_\br,
+ .Va int *prt ) : _\bi_\bn_\bt _\b*_\bp_\br_\bt):
+ .Va char s ] ) ) , _\bc_\bh_\ba_\br _\bs])),
+
+ It is an error to call `.Va' without any arguments. The `.Va' macro is
+ parsed and is callable.
+
+ M\bMa\ban\bnu\bua\bal\bl P\bPa\bag\bge\be C\bCr\bro\bos\bss\bs R\bRe\bef\bfe\ber\bre\ben\bnc\bce\bes\bs
+ The `.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.
+
+ Usage: .Xr man_page [1,...,8] { . , ; : ( ) [ ]}
+ .Xr mdoc mdoc
+ .Xr mdoc , mdoc,
+ .Xr mdoc 7 mdoc(7)
+ .Xr mdoc 7 ) ) , mdoc(7))),
+
+ The `.Xr' macro is parsed and is callable. It is an error to call `.Xr'
+ without any arguments.
+
+G\bGE\bEN\bNE\bER\bRA\bAL\bL T\bTE\bEX\bXT\bT D\bDO\bOM\bMA\bAI\bIN\bN
+ A\bAT\bT&\b&T\bT M\bMa\bac\bcr\bro\bo
+ Usage: .At [v6 | v7 | 32v | V.1 | V.4] ... { . , ; : ( ) [ ]}
+ .At AT&T UNIX
+ .At v6 . Version 6 AT&T UNIX.
+
+ The `.At' macro is _\bn_\bo_\bt parsed and _\bn_\bo_\bt callable. It accepts at most two
+ arguments.
+
+ B\bBS\bSD\bD M\bMa\bac\bcr\bro\bo
+ Usage: .Bx [Version/release] ... { . , ; : ( ) [ ]}
+ .Bx BSD
+ .Bx 4.3 . 4.3BSD.
+
+ The `.Bx' macro is parsed and is callable.
+
+ U\bUN\bNI\bIX\bX M\bMa\bac\bcr\bro\bo
+ Usage: .Ux ... { . , ; : ( ) [ ]}
+ .Ux UNIX
+
+ The `.Ux' macro is parsed and is callable.
+
+
+ E\bEm\bmp\bph\bha\bas\bsi\bis\bs M\bMa\bac\bcr\bro\bo
+ Text may be stressed or emphasized with the `.Em' macro. The usual font
+ for emphasis is italic.
+
+ Usage: .Em argument ... { . , ; : ( ) [ ]}
+ .Em does not _\bd_\bo_\be_\bs _\bn_\bo_\bt
+ .Em exceed 1024 . _\be_\bx_\bc_\be_\be_\bd _\b1_\b0_\b2_\b4.
+ .Em vide infra ) ) , _\bv_\bi_\bd_\be _\bi_\bn_\bf_\br_\ba)),
+
+ The `.Em' macro is parsed and is callable. It is an error to call `.Em'
+ without arguments.
+
+ E\bEn\bnc\bcl\blo\bos\bsu\bur\bre\be a\ban\bnd\bd Q\bQu\buo\bot\bti\bin\bng\bg M\bMa\bac\bcr\bro\bos\bs
+ The concept of enclosure is similar to quoting. The object being to en-
+ close one or more strings between a pair of characters like quotes or
+ parentheses. The terms quoting and enclosure are used interchangeably
+ throughout this document. Most of the one line enclosure macros end end
+ in small letter `q' to give a hint of quoting, but there are a few irreg-
+ ularities. For each enclosure macro there is also a pair of open and
+ close macros which end in small letters `o' and `c' respectively. These
+ can be used across one or more lines of text and while they have nesting
+ limitations, the one line quote macros can be used inside of them.
+
+ _\bQ_\bu_\bo_\bt_\be _\bC_\bl_\bo_\bs_\be _\bO_\bp_\be_\bn _\bF_\bu_\bn_\bc_\bt_\bi_\bo_\bn _\bR_\be_\bs_\bu_\bl_\bt
+ .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
+ .Pq .Pc .Po Parenthesis Enclosure (string)
+ .Ql Quoted Literal `st' or string
+ .Qq .Qc .Qo Straight Double Quote "string"
+ .Sq .Sc .So Single Quote `string'
+
+ Except for the irregular macros noted below, all of the quoting macros
+ are parsed and callable. All handle punctuation properly, as long as it
+ is presented one character at a time and separated by spaces. The quot-
+ ing macros examine opening and closing punctuation to determine whether
+ it comes before or after the enclosing string. This makes some nesting
+ possible.
+
+ .Ec, .Eo These macros expect the first argument to be the opening and
+ closing strings respectively.
+
+ .Ql The quoted literal macro behaves differently for troff than
+ nroff. If formatted with nroff, a quoted literal is always
+ quoted. If formatted with troff, an item is only quoted if the
+ width of the item is less than three constant width characters.
+ This is to make short strings more visible where the font
+ change to literal (constant width) is less noticeable.
+
+ .Pf The prefix macro is not callable, but it is parsed:
+
+ .Pf ( Fa name2
+ becomes (_\bn_\ba_\bm_\be_\b2.
+
+ The `.Ns' (no space) macro performs the analogous suffix func-
+ tion.
+
+ Examples of quoting:
+ .Aq <>
+ .Aq Ar ctype.h ) , <_\bc_\bt_\by_\bp_\be_\b._\bh>),
+ .Bq []
+ .Bq Em Greek , French . [_\bG_\br_\be_\be_\bk, _\bF_\br_\be_\bn_\bc_\bh].
+
+
+ .Dq ``''
+ .Dq string abc . ``string abc''.
+ .Dq '^[A-Z]' ``'^[A-Z]'''
+ .Ql man mdoc `man mdoc'
+ .Qq ""
+ .Qq string ) , "string"),
+ .Qq string Ns ), "string),"
+ .Sq `'
+ .Sq string `string'
+
+ For a good example of nested enclosure macros, see the `.Op' option
+ macro. It was created from the same underlying enclosure macros as those
+ presented in the list above. The `.Xo' and `.Xc' extended argument list
+ macros were also built from the same underlying routines and are a good
+ example of -\b-m\bmd\bdo\boc\bc macro usage at its worst.
+
+ N\bNo\bo-\b-O\bOp\bp o\bor\br N\bNo\bor\brm\bma\bal\bl T\bTe\bex\bxt\bt M\bMa\bac\bcr\bro\bo
+ The macro .No is a hack for words in a macro command line which should
+ _\bn_\bo_\bt be formatted and follows the conventional syntax for content macros.
+
+ N\bNo\bo S\bSp\bpa\bac\bce\be M\bMa\bac\bcr\bro\bo
+ The `.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:
+
+ .Op Fl I Ns Ar directory produces [-\b-I\bI_\bd_\bi_\br_\be_\bc_\bt_\bo_\br_\by]
+
+ Note: the `.Ns' macro always invokes the `.No' macro after eliminating
+ the space unless another macro name follows it. The macro `.Ns' is
+ parsed and is callable.
+
+ S\bSe\bec\bct\bti\bio\bon\bn C\bCr\bro\bos\bss\bs R\bRe\bef\bfe\ber\bre\ben\bnc\bce\bes\bs
+ The `.Sx' macro designates a reference to a section header within the
+ same document. It is parsed and is callable.
+
+ .Sx FILES _\bF_\bI_\bL_\bE_\bS
+
+ S\bSy\bym\bmb\bbo\bol\bli\bic\bc
+ The symbolic emphasis macro is generally a boldface macro in either the
+ symbolic sense or the traditional English usage.
+
+ Usage: .Sy symbol ... { . , ; : ( ) [ ]}
+ .Sy Important Notice I\bIm\bmp\bpo\bor\brt\bta\ban\bnt\bt N\bNo\bot\bti\bic\bce\be
+
+ The `.Sy' macro is parsed and is callable. Arguments to `.Sy' may be
+ quoted.
+
+ R\bRe\bef\bfe\ber\bre\ben\bnc\bce\bes\bs a\ban\bnd\bd C\bCi\bit\bta\bat\bti\bio\bon\bns\bs
+ The following macros make a modest attempt to handle references. At
+ best, the macros make it convenient to manually drop in a subset of refer
+ style references.
+
+ .Rs Reference Start. Causes a line break and begins collection
+ of reference information until the reference end macro is
+ read.
+ .Re Reference End. The reference is printed.
+ .%A Reference author name, one name per invocation.
+ .%B Book title.
+ .%C City/place.
+ .%D Date.
+ .%J Journal name.
+ .%N Issue number.
+ .%O Optional information.
+ .%P Page number.
+
+
+ .%R Report name.
+ .%T Title of article.
+ .%V Volume(s).
+
+ The macros beginning with `%' are not callable, and are parsed only for
+ the trade name macro which returns to its caller. (And not very pre-
+ dictably at the moment either.) The purpose is to allow trade names to
+ be pretty printed in troff/ditroff output.
+
+ T\bTr\bra\bad\bde\be N\bNa\bam\bme\bes\bs (\b(o\bor\br A\bAc\bcr\bro\bon\bny\bym\bms\bs a\ban\bnd\bd T\bTy\byp\bpe\be N\bNa\bam\bme\bes\bs)\b)
+ The trade name macro is generally a small caps macro for all upper case
+ words longer than two characters.
+
+ Usage: .Tn symbol ... { . , ; : ( ) [ ]}
+ .Tn DEC DEC
+ .Tn ASCII ASCII
+
+ The `.Tn' macro is parsed and is callable by other macros.
+
+ E\bEx\bxt\bte\ben\bnd\bde\bed\bd A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs
+ The .Xo and .Xc macros 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 `.Op'.
+
+ Here is an example of `.Xo' using the space mode macro to turn spacing
+ off:
+
+ .Sm off
+ .It Xo Sy I Ar operation
+ .No \en Ar count No \en
+ .Xc
+ .Sm on
+
+ Produces
+
+ I\bI_\bo_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn\n_\bc_\bo_\bu_\bn_\bt\n
+
+ Another one:
+
+ .Sm off
+ .It Cm S No / Ar old_pattern Xo
+ .No / Ar new_pattern
+ .No / Op Cm g
+ .Xc
+ .Sm on
+
+ Produces
+
+ S\bS/_\bo_\bl_\bd_\b__\bp_\ba_\bt_\bt_\be_\br_\bn/_\bn_\be_\bw_\b__\bp_\ba_\bt_\bt_\be_\br_\bn/[g\bg]
+
+ Another example of `.Xo' and using enclosure macros: Test the value of an
+ variable.
+
+ .It Xo
+ .Ic .ifndef
+ .Oo \&! Oc Ns Ar variable
+ .Op Ar operator variable ...
+ .Xc
+
+ Produces
+
+ .\b.i\bif\bfn\bnd\bde\bef\bf [!]_\bv_\ba_\br_\bi_\ba_\bb_\bl_\be [_\bo_\bp_\be_\br_\ba_\bt_\bo_\br _\bv_\ba_\br_\bi_\ba_\bb_\bl_\be _\b._\b._\b.]
+
+ All of the above examples have used the `.Xo' macro on the argument list
+ of the `.It' (list-item) macro. The extend macros are not used very of-
+ ten, and when they are it is usually to extend the list-item argument
+ list. Unfortunately, this is also where the extend macros are the most
+ finicky. In the first two examples, spacing was turned off; in the
+ third, spacing was desired in part of the output but not all of it. To
+ make these macros work in this situation make sure the `.Xo' and `.Xc'
+ macros are placed as shown in the third example. If the `.Xo' macro is
+ not alone on the `.It' argument list, spacing will be unpredictable. The
+ `.Ns' (no space macro) must not occur as the first or last macro on a
+ line in this situation. Out of 900 manual pages (about 1500 actual
+ pages) currently released with BSD only fifteen use the `.Xo' macro.
+
+P\bPA\bAG\bGE\bE S\bST\bTR\bRU\bUC\bCT\bTU\bUR\bRE\bE D\bDO\bOM\bMA\bAI\bIN\bN
+ S\bSe\bec\bct\bti\bio\bon\bn H\bHe\bea\bad\bde\ber\brs\bs
+ The first three `.Sh' section header macros list below are required in
+ every man page. The remaining section headers are recommended at the
+ discretion of the author writing the manual page. The `.Sh' macro can
+ take up to nine arguments. It is parsed and but is not callable.
+
+ .Sh NAME The `.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 _\bN_\bA_\bM_\bE section
+ consists of at least three items. The first is the `.Nm'
+ name macro naming the subject of the man page. The second
+ is the Name Description macro, `.Nd', which separates the
+ subject name from the third item, which is the description.
+ The description should be the most terse and lucid possi-
+ ble, as the space available is small.
+
+ .Sh SYNOPSIS The _\bS_\bY_\bN_\bO_\bP_\bS_\bI_\bS section describes the typical usage of the
+ subject of a man page. The macros required are either
+ `.Nm', `.Cd', `.Fn', (and possibly `.Fo', `.Fc', `.Fd',
+ `.Ft' macros). The function name macro `.Fn' is required
+ for manual page sections 2 and 3, the command and general
+ name macro `.Nm' is required for sections 1, 5, 6, 7, 8.
+ Section 4 manuals require a `.Nm, .Fd' or a `.Cd' configu-
+ ration device usage macro. Several other macros may be
+ necessary to produce the synopsis line as shown below:
+
+ c\bca\bat\bt [-\b-b\bbe\ben\bns\bst\btu\buv\bv] [-\b-] _\bf_\bi_\bl_\be _\b._\b._\b.
+
+ The following macros were used:
+
+ .Nm cat
+ .Op Fl benstuv
+ .Op Fl
+ .Ar
+
+ N\bNo\bot\bte\be: The macros `.Op', `.Fl', and `.Ar' recognize the pipe
+ bar character `|', so a command line such as:
+
+ .Op Fl a | Fl b
+
+ will not go orbital. Troff normally interprets a | as a
+ special operator. See _\bP_\bR_\bE_\bD_\bE_\bF_\bI_\bN_\bE_\bD _\bS_\bT_\bR_\bI_\bN_\bG_\bS for a usable |
+ character in other situations.
+
+ .Sh DESCRIPTION
+ In most cases the first text in the _\bD_\bE_\bS_\bC_\bR_\bI_\bP_\bT_\bI_\bO_\bN section is
+ a brief paragraph on the command, function or file, fol-
+ lowed by a lexical list of options and respective explana-
+ tions. To create such a list, the `.Bl' begin-list, `.It'
+ list-item and `.El' end-list macros are used (see _\bL_\bi_\bs_\bt_\bs _\ba_\bn_\bd
+ _\bC_\bo_\bl_\bu_\bm_\bn_\bs below).
+
+ 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 _\bE_\bN_\bV_\bI_\bR_\bO_\bN_\bM_\bE_\bN_\bT section should reveal any related environment
+ variables and clues to their behavior and/or usage.
+
+ .Sh EXAMPLES
+ There are several ways to create examples. See the _\bE_\bX_\bA_\bM_\bP_\bL_\bE_\bS
+ section below for details.
+
+ .Sh FILES
+ Files which are used or created by the man page subject should
+ be listed via the `.Pa' macro in the _\bF_\bI_\bL_\bE_\bS 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
+ _\bS_\bE_\bE _\bA_\bL_\bS_\bO section. Cross references are specified using the
+ `.Xr' macro. At this time refer(1) style references are not
+ accommodated.
+
+ .Sh STANDARDS
+ If the command, library function or file adheres to a specific
+ implementation such as IEEE Std1003.2 (``POSIX'') or ANSI C
+ X3.159-1989 (``ANSI C '') this should be noted here. If the
+ command does not adhere to any standard, its history should be
+ noted in the _\bH_\bI_\bS_\bT_\bO_\bR_\bY 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' macro is used
+ to specify an errno.
+
+ .Sh BUGS Blatant problems with the topic go here...
+
+ User specified `.Sh' sections may be added, for example, this section was
+ set with:
+
+ .Sh PAGE LAYOUT MACROS
+
+ P\bPa\bar\bra\bag\bgr\bra\bap\bph\bhs\bs a\ban\bnd\bd L\bLi\bin\bne\be S\bSp\bpa\bac\bci\bin\bng\bg.\b.
+
+ .Pp The .Pp paragraph command may be used to specify a line space
+ where necessary. The macro is not necessary after a `.Sh' or
+ `.Ss' macro or before a `.Bl' macro. (The `.Bl' macro asserts a
+ vertical distance unless the -compact flag is given).
+
+ K\bKe\bee\bep\bps\bs
+ The only keep that is implemented at this time is for words. The macros
+ are `.Bk' (begin-keep) and `.Ek' (end-keep). The only option that `.Bl'
+ accepts is -\b-w\bwo\bor\brd\bds\bs and is useful for preventing line breaks in the middle
+ of options. In the example for the make command line arguments (see
+ _\bW_\bh_\ba_\bt_\b'_\bs _\bi_\bn _\ba _\bn_\ba_\bm_\be), the keep prevented nroff from placing up the flag and
+ the argument on separate lines. (Actually, the option macro used to pre-
+ vent this from occurring, but was dropped when the decision (religious)
+ was made to force right justified margins in troff as options in general
+ look atrocious when spread across a sparse line. More work needs to be
+ done with the keep macros, a -\b-l\bli\bin\bne\be option needs to be added.)
+
+ E\bEx\bxa\bam\bmp\bpl\ble\bes\bs a\ban\bnd\bd D\bDi\bis\bsp\bpl\bla\bay\bys\bs
+ There are five types of displays, a quickie one line indented display
+ `.D1', a quickie one line literal display `.Dl', and a block literal,
+ block filled and block ragged which use the `.Bd' begin-display and `.Ed'
+ end-display macros.
+
+ .D1 (D-one) Display one line of indented text. This macro is parsed,
+ but it is not callable.
+
+ -\b-l\bld\bdg\bgh\bhf\bfs\bst\btr\bru\bu
+
+ The above was produced by: .Dl -\b-l\bld\bdg\bgh\bhf\bfs\bst\btr\bru\bu.
+
+ .Dl (D-ell) Display one line of indented _\bl_\bi_\bt_\be_\br_\ba_\bl text. The `.Dl' ex-
+ ample macro has been used throughout this file. It allows the in-
+ dent (display) of one line of text. Its default font is set to
+ constant width (literal) however it is parsed and will recognized
+ other macros. It is not callable however.
+
+ % ls -ldg /usr/local/bin
+
+ The above was produced by .Dl % ls -ldg /usr/local/bin.
+
+ .Bd Begin-display. The `.Bd' display must be ended with the `.Ed'
+ macro. Displays may be nested within displays and lists. `.Bd'
+ has the following syntax:
+
+ .Bd display-type [-offset offset_value] [-compact]
+
+ The display-type must be one of the following four types and may
+ have an offset specifier for indentation: `.Bd'.
+
+ -\b-r\bra\bag\bgg\bge\bed\bd Display a block of text as typed, right (and
+ left) margin edges are left ragged.
+ -\b-f\bfi\bil\bll\ble\bed\bd Display a filled (formatted) block. The block
+ of text is formatted (the edges are filled - not
+ left unjustified).
+ -\b-l\bli\bit\bte\ber\bra\bal\bl Display a literal block, useful for source code
+ or simple tabbed or spaced text.
+ -\b-f\bfi\bil\ble\be _\bf_\bi_\bl_\be_\b__\bn_\ba_\bm_\be The file name following the -\b-f\bfi\bil\ble\be flag is read
+ and displayed. Literal mode is asserted and
+ tabs are set at 8 constant width character in-
+ tervals, however any troff/-\b-m\bmd\bdo\boc\bc commands in
+ file will be processed.
+ -\b-o\bof\bff\bfs\bse\bet\bt _\bs_\bt_\br_\bi_\bn_\bg If -\b-o\bof\bff\bfs\bse\bet\bt is specified with one of the follow-
+ ing strings, the string is interpreted to indi-
+ cate the level of indentation for the forthcom-
+ ing block of text:
+
+ _\bl_\be_\bf_\bt Align block on the current left mar-
+ gin, this is the default mode of
+ `.Bd'.
+ _\bc_\be_\bn_\bt_\be_\br Supposedly center the block. At
+ this time unfortunately, the block
+ merely gets left aligned about an
+ imaginary center margin.
+ _\bi_\bn_\bd_\be_\bn_\bt Indents by one default indent value
+ or tab. The default indent value is
+ also used for the `.D1' display so
+ one is guaranteed the two types of
+ displays will line up. This indent
+ is normally set to 6n or about two
+ thirds of an inch (six constant
+
+ width characters).
+ _\bi_\bn_\bd_\be_\bn_\bt_\b-_\bt_\bw_\bo Indents two times the default indent
+ value.
+ _\br_\bi_\bg_\bh_\bt This _\bl_\be_\bf_\bt aligns the block about two
+ inches from the right side of the
+ page. This macro needs work and
+ perhaps may never do the right thing
+ by troff.
+
+ .Ed End-display.
+
+ T\bTa\bag\bgg\bge\bed\bd L\bLi\bis\bst\bts\bs a\ban\bnd\bd C\bCo\bol\blu\bum\bmn\bns\bs
+ There are several types of lists which may be initiated with the `.Bl'
+ begin-list macro. Items within the list are specified with the `.It'
+ item macro and each list must end with the `.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.
+
+ In addition, several list attributes may be specified such as the width
+ of a tag, the list offset, and compactness (blank lines between items al-
+ lowed or disallowed). Most of this document has been formatted with a
+ tag style list (-\b-t\bta\bag\bg). For a change of pace, the list-type used to pre-
+ sent the list-types is an over-hanging list (-\b-o\boh\bha\ban\bng\bg). This type of list
+ is quite popular with TeX users, but might look a bit funny after having
+ read many pages of tagged lists. The following list types are accepted
+ by `.Bl':
+
+ -\b-b\bbu\bul\bll\ble\bet\bt
+ -\b-i\bit\bte\bem\bm
+ -\b-e\ben\bnu\bum\bm
+ These three are the simplest types of lists. Once the `.Bl' macro has
+ been given, items in the list are merely indicated by a line consisting
+ solely of the `.It' macro. For example, the source text for a simple
+ enumerated list would look like:
+
+ .Bl -enum -compact
+ .It
+ Item one goes here.
+ .It
+ And item two here.
+ .It
+ Lastly item three goes here.
+ .El
+
+ The results:
+
+ 1. Item one goes here.
+ 2. And item two here.
+ 3. Lastly item three goes here.
+
+ A simple bullet list construction:
+
+ .Bl -bullet -compact
+ .It
+ Bullet one goes here.
+ .It
+ Bullet two here.
+ .El
+
+ Produces:
+ +\b+\bo\bo Bullet one goes here.
+ +\b+\bo\bo Bullet two here.
+
+
+
+ -\b-t\bta\bag\bg
+ -\b-d\bdi\bia\bag\bg
+ -\b-h\bha\ban\bng\bg
+ -\b-o\boh\bha\ban\bng\bg
+ -\b-i\bin\bns\bse\bet\bt
+ These list-types collect arguments specified with the `.It' macro and
+ create a label which may be _\bi_\bn_\bs_\be_\bt into the forth coming text, _\bh_\ba_\bn_\bg_\be_\bd from
+ the forth coming text, _\bo_\bv_\be_\br_\bh_\ba_\bn_\bg_\be_\bd from above and not indented or _\bt_\ba_\bg_\bg_\be_\bd.
+ This list was constructed with the `-\b-o\boh\bha\ban\bng\bg' list-type. The `.It' macro
+ is parsed only for the inset, hang and tag list-types and is not
+ callable. Here is an example of inset labels:
+
+ _\bT_\ba_\bg The tagged list (also called a tagged paragraph) is the most
+ common type of list used in the Berkeley manuals.
+
+ _\bD_\bi_\ba_\bg Diag lists create section four diagnostic lists and are simi-
+ lar to inset lists except callable macros are ignored.
+
+ _\bH_\ba_\bn_\bg Hanged labels are a matter of taste.
+
+ _\bO_\bh_\ba_\bn_\bg Over hanging labels are nice when space is constrained.
+
+ _\bI_\bn_\bs_\be_\bt Inset labels are useful for controlling blocks of paragraphs
+ and are valuable for converting -\b-m\bmd\bdo\boc\bc manuals to other formats.
+
+ Here is the source text which produced the above example:
+
+ .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
+
+ Here is a hanged list with just one item:
+
+ _\bH_\ba_\bn_\bg_\be_\bd labels appear similar to tagged lists when the label is
+ smaller than the label width.
+
+ _\bL_\bo_\bn_\bg_\be_\br _\bh_\ba_\bn_\bg_\be_\bd _\bl_\bi_\bs_\bt _\bl_\ba_\bb_\be_\bl_\bs blend in to the paragraph unlike tagged
+ paragraph labels.
+
+ And the unformatted text which created it:
+
+ .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
+
+
+ The tagged list which follows uses an optional width specifier to control
+ the width of the tag.
+
+ SL sleep time of the process (seconds blocked)
+ PAGEIN number of disk I/O's resulting from references by the pro-
+ cess to pages not loaded in core.
+ UID numerical user-id of process owner
+ PPID numerical id of parent of process process priority (non-
+ positive when in non-interruptible wait)
+
+ The raw text:
+
+ .Bl -tag -width "PAGEIN" -compact -offset indent
+ .It SL
+ sleep time of the process (seconds blocked)
+ .It PAGEIN
+ number of disk
+ .Tn I/O Ns 's
+ resulting from references
+ by the process to pages not loaded in core.
+ .It UID
+ numerical user-id of process owner
+ .It PPID
+ numerical id of parent of process process priority
+ (non-positive when in non-interruptible wait)
+ .El
+
+ Acceptable width specifiers:
+
+ -\b-w\bwi\bid\bdt\bth\bh _\bF_\bl sets the width to the default width for a flag. All
+ callable macros have a default width value. The
+ `.Fl', value is presently set to ten constant width
+ characters or about five sixth of an inch.
+
+ -\b-w\bwi\bid\bdt\bth\bh _\b2_\b4_\bn sets the width to 24 constant width characters or
+ about two inches. The `n' is absolutely necessary
+ for the scaling to work correctly.
+
+ -\b-w\bwi\bid\bdt\bth\bh _\bE_\bN_\bA_\bM_\bE_\bT_\bO_\bO_\bL_\bO_\bN_\bG
+ sets width to the constant width length of the string
+ given.
+
+ -\b-w\bwi\bid\bdt\bth\bh _\b"_\bi_\bn_\bt _\bm_\bk_\bf_\bi_\bf_\bo_\b"
+ again, the width is set to the constant width of the
+ string given.
+
+ If a width is not specified for the tag list type, the first time `.It'
+ is invoked, an attempt is made to determine an appropriate width. If the
+ first argument to `.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.
+
+P\bPR\bRE\bED\bDE\bEF\bFI\bIN\bNE\bED\bD S\bST\bTR\bRI\bIN\bNG\bGS\bS
+ The following strings are predefined as may be used by preceding with the
+ troff string interpreting sequence `\*(xx' where _\bx_\bx is the name of the
+ defined string or as `\*x' where _\bx is the name of the string. The inter-
+ preting sequence may be used any where in the text.
+
+ S\bSt\btr\bri\bin\bng\bg N\bNr\bro\bof\bff\bf T\bTr\bro\bof\bff\bf
+ <= <= <=
+ >= >= >=
+ Rq '' ''
+ Lq `` ``
+
+
+ ua ^ ^
+ aa '
+ ga ` `
+ q " "
+ Pi pi pi
+ Ne != !=
+ Le <= <=
+ Ge >= >=
+ Lt < >
+ Gt > <
+ Pm +- +-
+ If infinity infinity
+ Na _\bN_\ba_\bN _\bN_\ba_\bN
+ Ba | |
+
+ N\bNo\bot\bte\be: The string named `q' should be written as `\*q' since it is only
+ one char.
+
+D\bDI\bIA\bAG\bGN\bNO\bOS\bST\bTI\bIC\bCS\bS
+ The debugging facilities for -\b-m\bmd\bdo\boc\bc are limited, but can help detect sub-
+ tle 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 troff with a one or two character name. All registers internal
+ to -\b-m\bmd\bdo\boc\bc for troff and ditroff are two characters and of the form <up-
+ per_case><lower_case> such as `Ar', <lower_case><upper_case> as `aR' or
+ <upper or lower letter><digit> as `C1'. And adding to the muddle, troff
+ has its own internal registers all of which are either two lower case
+ 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 `\&'. This is sufficient for the
+ internal register names also.
+
+ If a non-escaped register name is given in the argument list of a request
+ unpredictable behavior will occur. In general, any time 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 ar-
+ gument 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 `.Db' (debug) macro displays the interpre-
+ tation of the argument list for most macros. Macros such as the `.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 `.Db' macro.
+
+ Usage: .Db [on | off]
+
+ An example of a portion of text with the debug macro placed above and be-
+ low an artificially created problem (a flag argument `aC' which should be
+ `\&aC' in order to work):
+
+ .Db on
+ .Op Fl aC Ar file )
+ .Db off
+
+ The resulting output:
+
+ 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
+
+ The first line of information tells the name of the calling macro, here
+ `.Op', and the line number it appears on. If one or more files are in-
+ volved (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 (`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 al-
+ lotted 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, exe-
+ cutable, closing punctuation and opening punctuation. The last line
+ shows the entire argument list as it was read. In this next example, the
+ offending `aC' is escaped:
+
+ .Db on
+ .Em An escaped \&aC
+ .Db off
+
+ 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
+
+ The argument `\&aC' shows up with the same length of 2 as the `\&' se-
+ quence produces a zero width, but a register named `\&aC' was not found
+ and the type classified as string.
+
+ Other diagnostics consist of usage statements and are self explanatory.
+
+G\bGR\bRO\bOF\bFF\bF,\b, T\bTR\bRO\bOF\bFF\bF A\bAN\bND\bD N\bNR\bRO\bOF\bFF\bF
+ The -\b-m\bmd\bdo\boc\bc package does not need compatibility mode with groff.
+
+ The package inhibits page breaks, and the headers and footers which nor-
+ mally occur at those breaks with nroff, to make the manual more effi-
+ cient for viewing on-line. At the moment, groff with -\b-T\bT_\ba_\bs_\bc_\bi_\bi does eject
+ the imaginary remainder of the page at end of file. The inhibiting of
+ the page breaks makes nroff'd files unsuitable for hardcopy. There is a
+ register named `cR' which can be set to zero in the site dependent style
+ file _\b/_\bu_\bs_\br_\b/_\bs_\br_\bc_\b/_\bs_\bh_\ba_\br_\be_\b/_\bt_\bm_\ba_\bc_\b/_\bd_\bo_\bc_\b-_\bn_\br_\bo_\bf_\bf to restore the old style behavior.
+
+F\bFI\bIL\bLE\bES\bS
+ /usr/share/tmac/tmac.doc manual macro package
+ /usr/share/man0/template.doc template for writing a man page
+
+S\bSE\bEE\bE A\bAL\bLS\bSO\bO
+ mdoc(7), man(1), troff(1)
+
+B\bBU\bUG\bGS\bS
+ Undesirable hyphenation on the dash of a flag argument is not yet re-
+ solved, and causes occasional mishaps in the _\bD_\bE_\bS_\bC_\bR_\bI_\bP_\bT_\bI_\bO_\bN section. (line
+ break on the hyphen).
+
+ Predefined strings are not declared in documentation.
+
+
+ Section 3f has not been added to the header routines.
+
+ `.Nm' font should be changed in _\bN_\bA_\bM_\bE section.
+
+ `.Fn' needs to have a check to prevent splitting up if the line length is
+ too short. Occasionally 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 occasionally places an un-
+ sightly partially filled line (blank) at the would be bottom of the page.
+
+ The list and display macros to not do any keeps and certainly should be
+ able to.
+
+4.4BSD June 9, 1993 23
projects / unix-history / commitdiff