[BACK]Return to mdoc.samples.7 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / share / man / man7

Annotation of src/share/man/man7/mdoc.samples.7, Revision 1.45

1.45    ! joerg       1: .\"    $NetBSD: mdoc.samples.7,v 1.44 2009/03/09 23:01:08 wiz Exp $
1.4       jtc         2: .\"
                      3: .\" Copyright (c) 1990, 1993
                      4: .\"    The Regents of the University of California.  All rights reserved.
1.1       cgd         5: .\"
                      6: .\" Redistribution and use in source and binary forms, with or without
                      7: .\" modification, are permitted provided that the following conditions
                      8: .\" are met:
                      9: .\" 1. Redistributions of source code must retain the above copyright
                     10: .\"    notice, this list of conditions and the following disclaimer.
                     11: .\" 2. Redistributions in binary form must reproduce the above copyright
                     12: .\"    notice, this list of conditions and the following disclaimer in the
                     13: .\"    documentation and/or other materials provided with the distribution.
1.40      agc        14: .\" 3. Neither the name of the University nor the names of its contributors
1.1       cgd        15: .\"    may be used to endorse or promote products derived from this software
                     16: .\"    without specific prior written permission.
                     17: .\"
                     18: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
                     19: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
                     20: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
                     21: .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
                     22: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
                     23: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
                     24: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
                     25: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
                     26: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
                     27: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
                     28: .\" SUCH DAMAGE.
                     29: .\"
1.4       jtc        30: .\"     @(#)mdoc.samples.7     8.2 (Berkeley) 12/30/93
1.1       cgd        31: .\"
1.4       jtc        32: .\" This tutorial sampler invokes every macro in the package several
                     33: .\" times and is guaranteed to give a worst case performance
1.1       cgd        34: .\" for an already extremely slow package.
1.4       jtc        35: .\"
1.43      joerg      36: .Dd March 9, 2009
1.44      wiz        37: .Dt MDOC.SAMPLES 7
1.4       jtc        38: .Os
1.1       cgd        39: .Sh NAME
1.2       jtc        40: .Nm mdoc.samples
1.4       jtc        41: .Nd tutorial sampler for writing
                     42: .Bx
                     43: manuals with
                     44: .Nm \-mdoc
1.1       cgd        45: .Sh SYNOPSIS
1.2       jtc        46: .Nm man mdoc.samples
1.1       cgd        47: .Sh DESCRIPTION
                     48: A tutorial sampler for writing
                     49: .Bx
                     50: manual pages with the
                     51: .Nm \-mdoc
                     52: macro package, a
                     53: .Em content Ns \-based
1.4       jtc        54: and
                     55: .Em domain Ns \-based
1.1       cgd        56: formatting
                     57: package for
                     58: .Xr troff 1 .
                     59: Its predecessor, the
1.30      wiz        60: .Nm -man
                     61: package (see
                     62: .Xr groff_man 7 ) ,
1.4       jtc        63: addressed page layout leaving the
1.1       cgd        64: manipulation of fonts and other
                     65: typesetting details to the individual author.
1.4       jtc        66: In
                     67: .Nm \-mdoc ,
                     68: page layout macros
                     69: make up the
                     70: .Em "page structure domain"
                     71: which consists of macros for titles, section headers, displays
1.36      wiz        72: and lists.
                     73: Essentially items which affect the physical position
1.4       jtc        74: of text on a formatted page.
                     75: In addition to the page structure domain, there are two more domains,
                     76: the manual domain and the general text domain.
                     77: The general text domain is defined as macros which
                     78: perform tasks such as quoting or emphasizing pieces of text.
                     79: The manual domain is defined as macros that are a subset of the
                     80: day to day informal language used to describe commands, routines
                     81: and related
                     82: .Bx
                     83: files.
                     84: Macros in the manual domain handle
                     85: command names, command line arguments and options, function names,
                     86: function parameters, pathnames, variables, cross
                     87: references to other manual pages, and so on.
                     88: These domain
1.1       cgd        89: items have value
                     90: for both the author and the future user of the manual page.
                     91: It is hoped the consistency gained
                     92: across the manual set will provide easier
                     93: translation to future documentation tools.
                     94: .Pp
1.4       jtc        95: Throughout the
1.1       cgd        96: .Ux
                     97: manual pages, a manual entry
                     98: is simply referred
                     99: to as a man page, regardless of actual length and without
                    100: sexist intention.
1.4       jtc       101: .Sh GETTING STARTED
                    102: Since a tutorial document is normally read when a person
                    103: desires to use the material immediately, the assumption has
                    104: been made that the user of this document may be impatient.
1.22      kristerw  105: The material presented in the remainder of this document is
1.4       jtc       106: outlined as follows:
                    107: .Bl -enum -offset indent
                    108: .It
                    109: .Tn "TROFF IDIOSYNCRASIES"
                    110: .Bl -tag -width flag -compact -offset indent
                    111: .It "Macro Usage" .
                    112: .It "Passing Space Characters in an Argument" .
                    113: .It "Trailing Blank Space Characters (a warning)" .
                    114: .It "Escaping Special Characters" .
                    115: .El
                    116: .It
                    117: .Tn "THE ANATOMY OF A MAN PAGE"
                    118: .Bl -tag -width flag -compact -offset indent
                    119: .It "A manual page template" .
                    120: .El
                    121: .It
                    122: .Tn "INTRODUCTION OF TITLE MACROS" .
                    123: .It
                    124: .Tn "INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS" .
                    125: .Bl -tag -width flag -compact -offset indent
                    126: .It "What's in a name..." .
                    127: .It "General Syntax" .
                    128: .El
                    129: .It
                    130: .Tn "MANUAL DOMAIN"
                    131: .Bl -tag -width flag -compact -offset indent
                    132: .It "Addresses" .
                    133: .It "Arguments" .
                    134: .It "Configuration Declarations (section four only)" .
1.6       explorer  135: .It "Command Modifier" .
1.4       jtc       136: .It "Defined Variables" .
                    137: .It "Errno's (Section two only)" .
                    138: .It "Environment Variables" .
                    139: .It "Function Argument" .
                    140: .It "Function Declaration" .
                    141: .It "Flags" .
                    142: .It "Functions (library routines)" .
                    143: .It "Function Types" .
                    144: .\" .It "Header File (including source code)" .
                    145: .It "Interactive Commands" .
                    146: .It "Literals" .
                    147: .It "Names" .
                    148: .It "Options" .
                    149: .It "Pathnames" .
                    150: .It "Variables" .
                    151: .It "Cross References" .
                    152: .El
                    153: .It
                    154: .Tn "GENERAL TEXT DOMAIN"
                    155: .Bl -tag -width flag -compact -offset indent
1.33      ross      156: .It "AT\*[Am]T Macro" .
1.4       jtc       157: .It "BSD Macro" .
1.28      ad        158: .It "BSD/OS Macro" .
                    159: .It "FreeBSD Macro" .
                    160: .It "NetBSD Macro" .
                    161: .It "OpenBSD Macro" .
1.4       jtc       162: .It "UNIX Macro" .
                    163: .It "Emphasis Macro" .
                    164: .It "Enclosure/Quoting Macros"
                    165: .Bl -tag -width flag -compact -offset indent
                    166: .It "Angle Bracket Quote/Enclosure" .
                    167: .It "Bracket Quotes/Enclosure" .
                    168: .It "Double Quote macro/Enclosure" .
                    169: .It "Parenthesis Quote/Enclosure" .
                    170: .It "Single Quotes/Enclosure" .
                    171: .It "Prefix Macro" .
                    172: .El
                    173: .It "Extended  Arguments" .
                    174: .It "No\-Op or Normal Text Macro" .
                    175: .It "No Space Macro" .
                    176: .It "Section Cross References" .
                    177: .It "Symbolic Macro" .
                    178: .It "References and Citations" .
                    179: .It "Trade Names (Acronyms and Type Names)" .
                    180: .El
                    181: .It
                    182: .Tn "PAGE STRUCTURE DOMAIN"
                    183: .Bl -tag -width flag -compact -offset indent
                    184: .It "Section Headers" .
                    185: .It "Paragraphs and Line Spacing" .
                    186: .It "Keeps" .
                    187: .It "Displays" .
                    188: .It "Lists and Columns" .
                    189: .El
                    190: .It
                    191: .Tn "PREDEFINED STRINGS"
                    192: .It
                    193: .Tn "DIAGNOSTICS"
                    194: .It
                    195: .Tn "FORMATTING WITH GROFF, TROFF AND NROFF"
                    196: .It
                    197: .Tn "BUGS"
                    198: .El
                    199: .ne 7
1.1       cgd       200: .Sh TROFF IDIOSYNCRASIES
                    201: The
                    202: .Nm \-mdoc
                    203: package attempts to simplify the process of writing a man page.
                    204: Theoretically, one should not have to learn the dirty details of
                    205: .Xr troff 1
                    206: to use
                    207: .Nm \-mdoc ;
                    208: however, there are a few
                    209: limitations which are unavoidable and best gotten out
1.4       jtc       210: of the way.
                    211: And, too, be forewarned, this package is
1.1       cgd       212: .Em not
                    213: fast.
                    214: .Ss Macro Usage
                    215: As in
                    216: .Xr troff 1 ,
                    217: a macro is called by placing a
                    218: .Ql \&\.
                    219: (dot character)
                    220: at the beginning of
                    221: a line followed by the two character name for the macro.
                    222: Arguments may follow the macro separated by spaces.
                    223: It is the dot character at the beginning of the line which causes
                    224: .Xr troff 1
                    225: to interpret the next two characters as a macro name.
                    226: To place a
                    227: .Ql \&\.
                    228: (dot character)
                    229: at the beginning of a line in some context other than
1.4       jtc       230: a macro invocation, precede the
1.1       cgd       231: .Ql \&\.
1.4       jtc       232: (dot) with the
1.33      ross      233: .Ql \e\*[Am]
1.4       jtc       234: escape sequence.
                    235: The
1.33      ross      236: .Ql \e\*[Am]
1.4       jtc       237: translates literally to a zero width space, and is never displayed in the
                    238: output.
1.1       cgd       239: .Pp
                    240: In general,
                    241: .Xr troff 1
                    242: macros accept up to nine arguments, any
                    243: extra arguments are ignored.
                    244: Most macros in
                    245: .Nm \-mdoc
                    246: accept nine arguments and,
                    247: in limited cases, arguments may be continued or extended
                    248: on the
                    249: next line (See
1.8       lukem     250: .Sx Extended Arguments ) .
1.4       jtc       251: A few macros handle quoted arguments (see
1.1       cgd       252: .Sx Passing Space Characters in an Argument
                    253: below).
1.4       jtc       254: .Pp
                    255: Most of the
1.1       cgd       256: .Nm \-mdoc
1.4       jtc       257: general text domain and manual domain macros are special
                    258: in that their argument lists are
                    259: .Em parsed
                    260: for callable macro names.
                    261: This means an argument on the argument list which matches
                    262: a general text or manual domain macro name and is determined
                    263: to be callable will be executed
                    264: or called when it is processed.
                    265: In this case
1.1       cgd       266: the argument, although the name of a macro,
                    267: is not preceded by a
                    268: .Ql \&\.
1.4       jtc       269: (dot).
                    270: It is in this manner that many macros are nested; for
1.1       cgd       271: example
                    272: the option macro,
                    273: .Ql \&.Op ,
                    274: may
                    275: .Em call
                    276: the flag and argument macros,
1.4       jtc       277: .Ql \&Fl
1.1       cgd       278: and
1.4       jtc       279: .Ql \&Ar ,
1.1       cgd       280: to specify an optional flag with an argument:
                    281: .Bl -tag -width "\&.Op \&Fl s \&Ar bytes" -offset indent
                    282: .It Op Fl s Ar bytes
                    283: is produced by
                    284: .Li \&.Op \&Fl s \&Ar bytes
                    285: .El
                    286: .Pp
                    287: To prevent a two character
                    288: string from being interpreted as a macro name, precede
                    289: the string with the
                    290: escape sequence
1.33      ross      291: .Ql \e\*[Am] :
1.4       jtc       292: .Bl -tag -width "\&.Op \&Fl s \&Ar bytes" -offset indent
1.1       cgd       293: .It Op \&Fl s \&Ar bytes
                    294: is produced by
1.33      ross      295: .Li \&.Op \e\*[Am]Fl s \e\*[Am]Ar bytes
1.1       cgd       296: .El
                    297: .Pp
                    298: Here the strings
                    299: .Ql \&Fl
                    300: and
                    301: .Ql \&Ar
1.4       jtc       302: are not interpreted as macros.
                    303: Macros whose argument lists are parsed for callable arguments
                    304: are referred to
                    305: as parsed and macros which may be called from an argument
                    306: list are referred to as callable
                    307: throughout this document and in the companion quick reference
                    308: manual
                    309: .Xr mdoc 7 .
                    310: This is a technical
                    311: .Em faux pas
1.30      wiz       312: as almost all of the macros in
1.4       jtc       313: .Nm \-mdoc
                    314: are parsed, but as it was cumbersome to constantly refer to macros
                    315: as being callable and being able to call other macros,
                    316: the term parsed has been used.
1.1       cgd       317: .Ss Passing Space Characters in an Argument
                    318: Sometimes it is desirable to give as one argument a string
1.4       jtc       319: containing one or more blank space characters.
                    320: This may be necessary
1.1       cgd       321: to defeat the nine argument limit or to specify arguments to macros
                    322: which expect particular arrangement of items in the argument list.
                    323: For example,
                    324: the function macro
                    325: .Ql \&.Fn
                    326: expects the first argument to be the name of a function and any
1.4       jtc       327: remaining arguments to be function parameters.
                    328: As
1.1       cgd       329: .Tn "ANSI C"
                    330: stipulates the declaration of function parameters in the
                    331: parenthesized parameter list, each parameter is guaranteed
1.4       jtc       332: to be at minimum a two word string.
                    333: For example,
1.1       cgd       334: .Fa int foo .
1.4       jtc       335: .Pp
1.1       cgd       336: There are two possible ways to pass an argument which contains
1.4       jtc       337: an embedded space.
                    338: .Em Implementation note :
                    339: Unfortunately, the most convenient way
                    340: of passing spaces in between quotes by reassigning individual
                    341: arguments before parsing was fairly expensive speed wise
                    342: and space wise to implement in all the macros for
1.33      ross      343: .Tn AT\*[Am]T
1.30      wiz       344: .Xr troff 1 .
1.4       jtc       345: It is not expensive for
1.30      wiz       346: .Xr groff 1
1.4       jtc       347: but for the sake of portability, has been limited
                    348: to the following macros which need
1.1       cgd       349: it the most:
                    350: .Pp
                    351: .Bl -tag -width 4n -offset indent -compact
                    352: .It Li \&Cd
1.4       jtc       353: Configuration declaration (section 4
                    354: .Sx SYNOPSIS )
1.1       cgd       355: .It Li \&Bl
                    356: Begin list (for the width specifier).
                    357: .It Li \&Em
                    358: Emphasized text.
                    359: .It Li \&Fn
                    360: Functions (sections two and four).
                    361: .It Li \&It
                    362: List items.
                    363: .It Li \&Li
                    364: Literal text.
                    365: .It Li \&Sy
                    366: Symbolic text.
                    367: .It Li \&%B
                    368: Book titles.
                    369: .It Li \&%J
                    370: Journal names.
                    371: .It Li \&%O
                    372: Optional notes for a reference.
                    373: .It Li \&%R
                    374: Report title (in a reference).
                    375: .It Li \&%T
                    376: Title of article in a book or journal.
                    377: .El
                    378: .Pp
                    379: One way of passing a string
                    380: containing blank spaces is to use the hard or unpaddable space character
                    381: .Ql \e\  ,
1.4       jtc       382: that is, a blank space preceded by the escape character
1.1       cgd       383: .Ql \e .
                    384: This method may be used with any macro but has the side effect
                    385: of interfering with the adjustment of text
                    386: over the length of a line.
1.30      wiz       387: .Xr troff 1
1.1       cgd       388: sees the hard space as if it were any other printable character and
                    389: cannot split the string into blank or newline separated pieces as one
1.4       jtc       390: would expect.
                    391: The method is useful for strings which are not expected
                    392: to overlap a line boundary.
                    393: For example:
1.1       cgd       394: .Bl -tag -width "fetch(char *str)" -offset indent
                    395: .It Fn fetch char\ *str
                    396: is created by
                    397: .Ql \&.Fn fetch char\e *str
                    398: .It Fn fetch "char *str"
                    399: can also be created by
                    400: .Ql \&.Fn fetch "\\*q*char *str\\*q"
                    401: .El
                    402: .Pp
                    403: If the
                    404: .Ql \e
                    405: or quotes
                    406: were omitted,
                    407: .Ql \&.Fn
                    408: would see three arguments and
                    409: the result would be:
                    410: .Pp
                    411: .Dl Fn fetch char *str
                    412: .Pp
                    413: For an example of what happens when the parameter list overlaps
                    414: a newline boundary, see the
                    415: .Sx BUGS
                    416: section.
                    417: .Ss Trailing Blank Space Characters
1.30      wiz       418: .Xr troff 1
1.4       jtc       419: can be confused by blank space characters at the end of a line.
                    420: It
                    421: is a wise preventive measure to globally remove all blank spaces
1.33      ross      422: from \*[Lt]blank-space\*[Gt]\*[Lt]end-of-line\*[Gt] character sequences.
1.4       jtc       423: Should the need
1.1       cgd       424: arise to force a blank character at the end of a line,
                    425: it may be forced with an unpaddable space and the
1.33      ross      426: .Ql \e\*[Am]
1.1       cgd       427: escape character.
                    428: For example,
1.33      ross      429: .Ql string\e\ \e\*[Am] .
1.36      wiz       430: .Ss Sentences
                    431: To recognize the end of a sentence,
                    432: .Xr troff 1
                    433: needs two spaces or a newline character.
                    434: Since it is easy to forget about the second space, policy
                    435: is to begin new sentences on a new line.
1.1       cgd       436: .Ss Escaping Special Characters
                    437: Special characters
                    438: like the newline character
                    439: .Ql \en ,
                    440: are handled by replacing the
                    441: .Ql \e
                    442: with
                    443: .Ql \ee
                    444: (e.g.
                    445: .Ql \een )
                    446: to preserve
                    447: the backslash.
1.4       jtc       448: .Sh THE ANATOMY OF A MAN PAGE
1.1       cgd       449: The body of a man page is easily constructed from a basic
                    450: template found in the file:
                    451: .Bd -literal -offset indent
1.10      mikel     452: \&.\e" /usr/share/misc/mdoc.template:
1.1       cgd       453: \&.\e" The following six lines are required.
1.4       jtc       454: \&.Dd Month day, year
1.43      joerg     455: \&.Dt DOCUMENT_TITLE SECTION_NUMBER [MACHINE]
1.32      wiz       456: \&.Os
1.1       cgd       457: \&.Sh NAME
1.29      kleink    458: \&.\e" This next request is for sections 2 and 3 only; see next comment.
                    459: \&.Sh LIBRARY
1.1       cgd       460: \&.Sh SYNOPSIS
                    461: \&.Sh DESCRIPTION
                    462: \&.\e" The following requests should be uncommented and
1.36      wiz       463: \&.\e" used where appropriate.
                    464: \&.\e" This next request is for
1.32      wiz       465: \&.\e" sections 1 and 8 exit statuses only.
                    466: \&.\e" .Sh EXIT STATUS
                    467: \&.\e" This next request is for sections 2 and 3 function return
                    468: \&.\e"     values only.
1.1       cgd       469: \&.\e" .Sh RETURN VALUES
1.33      ross      470: \&.\e" This next request is for sections 1, 6, 7 \*[Am] 8 only
1.1       cgd       471: \&.\e" .Sh ENVIRONMENT
                    472: \&.\e" .Sh FILES
                    473: \&.\e" .Sh EXAMPLES
1.33      ross      474: \&.\e" This next request is for sections 1, 6, 7 \*[Am] 8 only
1.1       cgd       475: \&.\e"     (command return values (to shell) and
1.32      wiz       476: \&.\e"    fprintf/stderr type diagnostics)
1.1       cgd       477: \&.\e" .Sh DIAGNOSTICS
                    478: \&.\e" The next request is for sections 2 and 3 error
                    479: \&.\e" and signal handling only.
                    480: \&.\e" .Sh ERRORS
                    481: \&.\e" .Sh SEE ALSO
                    482: \&.\e" .Sh STANDARDS
                    483: \&.\e" .Sh HISTORY
                    484: \&.\e" .Sh AUTHORS
                    485: \&.\e" .Sh BUGS
1.32      wiz       486: \&.\e" .Sh SECURITY CONSIDERATIONS
1.1       cgd       487: .Ed
                    488: .Pp
                    489: The first items in the template are the macros
1.4       jtc       490: .Pq Li \&.Dd , \&.Os , \&.Dt ;
                    491: the document date,
                    492: the operating system the man page or subject source is developed
1.32      wiz       493: or modified for (should have no argument by default),
1.4       jtc       494: and the man page title
                    495: .Pq Em in upper case
                    496: along with the section of the manual the page
1.32      wiz       497: belongs in, and optionally the machine if it is machine specific.
1.4       jtc       498: These macros identify the page,
1.1       cgd       499: and are discussed below in
                    500: .Sx TITLE MACROS .
                    501: .Pp
                    502: The remaining items in the template are section headers
                    503: .Pq Li \&.Sh ;
1.4       jtc       504: of which
                    505: .Sx NAME ,
                    506: .Sx SYNOPSIS
                    507: and
                    508: .Sx DESCRIPTION
                    509: are mandatory.
                    510: The
1.1       cgd       511: headers are
                    512: discussed in
1.4       jtc       513: .Sx PAGE STRUCTURE DOMAIN ,
1.1       cgd       514: after
                    515: presentation of
1.4       jtc       516: .Sx MANUAL DOMAIN .
1.1       cgd       517: Several content macros are used to demonstrate page layout macros;
                    518: reading about content macros before page layout macros is
                    519: recommended.
                    520: .Sh TITLE MACROS
1.4       jtc       521: The title macros are the first portion of the page structure
                    522: domain, but are presented first and separate for someone who
                    523: wishes to start writing a man page yesterday.
1.1       cgd       524: Three header macros designate the document title or manual page title,
                    525: the operating system,
                    526: and the date of authorship.
1.35      wiz       527: These macros are called once at the very beginning of the document
1.1       cgd       528: and are used to construct the headers and footers only.
                    529: .Bl -tag -width 6n
1.32      wiz       530: .It Li \&.Dt DOCUMENT_TITLE SECTION_NUMBER [MACHINE]
1.1       cgd       531: The document title is the
1.4       jtc       532: subject of the man page and must be in
                    533: .Tn CAPITALS
                    534: due to troff
1.1       cgd       535: limitations.
1.32      wiz       536: The section number may be 1,\ ...,\ 9, and the machine should be the
                    537: machine the man page is for (that is, the
                    538: .Nx
                    539: port to which it applies).
1.1       cgd       540: .It Li \&.Os operating_system release#
1.32      wiz       541: This should have no argument on
                    542: .Nx
                    543: man pages by default.
                    544: Otherwise, the name of the operating system
1.4       jtc       545: should be the common acronym, e.g.
                    546: .Tn BSD
                    547: or
                    548: .Tn ATT .
                    549: The release should be the standard release
1.1       cgd       550: nomenclature for the system specified, e.g. 4.3, 4.3+Tahoe, V.3,
1.4       jtc       551: V.4.
                    552: Unrecognized arguments are displayed as given in the page footer.
                    553: For instance, a typical footer might be:
                    554: .Pp
                    555: .Dl \&.Os BSD 4.3
                    556: .Pp
                    557: or for a locally produced set
                    558: .Pp
                    559: .Dl \&.Os CS Department
                    560: .Pp
                    561: The Berkeley default,
                    562: .Ql \&.Os
1.32      wiz       563: without an argument, has been defined as the current
                    564: .Nx
                    565: version, see
1.18      garbled   566: .Pa /usr/share/tmac/tmac.doc-common .
1.4       jtc       567: Note, if the
                    568: .Ql \&.Os
                    569: macro is not present, the bottom left corner of the page
                    570: will be ugly.
1.1       cgd       571: .It Li \&.Dd month day, year
1.38      wiz       572: The date of the last significant revision to the manual page;
                    573: the date should be written formally:
1.1       cgd       574: .Pp
1.4       jtc       575: .ne 5
1.1       cgd       576: .Dl January 25, 1989
1.16      perry     577: .sp
                    578: Note that the date must not be placed in quotes!
1.1       cgd       579: .El
1.4       jtc       580: .Sh MANUAL DOMAIN
1.1       cgd       581: .Ss What's in a name...
1.4       jtc       582: The manual domain macro names are derived from the day to day
1.1       cgd       583: informal language used to describe commands, subroutines and related
1.4       jtc       584: files.
                    585: Slightly
1.1       cgd       586: different variations of this language are used to describe
                    587: the three different aspects of writing a man page.
                    588: First, there is the description of
                    589: .Nm \-mdoc
                    590: macro request usage.
                    591: Second is the description of a
                    592: .Ux
                    593: command
                    594: .Em with
                    595: .Nm \-mdoc
                    596: macros and third,
                    597: the
1.4       jtc       598: description of a command to a user in the verbal sense;
1.1       cgd       599: that is, discussion of a command in the text of a man page.
                    600: .Pp
                    601: In the first case,
                    602: .Xr troff 1
                    603: macros are themselves a type of command;
                    604: the general syntax for a troff command is:
1.30      wiz       605: .Bd -literal -offset indent
1.1       cgd       606: \&.Va argument1 argument2 ... argument9
                    607: .Ed
                    608: .Pp
                    609: The
                    610: .Ql \&.Va
                    611: is a macro command or request, and anything following it is an argument to
                    612: be processed.
                    613: In the second case,
                    614: the description of a
                    615: .Ux
                    616: command using the content macros is a
                    617: bit more involved;
1.4       jtc       618: a typical
                    619: .Sx SYNOPSIS
                    620: command line might be displayed as:
1.1       cgd       621: .Bd -filled -offset indent
                    622: .Nm filter
                    623: .Op Fl flag
                    624: .Ar infile outfile
                    625: .Ed
                    626: .Pp
                    627: Here,
                    628: .Nm filter
                    629: is the command name and the
                    630: bracketed string
                    631: .Fl flag
                    632: is a
                    633: .Em flag
                    634: argument designated as optional by the option brackets.
                    635: In
                    636: .Nm \-mdoc
                    637: terms,
                    638: .Ar infile
                    639: and
                    640: .Ar outfile
                    641: are
                    642: called
                    643: .Em arguments .
                    644: The macros which formatted the above example:
                    645: .Bd -literal -offset indent
                    646: \&.Nm filter
                    647: \&.Op \&Fl flag
                    648: \&.Ar infile outfile
                    649: .Ed
                    650: .Pp
                    651: In the third case, discussion of commands and command syntax
1.4       jtc       652: includes both examples above, but may add more detail.
                    653: The
1.1       cgd       654: arguments
                    655: .Ar infile
                    656: and
                    657: .Ar outfile
1.4       jtc       658: from the example above might be referred to as
1.1       cgd       659: .Em operands
                    660: or
                    661: .Em file arguments .
                    662: Some command line argument lists are quite long:
                    663: .Bl -tag -width make -offset indent
                    664: .It Nm make
                    665: .Op Fl eiknqrstv
                    666: .Op Fl D Ar variable
                    667: .Op Fl d Ar flags
                    668: .Op Fl f Ar makefile
1.4       jtc       669: .Bk -words
1.1       cgd       670: .Op Fl I Ar directory
1.4       jtc       671: .Ek
1.1       cgd       672: .Op Fl j Ar max_jobs
                    673: .Op Ar variable=value
1.4       jtc       674: .Bk -words
                    675: .Op Ar target ...
                    676: .Ek
1.1       cgd       677: .El
                    678: .Pp
                    679: Here one might talk about the command
                    680: .Nm make
                    681: and qualify the argument
                    682: .Ar makefile ,
                    683: as an argument to the flag,
                    684: .Fl f ,
                    685: or discuss the optional
                    686: file
                    687: operand
                    688: .Ar target .
                    689: In the verbal context, such detail can prevent confusion,
                    690: however the
                    691: .Nm \-mdoc
                    692: package
                    693: does not have a macro for an argument
                    694: .Em to
                    695: a flag.
                    696: Instead the
                    697: .Ql \&Ar
                    698: argument macro is used for an operand or file argument like
                    699: .Ar target
                    700: as well as an argument to a flag like
1.4       jtc       701: .Ar variable .
                    702: The make command line was produced from:
1.1       cgd       703: .Bd -literal -offset indent
                    704: \&.Nm make
                    705: \&.Op Fl eiknqrstv
                    706: \&.Op Fl D Ar variable
                    707: \&.Op Fl d Ar flags
                    708: \&.Op Fl f Ar makefile
                    709: \&.Op Fl I Ar directory
                    710: \&.Op Fl j Ar max_jobs
                    711: \&.Op Ar variable=value
1.4       jtc       712: \&.Bk -words
1.1       cgd       713: \&.Op Ar target ...
1.4       jtc       714: \&.Ek
1.1       cgd       715: .Ed
1.4       jtc       716: .Pp
                    717: The
                    718: .Ql \&.Bk
                    719: and
                    720: .Ql \&.Ek
                    721: macros are explained in
                    722: .Sx Keeps .
1.1       cgd       723: .Ss General Syntax
1.4       jtc       724: The manual domain and general text domain macros share a similar
1.1       cgd       725: syntax with a few minor deviations:
                    726: .Ql \&.Ar ,
                    727: .Ql \&.Fl ,
                    728: .Ql \&.Nm ,
                    729: and
                    730: .Ql \&.Pa
                    731: differ only when called without arguments;
                    732: .Ql \&.Fn
                    733: and
                    734: .Ql \&.Xr
                    735: impose an order on their argument lists
                    736: and the
1.4       jtc       737: .Ql \&.Op
1.1       cgd       738: and
1.4       jtc       739: .Ql \&.Fn
1.1       cgd       740: macros
1.4       jtc       741: have nesting limitations.
                    742: All content macros
                    743: are capable of recognizing and properly handling punctuation,
                    744: provided each punctuation character is separated by a leading space.
1.30      wiz       745: If a request is given:
1.4       jtc       746: .Pp
                    747: .Dl \&.Li sptr, ptr),
                    748: .Pp
                    749: The result is:
                    750: .Pp
                    751: .Dl Li sptr, ptr),
                    752: .Pp
                    753: The punctuation is not recognized and all is output in the
1.36      wiz       754: literal font.
                    755: If the punctuation is separated by a leading white space:
1.4       jtc       756: .Pp
                    757: .Dl \&.Li "sptr , ptr ) ,"
                    758: .Pp
                    759: The result is:
                    760: .Pp
                    761: .Dl Li sptr , ptr ) ,
                    762: .Pp
                    763: The punctuation is now recognized and is output in the
                    764: default font distinguishing it from the strings in literal font.
                    765: .Pp
                    766: To remove the special meaning from a punctuation character
                    767: escape it with
1.33      ross      768: .Ql \e\*[Am] .
1.30      wiz       769: .Xr troff 1
1.4       jtc       770: is limited as a macro language, and has difficulty
                    771: when presented with a string containing
                    772: a member of the mathematical, logical or
1.1       cgd       773: quotation set:
1.4       jtc       774: .Bd -literal -offset indent-two
1.33      ross      775: \&{+,\-,/,*,\&%,\*[Lt],\*[Gt],\*[Le],\*[Ge],=,==,\*[Am],`,',"}
1.1       cgd       776: .Ed
1.4       jtc       777: .Pp
                    778: The problem is that
1.30      wiz       779: .Xr troff 1
1.4       jtc       780: may assume it is supposed to actually perform the operation
1.36      wiz       781: or evaluation suggested by the characters.
                    782: To prevent the accidental evaluation of these characters,
1.4       jtc       783: escape them with
1.33      ross      784: .Ql \e\*[Am] .
1.1       cgd       785: Typical syntax is shown in the first content macro displayed
                    786: below,
1.4       jtc       787: .Ql \&.Ad .
1.1       cgd       788: .Ss Address Macro
1.4       jtc       789: The address macro identifies an address construct
1.1       cgd       790: of the form addr1[,addr2[,addr3]].
                    791: .Pp
                    792: .Dl Usage: .Ad address ... \*(Pu
                    793: .Bl -tag -width ".Ad f1 , f2 , f3 :" -compact -offset 14n
                    794: .It Li \&.Ad addr1
                    795: .Ad addr1
                    796: .It Li \&.Ad addr1\ .
                    797: .Ad addr1 .
                    798: .It Li \&.Ad addr1\ , file2
                    799: .Ad addr1 , file2
                    800: .It Li \&.Ad f1\ , f2\ , f3\ :
                    801: .Ad f1 , f2 , f3 :
                    802: .It Li \&.Ad addr\ )\ )\ ,
                    803: .Ad addr ) ) ,
                    804: .El
                    805: .Pp
                    806: It is an error to call
                    807: .Li \&.Ad
                    808: without arguments.
                    809: .Li \&.Ad
1.4       jtc       810: is callable by other macros and is parsed.
1.1       cgd       811: .Ss Argument Macro
                    812: The
                    813: .Li \&.Ar
                    814: argument macro may be used whenever
                    815: a command line argument is referenced.
                    816: .Pp
                    817: .Dl Usage: .Ar argument ... \*(Pu
                    818: .Bl -tag -width ".Ar file1 file2" -compact -offset 15n
                    819: .It Li \&.Ar
                    820: .Ar
                    821: .It Li \&.Ar file1
                    822: .Ar file1
                    823: .It Li \&.Ar file1\ .
                    824: .Ar file1 .
                    825: .It Li \&.Ar file1 file2
                    826: .Ar file1 file2
                    827: .It Li \&.Ar f1 f2 f3\ :
                    828: .Ar f1 f2 f3 :
                    829: .It Li \&.Ar file\ )\ )\ ,
                    830: .Ar file ) ) ,
                    831: .El
                    832: .Pp
                    833: If
                    834: .Li \&.Ar
                    835: is called without arguments
                    836: .Ql Ar
1.4       jtc       837: is assumed.
                    838: The
1.1       cgd       839: .Li \&.Ar
1.4       jtc       840: macro is parsed and is callable.
1.1       cgd       841: .Ss Configuration Declaration (section four only)
                    842: The
                    843: .Ql \&.Cd
                    844: macro is used to demonstrate a
1.42      peter     845: .Xr config 1
1.1       cgd       846: declaration for a device interface in a section four manual.
                    847: This macro accepts quoted arguments (double quotes only).
                    848: .Pp
                    849: .Bl -tag -width "device le0 at scode?" -offset indent
                    850: .It Cd "device le0 at scode?"
                    851: produced by:
                    852: .Ql ".Cd device le0 at scode?" .
                    853: .El
                    854: .Ss Command Modifier
                    855: The command modifier is identical to the
                    856: .Ql \&.Fl
                    857: (flag) command with the exception
                    858: the
                    859: .Ql \&.Cm
                    860: macro does not assert a dash
1.4       jtc       861: in front of every argument.
                    862: Traditionally flags are marked by the
1.1       cgd       863: preceding dash, some commands or subsets of commands do not use them.
                    864: Command modifiers may also be specified in conjunction with interactive
                    865: commands such as editor commands.
                    866: See
                    867: .Sx Flags .
                    868: .Ss Defined Variables
                    869: A variable which is defined in an include file is specified
                    870: by the macro
                    871: .Ql \&.Dv .
                    872: .Pp
                    873: .Dl Usage: .Dv defined_variable ... \*(Pu
                    874: .Bl -tag -width ".Dv MAXHOSTNAMELEN" -compact -offset 14n
                    875: .It Li ".Dv MAXHOSTNAMELEN"
                    876: .Dv MAXHOSTNAMELEN
                    877: .It Li ".Dv TIOCGPGRP )"
                    878: .Dv TIOCGPGRP )
                    879: .El
                    880: .Pp
                    881: It is an error to call
                    882: .Ql \&.Dv
                    883: without arguments.
                    884: .Ql \&.Dv
1.4       jtc       885: is parsed and is callable.
1.1       cgd       886: .Ss Errno's (Section two only)
                    887: The
                    888: .Ql \&.Er
                    889: errno macro specifies the error return value
1.4       jtc       890: for section two library routines.
                    891: The second example
1.1       cgd       892: below shows
                    893: .Ql \&.Er
                    894: used with the
                    895: .Ql \&.Bq
1.4       jtc       896: general text domain macro, as it would be used in
1.1       cgd       897: a section two manual page.
                    898: .Pp
                    899: .Dl Usage: .Er ERRNOTYPE ... \*(Pu
                    900: .Bl -tag -width ".Bq Er ENOTDIR" -compact -offset 14n
                    901: .It Li \&.Er ENOENT
                    902: .Er ENOENT
                    903: .It Li \&.Er ENOENT\ )\ ;
                    904: .Er ENOENT ) ;
                    905: .It Li \&.Bq \&Er ENOTDIR
                    906: .Bq Er ENOTDIR
                    907: .El
                    908: .Pp
                    909: It is an error to call
                    910: .Ql \&.Er
                    911: without arguments.
                    912: The
                    913: .Ql \&.Er
1.4       jtc       914: macro is parsed and is callable.
1.1       cgd       915: .Ss Environment Variables
                    916: The
                    917: .Ql \&.Ev
1.4       jtc       918: macro specifies an environment variable.
1.1       cgd       919: .Pp
                    920: .Dl Usage: .Ev argument ... \*(Pu
                    921: .Bl -tag -width ".Ev PRINTER ) ) ," -compact -offset 14n
                    922: .It Li \&.Ev DISPLAY
                    923: .Ev  DISPLAY
                    924: .It Li \&.Ev PATH\ .
                    925: .Ev PATH .
                    926: .It Li \&.Ev PRINTER\ )\ )\ ,
                    927: .Ev PRINTER ) ) ,
                    928: .El
                    929: .Pp
                    930: It is an error to call
                    931: .Ql \&.Ev
                    932: without arguments.
                    933: The
                    934: .Ql \&.Ev
1.4       jtc       935: macro is parsed and is callable.
1.1       cgd       936: .Ss Function Argument
                    937: The
                    938: .Ql \&.Fa
                    939: macro is used to refer to function arguments (parameters)
1.4       jtc       940: outside of the
                    941: .Sx SYNOPSIS
                    942: section of the manual or inside
                    943: the
                    944: .Sx SYNOPSIS
                    945: section should a parameter list be too
1.1       cgd       946: long for the
                    947: .Ql \&.Fn
                    948: macro and the enclosure macros
                    949: .Ql \&.Fo
                    950: and
                    951: .Ql \&.Fc
                    952: must be used.
                    953: .Ql \&.Fa
                    954: may also be used to refer to structure members.
                    955: .Pp
                    956: .Dl Usage: .Fa function_argument ... \*(Pu
                    957: .Bl -tag -width ".Fa d_namlen\ )\ )\ ," -compact -offset 14n
                    958: .It Li \&.Fa d_namlen\ )\ )\ ,
                    959: .Fa d_namlen ) ) ,
                    960: .It Li \&.Fa iov_len
                    961: .Fa iov_len
                    962: .El
                    963: .Pp
                    964: It is an error to call
                    965: .Ql \&.Fa
                    966: without arguments.
                    967: .Ql \&.Fa
1.4       jtc       968: is parsed and is callable.
1.1       cgd       969: .Ss Function Declaration
                    970: The
                    971: .Ql \&.Fd
1.4       jtc       972: macro is used in the
                    973: .Sx SYNOPSIS
1.27      mycroft   974: section with section two, three or nine
1.4       jtc       975: functions.
                    976: The
1.1       cgd       977: .Ql \&.Fd
                    978: macro does not call other macros and is not callable by other
                    979: macros.
                    980: .Pp
                    981: .Dl Usage: .Fd include_file (or defined variable)
                    982: .Pp
1.4       jtc       983: In the
                    984: .Sx SYNOPSIS
                    985: section a
1.1       cgd       986: .Ql \&.Fd
                    987: request causes a line break if a function has already been presented
1.4       jtc       988: and a break has not occurred.
                    989: This leaves a nice vertical space
1.1       cgd       990: in between the previous function call and the declaration for the
                    991: next function.
                    992: .Ss Flags
                    993: The
                    994: .Ql \&.Fl
1.4       jtc       995: macro handles command line flags.
                    996: It prepends
1.1       cgd       997: a dash,
                    998: .Ql \- ,
1.4       jtc       999: to the flag.
                   1000: For interactive command flags, which
1.1       cgd      1001: are not prepended with a dash, the
                   1002: .Ql \&.Cm
                   1003: (command modifier)
1.4       jtc      1004: macro is identical, but without the dash.
1.1       cgd      1005: .Pp
                   1006: .Dl Usage: .Fl argument ... \*(Pu
                   1007: .Bl -tag -width ".Fl \-s \-t \-v" -compact -offset 14n
                   1008: .It Li \&.Fl
                   1009: .Fl
                   1010: .It Li \&.Fl cfv
                   1011: .Fl cfv
                   1012: .It Li \&.Fl cfv\ .
                   1013: .Fl cfv .
                   1014: .It Li \&.Fl s v t
                   1015: .Fl s v t
                   1016: .It Li \&.Fl -\ ,
                   1017: .Fl - ,
                   1018: .It Li \&.Fl xyz\ )\ ,
                   1019: .Fl xyz ) ,
                   1020: .El
                   1021: .Pp
                   1022: The
                   1023: .Ql \&.Fl
                   1024: macro without any arguments results
                   1025: in a dash representing stdin/stdout.
                   1026: Note that giving
                   1027: .Ql \&.Fl
                   1028: a single dash, will result in two dashes.
                   1029: The
                   1030: .Ql \&.Fl
1.4       jtc      1031: macro is parsed and is callable.
1.1       cgd      1032: .Ss Functions (library routines)
1.30      wiz      1033: The
                   1034: .Ql \&.Fn
                   1035: macro is modeled on ANSI C conventions.
1.1       cgd      1036: .Bd -literal
1.4       jtc      1037: Usage: .Fn [type] function [[type] parameters ... \*(Pu]
1.1       cgd      1038: .Ed
                   1039: .Bl -tag -width ".Fn .int align. .const * char *sptrsxx" -compact
                   1040: .It Li "\&.Fn getchar"
                   1041: .Fn getchar
                   1042: .It Li "\&.Fn strlen ) ,"
                   1043: .Fn strlen ) ,
                   1044: .It Li \&.Fn "\\*qint align\\*q" "\\*qconst * char *sptrs\\*q" ,
                   1045: .Fn "int align" "const * char *sptrs" ,
                   1046: .El
                   1047: .Pp
                   1048: It is an error to call
                   1049: .Ql \&.Fn
                   1050: without any arguments.
                   1051: The
                   1052: .Ql \&.Fn
                   1053: macro
1.4       jtc      1054: is parsed and is callable,
1.1       cgd      1055: note that any call to another macro signals the end of
                   1056: the
                   1057: .Ql \&.Fn
1.4       jtc      1058: call (it will close-parenthesis at that point).
                   1059: .Pp
                   1060: For functions that have more than eight parameters (and this
                   1061: is rare), the
                   1062: macros
                   1063: .Ql \&.Fo
                   1064: (function open)
                   1065: and
                   1066: .Ql \&.Fc
                   1067: (function close)
                   1068: may be used with
                   1069: .Ql \&.Fa
                   1070: (function argument)
1.36      wiz      1071: to get around the limitation.
                   1072: For example:
1.4       jtc      1073: .Bd -literal -offset indent
1.31      blymn    1074: \&.Ft "int"
                   1075: \&.Fo "res_mkquery"
1.4       jtc      1076: \&.Fa "int op"
                   1077: \&.Fa "char *dname"
                   1078: \&.Fa "int class"
                   1079: \&.Fa "int type"
                   1080: \&.Fa "char *data"
                   1081: \&.Fa "int datalen"
                   1082: \&.Fa "struct rrec *newrr"
                   1083: \&.Fa "char *buf"
                   1084: \&.Fa "int buflen"
                   1085: \&.Fc
                   1086: .Ed
                   1087: .Pp
                   1088: Produces:
                   1089: .Bd -filled -offset indent
1.31      blymn    1090: .Ft "int"
                   1091: .Fo "res_mkquery"
1.4       jtc      1092: .Fa "int op"
                   1093: .Fa "char *dname"
                   1094: .Fa "int class"
                   1095: .Fa "int type"
                   1096: .Fa "char *data"
                   1097: .Fa "int datalen"
                   1098: .Fa "struct rrec *newrr"
                   1099: .Fa "char *buf"
                   1100: .Fa "int buflen"
                   1101: .Fc
                   1102: .Ed
1.1       cgd      1103: .Pp
1.4       jtc      1104: The
                   1105: .Ql \&.Fo
                   1106: and
                   1107: .Ql \&.Fc
                   1108: macros are parsed and are callable.
                   1109: In the
                   1110: .Sx SYNOPSIS
                   1111: section, the function will always begin at
                   1112: the beginning of line.
                   1113: If there is more than one function
                   1114: presented in the
                   1115: .Sx SYNOPSIS
                   1116: section and a function type has not been
1.1       cgd      1117: given, a line break will occur, leaving a nice vertical space
                   1118: between the current function name and the one prior.
                   1119: At the moment,
                   1120: .Ql \&.Fn
                   1121: does not check its word boundaries
                   1122: against troff line lengths and may split across a newline
1.4       jtc      1123: ungracefully.
                   1124: This will be fixed in the near future.
1.1       cgd      1125: .Ss Function Type
1.4       jtc      1126: This macro is intended for the
                   1127: .Sx SYNOPSIS
                   1128: section.
                   1129: It may be used
                   1130: anywhere else in the man page without problems, but its main purpose
                   1131: is to present the function type in kernel normal form for the
                   1132: .Sx SYNOPSIS
1.1       cgd      1133: of sections two and three
                   1134: (it causes a page break allowing the function name to appear
                   1135: on the next line).
                   1136: .Pp
                   1137: .Dl Usage: .Ft type ... \*(Pu
                   1138: .Bl -tag -width "\&.Ft struct stat" -offset 14n -compact
                   1139: .It Li \&.Ft struct stat
                   1140: .Ft struct stat
                   1141: .El
                   1142: .Pp
                   1143: The
                   1144: .Ql \&.Ft
                   1145: request is not callable by other macros.
1.39      wiz      1146: .Pp
                   1147: The
                   1148: .Ql .In
                   1149: .Li ( #include
                   1150: statement)
                   1151: macro is the short form for
                   1152: .Dl Li \&.Ft #include <header.h> .
                   1153: It specifies the C\~header file as being included in a C\~program.
                   1154: It also causes a line break, and is neither callable nor parsed.
                   1155: .Pp
                   1156: .Dl Usage: .In Ao header file Ac
                   1157: .Pp
                   1158: .Bl -tag -width ".Li .In\ stdio.h" -compact -offset 15n
                   1159: .It Li ".In stdio.h"
                   1160: .In stdio.h
                   1161: .El
                   1162: .
1.1       cgd      1163: .Ss Interactive Commands
                   1164: The
                   1165: .Ql \&.Ic
                   1166: macro designates an interactive or internal command.
                   1167: .Pp
1.25      tron     1168: .Dl Usage: .Ic command ... \*(Pu
1.4       jtc      1169: .Bl -tag -width ".Ic setenv , unsetenvxx" -compact -offset 14n
1.1       cgd      1170: .It Li \&.Ic :wq
                   1171: .Ic :wq
                   1172: .It Li \&.Ic do while {...}
                   1173: .Ic do while {...}
                   1174: .It Li \&.Ic setenv\ , unsetenv
                   1175: .Ic setenv , unsetenv
                   1176: .El
                   1177: .Pp
                   1178: It is an error to call
                   1179: .Ql \&.Ic
                   1180: without arguments.
                   1181: The
                   1182: .Ql \&.Ic
1.4       jtc      1183: macro is parsed and is callable.
1.1       cgd      1184: .Ss Literals
                   1185: The
                   1186: .Ql \&.Li
                   1187: literal macro may be used for special characters,
                   1188: variable constants, anything which should be displayed as it
                   1189: would be typed.
                   1190: .Pp
                   1191: .Dl Usage: .Li argument ... \*(Pu
                   1192: .Bl -tag -width ".Li cntrl-D ) ,"  -compact -offset 14n
                   1193: .It Li \&.Li \een
                   1194: .Li \en
                   1195: .It Li \&.Li M1 M2 M3\ ;
                   1196: .Li M1 M2 M3 ;
                   1197: .It Li \&.Li cntrl-D\ )\ ,
                   1198: .Li cntrl-D ) ,
                   1199: .It Li \&.Li 1024\ ...
                   1200: .Li 1024 ...
                   1201: .El
                   1202: .Pp
                   1203: The
                   1204: .Ql \&.Li
1.4       jtc      1205: macro is parsed and is callable.
1.1       cgd      1206: .Ss Name Macro
                   1207: The
                   1208: .Ql \&.Nm
                   1209: macro is used for the document title or subject name.
                   1210: It has the peculiarity of remembering the first
                   1211: argument it was called with, which should
1.4       jtc      1212: always be the subject name of the page.
                   1213: When called without
1.1       cgd      1214: arguments,
                   1215: .Ql \&.Nm
                   1216: regurgitates this initial name for the sole purpose
                   1217: of making less work for the author.
1.9       lukem    1218: If trailing punctuation is required with this feature,
                   1219: use
                   1220: .Qq
                   1221: as a first argument to
                   1222: .Ql \&.Nm .
1.1       cgd      1223: Note:
1.27      mycroft  1224: a section two, three or nine document function name is addressed with the
1.1       cgd      1225: .Ql \&.Nm
1.4       jtc      1226: in the
                   1227: .Sx NAME
                   1228: section, and with
1.1       cgd      1229: .Ql \&.Fn
1.4       jtc      1230: in the
                   1231: .Sx SYNOPSIS
1.1       cgd      1232: and remaining sections.
                   1233: For interactive commands, such as the
                   1234: .Ql while
                   1235: command keyword in
                   1236: .Xr csh 1 ,
                   1237: the
                   1238: .Ql \&.Ic
                   1239: macro should be used.
                   1240: While the
                   1241: .Ql \&.Ic
                   1242: is nearly identical
                   1243: to
                   1244: .Ql \&.Nm ,
                   1245: it can not recall the first argument it was invoked with.
                   1246: .Pp
                   1247: .Dl Usage: .Nm argument ... \*(Pu
1.2       jtc      1248: .Bl -tag -width ".Nm mdoc.samples" -compact -offset 14n
                   1249: .It Li \&.Nm mdoc.samples
                   1250: .Nm  mdoc.samples
1.4       jtc      1251: .It Li \&.Nm \e-mdoc
1.9       lukem    1252: .Nm \-mdoc
1.1       cgd      1253: .It Li \&.Nm foo\ )\ )\ ,
                   1254: .Nm foo ) ) ,
                   1255: .It Li \&.Nm
                   1256: .Nm
1.9       lukem    1257: .It Li \&.Nm \&"\&"\ :
1.37      wiz      1258: .Nm :
1.1       cgd      1259: .El
                   1260: .Pp
                   1261: The
                   1262: .Ql \&.Nm
1.4       jtc      1263: macro is parsed and is callable.
1.1       cgd      1264: .Ss Options
                   1265: The
                   1266: .Ql \&.Op
                   1267: macro
                   1268: places option brackets around the any remaining arguments on the command
                   1269: line, and places any
1.4       jtc      1270: trailing punctuation outside the brackets.
                   1271: The macros
1.1       cgd      1272: .Ql \&.Oc
                   1273: and
                   1274: .Ql \&.Oo
                   1275: may be used across one or more lines.
                   1276: .Pp
                   1277: .Dl Usage: .Op options ... \*(Pu
                   1278: .Bl -tag -width ".Op Fl c Ar objfil Op Ar corfil ," -compact -offset indent
                   1279: .It Li \&.Op
                   1280: .Op
                   1281: .It Li ".Op Fl k"
                   1282: .Op Fl k
                   1283: .It Li ".Op Fl k ) ."
                   1284: .Op Fl k ) .
                   1285: .It Li ".Op Fl k Ar kookfile"
                   1286: .Op Fl k Ar kookfile
                   1287: .It Li ".Op Fl k Ar kookfile ,"
                   1288: .Op Fl k Ar kookfile ,
                   1289: .It Li ".Op Ar objfil Op Ar corfil"
                   1290: .Op Ar objfil Op Ar corfil
                   1291: .It Li ".Op Fl c Ar objfil Op Ar corfil ,"
                   1292: .Op Fl c Ar objfil Op Ar corfil ,
                   1293: .It Li \&.Op word1 word2
                   1294: .Op word1 word2
                   1295: .El
                   1296: .Pp
                   1297: The
                   1298: .Ql \&.Oc
                   1299: and
                   1300: .Ql \&.Oo
                   1301: macros:
                   1302: .Bd -literal -offset indent
                   1303: \&.Oo
                   1304: \&.Op \&Fl k \&Ar kilobytes
                   1305: \&.Op \&Fl i \&Ar interval
                   1306: \&.Op \&Fl c \&Ar count
                   1307: \&.Oc
                   1308: .Ed
                   1309: .Pp
                   1310: Produce:
                   1311: .Oo
                   1312: .Op Fl k Ar kilobytes
                   1313: .Op Fl i Ar interval
                   1314: .Op Fl c Ar count
                   1315: .Oc
                   1316: .Pp
                   1317: The macros
                   1318: .Ql \&.Op ,
                   1319: .Ql \&.Oc
                   1320: and
                   1321: .Ql \&.Oo
1.4       jtc      1322: are parsed and are callable.
1.1       cgd      1323: .Ss Pathnames
                   1324: The
                   1325: .Ql \&.Pa
                   1326: macro formats path or file names.
                   1327: .Pp
                   1328: .Dl Usage: .Pa pathname \*(Pu
                   1329: .Bl -tag -width ".Pa /tmp/fooXXXXX ) ." -compact -offset 14n
                   1330: .It Li \&.Pa /usr/share
                   1331: .Pa /usr/share
                   1332: .It Li \&.Pa /tmp/fooXXXXX\ )\ .
                   1333: .Pa /tmp/fooXXXXX ) .
                   1334: .El
                   1335: .Pp
                   1336: The
                   1337: .Ql \&.Pa
1.4       jtc      1338: macro is parsed and is callable.
                   1339: .Ss Variables
                   1340: Generic variable reference:
                   1341: .Pp
                   1342: .Dl Usage: .Va variable ... \*(Pu
                   1343: .Bl -tag -width ".Va char s ] ) ) ," -compact -offset 14n
                   1344: .It Li \&.Va count
                   1345: .Va count
                   1346: .It Li \&.Va settimer ,
                   1347: .Va settimer ,
                   1348: .It Li \&.Va int\ *prt\ )\ :
                   1349: .Va int\ *prt ) :
                   1350: .It Li \&.Va char\ s\ ]\ )\ )\ ,
                   1351: .Va char\ s ] ) ) ,
                   1352: .El
                   1353: .Pp
                   1354: It is an error to call
                   1355: .Ql \&.Va
                   1356: without any arguments.
                   1357: The
                   1358: .Ql \&.Va
                   1359: macro is parsed and is callable.
                   1360: .Ss Manual Page Cross References
                   1361: The
                   1362: .Ql \&.Xr
                   1363: macro expects the first argument to be
                   1364: a manual page name, and the second argument, if it exists,
                   1365: to be either a section page number or punctuation.
                   1366: Any
                   1367: remaining arguments are assumed to be punctuation.
                   1368: .Pp
1.14      perry    1369: .Dl Usage: .Xr man_page [1,...,9] \*(Pu
1.4       jtc      1370: .Bl -tag -width ".Xr mdoc 7 ) ) ," -compact -offset 14n
                   1371: .It Li \&.Xr mdoc
                   1372: .Xr mdoc
                   1373: .It Li \&.Xr mdoc\ ,
                   1374: .Xr mdoc ,
                   1375: .It Li \&.Xr mdoc 7
                   1376: .Xr mdoc 7
                   1377: .It Li \&.Xr mdoc 7\ )\ )\ ,
                   1378: .Xr mdoc 7 ) ) ,
                   1379: .El
                   1380: .Pp
                   1381: The
                   1382: .Ql \&.Xr
                   1383: macro is parsed and is callable.
                   1384: It is an error to call
                   1385: .Ql \&.Xr
                   1386: without
                   1387: any arguments.
                   1388: .Sh GENERAL TEXT DOMAIN
1.33      ross     1389: .Ss AT\*[Am]T Macro
1.4       jtc      1390: .Bd -literal -offset indent -compact
1.18      garbled  1391: Usage: .At [v1 .. v7 | 32v | V.1 | V.4] ... \*(Pu
1.4       jtc      1392: .Ed
                   1393: .Bl -tag -width ".At v6 ) ," -compact -offset 14n
                   1394: .It Li ".At"
                   1395: .At
                   1396: .It Li ".At v6 ."
                   1397: .At v6 .
                   1398: .El
                   1399: .Pp
                   1400: The
                   1401: .Ql \&.At
                   1402: macro is
                   1403: .Em not
                   1404: parsed and
                   1405: .Em not
1.36      wiz      1406: callable.
                   1407: It accepts at most two arguments.
1.4       jtc      1408: .Ss BSD Macro
                   1409: .Dl Usage: .Bx [Version/release] ... \*(Pu
                   1410: .Bl -tag -width ".Bx 4.3 ) ," -compact -offset 14n
                   1411: .It Li ".Bx"
                   1412: .Bx
                   1413: .It Li ".Bx 4.3 ."
                   1414: .Bx 4.3 .
                   1415: .El
                   1416: .Pp
                   1417: The
                   1418: .Ql \&.Bx
1.7       perry    1419: macro is parsed and is callable.
1.28      ad       1420: .Ss BSD/OS Macro
                   1421: .Dl Usage: .Bsx [Version/release] ... \*(Pu
                   1422: .Bl -tag -width ".Bsx 4.1 ) ," -compact -offset 14n
                   1423: .It Li ".Bsx"
                   1424: .Bsx
                   1425: .It Li ".Bsx 4.1 ."
                   1426: .Bsx 4.1 .
                   1427: .El
                   1428: .Pp
                   1429: The
                   1430: .Ql \&.Bsx
                   1431: macro is parsed and is callable.
                   1432: .Ss FreeBSD Macro
                   1433: .Dl Usage: .Fx [Version/release] ... \*(Pu
                   1434: .Bl -tag -width ".Fx 2.2 ) ," -compact -offset 14n
                   1435: .It Li ".Fx"
                   1436: .Fx
                   1437: .It Li ".Fx 2.2 ."
                   1438: .Fx 2.2 .
                   1439: .El
                   1440: .Pp
                   1441: The
                   1442: .Ql \&.Fx
                   1443: macro is parsed and is callable.
1.7       perry    1444: .Ss NetBSD Macro
                   1445: .Dl Usage: .Nx [Version/release] ... \*(Pu
1.16      perry    1446: .Bl -tag -width ".Nx 1.4 ) ," -compact -offset 14n
1.7       perry    1447: .It Li ".Nx"
                   1448: .Nx
1.16      perry    1449: .It Li ".Nx 1.4 ."
                   1450: .Nx 1.4 .
1.7       perry    1451: .El
                   1452: .Pp
                   1453: The
                   1454: .Ql \&.Nx
1.16      perry    1455: macro is parsed and is callable.
1.28      ad       1456: .Ss OpenBSD Macro
                   1457: .Dl Usage: .Ox [Version/release] ... \*(Pu
                   1458: .Bl -tag -width ".Ox 2.7 ) ," -compact -offset 14n
                   1459: .It Li ".Ox"
                   1460: .Ox
                   1461: .It Li ".Ox 2.7 ."
                   1462: .Ox 2.7 .
1.16      perry    1463: .El
                   1464: .Pp
                   1465: The
1.28      ad       1466: .Ql \&.Ox
1.4       jtc      1467: macro is parsed and is callable.
                   1468: .Ss UNIX Macro
                   1469: .Dl Usage: .Ux ... \*(Pu
                   1470: .Bl -tag -width ".Ux 4.3 ) ," -compact -offset 14n
                   1471: .It Li ".Ux"
                   1472: .Ux
                   1473: .El
                   1474: .Pp
                   1475: The
                   1476: .Ql \&.Ux
                   1477: macro is parsed and is callable.
                   1478: .Ss Emphasis Macro
                   1479: Text may be stressed or emphasized with the
                   1480: .Ql \&.Em
                   1481: macro.
                   1482: The usual font for emphasis is italic.
                   1483: .Pp
                   1484: .Dl Usage: .Em argument ... \*(Pu
                   1485: .Bl -tag -width ".Em vide infra ) ) ," -compact -offset 14n
                   1486: .It Li ".Em does not"
                   1487: .Em does not
                   1488: .It Li ".Em exceed 1024 ."
                   1489: .Em exceed 1024 .
                   1490: .It Li ".Em vide infra ) ) ,"
                   1491: .Em vide infra ) ) ,
                   1492: .El
                   1493: .\" .Pp
                   1494: .\" The emphasis can be forced across several lines of text by using
                   1495: .\" the
                   1496: .\" .Ql \&.Bf
                   1497: .\" macro discussed in
                   1498: .\" .Sx Modes
                   1499: .\" under
                   1500: .\" .Sx PAGE STRUCTURE DOMAIN .
                   1501: .\" .Pp
                   1502: .\" .Bf -emphasis
                   1503: .\" We are certain the reason most people desire a Harvard MBA
1.36      wiz      1504: .\" so they can become to be successful philanthropists.
                   1505: .\" Only mathematicians and physicists go to graduate school strictly
                   1506: .\" to acquire infinite wealthy and fame.
                   1507: .\" It's that infinity word that does it to them.
                   1508: .\" Ruins them.
1.4       jtc      1509: .\" .Ef
                   1510: .Pp
1.1       cgd      1511: The
1.4       jtc      1512: .Ql \&.Em
                   1513: macro is parsed and is callable.
                   1514: It is an error to call
                   1515: .Ql \&.Em
                   1516: without arguments.
                   1517: .Ss Enclosure and Quoting Macros
                   1518: The concept of enclosure is similar to quoting.
                   1519: The object being to enclose one or more strings between
                   1520: a pair of characters like quotes or parentheses.
                   1521: The terms quoting and enclosure are used
                   1522: interchangeably throughout this document.
                   1523: Most of the
                   1524: one line enclosure macros end
                   1525: in small letter
                   1526: .Ql q
                   1527: to give a hint of quoting, but there are a few irregularities.
                   1528: For each enclosure macro
                   1529: there is also a pair of open and close macros which end
                   1530: in small letters
                   1531: .Ql o
                   1532: and
                   1533: .Ql c
                   1534: respectively.
                   1535: These can be used across one or more lines of text
                   1536: and while they have nesting limitations, the one line quote macros
                   1537: can be used inside
                   1538: of them.
                   1539: .Pp
                   1540: .ne 5
                   1541: .Bd -filled -offset indent
                   1542: .Bl -column "quote " "close " "open " "Enclose Stringx(in XX) " XXstringXX
1.45    ! joerg    1543: .It Em " Quote  Close   Open   Function        Result"
1.33      ross     1544: .It Li ".Aq    .Ac     .Ao" Ta No Angle Bracket Enclosure      \*[Lt]string\*[Gt]
1.30      wiz      1545: .It Li ".Bq    .Bc     .Bo" Ta No Bracket Enclosure    [string]
                   1546: .It Li ".Dq    .Dc     .Do" Ta No Double Quote ``string''
                   1547: .It Li ".Ec    .Eo     " Ta No Enclose String (in XX)  XXstringXX
                   1548: .It Li ".Pq    .Pc     .Po" Ta No Parenthesis Enclosure        (string)
                   1549: .It Li ".Ql            " Ta No Quoted Literal  `st' or string
                   1550: .It Li ".Qq    .Qc     .Qo" Ta No Straight Double Quote        "string"
                   1551: .It Li ".Sq    .Sc     .So" Ta No Single Quote `string'
1.4       jtc      1552: .El
                   1553: .Ed
1.1       cgd      1554: .Pp
1.4       jtc      1555: Except for the irregular macros noted below, all
                   1556: of the quoting macros are parsed and callable.
                   1557: All handle punctuation properly, as long as it
                   1558: is presented one character at a time and separated by spaces.
                   1559: The quoting macros examine opening and closing punctuation
                   1560: to determine whether it comes before or after the
1.36      wiz      1561: enclosing string.
                   1562: This makes some nesting possible.
1.4       jtc      1563: .Bl -tag -width xxx,xxxx
                   1564: .It Li \&.Ec , \&.Eo
                   1565: These macros expect the first argument to be the
                   1566: opening and closing strings respectively.
                   1567: .It Li \&.Ql
                   1568: The quoted literal macro behaves differently for
1.30      wiz      1569: .Xr troff 1
1.4       jtc      1570: than
1.30      wiz      1571: .Xr nroff 1 .
1.4       jtc      1572: If formatted with
1.30      wiz      1573: .Xr nroff 1 ,
1.36      wiz      1574: a quoted literal is always quoted.
                   1575: If formatted with troff, an item is only quoted if the width
1.4       jtc      1576: of the item is less than three constant width characters.
                   1577: This is to make short strings more visible where the font change
                   1578: to literal (constant width) is less noticeable.
                   1579: .It Li \&.Pf
                   1580: The prefix macro is not callable, but it is parsed:
                   1581: .Bl -tag -width "(namexx" -offset indent
1.1       cgd      1582: .It Li ".Pf ( Fa name2"
                   1583: becomes
1.4       jtc      1584: .Pf ( Fa name2 .
1.1       cgd      1585: .El
1.21      ross     1586: .It Li \&.Ns
1.1       cgd      1587: The
                   1588: .Ql \&.Ns
1.21      ross     1589: (no space) macro, which
                   1590: .Em is
                   1591: callable,
                   1592: performs the analogous suffix function.
1.30      wiz      1593: .It Li \&.Ap
                   1594: The
                   1595: .Ql \&.Ap
                   1596: macro inserts an apostrophe and exits any special text modes,
1.21      ross     1597: continuing in
                   1598: .Li \&.No
                   1599: mode.
1.4       jtc      1600: .El
                   1601: .Pp
                   1602: .ne 4
                   1603: Examples of quoting:
1.45    ! joerg    1604: .Bl -tag -width ".Aq ENTER ) ,xxxxxxxx" -compact -offset indent
1.4       jtc      1605: .It Li \&.Aq
                   1606: .Aq
1.45    ! joerg    1607: .It Li \&.Aq ENTER\ )\ ,
        !          1608: .Aq ENTER ) ,
1.4       jtc      1609: .It Li \&.Bq
                   1610: .Bq
                   1611: .It Li \&.Bq \&Em Greek \&, French \&.
                   1612: .Bq Em Greek , French .
                   1613: .It Li \&.Dq
                   1614: .Dq
                   1615: .It Li ".Dq string abc ."
                   1616: .Dq string abc .
                   1617: .It Li ".Dq \'^[A-Z]\'"
                   1618: .Dq \'^[A-Z]\'
                   1619: .It Li "\&.Ql man mdoc"
                   1620: .Ql man mdoc
                   1621: .It Li \&.Qq
                   1622: .Qq
                   1623: .It Li "\&.Qq string ) ,"
                   1624: .Qq string ) ,
                   1625: .It Li "\&.Qq string Ns ),"
                   1626: .Qq string Ns ),
                   1627: .It Li \&.Sq
                   1628: .Sq
                   1629: .It Li "\&.Sq string
                   1630: .Sq string
1.21      ross     1631: .It Li "\&.Em or Ap ing
                   1632: .Em or Ap ing
1.4       jtc      1633: .El
                   1634: .Pp
                   1635: For a good example of nested enclosure macros, see the
                   1636: .Ql \&.Op
                   1637: option macro.
                   1638: It was created from the same
                   1639: underlying enclosure macros as those presented in the list
                   1640: above.
                   1641: The
                   1642: .Ql \&.Xo
                   1643: and
                   1644: .Ql \&.Xc
                   1645: extended argument list macros
                   1646: were also built from the same underlying routines and are a good
                   1647: example of
                   1648: .Nm \-mdoc
                   1649: macro usage at its worst.
                   1650: .Ss No\-Op or Normal Text Macro
                   1651: The macro
                   1652: .Li \&.No
                   1653: is
                   1654: a hack for words in a macro command line which should
                   1655: .Em not
                   1656: be formatted and follows the conventional syntax
                   1657: for content macros.
                   1658: .Ss No Space Macro
                   1659: The
                   1660: .Ql \&.Ns
                   1661: macro eliminates unwanted spaces in between macro requests.
                   1662: It is useful for old style argument lists where there is no space
                   1663: between the flag and argument:
                   1664: .Bl -tag -width ".Op Fl I Ns Ar directoryxx" -offset indent
                   1665: .It Li ".Op Fl I Ns Ar directory"
                   1666: produces
                   1667: .Op Fl I Ns Ar directory
                   1668: .El
                   1669: .Pp
                   1670: Note: the
                   1671: .Ql \&.Ns
                   1672: macro always invokes the
                   1673: .Ql \&.No
                   1674: macro after eliminating the space unless another macro name
                   1675: follows it.
                   1676: The macro
                   1677: .Ql \&.Ns
                   1678: is parsed and is callable.
1.1       cgd      1679: .Ss Section Cross References
                   1680: The
                   1681: .Ql \&.Sx
                   1682: macro designates a reference to a section header
1.4       jtc      1683: within the same document.
                   1684: It is parsed and is callable.
1.1       cgd      1685: .Pp
                   1686: .Bl -tag -width "Li \&.Sx FILES" -offset 14n
                   1687: .It Li \&.Sx FILES
                   1688: .Sx FILES
                   1689: .El
1.4       jtc      1690: .Ss Symbolic
                   1691: The symbolic emphasis macro is generally a boldface macro in
                   1692: either the symbolic sense or the traditional English usage.
                   1693: .Pp
                   1694: .Dl Usage: .Sy symbol ... \*(Pu
                   1695: .Bl -tag -width ".Sy Important Noticex" -compact -offset 14n
                   1696: .It Li \&.Sy Important Notice
                   1697: .Sy Important Notice
                   1698: .El
                   1699: .Pp
                   1700: The
                   1701: .Ql \&.Sy
                   1702: macro is parsed and is callable.
                   1703: Arguments to
                   1704: .Ql \&.Sy
                   1705: may be quoted.
1.1       cgd      1706: .Ss References and Citations
                   1707: The following macros make a modest attempt to handle references.
1.4       jtc      1708: At best, the macros make it convenient to manually drop in a subset of
1.1       cgd      1709: refer style references.
                   1710: .Pp
                   1711: .Bl -tag -width 6n -offset indent -compact
                   1712: .It Li ".Rs"
1.4       jtc      1713: Reference Start.
                   1714: Causes a line break and begins collection
1.1       cgd      1715: of reference information until the
                   1716: reference end macro is read.
                   1717: .It Li ".Re"
1.4       jtc      1718: Reference End.
                   1719: The reference is printed.
1.1       cgd      1720: .It Li ".%A"
                   1721: Reference author name, one name per invocation.
                   1722: .It Li ".%B"
                   1723: Book title.
1.4       jtc      1724: .It Li ".\&%C"
                   1725: City/place.
                   1726: .It Li ".\&%D"
                   1727: Date.
1.1       cgd      1728: .It Li ".%J"
1.4       jtc      1729: Journal name.
1.1       cgd      1730: .It Li ".%N"
                   1731: Issue number.
                   1732: .It Li ".%O"
                   1733: Optional information.
1.4       jtc      1734: .It Li ".%P"
                   1735: Page number.
1.1       cgd      1736: .It Li ".%R"
                   1737: Report name.
                   1738: .It Li ".%T"
                   1739: Title of article.
                   1740: .It Li ".%V"
                   1741: Volume(s).
                   1742: .El
                   1743: .Pp
1.4       jtc      1744: The macros beginning with
1.1       cgd      1745: .Ql %
1.4       jtc      1746: are not callable, and are parsed only for the trade name macro which
                   1747: returns to its caller.
                   1748: (And not very predictably at the moment either.)
                   1749: The purpose is to allow trade names
                   1750: to be pretty printed in
1.30      wiz      1751: .Xr troff 1 Ns / Ns Ic ditroff
1.4       jtc      1752: output.
                   1753: .Ss Trade Names (or Acronyms and Type Names)
                   1754: The trade name macro is generally a small caps macro for
                   1755: all upper case words longer than two characters.
                   1756: .Pp
                   1757: .Dl Usage: .Tn symbol ... \*(Pu
                   1758: .Bl -tag -width ".Tn ASCII" -compact -offset 14n
                   1759: .It Li \&.Tn DEC
                   1760: .Tn DEC
                   1761: .It Li \&.Tn ASCII
                   1762: .Tn ASCII
1.1       cgd      1763: .El
                   1764: .Pp
                   1765: The
1.4       jtc      1766: .Ql \&.Tn
1.1       cgd      1767: macro
1.4       jtc      1768: is parsed and is callable by other macros.
1.8       lukem    1769: .Ss Extended Arguments
1.1       cgd      1770: The
                   1771: .Li \&.Xo
                   1772: and
                   1773: .Li \&.Xc
1.4       jtc      1774: macros allow one to extend an argument list
                   1775: on a macro boundary.
                   1776: Argument lists cannot
1.1       cgd      1777: be extended within a macro
                   1778: which expects all of its arguments on one line such
                   1779: as
                   1780: .Ql \&.Op .
1.4       jtc      1781: .Pp
                   1782: Here is an example of
                   1783: .Ql \&.Xo
                   1784: using the space mode macro to turn spacing off:
                   1785: .Bd -literal -offset indent
                   1786: \&.Sm off
                   1787: \&.It Xo Sy I Ar operation
                   1788: \&.No \een Ar count No \een
                   1789: \&.Xc
                   1790: \&.Sm on
                   1791: .Ed
                   1792: .Pp
                   1793: Produces
                   1794: .Bd -filled -offset indent
                   1795: .Bl -tag -width flag -compact
                   1796: .Sm off
1.45    ! joerg    1797: .It Sy I Ar operation No \en Ar count No \en
1.4       jtc      1798: .Sm on
                   1799: .El
                   1800: .Ed
                   1801: .Pp
                   1802: Another one:
                   1803: .Bd -literal -offset indent
                   1804: \&.Sm off
                   1805: \&.It Cm S No \&/ Ar old_pattern Xo
                   1806: \&.No \&/ Ar new_pattern
                   1807: \&.No \&/ Op Cm g
                   1808: \&.Xc
                   1809: \&.Sm on
                   1810: .Ed
                   1811: .Pp
                   1812: Produces
                   1813: .Bd -filled -offset indent
                   1814: .Bl -tag -width flag -compact
                   1815: .Sm off
1.45    ! joerg    1816: .It Cm S No \&/ Ar old_pattern No \&/ Ar new_pattern No \&/ Op Cm g
1.4       jtc      1817: .Sm on
                   1818: .El
                   1819: .Ed
                   1820: .Pp
                   1821: Another example of
                   1822: .Ql \&.Xo
                   1823: and using enclosure macros:
                   1824: Test the value of an variable.
                   1825: .Bd -literal -offset indent
                   1826: \&.It Xo
                   1827: \&.Ic .ifndef
1.33      ross     1828: \&.Oo \e\*[Am]! Oc Ns Ar variable
1.4       jtc      1829: \&.Op Ar operator variable ...
                   1830: \&.Xc
                   1831: .Ed
                   1832: .Pp
                   1833: Produces
                   1834: .Bd -filled -offset indent
                   1835: .Bl -tag -width flag -compact
1.45    ! joerg    1836: .It Ic .ifndef Oo \&! Oc Ns Ar variable Op Ar operator variable ...
1.4       jtc      1837: .El
                   1838: .Ed
                   1839: .Pp
                   1840: All of the above examples have used the
                   1841: .Ql \&.Xo
                   1842: macro on the argument list of the
                   1843: .Ql \&.It
                   1844: (list-item)
                   1845: macro.
                   1846: The extend macros are not used very often, and when they are
                   1847: it is usually to extend the list-item argument list.
                   1848: Unfortunately, this is also where the extend macros are the
                   1849: most finicky.
                   1850: In the first two examples, spacing was turned off;
                   1851: in the third, spacing was desired in part of the output but
                   1852: not all of it.
                   1853: To make these macros work in this situation make sure
                   1854: the
                   1855: .Ql \&.Xo
                   1856: and
                   1857: .Ql \&.Xc
                   1858: macros are placed as shown in the third example.
                   1859: If the
                   1860: .Ql \&.Xo
                   1861: macro is not alone on the
                   1862: .Ql \&.It
                   1863: argument list, spacing will be unpredictable.
                   1864: The
                   1865: .Ql \&.Ns
                   1866: (no space macro)
                   1867: must not occur as the first or last macro on a line
                   1868: in this situation.
                   1869: Out of 900 manual pages (about 1500 actual pages)
                   1870: currently released with
                   1871: .Bx
                   1872: only fifteen use the
                   1873: .Ql \&.Xo
                   1874: macro.
                   1875: .Sh PAGE STRUCTURE DOMAIN
1.1       cgd      1876: .Ss Section Headers
                   1877: The first three
                   1878: .Ql \&.Sh
                   1879: section header macros
1.35      wiz      1880: listed below are required in every
1.4       jtc      1881: man page.
                   1882: The remaining section headers
                   1883: are recommended at the discretion of the author
                   1884: writing the manual page.
                   1885: The
1.1       cgd      1886: .Ql \&.Sh
1.4       jtc      1887: macro can take up to nine arguments.
1.35      wiz      1888: It is parsed but is not callable.
1.45    ! joerg    1889: .Bl -tag -width "\&.Sh DESCRIPTION"
1.30      wiz      1890: .It Li \&.Sh NAME
1.1       cgd      1891: The
                   1892: .Ql \&.Sh NAME
1.4       jtc      1893: macro is mandatory.
                   1894: If not specified,
1.1       cgd      1895: the headers, footers and page layout defaults
                   1896: will not be set and things will be rather unpleasant.
1.4       jtc      1897: The
                   1898: .Sx NAME
                   1899: section consists of at least three items.
1.1       cgd      1900: The first is the
                   1901: .Ql \&.Nm
                   1902: name macro naming the subject of the man page.
                   1903: The second is the Name Description macro,
                   1904: .Ql \&.Nd ,
                   1905: which separates the subject
1.4       jtc      1906: name from the third item, which is the description.
                   1907: The
1.1       cgd      1908: description should be the most terse and lucid possible,
                   1909: as the space available is small.
1.30      wiz      1910: .It Li \&.Sh SYNOPSIS
1.4       jtc      1911: The
                   1912: .Sx SYNOPSIS
                   1913: section describes the typical usage of the
                   1914: subject of a man page.
                   1915: The  macros required
1.1       cgd      1916: are either
                   1917: .Ql ".Nm" ,
                   1918: .Ql ".Cd" ,
1.4       jtc      1919: .Ql ".Fn" ,
1.1       cgd      1920: (and possibly
1.4       jtc      1921: .Ql ".Fo" ,
                   1922: .Ql ".Fc" ,
1.1       cgd      1923: .Ql ".Fd" ,
                   1924: .Ql ".Ft"
                   1925: macros).
                   1926: The function name
                   1927: macro
                   1928: .Ql ".Fn"
                   1929: is required
                   1930: for manual page sections 2 and 3, the command and general
                   1931: name macro
                   1932: .Ql \&.Nm
                   1933: is required for sections 1, 5, 6, 7, 8.
                   1934: Section 4 manuals require a
                   1935: .Ql ".Nm" , ".Fd"
                   1936: or a
                   1937: .Ql ".Cd"
                   1938: configuration device usage macro.
                   1939: Several other macros may be necessary to produce
                   1940: the synopsis line as shown below:
                   1941: .Pp
                   1942: .Bd -filled -offset indent
                   1943: .Nm cat
                   1944: .Op Fl benstuv
                   1945: .Op Fl
                   1946: .Ar
                   1947: .Ed
                   1948: .Pp
                   1949: The following macros were used:
                   1950: .Pp
                   1951: .Dl \&.Nm cat
                   1952: .Dl \&.Op \&Fl benstuv
                   1953: .Dl \&.Op \&Fl
                   1954: .Dl \&.Ar
1.4       jtc      1955: .Pp
                   1956: .Sy Note :
                   1957: The macros
                   1958: .Ql \&.Op ,
                   1959: .Ql \&.Fl ,
                   1960: and
                   1961: .Ql \&.Ar
                   1962: recognize the pipe bar character
                   1963: .Ql \*(Ba ,
                   1964: so a command line such as:
                   1965: .Pp
                   1966: .Dl ".Op Fl a | Fl b"
                   1967: .Pp
                   1968: will not go orbital.
1.30      wiz      1969: .Xr troff 1
1.4       jtc      1970: normally interprets a \*(Ba as a special operator.
                   1971: See
                   1972: .Sx PREDEFINED STRINGS
                   1973: for a usable \*(Ba
                   1974: character in other situations.
1.30      wiz      1975: .It Li \&.Sh DESCRIPTION
1.4       jtc      1976: In most cases the first text in the
                   1977: .Sx DESCRIPTION
                   1978: section
1.1       cgd      1979: is a brief paragraph on the command, function or file,
                   1980: followed by a lexical list of options and respective
1.4       jtc      1981: explanations.
                   1982: To create such a list, the
1.1       cgd      1983: .Ql \&.Bl
                   1984: begin-list,
                   1985: .Ql \&.It
                   1986: list-item and
                   1987: .Ql \&.El
                   1988: end-list
                   1989: macros are used (see
                   1990: .Sx Lists and Columns
                   1991: below).
                   1992: .El
                   1993: .Pp
                   1994: The following
                   1995: .Ql \&.Sh
                   1996: section headers are part of the
                   1997: preferred manual page layout and must be used appropriately
1.4       jtc      1998: to maintain consistency.
                   1999: They are listed in the order
1.1       cgd      2000: in which they would be used.
                   2001: .Bl -tag -width SYNOPSIS
1.30      wiz      2002: .It Li \&.Sh ENVIRONMENT
1.4       jtc      2003: The
                   2004: .Sx ENVIRONMENT
                   2005: section should reveal any related
1.1       cgd      2006: environment
1.4       jtc      2007: variables and clues to their behavior and/or usage.
1.30      wiz      2008: .It Li \&.Sh EXAMPLES
1.4       jtc      2009: There are several ways to create examples.
                   2010: See
                   2011: the
                   2012: .Sx EXAMPLES
                   2013: section below
1.1       cgd      2014: for details.
1.30      wiz      2015: .It Li \&.Sh FILES
1.1       cgd      2016: Files which are used or created by the man page subject
                   2017: should be listed via the
                   2018: .Ql \&.Pa
1.4       jtc      2019: macro in the
                   2020: .Sx FILES
                   2021: section.
1.30      wiz      2022: .It Li \&.Sh SEE ALSO
1.1       cgd      2023: References to other material on the man page topic and
                   2024: cross references to other relevant man pages should
1.4       jtc      2025: be placed in the
                   2026: .Sx SEE ALSO
                   2027: section.
                   2028: Cross references
1.1       cgd      2029: are specified using the
                   2030: .Ql \&.Xr
1.4       jtc      2031: macro.
                   2032: At this time
1.1       cgd      2033: .Xr refer 1
                   2034: style references are not accommodated.
1.13      lukem    2035: .Pp
                   2036: It is recommended that the cross references are sorted on the section
                   2037: number, and then alphabetically on the names within a section.
1.30      wiz      2038: .It Li \&.Sh STANDARDS
1.1       cgd      2039: If the command, library function or file adheres to a
1.4       jtc      2040: specific implementation such as
                   2041: .St -p1003.2
                   2042: or
                   2043: .St -ansiC
                   2044: this should be noted here.
                   2045: If the
1.1       cgd      2046: command does not adhere to any standard, its history
1.4       jtc      2047: should be noted in the
                   2048: .Sx HISTORY
                   2049: section.
1.30      wiz      2050: .It Li \&.Sh HISTORY
1.1       cgd      2051: Any command which does not adhere to any specific standards
                   2052: should be outlined historically in this section.
1.30      wiz      2053: .It Li \&.Sh AUTHORS
1.1       cgd      2054: Credits, if need be, should be placed here.
1.30      wiz      2055: .It Li \&.Sh DIAGNOSTICS
1.1       cgd      2056: Diagnostics from a command should be placed in this section.
1.30      wiz      2057: .It Li \&.Sh ERRORS
1.1       cgd      2058: Specific error handling, especially from library functions
1.4       jtc      2059: (man page sections 2 and 3) should go here.
                   2060: The
1.1       cgd      2061: .Ql \&.Er
                   2062: macro is used to specify an errno.
1.30      wiz      2063: .It Li \&.Sh BUGS
1.1       cgd      2064: Blatant problems with the topic go here...
                   2065: .El
                   2066: .Pp
                   2067: User specified
                   2068: .Ql \&.Sh
                   2069: sections may be added,
                   2070: for example, this section was set with:
                   2071: .Bd -literal -offset 14n
1.30      wiz      2072: \&.Sh PAGE STRUCTURE DOMAIN
1.1       cgd      2073: .Ed
                   2074: .Ss Paragraphs and Line Spacing.
                   2075: .Bl -tag -width 6n
1.30      wiz      2076: .It Li \&.Pp
1.25      tron     2077: The
                   2078: .Ql \&.Pp
                   2079: paragraph command may
1.1       cgd      2080: be used to specify a line space where necessary.
                   2081: The macro is not necessary after a
                   2082: .Ql \&.Sh
                   2083: or
                   2084: .Ql \&.Ss
                   2085: macro or before
                   2086: a
                   2087: .Ql \&.Bl
                   2088: macro.
                   2089: (The
                   2090: .Ql \&.Bl
                   2091: macro asserts a vertical distance unless the -compact flag is given).
                   2092: .El
1.4       jtc      2093: .\" This worked with version one, need to redo for version three
1.1       cgd      2094: .\" .Pp
                   2095: .\" .Ds I
                   2096: .\" .Cw (ax+bx+c) \ is\ produced\ by\ \&
                   2097: .\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\&
                   2098: .\" .Cl Cx \t\t
                   2099: .\" .Li \&.Cx\ (
                   2100: .\" .Cx
                   2101: .\" .Cl Cx \t\t
                   2102: .\" .Li \&.Va ax
                   2103: .\" .Cx
                   2104: .\" .Cl Cx \t\t
                   2105: .\" .Li \&.Sy \+
                   2106: .\" .Cx
                   2107: .\" .Cl Cx \&(\&
                   2108: .\" .Va ax
                   2109: .\" .Cx +
                   2110: .\" .Va by
                   2111: .\" .Cx +
                   2112: .\" .Va c )
                   2113: .\" .Cx \t
                   2114: .\" .Em is produced by
                   2115: .\" .Cx \t
                   2116: .\" .Li \&.Va by
                   2117: .\" .Cx
                   2118: .\" .Cl Cx \t\t
                   2119: .\" .Li \&.Sy \+
                   2120: .\" .Cx
                   2121: .\" .Cl Cx \t\t
                   2122: .\" .Li \&.Va c )
                   2123: .\" .Cx
                   2124: .\" .Cl Cx \t\t
                   2125: .\" .Li \&.Cx
                   2126: .\" .Cx
                   2127: .\" .Cw
                   2128: .\" .De
                   2129: .\" .Pp
1.4       jtc      2130: .\" This example shows the same equation in a different format.
                   2131: .\" The spaces
1.1       cgd      2132: .\" around the
                   2133: .\" .Li \&+
                   2134: .\" signs were forced with
                   2135: .\" .Li \e :
                   2136: .\" .Pp
                   2137: .\" .Ds I
                   2138: .\" .Cw (ax\ +\ bx\ +\ c) \ is\ produced\ by\ \&
                   2139: .\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\&
                   2140: .\" .Cl Cx \t\t
                   2141: .\" .Li \&.Cx\ (
                   2142: .\" .Cx
                   2143: .\" .Cl Cx \t\t
                   2144: .\" .Li \&.Va a
                   2145: .\" .Cx
                   2146: .\" .Cl Cx \t\t
                   2147: .\" .Li \&.Sy x
                   2148: .\" .Cx
                   2149: .\" .Cl Cx \t\t
                   2150: .\" .Li \&.Cx \e\ +\e\ \e&
                   2151: .\" .Cx
                   2152: .\" .Cl Cx \&(\&
                   2153: .\" .Va a
                   2154: .\" .Sy x
                   2155: .\" .Cx \ +\ \&
                   2156: .\" .Va b
                   2157: .\" .Sy y
                   2158: .\" .Cx \ +\ \&
                   2159: .\" .Va c )
                   2160: .\" .Cx \t
                   2161: .\" .Em is produced by
                   2162: .\" .Cl Cx \t\t
                   2163: .\" .Li \&.Va b
                   2164: .\" .Cx
                   2165: .\" .Cl Cx \t\t
                   2166: .\" .Li \&.Sy y
                   2167: .\" .Cx
                   2168: .\" .Cl Cx \t\t
                   2169: .\" .Li \&.Cx \e\ +\e\ \e&
                   2170: .\" .Cx
                   2171: .\" .Cl Cx \t\t
                   2172: .\" .Li \&.Va c )
                   2173: .\" .Cx
                   2174: .\" .Cl Cx \t\t
                   2175: .\" .Li \&.Cx
                   2176: .\" .Cx
                   2177: .\" .Cw
                   2178: .\" .De
                   2179: .\" .Pp
                   2180: .\" The incantation below was
                   2181: .\" lifted from the
                   2182: .\" .Xr adb 1
                   2183: .\" manual page:
                   2184: .\" .Pp
                   2185: .\" .Ds I
                   2186: .\" .Cw \&[?/]m_b1_e1_f1[?/]\& is\ produced\ by
                   2187: .\" .Cl Cx \t\t
                   2188: .\" .Li \&.Cx Op Sy ?/
                   2189: .\" .Cx
                   2190: .\" .Cl Cx \t\t
                   2191: .\" .Li \&.Nm m
                   2192: .\" .Cx
                   2193: .\" .Cl Cx Op Sy ?/
                   2194: .\" .Nm m
                   2195: .\" .Ad \ b1 e1 f1
                   2196: .\" .Op Sy ?/
                   2197: .\" .Cx \t
                   2198: .\" .Em is produced by
                   2199: .\" .Cx \t
                   2200: .\" .Li \&.Ar \e\ b1 e1 f1
                   2201: .\" .Cx
                   2202: .\" .Cl Cx \t\t
                   2203: .\" .Li \&.Op Sy ?/
                   2204: .\" .Cx
                   2205: .\" .Cl Cx \t\t
                   2206: .\" .Li \&.Cx
                   2207: .\" .Cx
                   2208: .\" .Cw
                   2209: .\" .De
                   2210: .\" .Pp
1.4       jtc      2211: .Ss Keeps
                   2212: The only keep that is implemented at this time is for words.
                   2213: The macros are
                   2214: .Ql \&.Bk
                   2215: (begin-keep)
                   2216: and
                   2217: .Ql \&.Ek
                   2218: (end-keep).
                   2219: The only option that
1.23      lukem    2220: .Ql \&.Bk
1.4       jtc      2221: accepts is
                   2222: .Fl words
                   2223: and is useful for preventing line breaks in the middle of options.
                   2224: In the example for the make command line arguments (see
                   2225: .Sx What's in a name ) ,
                   2226: the keep prevented
1.30      wiz      2227: .Xr nroff 1
1.25      tron     2228: from placing the
1.4       jtc      2229: flag and the argument
                   2230: on separate lines.
1.25      tron     2231: (Actually, the option macro formerly prevented this from occurring,
1.4       jtc      2232: but was dropped when the decision (religious) was made to force
                   2233: right justified margins in
1.30      wiz      2234: .Xr troff 1
1.4       jtc      2235: as options in general look atrocious when spread across a sparse
                   2236: line.
                   2237: More work needs to be done with the keep macros, a
                   2238: .Fl line
                   2239: option needs to be added.)
1.1       cgd      2240: .Ss Examples and Displays
1.25      tron     2241: There are six types of displays: a quickie, one-line indented display
                   2242: .Ql \&.D1 ;
                   2243: a quickie, one-line literal display
                   2244: .Ql \&.Dl ;
                   2245: and block-literal, block-filled, block-unfilled, and block-ragged which use
1.1       cgd      2246: the
                   2247: .Ql \&.Bd
                   2248: begin-display
                   2249: and
                   2250: .Ql \&.Ed
                   2251: end-display macros.
                   2252: .Pp
1.4       jtc      2253: .Bl -tag -width \&.Dlxx
1.1       cgd      2254: .It Li \&.D1
                   2255: (D-one) Display one line of indented text.
1.4       jtc      2256: This macro is parsed, but it is not callable.
1.1       cgd      2257: .Pp
1.25      tron     2258: .D1 Fl ldghfstru
1.1       cgd      2259: .Pp
1.4       jtc      2260: The above was produced by:
1.25      tron     2261: .Li \&.D1 \&Fl ldghfstru .
1.1       cgd      2262: .It Li \&.Dl
                   2263: (D-ell)
                   2264: Display one line of indented
                   2265: .Em literal
1.4       jtc      2266: text.
                   2267: The
1.1       cgd      2268: .Ql \&.Dl
                   2269: example macro has been used throughout this
1.4       jtc      2270: file.
                   2271: It allows
1.1       cgd      2272: the indent (display) of one line of text.
                   2273: Its default font is set to
                   2274: constant width (literal) however
1.24      mjl      2275: it is parsed and will recognize other macros.
1.25      tron     2276: It is however not callable.
1.1       cgd      2277: .Pp
1.4       jtc      2278: .Dl % ls -ldg /usr/local/bin
1.1       cgd      2279: .Pp
1.25      tron     2280: The above was produced by:
1.4       jtc      2281: .Li \&.Dl % ls -ldg /usr/local/bin .
1.1       cgd      2282: .It Li \&.Bd
1.4       jtc      2283: Begin-display.
                   2284: The
1.1       cgd      2285: .Ql \&.Bd
                   2286: display must be ended with the
                   2287: .Ql \&.Ed
1.4       jtc      2288: macro.
1.19      ross     2289: Displays may be nested within lists, but may
                   2290: .Em not
                   2291: contain other displays; this also prohibits nesting
1.30      wiz      2292: of
                   2293: .Ql \&.D1
                   2294: and
                   2295: .Ql \&.Dl
                   2296: one-line displays.
1.1       cgd      2297: .Ql \&.Bd
                   2298: has the following syntax:
                   2299: .Pp
1.4       jtc      2300: .Dl ".Bd display-type [-offset offset_value] [-compact]"
1.1       cgd      2301: .Pp
1.25      tron     2302: The display-type must be one of the four types
                   2303: .Fl ( ragged , unfilled , filled , literal )
                   2304: and may have an offset specifier for indentation:
1.1       cgd      2305: .Ql \&.Bd .
                   2306: .Pp
1.4       jtc      2307: .Bl -tag -width "file file_name  " -compact
1.1       cgd      2308: .It Fl ragged
1.20      ross     2309: Fill, but do not adjust the right margin.
                   2310: .It Fl unfilled
                   2311: Do not fill: display a block of text as typed, the
1.1       cgd      2312: right (and left) margin edges are left ragged.
                   2313: .It Fl filled
                   2314: Display a filled (formatted) block.
                   2315: The block of text is formatted (the edges are filled \-
1.4       jtc      2316: not left unjustified).
1.1       cgd      2317: .It Fl literal
                   2318: Display a literal block, useful for source code or
                   2319: simple tabbed or spaced text.
                   2320: .It Fl file Ar file_name
                   2321: The file name following the
                   2322: .Fl file
1.4       jtc      2323: flag is read and displayed.
                   2324: Literal mode is
1.1       cgd      2325: asserted and tabs are set at 8 constant width character
                   2326: intervals, however any
1.30      wiz      2327: .Xr troff 1 Ns / Ns Nm \-mdoc
1.1       cgd      2328: commands in file will be processed.
                   2329: .It Fl offset Ar string
                   2330: If
                   2331: .Fl offset
                   2332: is specified with one of the following strings, the string
                   2333: is interpreted to indicate the level of indentation for the
                   2334: forthcoming block of text:
                   2335: .Pp
1.4       jtc      2336: .Bl -tag -width "indent-two" -compact
1.1       cgd      2337: .It Ar left
                   2338: Align block on the current left margin,
                   2339: this is the default mode of
                   2340: .Ql \&.Bd .
                   2341: .It Ar center
1.4       jtc      2342: Supposedly center the block.
                   2343: At this time
1.1       cgd      2344: unfortunately, the block merely gets
                   2345: left aligned about an imaginary center margin.
                   2346: .It Ar indent
1.4       jtc      2347: Indents by one default indent value or tab.
                   2348: The default
1.1       cgd      2349: indent value is also used for the
                   2350: .Ql \&.D1
1.4       jtc      2351: display so one is guaranteed the two types of displays
                   2352: will line up.
                   2353: This indent is normally set to 6n or about two
1.1       cgd      2354: thirds of an inch (six constant width characters).
                   2355: .It Ar indent-two
                   2356: Indents two times the default indent value.
                   2357: .It Ar right
                   2358: This
                   2359: .Em left
                   2360: aligns the block about two inches from
1.4       jtc      2361: the right side of the page.
                   2362: This macro needs
                   2363: work and perhaps may never do the right thing by
1.30      wiz      2364: .Xr troff 1 .
1.1       cgd      2365: .El
                   2366: .El
1.30      wiz      2367: .It Li ".Ed"
1.1       cgd      2368: End-display.
                   2369: .El
                   2370: .Ss Tagged Lists and Columns
                   2371: There are several types of lists which may be initiated with the
                   2372: .Ql ".Bl"
1.4       jtc      2373: begin-list macro.
                   2374: Items within the list
1.1       cgd      2375: are specified with the
                   2376: .Ql ".It"
                   2377: item macro and
                   2378: each list must end with the
                   2379: .Ql ".El"
1.4       jtc      2380: macro.
1.19      ross     2381: Lists other than
                   2382: .Li \-enum
                   2383: may be nested within themselves and within displays.
                   2384: The use of columns inside of lists or lists inside of columns
1.12      lukem    2385: is unproven.
1.1       cgd      2386: .Pp
                   2387: In addition, several list attributes may be specified such as
1.4       jtc      2388: the width of a tag, the list offset, and compactness
1.1       cgd      2389: (blank lines between items allowed or disallowed).
1.4       jtc      2390: Most of this document has been formatted with a tag style list
                   2391: .Pq Fl tag .
                   2392: For a change of pace, the list-type used to present the list-types
                   2393: is an over-hanging list
                   2394: .Pq Fl ohang .
                   2395: This type of list is quite popular with
                   2396: .Tn TeX
                   2397: users, but might look a bit funny after having read many pages of
                   2398: tagged lists.
1.1       cgd      2399: The following list types are accepted by
1.4       jtc      2400: .Ql ".Bl" :
1.1       cgd      2401: .Pp
                   2402: .Bl -ohang -compact
                   2403: .It Fl bullet
1.11      lukem    2404: .It Fl dash
                   2405: .It Fl enum
                   2406: .It Fl hyphen
1.1       cgd      2407: .It Fl item
1.11      lukem    2408: These five are the simplest types of lists.
1.4       jtc      2409: Once the
1.1       cgd      2410: .Ql ".Bl"
                   2411: macro has been given, items in the list are merely
                   2412: indicated by a line consisting solely of the
                   2413: .Ql ".It"
1.4       jtc      2414: macro.
                   2415: For example, the source text for a simple enumerated list
1.1       cgd      2416: would look like:
                   2417: .Bd -literal -offset indent-two
                   2418: \&.Bl -enum -compact
                   2419: \&.It
                   2420: \&Item one goes here.
                   2421: \&.It
                   2422: \&And item two here.
                   2423: \&.It
                   2424: \&Lastly item three goes here.
                   2425: \&.El
                   2426: .Ed
                   2427: .Pp
                   2428: The results:
                   2429: .Pp
                   2430: .Bl -enum -offset indent-two -compact
                   2431: .It
                   2432: Item one goes here.
                   2433: .It
                   2434: And item two here.
                   2435: .It
                   2436: Lastly item three goes here.
                   2437: .El
                   2438: .Pp
                   2439: A simple bullet list construction:
                   2440: .Bd -literal -offset indent-two
                   2441: \&.Bl -bullet -compact
                   2442: \&.It
                   2443: \&Bullet one goes here.
                   2444: \&.It
                   2445: \&Bullet two here.
                   2446: \&.El
                   2447: .Ed
                   2448: .Pp
                   2449: Produces:
                   2450: .Bl -bullet -offset indent-two -compact
                   2451: .It
                   2452: Bullet one goes here.
                   2453: .It
                   2454: Bullet two here.
                   2455: .El
                   2456: .Pp
1.25      tron     2457: .It Fl inset
1.1       cgd      2458: .It Fl diag
                   2459: .It Fl hang
                   2460: .It Fl ohang
1.25      tron     2461: .It Fl tag
1.1       cgd      2462: These list-types collect arguments specified with the
                   2463: .Ql \&.It
                   2464: macro and create a label which may be
                   2465: .Em inset
1.4       jtc      2466: into the forthcoming text,
1.1       cgd      2467: .Em hanged
1.4       jtc      2468: from the forthcoming text,
1.1       cgd      2469: .Em overhanged
1.4       jtc      2470: from above and not indented or
                   2471: .Em tagged .
                   2472: This
1.1       cgd      2473: list was constructed with the
                   2474: .Ql Fl ohang
1.4       jtc      2475: list-type.
                   2476: The
1.1       cgd      2477: .Ql \&.It
1.4       jtc      2478: macro is parsed only for the inset, hang
                   2479: and tag list-types and is not callable.
1.1       cgd      2480: Here is an example of inset labels:
                   2481: .Bl -inset -offset indent
                   2482: .It Em Tag
                   2483: The tagged list (also called a tagged paragraph) is the
1.36      wiz      2484: most common type of list used in the Berkeley manuals.
                   2485: Use a
1.17      ross     2486: .Fl width
                   2487: attribute as described below.
1.1       cgd      2488: .It Em Diag
                   2489: Diag lists create section four diagnostic lists
                   2490: and are similar to inset lists except callable
                   2491: macros are ignored.
                   2492: .It Em Hang
                   2493: Hanged labels are a matter of taste.
                   2494: .It Em Ohang
1.4       jtc      2495: Overhanging labels are nice when space is constrained.
1.1       cgd      2496: .It Em Inset
                   2497: Inset labels are useful for controlling blocks of
                   2498: paragraphs and are valuable for converting
                   2499: .Nm \-mdoc
                   2500: manuals to other formats.
                   2501: .El
                   2502: .Pp
                   2503: Here is the source text which produced the above example:
                   2504: .Bd -literal -offset indent
                   2505: \&.Bl -inset -offset indent
                   2506: \&.It Em Tag
                   2507: \&The tagged list (also called a tagged paragraph) is the
1.36      wiz      2508: \&most common type of list used in the Berkeley manuals.
                   2509: Use a
1.30      wiz      2510: \&.Fl width
                   2511: \&attribute as described below.
1.1       cgd      2512: \&.It Em Diag
                   2513: \&Diag lists create section four diagnostic lists
                   2514: \&and are similar to inset lists except callable
                   2515: \&macros are ignored.
                   2516: \&.It Em Hang
                   2517: \&Hanged labels are a matter of taste.
                   2518: \&.It Em Ohang
1.4       jtc      2519: \&Overhanging labels are nice when space is constrained.
1.1       cgd      2520: \&.It Em Inset
                   2521: \&Inset labels are useful for controlling blocks of
                   2522: \&paragraphs and are valuable for converting
                   2523: \&.Nm \-mdoc
                   2524: \&manuals to other formats.
                   2525: \&.El
                   2526: .Ed
                   2527: .Pp
1.25      tron     2528: Here is a hanged list with just two items:
1.1       cgd      2529: .Bl -hang -offset indent
                   2530: .It Em Hanged
                   2531: labels appear similar to tagged lists when the
                   2532: label is smaller than the label width.
                   2533: .It Em Longer hanged list labels
                   2534: blend in to the paragraph unlike
                   2535: tagged paragraph labels.
                   2536: .El
                   2537: .Pp
1.4       jtc      2538: And the unformatted text which created it:
1.1       cgd      2539: .Bd -literal -offset indent
                   2540: \&.Bl -hang -offset indent
                   2541: \&.It Em Hanged
                   2542: \&labels appear similar to tagged lists when the
                   2543: \&label is smaller than the label width.
                   2544: \&.It Em Longer hanged list labels
                   2545: \&blend in to the paragraph unlike
                   2546: \&tagged paragraph labels.
                   2547: \&.El
                   2548: .Ed
                   2549: .Pp
1.17      ross     2550: The tagged list which follows uses a width specifier to control
1.1       cgd      2551: the width of the tag.
                   2552: .Pp
1.4       jtc      2553: .Bl -tag -width "PAGEIN" -compact -offset indent
                   2554: .It SL
1.1       cgd      2555: sleep time of the process (seconds blocked)
1.4       jtc      2556: .It PAGEIN
                   2557: number of disk
                   2558: .Tn I/O Ns 's
                   2559: resulting from references
1.1       cgd      2560: by the process to pages not loaded in core.
1.4       jtc      2561: .It UID
1.1       cgd      2562: numerical user-id of process owner
1.4       jtc      2563: .It PPID
1.41      rumble   2564: numerical id of parent of process priority
1.1       cgd      2565: (non-positive when in non-interruptible wait)
                   2566: .El
                   2567: .Pp
                   2568: The raw text:
                   2569: .Bd -literal -offset indent
1.4       jtc      2570: \&.Bl -tag -width "PAGEIN" -compact -offset indent
                   2571: \&.It SL
1.1       cgd      2572: \&sleep time of the process (seconds blocked)
1.4       jtc      2573: \&.It PAGEIN
                   2574: \&number of disk
                   2575: \&.Tn I/O Ns 's
                   2576: \&resulting from references
1.1       cgd      2577: \&by the process to pages not loaded in core.
1.4       jtc      2578: \&.It UID
1.1       cgd      2579: \&numerical user-id of process owner
1.4       jtc      2580: \&.It PPID
1.41      rumble   2581: \&numerical id of parent of process priority
1.1       cgd      2582: \&(non-positive when in non-interruptible wait)
                   2583: \&.El
                   2584: .Ed
                   2585: .Pp
                   2586: Acceptable width specifiers:
                   2587: .Bl -tag -width Ar -offset indent
                   2588: .It Fl width Ar "\&Fl"
1.4       jtc      2589: sets the width to the default width for a flag.
                   2590: All callable
                   2591: macros have a default width value.
                   2592: The
1.1       cgd      2593: .Ql \&.Fl ,
                   2594: value is presently
                   2595: set to ten constant width characters or about five sixth of
                   2596: an inch.
                   2597: .It Fl width Ar "24n"
                   2598: sets the width to 24 constant width characters or about two
1.4       jtc      2599: inches.
                   2600: The
1.1       cgd      2601: .Ql n
                   2602: is absolutely necessary for the scaling to work correctly.
                   2603: .It Fl width Ar "ENAMETOOLONG"
                   2604: sets width to the constant width length of the
                   2605: string given.
                   2606: .It Fl width  Ar "\\*qint mkfifo\\*q"
                   2607: again, the width is set to the constant width of the string
                   2608: given.
                   2609: .El
                   2610: .Pp
                   2611: If a width is not specified for the tag list type, the first
                   2612: time
                   2613: .Ql \&.It
                   2614: is invoked, an attempt is made to determine an appropriate
1.4       jtc      2615: width.
                   2616: If the first argument to
1.1       cgd      2617: .Ql ".It"
                   2618: is a callable macro, the default width for that macro will be used
1.4       jtc      2619: as if the macro name had been supplied as the width.
                   2620: However,
1.1       cgd      2621: if another item in the list is given with a different callable
1.36      wiz      2622: macro name, a new and nested list is assumed.
                   2623: This effectively means that
1.17      ross     2624: .Fl width
                   2625: is required for the tag list type.
1.12      lukem    2626: .Pp
                   2627: .It Fl column
                   2628: This list type generates multiple columns.
                   2629: The number of columns and the width of each column is determined by
                   2630: the arguments to the
                   2631: .Fl column
                   2632: list.
                   2633: Each
                   2634: .Ql ".It"
                   2635: argument is parsed to make a row, each column within the
                   2636: row is a separate argument separated by a tab or the
                   2637: .Ql ".Ta"
                   2638: macro.
                   2639: .El
                   2640: The table:
                   2641: .Bl -column "String" "Nroff" "Troff" -offset indent
                   2642: .It Sy "String" Ta Sy "Nroff" Ta Sy "Troff"
1.33      ross     2643: .It Li "\*[Le]" Ta \&\*[Lt]\&= Ta \*[Le]
                   2644: .It Li "\*[Ge]" Ta \&\*[Gt]\&= Ta \*[Ge]
1.12      lukem    2645: .El
                   2646: .Pp
                   2647: was produced by:
                   2648: .Bd -literal -offset indent
                   2649: \&.Bl -column "String" "Nroff" "Troff" -offset indent
                   2650: \&.It Sy "String" Ta Sy "Nroff" Ta Sy "Troff"
1.33      ross     2651: \&.It Li "\*[Le]" Ta \e\*[Am]\*[Lt]\e\*[Am]= Ta \e*(\*[Le]
                   2652: \&.It Li "\*[Ge]" Ta \e\*[Am]\*[Gt]\e\*[Am]= Ta \e*(\*[Ge]
1.12      lukem    2653: \&.El
                   2654: .Ed
1.4       jtc      2655: .Sh PREDEFINED STRINGS
1.24      mjl      2656: The following strings are predefined and may be used by
1.4       jtc      2657: preceding with the troff string interpreting sequence
                   2658: .Ql \&\e*(xx
                   2659: where
                   2660: .Em xx
                   2661: is the name of the defined string or as
                   2662: .Ql \&\e*x
                   2663: where
                   2664: .Em x
                   2665: is the name of the string.
                   2666: The interpreting sequence may be used any where in the text.
                   2667: .Pp
                   2668: .Bl -column "String " "Nroff " "Troff " -offset indent
                   2669: .It Sy "String Nroff   Troff"
1.33      ross     2670: .It Li "\*[Le]" Ta \&\*[Lt]\&= Ta \*[Le]
                   2671: .It Li "\*[Ge]" Ta \&\*[Gt]\&= Ta \*[Ge]
1.4       jtc      2672: .It Li "Rq" Ta "''" Ta \*(Rq
                   2673: .It Li "Lq" Ta "``" Ta \*(Lq
                   2674: .It Li "ua" Ta ^ Ta \*(ua
                   2675: .It Li "aa" Ta ' Ta \*(aa
                   2676: .It Li "ga" Ta \` Ta \*(ga
                   2677: .\" .It Li "sL" Ta ` Ta \*(sL
                   2678: .\" .It Li "sR" Ta ' Ta \*(sR
                   2679: .It Li "q" Ta \&" Ta \*q
                   2680: .It Li "Pi" Ta pi Ta \*(Pi
                   2681: .It Li "Ne" Ta != Ta \*(Ne
1.33      ross     2682: .It Li "Le" Ta \*[Le] Ta \*(Le
                   2683: .It Li "Ge" Ta \*[Ge] Ta \*(Ge
                   2684: .It Li "Lt" Ta \*[Lt] Ta \*(Gt
                   2685: .It Li "Gt" Ta \*[Gt] Ta \*(Lt
1.4       jtc      2686: .It Li "Pm" Ta +- Ta \*(Pm
                   2687: .It Li "If" Ta infinity Ta \*(If
                   2688: .It Li "Na" Ta \fINaN\fP Ta \*(Na
                   2689: .It Li "Ba" Ta \fR\&|\fP Ta \*(Ba
                   2690: .El
                   2691: .Pp
                   2692: .Sy Note :
                   2693: The string named
                   2694: .Ql q
                   2695: should be written as
                   2696: .Ql \e*q
                   2697: since it is only one char.
1.1       cgd      2698: .Sh DIAGNOSTICS
                   2699: The debugging facilities for
                   2700: .Nm \-mdoc
                   2701: are limited, but can help detect subtle errors such
                   2702: as the collision of an argument name with an internal
1.4       jtc      2703: register or macro name.
                   2704: (A what?)
1.1       cgd      2705: A register is an arithmetic storage class for
1.30      wiz      2706: .Xr troff 1
1.1       cgd      2707: with a one or two character name.
                   2708: All registers internal to
                   2709: .Nm \-mdoc
                   2710: for
1.30      wiz      2711: .Xr troff 1
1.1       cgd      2712: and
1.30      wiz      2713: .Ic ditroff
1.1       cgd      2714: are two characters and
1.33      ross     2715: of the form \*[Lt]upper_case\*[Gt]\*[Lt]lower_case\*[Gt] such as
1.1       cgd      2716: .Ql \&Ar ,
1.33      ross     2717: \*[Lt]lower_case\*[Gt]\*[Lt]upper_case\*[Gt] as
1.1       cgd      2718: .Ql \&aR
                   2719: or
1.33      ross     2720: \*[Lt]upper or lower letter\*[Gt]\*[Lt]digit\*[Gt] as
1.1       cgd      2721: .Ql \&C\&1 .
                   2722: And adding to the muddle,
1.30      wiz      2723: .Xr troff 1
1.1       cgd      2724: has its own internal registers all of which are either
1.4       jtc      2725: two lower case characters or a dot plus a letter or meta-character
1.1       cgd      2726: character.
                   2727: In one of the introduction examples, it was shown how to
                   2728: prevent the interpretation of a macro name with the escape sequence
1.33      ross     2729: .Ql \e\*[Am] .
1.1       cgd      2730: This is sufficient for the internal register names also.
                   2731: .Pp
                   2732: .\" Every callable macro name has a corresponding register
1.4       jtc      2733: .\" of the same name (<upper_case><lower_case>).
1.1       cgd      2734: .\" There are also specific registers which have
                   2735: .\" been used for stacks and arrays and are listed in the
                   2736: .\" .Sx Appendix .
                   2737: .\" .Bd -ragged -offset 4n
                   2738: .\" [A-Z][a-z] registers corresponding to macro names (example ``Ar'')
                   2739: .\" [a-z][A-Z] registers corresponding to macro names (example ``aR'')
                   2740: .\" C[0-9]             argument types (example C1)
                   2741: .\" O[0-9]             offset stack (displays)
                   2742: .\" h[0-9]             horizontal spacing stack (lists)
                   2743: .\" o[0-9]             offset (stack) (lists)
                   2744: .\" t[0-9]             tag stack (lists)
                   2745: .\" v[0-9]             vertical spacing stack (lists)
                   2746: .\" w[0-9]             width tag/label stack
                   2747: .\" .Ed
                   2748: .\" .Pp
                   2749: If a non-escaped register name is given in the argument list of a request
1.4       jtc      2750: unpredictable behavior will occur.
                   2751: In general, any time huge portions
1.1       cgd      2752: of text do not appear where expected in the output, or small strings
                   2753: such as list tags disappear, chances are there is a misunderstanding
                   2754: about an argument type in the argument list.
                   2755: Your mother never intended for you to remember this evil stuff - so here
                   2756: is a way to find out whether or not your arguments are valid: The
                   2757: .Ql \&.Db
                   2758: (debug)
                   2759: macro displays the interpretation of the argument list for most
1.4       jtc      2760: macros.
                   2761: Macros such as the
1.1       cgd      2762: .Ql \&.Pp
                   2763: (paragraph)
1.4       jtc      2764: macro do not contain debugging information.
                   2765: All of the callable macros do,
1.1       cgd      2766: and it is strongly advised whenever in doubt,
                   2767: turn on the
                   2768: .Ql \&.Db
                   2769: macro.
                   2770: .Pp
                   2771: .Dl Usage: \&.Db [on | off]
                   2772: .Pp
                   2773: An example of a portion of text with
                   2774: the debug macro placed above and below an
                   2775: artificially created problem (a flag argument
                   2776: .Ql \&aC
                   2777: which should be
1.33      ross     2778: .Ql \e\*[Am]aC
1.1       cgd      2779: in order to work):
                   2780: .Bd -literal -offset indent
                   2781: \&.Db on
                   2782: \&.Op Fl aC Ar file )
                   2783: \&.Db off
                   2784: .Ed
                   2785: .Pp
                   2786: The resulting output:
                   2787: .Bd -literal -offset indent
                   2788: DEBUGGING ON
                   2789: DEBUG(argv) MACRO: `.Op'  Line #: 2
                   2790:        Argc: 1  Argv: `Fl'  Length: 2
                   2791:        Space: `'  Class: Executable
                   2792:        Argc: 2  Argv: `aC'  Length: 2
                   2793:        Space: `'  Class: Executable
                   2794:        Argc: 3  Argv: `Ar'  Length: 2
                   2795:        Space: `'  Class: Executable
                   2796:        Argc: 4  Argv: `file'  Length: 4
                   2797:        Space: ` '  Class: String
                   2798:        Argc: 5  Argv: `)'  Length: 1
                   2799:        Space: ` '  Class: Closing Punctuation or suffix
                   2800:        MACRO REQUEST: .Op Fl aC Ar file )
                   2801: DEBUGGING OFF
                   2802: .Ed
                   2803: .Pp
                   2804: The first line of information tells the name of the calling
                   2805: macro, here
                   2806: .Ql \&.Op ,
1.4       jtc      2807: and the line number it appears on.
                   2808: If one or more files are involved
1.1       cgd      2809: (especially if text from another file is included) the line number
1.4       jtc      2810: may be bogus.
                   2811: If there is only one file, it should be accurate.
1.1       cgd      2812: The second line gives the argument count, the argument
1.30      wiz      2813: .Pq Li \&Fl
1.4       jtc      2814: and its length.
                   2815: If the length of an argument is two characters, the
1.1       cgd      2816: argument is tested to see if it is executable (unfortunately, any
                   2817: register which contains a non-zero value appears executable).
                   2818: The third line gives the space allotted for a class, and the
1.4       jtc      2819: class type.
1.30      wiz      2820: The problem here is the argument
                   2821: .Ql \&aC
                   2822: should not be executable.
1.4       jtc      2823: The four types of classes are string, executable, closing
                   2824: punctuation and opening punctuation.
                   2825: The last line shows the entire
                   2826: argument list as it was read.
                   2827: In this next example, the offending
1.1       cgd      2828: .Ql \&aC
                   2829: is escaped:
                   2830: .Bd -literal -offset indent
                   2831: \&.Db on
1.33      ross     2832: \&.Em An escaped \e\*[Am]aC
1.1       cgd      2833: \&.Db off
                   2834: .Ed
                   2835: .Bd -literal -offset indent
                   2836: DEBUGGING ON
                   2837: DEBUG(fargv) MACRO: `.Em'  Line #: 2
                   2838:        Argc: 1  Argv: `An'  Length: 2
                   2839:        Space: ` '  Class: String
                   2840:        Argc: 2  Argv: `escaped'  Length: 7
                   2841:        Space: ` '  Class: String
                   2842:        Argc: 3  Argv: `aC'  Length: 2
                   2843:        Space: ` '  Class: String
1.33      ross     2844:        MACRO REQUEST: .Em An escaped \*[Am]aC
1.1       cgd      2845: DEBUGGING OFF
                   2846: .Ed
                   2847: .Pp
                   2848: The argument
1.33      ross     2849: .Ql \e\*[Am]aC
1.1       cgd      2850: shows up with the same length of 2 as the
1.33      ross     2851: .Ql \e\*[Am]
1.1       cgd      2852: sequence produces a zero width, but a register
                   2853: named
1.33      ross     2854: .Ql \e\*[Am]aC
1.1       cgd      2855: was not found and the type classified as string.
                   2856: .Pp
                   2857: Other diagnostics consist of usage statements and are self explanatory.
1.4       jtc      2858: .Sh GROFF, TROFF AND NROFF
                   2859: The
                   2860: .Nm \-mdoc
                   2861: package does not need compatibility mode with
1.30      wiz      2862: .Xr groff 1 .
1.4       jtc      2863: .Pp
                   2864: The package inhibits page breaks, and the headers and footers
                   2865: which normally occur at those breaks with
1.30      wiz      2866: .Xr nroff 1 ,
1.4       jtc      2867: to make the manual more efficient for viewing on-line.
                   2868: At the moment,
1.30      wiz      2869: .Xr groff 1
1.4       jtc      2870: with
                   2871: .Fl T Ns Ar ascii
                   2872: does eject the imaginary remainder of the page at end of file.
                   2873: The inhibiting of the page breaks makes
1.30      wiz      2874: .Xr nroff 1 Ns 'd
1.4       jtc      2875: files unsuitable for hardcopy.
                   2876: There is a register named
                   2877: .Ql \&cR
                   2878: which can be set to zero in the site dependent style file
                   2879: .Pa /usr/src/share/tmac/doc-nroff
                   2880: to restore the old style behavior.
1.1       cgd      2881: .Sh FILES
1.5       jtc      2882: .Bl -tag -width /usr/share/misc/mdoc.template -compact
1.1       cgd      2883: .It Pa /usr/share/tmac/tmac.doc
                   2884: manual macro package
1.5       jtc      2885: .It Pa /usr/share/misc/mdoc.template
1.1       cgd      2886: template for writing a man page
                   2887: .El
                   2888: .Sh SEE ALSO
                   2889: .Xr man 1 ,
1.26      enami    2890: .Xr troff 1 ,
                   2891: .Xr mdoc 7
1.1       cgd      2892: .Sh BUGS
                   2893: Undesirable hyphenation on the dash of a flag
                   2894: argument is not yet resolved, and causes
1.4       jtc      2895: occasional mishaps in the
                   2896: .Sx DESCRIPTION
                   2897: section.
1.1       cgd      2898: (line break on the hyphen).
                   2899: .Pp
                   2900: Predefined strings are not declared in documentation.
                   2901: .Pp
                   2902: Section 3f has not been added to the header routines.
                   2903: .Pp
                   2904: .Ql \&.Nm
1.4       jtc      2905: font should be changed in
                   2906: .Sx NAME
                   2907: section.
1.1       cgd      2908: .Pp
                   2909: .Ql \&.Fn
                   2910: needs to have a check to prevent splitting up
1.4       jtc      2911: if the line length is too short.
                   2912: Occasionally it
1.1       cgd      2913: separates the last parenthesis, and sometimes
                   2914: looks ridiculous if a line is in fill mode.
                   2915: .Pp
                   2916: The method used to prevent header and footer page
                   2917: breaks (other than the initial header and footer) when using
1.30      wiz      2918: .Xr nroff 1
1.25      tron     2919: occasionally places an unsightly partially filled line (blank)
1.4       jtc      2920: at the would be bottom of the page.
1.12      lukem    2921: .Pp
                   2922: If the outer-most list definition doesn't have a
                   2923: .Fl width
                   2924: argument, the
                   2925: .Ql ".It"
                   2926: elements of inner lists may not work (producing a list where
                   2927: each successive element
                   2928: .Sq walks
                   2929: to the right).
1.1       cgd      2930: .Pp
                   2931: The list and display macros to not do any keeps
                   2932: and certainly should be able to.
1.4       jtc      2933: .\" Note what happens if the parameter list overlaps a newline
                   2934: .\" boundary.
                   2935: .\" to make sure a line boundary is crossed:
                   2936: .\" .Bd -literal
                   2937: .\" \&.Fn struct\e\ dictionarytable\e\ *dictionarylookup struct\e\ dictionarytable\e\ *tab[]
                   2938: .\" .Ed
                   2939: .\" .Pp
                   2940: .\" produces, nudge nudge,
                   2941: .\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] ,
                   2942: .\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] ,
                   2943: .\" nudge
                   2944: .\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] .
                   2945: .\" .Pp
                   2946: .\" If double quotes are used, for example:
                   2947: .\" .Bd -literal
                   2948: .\" \&.Fn \*qstruct dictionarytable *dictionarylookup\*q \*qchar *h\*q \*qstruct dictionarytable *tab[]\*q
                   2949: .\" .Ed
                   2950: .\" .Pp
                   2951: .\" produces, nudge nudge,
                   2952: .\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" ,
                   2953: .\" nudge
                   2954: .\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" ,
                   2955: .\" nudge
                   2956: .\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" .
                   2957: .\" .Pp
                   2958: .\" Not a pretty sight...
                   2959: .\" In a paragraph, a long parameter containing unpaddable spaces as
                   2960: .\" in the former example will cause
1.30      wiz      2961: .\" .Xr troff 1
1.4       jtc      2962: .\" to break the line and spread
                   2963: .\" the remaining words out.
                   2964: .\" The latter example will adjust nicely to
                   2965: .\" justified margins, but may break in between an argument and its
                   2966: .\" declaration.
                   2967: .\" In
1.30      wiz      2968: .\" .Xr nroff 1
1.4       jtc      2969: .\" the right margin adjustment is normally ragged and the problem is
                   2970: .\" not as severe.

CVSweb <webmaster@jp.NetBSD.org>