diff options
Diffstat (limited to 'share/man/man7/mdoc.samples.7')
-rw-r--r-- | share/man/man7/mdoc.samples.7 | 3555 |
1 files changed, 0 insertions, 3555 deletions
diff --git a/share/man/man7/mdoc.samples.7 b/share/man/man7/mdoc.samples.7 deleted file mode 100644 index f1b5e8d87f8..00000000000 --- a/share/man/man7/mdoc.samples.7 +++ /dev/null @@ -1,3555 +0,0 @@ -.\" $OpenBSD: mdoc.samples.7,v 1.91 2011/07/07 20:24:12 jmc Exp $ -.\" $NetBSD: mdoc.samples.7,v 1.5 1996/04/03 20:17:34 jtc Exp $ -.\" -.\" Copyright (c) 1990, 1993 -.\" 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. 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 8.2 (Berkeley) 12/30/93 -.\" -.\" This tutorial sampler invokes every macro in the package several -.\" times and is guaranteed to give a worst case performance -.\" for an already extremely slow package. -.\" -.Dd $Mdocdate: July 7 2011 $ -.Dt MDOC.SAMPLES 7 -.Os -.Sh NAME -.Nm mdoc.samples -.Nd tutorial sampler for writing -.Ox -manuals with -.Nm \-mdoc -.ds Pu {.\ ,\ ;\ :\ ?\ !\ (\ )\ [\ ]} -.Sh SYNOPSIS -.Nm nroff -.Fl T Ns Ar Name -.Fl mandoc -.Ar file -.Sh DESCRIPTION -A tutorial sampler for writing -.Ox -manual pages with the -.Nm \-mdoc -macro package, a -.Em content Ns \-based -and -.Em domain Ns \-based -formatting -package for -.Xr troff 1 . -Its predecessor, the \-man package (see -.Xr man 7 ) -addressed page layout, leaving the -manipulation of fonts and other -typesetting details to the individual author. -.Pp -In -.Nm \-mdoc , -page layout macros -make up the -.Em page structure domain -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 domain. -.Pp -The general text domain is defined as macros which -perform tasks such as quoting or emphasizing pieces of text. -The manual domain is defined as macros that are a subset of the -day to day informal language used to describe commands, routines -and related -.Ox -files. -Macros in the manual domain handle -command names, command line arguments and options, function names, -function parameters, pathnames, variables, cross -references 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 -translation to future documentation tools. -.Pp -Throughout the -.Ux -manual pages, a manual entry -is simply referred -to as a man page, regardless of actual length and without -sexist intention. -.Sh GETTING STARTED -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 remainder of this document is -outlined as follows: -.Bl -enum -offset indent -.It -.Tn "TROFF IDIOSYNCRASIES" -.Bl -tag -width flag -compact -offset indent -.It "Macro Usage" . -.It "Passing Space Characters in an Argument" . -.It "Trailing Blank Space Characters (a warning)" . -.It "Escaping Special Characters" . -.It "Dashes and Hyphens" . -.El -.It -.Tn "THE ANATOMY OF A MAN PAGE" -.Bl -tag -width flag -compact -offset indent -.It "A manual page template" . -.El -.It -.Tn "TITLE MACROS" -.It -.Tn "INTRODUCTION TO MANUAL AND GENERAL TEXT DOMAINS" -.Bl -tag -width flag -compact -offset indent -.It "What's in a name..." . -.It "General Syntax" . -.El -.It -.Tn "MANUAL DOMAIN" -.Bl -tag -width flag -compact -offset indent -.It "Addresses" . -.It "Arguments" . -.It "Authors" . -.It "Command Modifier" . -.It "Configuration Declarations (section four only)" . -.It "Defined Variables" . -.It "Environment Variables" . -.It "Errno (section two only)" . -.It "Exit Values" . -.It "Flags" . -.It "Functions (library routines)" . -.It "Function Argument" . -.It "Function Declaration" . -.It "Function Types" . -.It "Interactive Commands" . -.It "Includes" . -.It "Literals" . -.It "Names" . -.It "Options" . -.It "Pathnames" . -.It "Return Values" . -.It "Standards" . -.It "Variables" . -.It "Cross References" . -.El -.It -.Tn "GENERAL TEXT DOMAIN" -.Bl -tag -width flag -compact -offset indent -.It "AT&T Macro" . -.It "BSD Macro" . -.It "BSDI Macro" . -.It "OpenBSD/FreeBSD/NetBSD Macros" . -.It "UNIX Macro" . -.It "Emphasis Macro" . -.It "Font mode" . -.It "Enclosure and Quoting Macros" -.Bl -tag -width flag -compact -offset indent -.It "Angle Bracket Quote/Enclosure" . -.It "Bracket Quote/Enclosure" . -.It "Double Quote macro/Enclosure" . -.It "Enclose String macro" . -.It "Parenthesis Quote/Enclosure" . -.It "Quoted Literal macro/Enclosure" . -.It "Straight Double Quote macro/Enclosure" . -.It "Single Quote macro/Enclosure" . -.El -.It "No\-Op or Normal Text Macro" . -.It "No Space Macro" . -.It "Prefix Macro" . -.It "Section Cross References" . -.It "Space Mode Macro" . -.It "Symbolic Macro" . -.It "Mathematical Symbols" . -.It "References and Citations" . -.It "Trade Names (or Acronyms and Type Names)" . -.It "Extended Arguments" . -.It "Miscellaneous Macros" . -.El -.It -.Tn "PAGE STRUCTURE DOMAIN" -.Bl -tag -width flag -compact -offset indent -.It "Section Headers" . -.It "Paragraphs and Line Spacing" . -.It "Keeps" . -.It "Displays" . -.It "Lists and Columns" . -.El -.It -.Tn "PREDEFINED STRINGS" -.It -.Tn "DIAGNOSTICS" -.It -.Tn "FORMATTING WITH GROFF, TROFF AND NROFF" -.It -.Tn "FILES" -.It -.Tn "SEE ALSO" -.It -.Tn "BUGS" -.El -.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 invocation, precede the -.Ql \&. -(dot) with the -.Ql \e& -escape sequence. -The -.Ql \e& -translates literally to a zero-width space, and is never displayed in the -output. -.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 Extended Arguments ) . -A few macros handle quoted arguments (see -.Sx Passing Space Characters in an Argument -below). -.Pp -Most of the -.Nm \-mdoc -general text domain and manual domain macros are special -in that their argument lists are -.Em parsed -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 executed -or called when it is processed. -In this case -the argument, although the name of a macro, -is not preceded by a -.Ql \&. -(dot). -It is in this manner that many 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: -.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 "\&.Op \&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 -Here the strings -.Ql \&Fl -and -.Ql \&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 -throughout this document and in the companion quick reference -manual -.Xr mdoc 7 . -This is a technical -.Em faux pas -as almost all of the macros in -.Nm \-mdoc -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. -.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 . -.Pp -There are two possible ways to pass an argument which contains -an embedded space. -.Em Implementation note : -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 implement in all the macros for -.Tn AT&T -.Xr troff 1 . -It is not expensive for -.Xr groff 1 -but for the sake of portability, has been limited -to the following macros which need -it the most: -.Pp -.Bl -tag -width 4n -offset indent -compact -.It Li \&Bl -Begin list (for the width specifier). -.It Li \&Cd -Configuration declaration (section 4 -.Sx SYNOPSIS ) . -.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 preceded 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. -.Em 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. -.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 "\*qchar *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. -.Ss Trailing Blank Space Characters -.Em 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 -.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. -.Ss Dashes and Hyphens -In typography there are different types of dashes of various width: -the hyphen (-), -the minus sign (\-), -the en-dash (\(en), -and the em-dash (\(em). -.Pp -Hyphens are used for adjectives; -to separate the two parts of a compound word; -or to separate a word across two successive lines of text. -The hyphen does not need to be escaped: -.Bd -unfilled -offset indent -blue-eyed -lorry-driver -.Ed -.Pp -The mathematical minus sign is used for negative numbers or subtraction. -It should be written as -.Sq \e- : -.Bd -unfilled -offset indent -a = 3 \e- 1; -b = \e-2; -.Ed -.Pp -The en-dash is used to separate the two elements of a range, -or can be used the same way as an em-dash. -It should be written as -.Sq \e(en : -.Bd -unfilled -offset indent -pp. 95\e(en97. -Go away \e(en or else! -.Ed -.Pp -The em-dash can be used to show an interruption -or can be used the same way as colons, semi-colons, or parentheses. -It should be written as -.Sq \e(em : -.Bd -unfilled -offset indent -Three things \e(em apples, oranges, and bananas. -This is not that \e(em rather, this is that. -.Ed -.Pp -Note: -hyphens, minus signs, and en-dashes look identical under normal ASCII output. -Other formats, such as PostScript, render them correctly, -with differing widths. -.Sh THE ANATOMY OF A MAN PAGE -The body of a man page is easily constructed from a basic -template found in the file -.Pa /usr/share/misc/mdoc.template . -.Bd -literal -offset indent -\&.\e" The following requests are required for all man pages. -\&.Dd $\&Mdocdate$ -\&.Dt NAME SECTION# -\&.Os -\&.Sh NAME -\&.Nm program -\&.Nd one line about what it does -\&.Sh SYNOPSIS -\&.\e" For a program: program [-abc] file ... -\&.Nm program -\&.Op Fl abc -\&.Ar -\&.Sh DESCRIPTION -The -\&.Nm -utility processes files ... -\&.\e" The following requests should be uncommented -\&.\e" and used where appropriate. -\&.\e" This next request is for sections 2, 3, and 9 -\&.\e" 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, 4, 6, and 8 only. -\&.\e" .Sh DIAGNOSTICS -\&.\e" The next request is for sections 2, 3, and 9 -\&.\e" error and signal handling only. -\&.\e" .Sh ERRORS -\&.\e" .Sh SEE ALSO -\&.\e" .Xr foobar 1 -\&.\e" .Sh STANDARDS -\&.\e" .Sh HISTORY -\&.\e" .Sh AUTHORS -\&.\e" .Sh CAVEATS -\&.\e" .Sh BUGS -.Ed -.Pp -The first items in the template are the macros -.Pq Li \&.Dd , \&.Dt , \&.Os ; -the document date, -the man page title -.Pq Em in upper case -along with the section of the manual the page -belongs in, -and the operating system the man page or subject source is developed or -modified for. -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 -.Sx NAME , -.Sx SYNOPSIS -and -.Sx DESCRIPTION -are mandatory. -The -headers are -discussed in -.Sx PAGE STRUCTURE DOMAIN , -after -presentation of -.Sx MANUAL DOMAIN . -Several content macros are used to demonstrate page layout macros; -reading about content macros before page layout macros is -recommended. -.Sh TITLE MACROS -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 document change (or creation). -These macros are 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 \&.Dd $\&Mdocdate$ -The literal string -.Dq $\&Mdocdate$ , -which is expanded by -.Xr cvs 1 -to the date a document is committed to a source repository. -.Pp -Alternatively the date may be written by hand. -The date should be written formally: -.Pp -.Dl \&.Dd January 25, 1989 -.It Li \&.Dt DOCUMENT_TITLE section# [volume] -The document title is the -subject of the man page and must be in -.Tn CAPITALS -due to troff -limitations. -If omitted, -.Sq UNTITLED -is used. -The section number may be a number in the range 1\-9, -or -.Sq unass , -.Sq draft , -or -.Sq paper . -The following section numbers are defined: -.Pp -.Bl -tag -width "3p " -offset indent -compact -.It 1 -General commands -.Pq tools and utilities -.It 2 -System calls and error numbers -.It 3 -Libraries -.It 3p -.Xr perl 1 -programmer's reference guide -.It 4 -Device drivers -.It 5 -File formats -.It 6 -Games -.It 7 -Miscellaneous -.It 8 -System maintenance and operation commands -.It 9 -Kernel internals -.El -.Pp -The volume title is optional; if specified, it should be one of the following: -.Pp -.Bl -column LOCAL -offset indent -compact -.It Li AMD OpenBSD Ancestral Manual Documents -.It Li IND OpenBSD Manual Master Index -.It Li KM OpenBSD Kernel Manual -.It Li LOCAL OpenBSD Local Manual -.It Li PRM OpenBSD Programmer's Manual -.It Li PS1 OpenBSD Programmer's Supplementary Documents -.It Li SMM OpenBSD System Manager's Manual -.It Li URM OpenBSD Reference Manual -.It Li USD OpenBSD User's Supplementary Documents -.El -.Pp -The default volume labeling is -.Li URM -for sections 1, 6, and 7; -.Li SMM -for section 8; -.Li PRM -for sections 2, 3, 4, and 5; -.Li KM -for section 9. -.Pp -If the third argument to -.Ql \&.Dt -is instead a machine architecture, -it will be displayed, -surrounded by parentheses, -next to the volume title. -This is useful for pages specific only to a particular architecture. -The architectures currently defined are: -.Bd -unfilled -offset indent -alpha, amd64, amiga, arc, armish, aviion, hp300, -hppa, hppa64, i386, landisk, loongson, luna88k, -mac68k, macppc, mips64, mvme68k, mvme88k, pmax, -sgi, socppc, sparc, sparc64, sun3, vax, zaurus -.Ed -.It Li \&.Os operating_system release# -The name of the operating system -should be a common acronym, e.g., -.Tn OpenBSD -or -.Tn 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: -.Pp -.Dl \&.Os OpenBSD 3.4 -.Pp -or for a locally produced set -.Pp -.Dl \&.Os \&"CS Department\&" -.Pp -The -.Ox -default, -.Ql \&.Os -without an argument, is defined as -.Ox -.Aq latest release# -in the site specific file -.Pa /usr/share/tmac/mdoc/doc-common . -It really should default to -.Tn LOCAL . -Note, if the -.Ql \&.Os -macro is not present, the bottom left corner of the page -will be ugly. -.El -.Sh INTRODUCTION TO MANUAL AND GENERAL TEXT DOMAINS -.Ss What's in a name... -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 description of -.Nm \-mdoc -macro request usage. -Second is the description of a -.Ux -command -.Em with -.Nm \-mdoc -macros and third, -the -description of 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 -.Xr troff 1 -command is: -.Bd -literal -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 -.Sx SYNOPSIS -command line might be displayed as: -.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: -.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 referred to as -.Em operands -or -.Em file arguments . -Some command line argument lists are quite long: -.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 -.Bk -words -.Op Fl I Ar directory -.Ek -.Op Fl j Ar max_jobs -.Op Ar variable=value -.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 . -The make command line was produced from: -.Bd -literal -offset indent -\&.Nm make -\&.Op Fl eiknqrstv -\&.Op Fl D Ar variable -\&.Op Fl d Ar flags -\&.Op Fl f Ar makefile -\&.Bk -words -\&.Op Fl I Ar directory -\&.Ek -\&.Op Fl j Ar max_jobs -\&.Op Ar variable=value -\&.Op Ar target ... -.Ed -.Pp -The -.Ql \&.Bk -and -.Ql \&.Ek -macros are explained in -.Sx Keeps . -.Ss General Syntax -The manual domain and general text domain 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 -.Ql \&.Op -and -.Ql \&.Fn -macros -have nesting limitations. -All content macros -are capable of recognizing and properly handling punctuation, -provided each punctuation character is separated by a leading space. -If a request is given: -.Pp -.D1 \&.Ar sptr, ptr), -.Pp -The result is: -.Pp -.D1 Ar sptr, ptr), -.Pp -The punctuation is not recognized and everything is output in the -font used by -.Sq \&.Ar . -If the punctuation is separated by a leading whitespace: -.Pp -.D1 \&.Ar "sptr , ptr ) ," -.Pp -The result is: -.Pp -.D1 Ar sptr , ptr ) , -.Pp -The punctuation is now recognized and is output in the -default font distinguishing it from the argument strings. -To remove the special meaning from a punctuation character -escape it with -.Ql \e& . -The following punctuation characters are recognised by -.Nm \-mdoc : -.Bd -literal -offset indent-two -\*(Pu -.Ed -.Pp -.Em Troff -is limited as a macro language, and has difficulty -when presented with a string containing -a member of the mathematical, logical or -quotation set: -.Bd -literal -offset indent-two -{+ \- / * % < > <= >= = == & ` ' "} -.Ed -.Pp -The problem is that -.Xr troff 1 -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 -.Ql \e& . -Typical syntax is shown in the first content macro displayed -below, -.Ql \&.Ad . -.Sh MANUAL DOMAIN -.Ss Address Macro -The address macro identifies an address construct -of the form addr1[,addr2[,addr3]]. -.Pp -.Dl Usage: .Ad address ... \*(Pu -.Pp -.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 -.Ql \&.Ad -without arguments. -The -.Ql \&.Ad -macro is parsed and is callable. -.Ss Argument Macro -The -.Ql \&.Ar -argument macro may be used whenever -a command line argument is referenced. -.Pp -.Dl Usage: .Ar argument ... \*(Pu -.Pp -.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 -.Ql \&.Ar -is called without arguments, -.Sq Ar -is assumed. -The -.Ql \&.Ar -macro is parsed and is callable. -.Ss Author Name -The -.Ql \&.An -macro is used to specify the name of the author of the utility, -or the name of the author of the man page. -.Pp -.Dl Usage: .An -nosplit \*(Ba -split \*(Ba author ... \*(Pu -.Pp -.Bl -tag -width ".An John Smith ) ) ," -offset indent -compact -.It Li "\&.An John Smith" -.An John Smith -.It Li "\&.An John Smith ," -.An John Smith , -.It Li "\&.An John Smith \&Aq john@email.address" -.An John Smith Aq john@email.address -.El -.Pp -In the -.Sx AUTHORS -section, -.Ql \&.An -causes a line break to occur before the author name. -The arguments -.Fl nosplit -and -.Fl split -can be used to toggle this behavior. -For example: -.Bd -literal -offset indent -\&.Sh AUTHORS -\&.An -nosplit -The -\&.Nm -utility was written by -\&.An John Smith Aq john@email.address -and -\&.An Jane Doe Aq jane@email.address . -.Ed -.Pp -The -.Ql \&.An -macro is parsed, but is not callable. -.Ss Command Modifier -The command modifier is identical to the -.Ql \&.Fl -(flag) command with the exception that 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 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). -.Bl -tag -width "device le0 at scode?" -offset indent -.It Cd "device le0 at scode?" -produced by: -.Ql ".Cd device le0 at scode?" . -.El -.Pp -It is an error to call -.Ql \&.Cd -without arguments. -The -.Ql \&.Cd -macro is neither parsed nor callable. -.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 -.Pp -.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. -The -.Ql \&.Dv -macro is parsed and is callable. -.Ss Environment Variables -The -.Ql \&.Ev -macro specifies an environment variable. -.Pp -.Dl Usage: .Ev argument ... \*(Pu -.Pp -.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 parsed and is callable. -.Ss Errno (section two only) -The -.Ql \&.Er -errno macro specifies the error return value -for section two library routines. -The third example -below shows -.Ql \&.Er -used with the -.Ql \&.Bq -general text domain macro, as it would be used in -a section two manual page. -.Pp -.Dl Usage: .Er ERRNOTYPE ... \*(Pu -.Pp -.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 parsed and is callable. -.Ss Exit Values (sections one, six, and eight only) -The -.Ql \&.Ex -macro displays a standardised text concerning the exit values of applications. -The -.Ql \&.Ex -macro is neither parsed nor callable. -The -.Ql -std -flag is purely for compatibility purposes, and must be included. -.Pp -.Dl Usage: .Ex [-std] utility -.Pp -For example, -.Ql \&.Ex -std cat -produces: -.Pp -The -.Nm cat -utility exits 0 on success, and \*(Gt0 if an error occurs. -.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 without the dash. -.Pp -.Dl Usage: .Fl argument ... \*(Pu -.Pp -.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 parsed and is callable. -.Ss Functions (library routines) -The -.Ql \&.Fn -macro is modeled on ANSI C conventions. -.Bd -literal -Usage: .Fn [type] function [[type] parameters ... \*(Pu] -.Ed -.Pp -.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 parsed and is callable. -Note that any call to another macro signals the end of -the -.Ql \&.Fn -call (it will close-parenthesis at that point). -.Pp -For functions that have more than eight parameters (and this -is rare), the macros -.Ql \&.Fo -(function open) -and -.Ql \&.Fc -(function close) -may be used with -.Ql \&.Fa -(function argument) -to get around the limitation. -For example: -.Bd -literal -offset indent -\&.Ft int -\&.Fo 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 -.Ed -.Pp -Produces: -.Bd -filled -offset indent -.Ft int -.Fo 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 -.Ed -.Pp -The -.Ql \&.Fo -and -.Ql \&.Fc -macros are parsed and are callable. -In the -.Sx SYNOPSIS -section, the function will always begin at -the beginning of line. -If there is more than one function -presented in the -.Sx 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 -.Xr troff 1 -line lengths and may split across a newline ungracefully. -This will be fixed in the near future. -.Ss Function Argument -The -.Ql \&.Fa -macro is used to refer to function arguments (parameters) -outside of the -.Sx SYNOPSIS -section of the manual or inside -the -.Sx 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 -.Pp -.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. -The -.Ql \&.Fa -macro is parsed and is callable. -.Ss Function Declaration -The -.Ql \&.Fd -macro is used in the -.Sx SYNOPSIS -section with section two, three, and nine functions. -The -.Ql \&.Fd -macro is neither parsed nor callable. -.Pp -.Dl Usage: .Fd include_file (or defined variable) -.Pp -In the -.Sx 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 Function Type -This macro is intended for the -.Sx SYNOPSIS -section. -It may be used -anywhere else in the man page without problems, but in the -.Sx SYNOPSIS -section it causes a line break after its use. -Its main purpose is to present the function type in kernel normal form -of a section two or three man page by forcing 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 -macro is neither parsed nor callable. -.Ss Interactive Commands -The -.Ql \&.Ic -macro designates an interactive or internal command. -.Pp -.Dl Usage: .Ic command ... \*(Pu -.Pp -.Bl -tag -width ".Ic setenv , unsetenvxx" -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 is parsed and is callable. -.Ss Includes -The -.Ql \&.In -macro is used in the -.Sx SYNOPSIS -section with section two, three, and nine header files. -The -.Ql \&.In -macro is neither parsed nor callable. -.Pp -.Dl Usage: .In include_file -.Pp -.Bl -tag -width ".In stdio.h " -compact -offset 14n -.It Li \&.In stdio.h -.In stdio.h -.El -.Pp -In the -.Sx SYNOPSIS -section a -.Ql \&.In -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 -include file. -.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 -.Pp -.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 parsed and is callable. -.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. -However, -.Ql \&.Nm -should -.Em always -be given an argument when used in the -.Sx SYNOPSIS -section. -.Pp -Note: -a section two -or three document function name is addressed with -.Ql \&.Nm -in the -.Sx NAME -section, and with -.Ql \&.Fn -in the -.Sx 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 -.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 -.Pp -.Bl -tag -width ".Nm mdoc.samples ." -compact -offset 14n -.It Li \&.Nm mdoc.samples -.Nm mdoc.samples -.It Li \&.Nm -.Nm -.It Li \&.Nm \&. -.Nm . -.It Li \&.Nm \e-mdoc -.Nm \-mdoc -.It Li \&.Nm foo\ )\ )\ , -.Nm foo ) ) , -.El -.Pp -The -.Ql \&.Nm -macro is parsed and is callable. -.Ss Options -The -.Ql \&.Op -macro -places option brackets around 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 -.Pp -.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 parsed and are callable. -.Ss Pathnames -The -.Ql \&.Pa -macro formats path or file names. -.Pp -.Dl Usage: .Pa pathname \*(Pu -.Pp -.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 parsed and is callable. -.Ss Return Values (sections two and three only) -The -.Ql \&.Rv -macro displays a standardised text concerning the return values of functions. -The -.Ql \&.Rv -macro is neither parsed nor callable. -The -.Ql -std -flag is purely for compatibility purposes, and must be included. -.Pp -.Dl Usage: .Rv [-std] function -.Pp -For example, -.Ql \&.Rv -std open -produces: -.Pp -The -.Fn open -function returns the value 0 if successful; -otherwise the value \-1 is returned and the global variable -.Va errno -is set to indicate the error. -.Ss Standards -The -.Ql \&.St -macro replaces standard abbreviature with its formal name. -.Pp -.Dl Usage: .St abbreviature -.Pp -Available pairs for -.Dq Abbreviature/Formal Name -are: -.Pp -.Bl -tag -width "-p1003.2-92XX." -compact -offset indent -.It Li "-p1003.1-88" -.St -p1003.1-88 -.It Li "-p1003.1-90" -.St -p1003.1-90 -.It Li "-p1003.1-96" -.St -p1003.1-96 -.It Li "-p1003.1-2001" -.St -p1003.1-2001 -.It Li "-p1003.1-2004" -.St -p1003.1-2004 -.It Li "-p1003.1-2008" -.St -p1003.1-2008 -.It Li "-p1003.1" -.St -p1003.1 -.It Li "-p1003.1b" -.St -p1003.1b -.It Li "-p1003.1b-93" -.St -p1003.1b-93 -.It Li "-p1003.1c-95" -.St -p1003.1c-95 -.It Li "-p1003.1g-2000" -.St -p1003.1g-2000 -.It Li "-p1003.2-92" -.St -p1003.2-92 -.It Li "-p1387.2-95" -.St -p1387.2-95 -.It Li "-p1003.2" -.St -p1003.2 -.It Li "-p1387.2" -.St -p1387.2 -.It Li "-isoC-90" -.St -isoC-90 -.It Li "-isoC-amd1" -.St -isoC-amd1 -.It Li "-isoC-tcor1" -.St -isoC-tcor1 -.It Li "-isoC-tcor2" -.St -isoC-tcor2 -.It Li "-isoC-99" -.St -isoC-99 -.It Li "-ansiC" -.St -ansiC -.It Li "-ansiC-89" -.St -ansiC-89 -.It Li "-ansiC-99" -.St -ansiC-99 -.It Li "-ieee754" -.St -ieee754 -.It Li "-iso8802-3" -.St -iso8802-3 -.It Li "-xpg3" -.St -xpg3 -.It Li "-xpg4" -.St -xpg4 -.It Li "-xpg4.2" -.St -xpg4.2 -.It Li "-xpg4.3" -.St -xpg4.3 -.It Li "-xbd5" -.St -xbd5 -.It Li "-xcu5" -.St -xcu5 -.It Li "-xsh5" -.St -xsh5 -.It Li "-xns5" -.St -xns5 -.It Li "-xns5.2d2.0" -.St -xns5.2d2.0 -.It Li "-xcurses4.2" -.St -xcurses4.2 -.It Li "-susv2" -.St -susv2 -.It Li "-susv3" -.St -susv3 -.It Li "-svid4" -.St -svid4 -.El -.Ss Variable Types -The -.Sq .Vt -macro may be used whenever a type is referenced. -In the -.Sx SYNOPSIS -section, it causes a line break -.Pq useful for old-style variable declarations . -.Pp -.Dl Usage: .Vt Ao type Ac ... \*(Pu -.Pp -.Bl -tag -width ".Vt extern char *optarg;" -compact -offset 14n -.It Li \&.Vt extern char *optarg; -.Vt extern char *optarg; -.It Li \&.Vt FILE * -.Vt FILE * -.El -.Pp -It is an error to call -.Ql \&.Vt -without any arguments. -The -.Ql \&.Vt -macro is parsed and is callable. -.Ss Variables -Generic variable reference: -.Pp -.Dl Usage: .Va variable ... \*(Pu -.Pp -.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 parsed and is callable. -.Ss Manual Page 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 number or punctuation. -Any -remaining arguments are assumed to be punctuation. -.Pp -.Dl Usage: .Xr man_page [1,...,9] \*(Pu -.Pp -.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 parsed and is callable. -It is an error to call -.Ql \&.Xr -without -any arguments. -.Sh GENERAL TEXT DOMAIN -.Ss AT&T Macro -.Bd -literal -offset indent -compact -Usage: .At [v[1-7] | 32v | V[1-4]] ... \" \*(Pu -.Ed -.Pp -.Bl -tag -width ".At v6 ) ," -compact -offset 14n -.It Li ".At" -.At -.It Li ".At v6" \"." -.At v6 \". -.El -.Pp -The -.Ql \&.At -macro is neither parsed nor callable. -It accepts at most two arguments. -It cannot currently handle punctuation. -.Ss BSD Macro -.Dl Usage: .Bx [Version/release] ... \*(Pu -.Pp -.Bl -tag -width ".Bx 4.3 ) ," -compact -offset 14n -.It Li ".Bx" -.Bx -.It Li ".Bx 4.3 ." -.Bx 4.3 . -.El -.Pp -The -.Ql \&.Bx -macro is parsed, but is not callable. -.Ss BSDI Macro -.Dl Usage: .Bsx [Version/release] ... \*(Pu -.Pp -.Bl -tag -width ".Bsx 3.0 ) ," -compact -offset 14n -.It Li ".Bsx" -.Bsx -.It Li ".Bsx 3.0 ." -.Bsx 3.0 . -.El -.Pp -The -.Ql \&.Bsx -macro is parsed, but is not callable. -.Ss OpenBSD/FreeBSD/NetBSD Macros -.Dl Usage: .Ox [Version/release] ... \*(Pu -.Pp -.Bl -tag -width ".Ox 2.7 ) ," -compact -offset 14n -.It Li ".Ox" -.Ox -.It Li ".Ox 2.7 ." -.Ox 2.7 . -.El -.Pp -.Dl Usage: .Fx [Version/release] ... \*(Pu -.Pp -.Bl -tag -width ".Fx 4.0 ) ," -compact -offset 14n -.It Li ".Fx" -.Fx -.It Li ".Fx 4.0 ." -.Fx 4.0 . -.El -.Pp -.Dl Usage: .Nx [Version/release] ... \*(Pu -.Pp -.Bl -tag -width ".Nx 1.5 ) ," -compact -offset 14n -.It Li ".Nx" -.Nx -.It Li ".Nx 1.5 ." -.Nx 1.5 . -.El -.Pp -The -.Ql \&.Ox , -.Ql \&.Fx , -and -.Ql \&.Nx -macros are parsed, but are not callable. -.Ss UNIX Macro -.Dl Usage: .Ux ... \*(Pu -.Pp -.Bl -tag -width ".Ux 4.3 ) ," -compact -offset 14n -.It Li ".Ux" -.Ux -.El -.Pp -The -.Ql \&.Ux -macro is parsed, but is not callable. -.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 -.Pp -.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 STRUCTURE DOMAIN . -.\" .Pp -.\" .Bf -emphasis -.\" We are certain the reason most people desire a Harvard MBA -.\" so they can become to be successful philanthropists. Only -.\" mathematicians and physicists go to graduate school strictly -.\" to acquire infinite wealthy and fame. Its that infinity -.\" word that does it to them. Ruins them. -.\" .Ef -.Pp -The -.Ql \&.Em -macro is parsed and is callable. -It is an error to call -.Ql \&.Em -without arguments. -.Ss Font Mode -The -.Ql \&.Bf -font mode must end with the -.Ql \&.Ef -macro (which takes no arguments). -Font modes may be nested within other font modes. -.Pp -.Dl Usage: \&.Bf font mode -.Pp -Font mode must be one of the following: -.Pp -.Bl -tag -width "Em | -emphasis" -offset indent -compact -.It Cm \&Em | Fl emphasis -Same as if the -.Ql \&.Em -macro was used for the entire block of text. -.It Cm \&Li | Fl literal -Same as if the -.Ql \&.Li -macro was used for the entire block of text. -.It Cm \&Sy | Fl symbolic -Same as if the -.Ql \&.Sy -macro was used for the entire block of text. -.El -.Ss Enclosure and Quoting Macros -The concept of enclosure is similar to quoting. -The object being to enclose 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 -in small letter -.Ql q -to give a hint of quoting, but there are a few irregularities. -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 have nesting limitations, the one line quote macros -can be used inside -of them. -.Bd -filled -offset indent -.Bl -column "quote " "close " "open " "Enclose Stringx(in XX) " XXstringXX -.It Em " Quote Close Open Function Result" -.It Li ".Aq .Ac .Ao" Ta No Angle Bracket Enclosure <string> -.It Li ".Bq .Bc .Bo" Ta No Bracket Enclosure [string] -.It Li ".Dq .Dc .Do" Ta No Double Quote ``string'' -.It Li " .Ec .Eo" Ta No Enclose String (in XX) XXstringXX -.It Li ".Pq .Pc .Po" Ta No Parenthesis Enclosure (string) -.It Li ".Ql " Ta No Quoted Literal `st' or string -.It Li ".Qq .Qc .Qo" Ta No Straight Double Quote "string" -.It Li ".Sq .Sc .So" Ta No Single Quote `string' -.El -.Ed -.Pp -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 quoting macros examine opening and closing punctuation -to determine whether it comes before or after the -enclosing string. -This makes some nesting possible. -.Bl -tag -width xxx,xxxx -.It Li \&.Eo , \&.Ec -These macros expect the first argument to be the -opening and closing strings respectively. -.It Li \&.Ql -The quoted literal macro behaves differently for -.Xr troff 1 -than -.Xr nroff 1 . -If formatted with -.Xr nroff 1 , -a quoted literal is always quoted. -If formatted with -.Xr troff 1 , -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. -.El -.Pp -Examples of quoting: -.Bl -tag -width ".Aq Pa ctype.h ) ,xxxxxxxx" -compact -offset indent -.It Li \&.Aq -.Aq -.It Li \&.Aq \&Ar ctype.h\ )\ , -.Aq Ar ctype.h ) , -.It Li \&.Bq -.Bq -.It Li \&.Bq \&Em Greek \&, French \&. -.Bq Em Greek , French . -.It Li \&.Dq -.Dq -.It Li ".Dq string abc ." -.Dq string abc . -.It Li ".Dq \'^[A-Z]\'" -.Dq \'^[A-Z]\' -.It Li "\&.Ql man mdoc" -.Ql man mdoc -.It Li \&.Qq -.Qq -.It Li "\&.Qq string ) ," -.Qq string ) , -.It Li "\&.Qq string Ns )," -.Qq string Ns ), -.It Li \&.Sq -.Sq -.It Li "\&.Sq string" -.Sq string -.El -.Pp -For a good example of nested enclosure macros, see the -.Ql \&.Op -option macro. -It was created from the same -underlying enclosure macros as those presented in the list -above. -The -.Ql \&.Xo -and -.Ql \&.Xc -extended argument list macros -were also built from the same underlying routines and are a good -example of -.Nm \-mdoc -macro usage at its worst. -.Ss No\-Op or Normal Text Macro -The macro -.Ql \&.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 directoryxx" -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 parsed and is callable. -.Ss Prefix Macro -The -.Ql \&.Pf -macro eliminates unwanted spaces between its -first and second arguments. -.Bl -tag -width ".Pf ( Fa name2XXXXXXXXXXXX" -offset indent -.It Li ".Pf ( Fa name2" -produces -.Pf ( Fa name2 -.El -.Pp -The prefix macro is parsed, but is not callable. -.Ss Section Cross References -The -.Ql \&.Sx -macro designates a reference to a section header -within the same document. -The -.Ql \&.Sx -macro is parsed and is callable. -.Bl -tag -width "Li \&.Sx FILES" -offset 14n -.It Li \&.Sx FILES -.Sx FILES -.El -.Ss Space Mode Macro -The -.Ql \&.Sm -macro turns spacing on or off. -It is especially useful in situations where the -.Ql \&.Ns -macro may be too clumsy to use. -An argument of either -.Cm on -or -.Cm off -must be specified, to turn spacing on or off, respectively. -.Pp -.Dl Usage: .Sm on | off -.Pp -See -.Sx Extended Arguments -.Pq below -for example usage. -.Ss Symbolic Macro -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 -.Pp -.Bl -tag -width ".Sy Important Noticex" -compact -offset 14n -.It Li \&.Sy Important Notice -.Sy Important Notice -.El -.Pp -The -.Ql \&.Sy -macro is parsed and is callable. -Arguments to -.Ql \&.Sy -may be quoted. -.Ss Mathematical Symbols -Use this macro for mathematical symbols. -.Pp -.Dl Usage: .Ms mathematical symbol ... \*(Pu -.Pp -.Bl -tag -width ".Ms sigma" -compact -offset 14n -.It Li ".Ms sigma" -.Ms sigma -.El -.Pp -The -.Ql \&.Ms -macro is parsed, but is not callable. -.Ss References and Citations -The following macros make a modest attempt to handle references. -At best, the macros make it convenient to manually drop in a subset of -.Xr refer 1 -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 ".%D" -Date. -.It Li ".%I" -Issuer/Publisher Name. -.It Li ".%J" -Journal name. -.It Li ".%N" -Issue number. -.It Li ".%O" -Optional information. -.It Li ".%P" -Page number. -.It Li ".%Q" -Corporate or Foreign Author. -.It Li ".%R" -Report name. -.It Li ".%T" -Title of article. -.It Li ".%V" -Volume(s). -.El -.Pp -The macros beginning with -.Ql % -are not callable, and are parsed only for the trade name macro which -returns to its caller. -(And not very predictably at the moment either.) -The purpose is to allow trade names -to be pretty printed in -.Xr troff 1 Ns / Ns ditroff -output. -.Ss Trade Names (or Acronyms and Type Names) -The trade name macro is generally a small caps macro for -all upper case words longer than two characters. -.Pp -.Dl Usage: .Tn symbol ... \*(Pu -.Pp -.Bl -tag -width ".Tn ASCII" -compact -offset 14n -.It Li \&.Tn DEC -.Tn DEC -.It Li \&.Tn ASCII -.Tn ASCII -.El -.Pp -The -.Ql \&.Tn -macro is parsed and is callable. -.Ss Extended Arguments -The -.Ql \&.Xo -and -.Ql \&.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 -.Ql \&.Op . -.Pp -Here is an example of -.Ql \&.Xo -using the space mode macro to turn spacing off: -.Bd -literal -offset indent -\&.Sm off -\&.It Xo Sy I Ar operation -\&.No \een Ar count No \een -\&.Xc -\&.Sm on -.Ed -.Pp -Produces -.Bd -filled -offset indent -.Bl -tag -width flag -compact -.Sm off -.It Xo Sy I Ar operation -.No \en Ar count No \en -.Xc -.Sm on -.El -.Ed -.Pp -Another one: -.Bd -literal -offset indent -\&.Sm off -\&.It Cm S No \&/ Ar old_pattern Xo -\&.No \&/ Ar new_pattern -\&.No \&/ Op Cm g -\&.Xc -\&.Sm on -.Ed -.Pp -Produces -.Bd -filled -offset indent -.Bl -tag -width flag -compact -.Sm off -.It Cm S No \&/ Ar old_pattern Xo -.No \&/ Ar new_pattern -.No \&/ Op Cm g -.Xc -.Sm on -.El -.Ed -.Pp -Another example of -.Ql \&.Xo -and using enclosure macros: -Test the value of an variable. -.Bd -literal -offset indent -\&.It Xo -\&.Ic .ifndef -\&.Oo \e&! Oc Ns Ar variable -\&.Op Ar operator variable ... -\&.Xc -.Ed -.Pp -Produces -.Bd -filled -offset indent -.Bl -tag -width flag -compact -.It Xo -.Ic .ifndef -.Oo \&! Oc Ns Ar variable -.Op Ar operator variable ... -.Xc -.El -.Ed -.Pp -All of the above examples have used the -.Ql \&.Xo -macro on the argument list of the -.Ql \&.It -(list-item) -macro. -The extend macros are not used very often, 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 -.Ql \&.Xo -and -.Ql \&.Xc -macros are placed as shown in the third example. -If the -.Ql \&.Xo -macro is not alone on the -.Ql \&.It -argument list, spacing will be unpredictable. -The -.Ql \&.Ns -(no space macro) -must not occur as the first or last macro on a line -in this situation. -.Ss Miscellaneous Macros -These macros are documented for the sake of completeness. -.Bl -tag -width Ds -.It \&.Bt -Prints -.Dq is currently in beta test. -.It \&.Hf -Includes a (header) file literally. -Prints -.Dq File: -followed by the file name, then the contents of the file. -.Pp -.Dl Usage: \&.Hf file -.It \&.Fr -Function return value. -Obsolete. -.Pp -.Dl Usage: \&.Fr return value -.It \&.Ot -Usage unknown. -The -.Nm \-mdoc -macro package describes it as -.Dq old function type (fortran) . -.It \&.Ud -Prints -.Dq currently under development. -.El -.Sh PAGE STRUCTURE DOMAIN -.Ss Section Headers -The first three -.Ql \&.Sh -section header macros -listed below are required in every -man page. -The remaining section headers -are recommended at the discretion of the author -writing the manual page. -The -.Ql \&.Sh -macro can take up to nine arguments. -The -.Ql \&.Sh -macro is neither parsed nor callable. -.Bl -tag -width "XSh SYNOPSIS" -.It Li \&.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 -.Sx 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 Li \&.Sh SYNOPSIS -The -.Sx SYNOPSIS -section describes the typical usage of the -subject of a man page. -The macros required are either -.Ql \&.Nm , -.Ql \&.Cd , -.Ql \&.Fn , -(and possibly -.Ql \&.Fo , -.Ql \&.Fc , -.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 , -.Ql \&.Fd , -or a -.Ql \&.Cd -configuration device usage macro. -Several other macros may be necessary to produce -the synopsis line as shown below: -.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 -.Pp -.Sy Note : -The macros -.Ql \&.Op , -.Ql \&.Fl , -and -.Ql \&.Ar -recognize the pipe bar character -.Ql \*(Ba , -so a command line such as: -.Pp -.Dl ".Op Fl a | b" -.Pp -will not go orbital. -.Em Troff -normally interprets a \*(Ba as a special operator. -See -.Sx PREDEFINED STRINGS -for a usable \*(Ba -character in other situations. -.It Li \&.Sh DESCRIPTION -In most cases the first text in the -.Sx 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 Li \&.Sh RETURN VALUES -Sections 2, 3, and 9 function return values. -.It Li \&.Sh ENVIRONMENT -The -.Sx ENVIRONMENT -section should reveal any related -environment -variables and clues to their behavior and/or usage. -.It Li \&.Sh FILES -Files which are used or created by the man page subject -should be listed via the -.Ql \&.Pa -macro in the -.Sx FILES -section. -.It Li \&.Sh EXAMPLES -There are several ways to create examples. -See -the -.Sx EXAMPLES -section below -for details. -.It Li \&.Sh DIAGNOSTICS -Diagnostics from a command should be placed in this section. -.It Li \&.Sh ERRORS -Specific error handling, especially from library functions -(man page sections 2, 3, and 9) should go here. -The -.Ql \&.Er -macro is used to specify an errno. -.It Li \&.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 -.Sx SEE ALSO -section. -Cross references -are specified using the -.Ql \&.Xr -macro. -Cross references in the -.Sx SEE ALSO -section should be sorted by section number, and then -placed in alphabetical order and comma separated. -For example: -.Pp -.Xr ls 1 , -.Xr ps 1 , -.Xr group 5 , -.Xr passwd 5 -.Pp -At this time -.Xr refer 1 -style references are not accommodated. -.It Li \&.Sh STANDARDS -If the command, library function or file adheres to a -specific implementation such as -.St -p1003.2 -or -.St -ansiC -this should be noted here. -If the -command does not adhere to any standard, its history -should be noted in the -.Sx HISTORY -section. -.It Li \&.Sh HISTORY -Any command which does not adhere to any specific standards -should be outlined historically in this section. -.It Li \&.Sh AUTHORS -Credits, if need be, should be placed here. -.It Li \&.Sh CAVEATS -Explanations of common misuses, e.g. security considerations -for certain library functions. -.It Li \&.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 STRUCTURE DOMAIN -.Ed -.Ss Subsection Headers -.Bl -tag -width 6n -.It Li \&.Ss -The -.Ql \&.Ss -macro begins a subsection header, -such as the one used for this subsection. -The -.Ql \&.Ss -macro can take up to nine arguments. -The -.Ql \&.Ss -macro is neither parsed nor callable. -.El -.Ss Paragraphs and Line Spacing. -.Bl -tag -width 6n -.It Li \&.Pp -The -.Ql \&.Pp -paragraph command may be used to specify a line space where necessary. -The macro is not necessary before or after -.Ql \&.Sh -macros, -before or after a -.Ql \&.Ss -macro, or before a -.Ql \&.Bl -or -.Ql \&.Bd -macro. -(The -.Ql \&.Bl -and -.Ql \&.Bd -macros assert a vertical distance unless the -.Fl compact -flag is given). -.El -.\" This worked with version one, need to redo for version three -.\" .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 Keeps -The only keep that is implemented at this time is for words. -The macros are -.Ql \&.Bk -(begin-keep) -and -.Ql \&.Ek -(end-keep). -The only option that -.Ql \&.Bk -accepts is -.Fl words -and is useful for preventing line breaks in the middle of options. -In the example for the make command line arguments (see -.Sx What's in a name ) , -the keep prevented -.Xr nroff 1 -from placing the flag and the argument on separate lines. -(Actually, the option macro used to prevent this from occurring, -but was dropped when the decision (religious) was made to force -right justified margins in -.Xr troff 1 -as options in general look atrocious when spread across a sparse -line. -More work needs to be done with the keep macros; a -.Fl line -option needs to be added.) -.Ss Examples and Displays -There are six types of displays: a quickie, one-line indented display -.Ql \&.D1 ; -a quickie one-line literal display -.Ql \&.Dl ; -and block-ragged, block-unfilled, block-filled, and block-literal displays, -which use the -.Ql \&.Bd -begin-display -and -.Ql \&.Ed -end-display macros. -.Bl -tag -width \&.Dlxx -.It Li \&.D1 -(D-one) Display one line of indented text. -The -.Ql \&.D1 -macro is parsed, but is not callable. -.Pp -.Dl Fl ldghfstru -.Pp -The above was produced by: -.Li \&.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). -The -.Ql \&.Dl -macro is parsed, but is not callable. -.Pp -.Dl % ls -ldg /usr/local/bin -.Pp -The above was produced by: -.Li \&.Dl % ls -ldg /usr/local/bin . -.It Li \&.Bd -Begin-display. -The -.Ql \&.Bd -display must end with the -.Ql \&.Ed -macro. -Displays may be nested within lists, but may -.Em not -contain other displays; this also prohibits nesting of -.Ql \&.D1 -and -.Ql \&.Dl -one-line displays. -.Ql \&.Bd -has the following syntax: -.Pp -.Dl ".Bd display-type [-offset offset_value] [-compact]" -.Pp -The display-type must be one of the following four types and -may have an offset specifier for indentation: -.Pp -.Bl -tag -width "file file_name " -compact -.It Fl ragged -Fill, but do not adjust the right margin. -.It Fl unfilled -Do not fill. -Display a block of text as typed. -The 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 unjustified). -.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 1 Ns / 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-two" -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 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). -.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 needs -work and perhaps may never do the right thing by -.Xr troff 1 . -.El -.El -.It Li ".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 other than -.Fl enum -may be nested within themselves and within displays. -The use of columns inside of lists or lists inside of columns is unproven. -.Pp -In addition, several list attributes may be specified such as -the width of a tag, the list offset, and compactness -(blank lines between items allowed or disallowed). -Most of this document has been formatted with a tag style list -.Pq Fl tag . -For a change of pace, the list-type used to present the list-types -is an over-hanging list -.Pq Fl ohang . -This type of list is quite popular with -.Tn TeX -users, but might look a bit funny after having read many pages of -tagged lists. -The following list types are accepted by -.Ql \&.Bl : -.Pp -.Bl -ohang -compact -.It Xo Fl bullet , Fl dash , -.Fl enum , Fl hyphen , Fl item -.Xc -.El -These five 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. -.Pp -Examples of the different types: -.Pp -.Fl bullet -\ \&\ \&A bullet list. -.Bd -literal -offset indent-two -\&.Bl -bullet -compact -\&.It -\&Bullet one goes here. -\&.It -\&Bullet two here. -\&.El -.Ed -.Pp -Produces: -.Bl -bullet -offset 12n -compact -.It -Bullet one goes here. -.It -Bullet two here. -.El -.Pp -.Fl dash -\ \&\ \&A dash (or -.Fl hyphen ) -list. -.Bd -literal -offset indent-two -\&.Bl -dash -compact -\&.It -\&Item one goes here. -\&.It -\&Item two here. -\&.El -.Ed -.Pp -Produces: -.Bl -dash -offset 12n -compact -.It -Item one goes here. -.It -Item two here. -.El -.Pp -.Fl enum -\ \&\ \&An enumerated list. -.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 12n -compact -.It -Item one goes here. -.It -And item two here. -.It -Lastly item three goes here. -.El -.Pp -.Fl item -\ \&\ \&An item list. -.Bd -literal -offset indent-two -\&.Bl -item -compact -\&.It -\&Item one goes here. -\&Item one goes here. -\&Item one goes here. -\&.It -\&Item two goes here. -\&Item two goes here. -\&Item two goes here. -\&.El -.Ed -.Pp -Produces: -.Bl -item -offset 12n -compact -.It -Item one goes here. -Item one goes here. -Item one goes here. -.It -Item two goes here. -Item two goes here. -Item two goes here. -.El -.Pp -.Bl -ohang -compact -.It Xo Fl tag , Fl diag , -.Fl hang , Fl ohang , Fl inset -.Xc -.El -These list types collect arguments specified with the -.Ql \&.It -macro and create a label which may be -.Em inset -into the forthcoming text, -.Em hanged -from the forthcoming text, -.Em overhanged -from above and not indented or -.Em tagged . -This -list was constructed with the -.Sq Fl ohang -list-type. -The -.Ql \&.It -macro is parsed only for the inset, hang -and tag list-types and is not callable. -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. -Use a -.Fl width -attribute as described below. -.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 -Overhanging 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 -\&Overhanging 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 two items: -.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 unformatted 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 -Here is an overhanged list: -.Bl -ohang -offset indent -.It Sy SL -Sleep time of the process (seconds blocked). -.It Sy PAGEIN -Number of disk I/O's resulting from references by the process -to pages not loaded in core. -.El -.Pp -And the unformatted text which created it: -.Bd -literal -offset indent -\&.Bl -ohang -\&.It Sy SL -\&Sleep time of the process. -\&.It Sy PAGEIN -\&Number of disk I/O's resulting from references by the process -\&to pages not in core. -\&.El -.Ed -.Pp -Diag lists create section four diagnostic lists and are similar to inset lists -except callable macros are ignored. -The -.Fl width -flag is not meaningful in this context. -.Bd -literal -offset indent -\&.Bl -diag -\&.It "xl%d: couldn't map memory" -\&A fatal initialization error has occurred. -\&.It "xl%d: couldn't map interrupt" -\&A fatal initialization error has occurred. -\&.El -.Ed -.Pp -produces: -.Bl -diag -.It "xl%d: couldn't map memory" -A fatal initialization error has occurred. -.It "xl%d: couldn't map interrupt" -A fatal initialization error has occurred. -.El -.Pp -The tagged list which follows uses a width specifier to control -the width of the tag. -.Pp -.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 priority -(non-positive when in non-interruptible wait) -.El -.Pp -The raw text: -.Bd -literal -offset indent -\&.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 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-sixths 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. -This effectively means that -.Fl width -is required for the tag list type. -.Pp -.Bl -ohang -compact -.It Fl column -.El -This list type generates multiple columns. -The number of columns and the width of each column is determined by -the arguments to the -.Fl column -list. -Each -.Ql \&.It -argument is parsed to make a row and each column within the row -is a separate argument separated by a tab or the -.Ql \&.Ta -macro. -.Pp -The table: -.Bl -column "String" "Nroff" "Troff" -offset indent -.It Sy "String" Ta Sy "Nroff" Ta Sy "Troff" -.It Li "<=" Ta \&<\&= Ta \*(<= -.It Li ">=" Ta \&>\&= Ta \*(>= -.El -.Pp -was produced by: -.Bd -literal -offset indent -\&.Bl -column "String" "Nroff" "Troff" -offset indent -\&.It Sy "String" Ta Sy "Nroff" Ta Sy "Troff" -\&.It Li "<=" Ta \e&<\e&= Ta \e*(<= -\&.It Li ">=" Ta \e&>\e&= Ta \e*(>= -\&.El -.Ed -.Sh PREDEFINED STRINGS -The following strings are predefined and may be used by -preceding them with the -.Xr troff 1 -string interpreting sequence -.Ql \&\e*(xx -where -.Em xx -is the name of the defined string or as -.Ql \&\e*x -where -.Em x -is the name of the string. -The interpreting sequence may be used anywhere in the text. -.Bl -column "String " "Nroff " "Troff " -offset indent -.It Sy "String Nroff Troff" -.It Li "<=" Ta \&<\&= Ta \*(<= -.It Li ">=" Ta \&>\&= Ta \*(>= -.It Li "Rq" Ta "''" Ta \*(Rq -.It Li "Lq" Ta "``" Ta \*(Lq -.It Li "ua" Ta ^ Ta \*(ua -.It Li "aa" Ta ' Ta \*(aa -.It Li "ga" Ta \` Ta \*(ga -.\" .It Li "sL" Ta ` Ta \*(sL -.\" .It Li "sR" Ta ' Ta \*(sR -.It Li "q" Ta \&" Ta \*q -.It Li "Pi" Ta pi Ta \*(Pi -.It Li "Ne" Ta != Ta \*(Ne -.It Li "Le" Ta <= Ta \*(Le -.It Li "Ge" Ta >= Ta \*(Ge -.It Li "Lt" Ta < Ta \*(Lt -.It Li "Gt" Ta > Ta \*(Gt -.It Li "Pm" Ta +- Ta \*(Pm -.It Li "If" Ta infinity Ta \*(If -.It Li "Na" Ta \fINaN\fP Ta \*(Na -.It Li "Ba" Ta \fR\&|\fP Ta \*(Ba -.El -.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 1 -with a one or two-character name. -All registers internal to -.Nm \-mdoc -for -.Xr troff 1 -and -.Em ditroff -are two characters and -of the form <upper_case><lower_case> such as -.Ql \&Ar , -<lower_case><upper_case> as -.Ql \&aR -or -<upper or lower letter><digit> as -.Ql \&C\&1 . -And adding to the muddle, -.Xr troff -has its own internal registers all of which are either -two 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 -.Ql \e& . -This is sufficient for the internal register names also. -.Pp -.\" Every callable macro name has a corresponding register -.\" of the same name (<upper_case><lower_case>). -.\" 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 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 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 Li \&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 -.Ql \&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 GROFF, TROFF AND NROFF -The -.Nm \-mdoc -package does not need compatibility mode with -.Xr groff 1 . -.Pp -The package inhibits page breaks, and the headers and footers -which normally occur at those breaks with -.Xr nroff 1 , -to make the manual more efficient for viewing on-line. -At the moment, -.Xr groff 1 -with -.Fl T Ns Ar ascii -does eject the imaginary remainder of the page at end of file. -The inhibiting of the page breaks makes -.Xr nroff 1 Ns 'd -files unsuitable for hardcopy. -There is a register named -.Ql \&cR -which can be set to zero in the site dependent style file -.Pa /usr/share/tmac/mdoc/doc-nroff -to restore the old style behavior. -.Sh FILES -.Bl -tag -width /usr/share/misc/mdoc.template -compact -.It Pa tmac.doc -manual macro package -.It Pa tmac.doc-common -common structural macros and definitions -.It Pa tmac.doc-ditroff -site dependent -.Xr troff 1 -style file -.It Pa tmac.doc-nroff -site dependent -.Xr nroff 1 -style file -.It Pa tmac.doc-syms -special defines -.It Pa /usr/share/misc/mdoc.template -template for writing a man page -.El -.Sh SEE ALSO -.Xr groff 1 , -.Xr man 1 , -.Xr nroff 1 , -.Xr troff 1 , -.Xr mdoc 7 -.Sh BUGS -Undesirable hyphenation on the dash of a macro argument is not yet resolved, -and can cause line break on the hyphen. -.Pp -A -.Ql \&.Pp -before a display causes a double vertical space in PostScript output. -.Pp -No macro yet exists to cause a line break without inserting a vertical space -(such as troff's -.Ql \&.br -macro). -.Pp -.Ql \&.Dt -does not allow arbitrary arguments, and certainly should. -.Pp -Arbitrary arguments to -.Ql \&.Os -must be double quoted. -.Pp -The -.Ql \&.At -macro cannot handle punctuation. -.Pp -.Ql \&.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. -.Pp -If the outer-most list definition does not have a -.Fl width -argument, the -.Ql \&.It -elements of inner lists may not work (producing a list where -each successive element -.Dq walks -to the right). -.Pp -The list and display macros do not do any keeps -and certainly should be able to. -.Pp -Section 3f has not been added to the header routines. -.\" Note what happens if the parameter list overlaps a newline -.\" boundary. -.\" 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. |