From: William F. Jolitz Date: Mon, 1 Jul 1991 21:27:06 +0000 (-0800) Subject: 386BSD 0.1 development X-Git-Tag: 386BSD-0.1~1181 X-Git-Url: https://git.subgeniuskitty.com/unix-history/.git/commitdiff_plain/00d46563f6d5cb247b75f165120a1a4e50d30870?ds=inline 386BSD 0.1 development Work on file usr/othersrc/share/man/man7/mdoc.samples.7 Co-Authored-By: Lynne Greer Jolitz Synthesized-from: 386BSD-0.1 --- diff --git a/usr/othersrc/share/man/man7/mdoc.samples.7 b/usr/othersrc/share/man/man7/mdoc.samples.7 new file mode 100644 index 0000000000..cf5b0bdc83 --- /dev/null +++ b/usr/othersrc/share/man/man7/mdoc.samples.7 @@ -0,0 +1,2268 @@ +.\" 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 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 +\&.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 such as +.Ql \&Ar , + as +.Ql \&aR +or + 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 (). +.\" 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.