Return to mdoc.samples.7 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / share / man / man7

Annotation of 43BSDReno/share/man/man7/mdoc.samples.7, revision 1.1

1.1     ! root        1: .\" Copyright (c) 1990 The Regents of the University of California.
        !             2: .\" All rights reserved.
        !             3: .\"
        !             4: .\" Redistribution and use in source and binary forms are permitted provided
        !             5: .\" that: (1) source distributions retain this entire copyright notice and
        !             6: .\" comment, and (2) distributions including binaries display the following
        !             7: .\" acknowledgement:  ``This product includes software developed by the
        !             8: .\" University of California, Berkeley and its contributors'' in the
        !             9: .\" documentation or other materials provided with the distribution and in
        !            10: .\" all advertising materials mentioning features or use of this software.
        !            11: .\" Neither the name of the University nor the names of its contributors may
        !            12: .\" be used to endorse or promote products derived from this software without
        !            13: .\" specific prior written permission.
        !            14: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
        !            15: .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
        !            16: .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
        !            17: .\"
        !            18: .\"     @(#)mdoc.samples.7     5.2 (Berkeley) 6/22/90
        !            19: .\"
        !            20: .\"    This sampler invokes every macro in the package several
        !            21: .\"    times and is garanteed to give a worst case performance
        !            22: .\"    for an already slow package.
        !            23: .Dd June 22, 1990
        !            24: .Os BSD 4.4
        !            25: .Dt MDOC.SAMPLES 7
        !            26: .Sh NAME
        !            27: .Nm mdoc.sample
        !            28: .Nd detailed samples utilizing
        !            29: the
        !            30: .Nm -mdoc
        !            31: macro package
        !            32: .Sh SYNOPSIS
        !            33: .Nm man mdoc.sample
        !            34: .Sh DESCRIPTION
        !            35: A fairly complete sampler of how the
        !            36: .Nm \-mdoc
        !            37: macro package is used.
        !            38: .Sh TROFF IDIOSYNCRASIES
        !            39: Although this is a content based formatting package, and
        !            40: theoretically one should not have to learn
        !            41: .Xr troff 1
        !            42: to use it, there are a few
        !            43: limitations which are unavoidable and best gotten out
        !            44: of the way. And, too, be forewarned, this package is slow.
        !            45: Its purpose is to allow translation of man pages from
        !            46: .Xr troff 1
        !            47: to
        !            48: .Xr TeX Coming\ Soon
        !            49: and vice versa.
        !            50: .Ss Macro Usage
        !            51: As in
        !            52: .Xr troff 1 ,
        !            53: a macro (request) is called by placing a
        !            54: .Li \&\.
        !            55: (dot character)
        !            56: at the beginning of
        !            57: a line followed by the two character name for the macro.
        !            58: Arguments may follow the request separated by spaces.
        !            59: It is the dot character at the beginning of the line which causes
        !            60: .Xr troff 1
        !            61: to interpret the next two characters as a request.
        !            62: To place a
        !            63: .Li \&\.
        !            64: (dot character)
        !            65: at the beginning of a line in some context other than
        !            66: a macro request, precede the
        !            67: .Li \&\.
        !            68: (dot) with a
        !            69: .Li \e&.
        !            70: In this macro package, some macros may be given the
        !            71: name of another macro as an argument. In this case
        !            72: the argument, although the name of a macro,
        !            73: is not preceded by a
        !            74: .Li \&\.
        !            75: (dot),
        !            76: and will be executed
        !            77: with the remaining arguments.
        !            78: It is in this manner that some requests are nested, such
        !            79: as the
        !            80: .Li \&.Op
        !            81: request may
        !            82: .Em call
        !            83: the flag request
        !            84: .Li \&.Fl .
        !            85: .Dp Op Fl ls
        !            86: is produced by
        !            87: .Li \&.Op Fl ls
        !            88: .Dp
        !            89: The only requests which check to see if the first argument
        !            90: is executable are:
        !            91: .Ds I
        !            92: .Cw \&.Cx\ Complex\ Expressions
        !            93: .Cl \&.Cl\ Column Line Entry   \&.Dp Display Examples (tagged paragraph)
        !            94: .Cl \&.Cx\ Complex\ Expressions        \&.Op\ Option Request
        !            95: .Cl \&.Dl\ Display (one) Line  \&.Sq Single Quotes
        !            96: .Cl \&.Dq\ Double Quotes       \&.Tp Tagged Paragraphs
        !            97: .Cw
        !            98: .De
        !            99: .Pp
        !           100: The eligible first arguments are:
        !           101: .Ds I
        !           102: .Cw \&.Cx\ Complex\ Expressions
        !           103: .Cl \&.Ad Addresses    \&.Fn Functions
        !           104: .Cl \&.Ar Arguments    \&.Ic Interactive Commands
        !           105: .Cl \&.Cl Column Entries       \&.Li Literals
        !           106: .Cl \&.Cm Command Modifiers    \&.Nm Names, subjects
        !           107: .Cl \&.Cw Column Widths        \&.Op Options
        !           108: .Cl \&.Cx Complex Expressions  \&.Pa Pathnames
        !           109: .Cl \&.Em Emphasis     \&.Sy Symbolic
        !           110: .Cl \&.Er Errno's      \&.Tp Tagged Paragraphs
        !           111: .Cl \&.Ev Environment  \&.Va Variables
        !           112: .Cl \&.Fl Flags        \&.Xr Cross References
        !           113: .Cw
        !           114: .De
        !           115: .Pp
        !           116: Requests which cannot be called, or call any other macro:
        !           117: .Ds I
        !           118: .Cw \&.Cx\ Complex\ Expressions
        !           119: .Cl \&.Di Display Indent       \&.Dw Display Tag Width
        !           120: .Cl \&.De Display End  \&.Pp Paragraph Start
        !           121: .Cl \&.Df Display Filled       \&.Tw Tagged Paragraph Tag Width
        !           122: .Cl \&.Df Display unfilled
        !           123: .Cw
        !           124: .De
        !           125: .Pp
        !           126: The macro
        !           127: .Li .Op
        !           128: is unusual that it can call more than one request on the same
        !           129: line.
        !           130: .Ss Passing Space Characters in an Argument
        !           131: To pass an argument
        !           132: to a macro request which contains spaces, the space must be preceded
        !           133: by a
        !           134: .Li \e
        !           135: to escape special interpretation:
        !           136: .Dw int\ *fetch()
        !           137: .Dp Fn int\ *fetch
        !           138: is created by
        !           139: .Li \&.Fn int\e *fetch
        !           140: .Dp
        !           141: For critical spaces at the end of a line, as might be needed
        !           142: with the request
        !           143: .Li \&.Cx ,
        !           144: following the space with
        !           145: .Li \e&
        !           146: is a good guarantee the space will not be stripped (e.g.
        !           147: .Li \e \e&) .
        !           148: A blank space at the end of a line is otherwise an open invitation
        !           149: to party for
        !           150: .Xr troff 1 .
        !           151: .Ss Escaping Special Characters
        !           152: Special characters
        !           153: like the newline character
        !           154: .Li \en ,
        !           155: are handled by replacing the
        !           156: .Li \e
        !           157: with
        !           158: .Li \ee
        !           159: (e.g.
        !           160: .Li \een )
        !           161: to preserve
        !           162: the backslash.
        !           163: .Sh HEADER REQUESTS
        !           164: Three header macros designate the document title or manual page title,
        !           165: the operating system,
        !           166: and the date of authorship (if not derived from
        !           167: .Xr sccs 1
        !           168: or
        !           169: .Xr rcs 1 ) .
        !           170: These macros are one called once at the very beginning of the document
        !           171: and are used to construct the headers and footers only.
        !           172: .Tp Li \&.Dt DOCUMENT_TITLE section# [volume]
        !           173: The document title is the
        !           174: subject of the man page and must be in CAPITALS due to troff
        !           175: limitations.
        !           176: The section number may be 1,...,8,
        !           177: and if it is specified,
        !           178: the volume title may be omitted.
        !           179: A volume title may be arbitrary or one of the following:
        !           180: .\" .Cl
        !           181: .\" USD        UNIX User's Supplementary Documents
        !           182: .\" .Cl
        !           183: .\" PS1        UNIX Programmers's Supplementary Documents
        !           184: .Cw SMM
        !           185: .Cl AMD        UNIX Ancestral Manual Documents
        !           186: .Cl SMM        UNIX System Manager's Manual
        !           187: .Cl URM        UNIX Reference Manual
        !           188: .Cl PRM        UNIX Programmers's Manual
        !           189: .Cw
        !           190: .\" .Cl
        !           191: .\" MMI        UNIX Manual Master Index
        !           192: .\" .Cl
        !           193: .\" CON        UNIX Contributed Software Manual
        !           194: .\" .Cl
        !           195: .\" LOC        UNIX Local Manual
        !           196: .Tp Li \&.Os operating_system release#
        !           197: The name of the operating system
        !           198: should be the common acronym, e.g. BSD
        !           199: or ATT.  The release should be the standard release
        !           200: nomenclature for the system specified, e.g. 4.3, 4.3+tahoe, V.3,
        !           201: V.4. Unrecognized arguments are displayed as given in the page footer.
        !           202: For instance, for the footer on this page, the 4.4 Berkeley Distribution
        !           203: was produced by:
        !           204: .Pp
        !           205: .Dl Li \&.Os BSD 4.4
        !           206: .Tp Li \&.Dd month day, year
        !           207: The date should be written formally:
        !           208: .Pp
        !           209: .Dl January 25, 1989
        !           210: .\" June 22, 1990 is not a standard SCCS id-key. ??
        !           211: .Tp
        !           212: .Sh TEXT MACROS
        !           213: The following macro requests have similar
        !           214: syntax; the exceptions being the behaviour of the
        !           215: request if called without an argument, and the
        !           216: behaviour of the requests
        !           217: .Li \&.Fn ,
        !           218: .Li \&.Pa ,
        !           219: and
        !           220: .Li \&.Xr ,
        !           221: which expect a specific format.
        !           222: The other requests can handle up to 9 arguments
        !           223: and will format punctuation properly as
        !           224: long as the punctuation is placed in the last
        !           225: arguments.  Punctuation placed in the middle
        !           226: of a string of text arguments will result
        !           227: in a out of place space character.
        !           228: .Pp
        !           229: Any argument which may be tested for punctuation
        !           230: and contains a member of the mathematical, logical or
        !           231: quotation
        !           232: set
        !           233: {+,\-,/,*,%,<,>,<=,>=,=,==,&,`,',"}
        !           234: should have
        !           235: the character escaped.
        !           236: .Pp
        !           237: .Ss Address Request
        !           238: The address request constructs and address
        !           239: of the form addr1[,addr2[,addr3]].
        !           240: .Pp
        !           241: .Dl \&.Ad Usage: .Ad address ... \*(Pu
        !           242: .Dw \&.Ad\ f1\ ,\ f2\ ,\ f3\ :
        !           243: .Dp Li \&.Ad addr1
        !           244: .Ad addr1
        !           245: .Dp Li \&.Ad addr1\ .
        !           246: .Ad addr1 .
        !           247: .Dp Li \&.Ad addr1\ , file2
        !           248: .Ad addr1 , file2
        !           249: .Dp Li \&.Ad f1\ , f2\ , f3\ :
        !           250: .Ad f1 , f2 , f3 :
        !           251: .Dp Li \&.Ad addr\ )\ )\ ,
        !           252: .Ad addr ) ) ,
        !           253: .Dp
        !           254: It is an error to call
        !           255: .Li \&.Ad
        !           256: without arguments.
        !           257: The request may be called by
        !           258: .Li \&.Cl ,
        !           259: .Li \&.Cx ,
        !           260: .Li \&.Dl ,
        !           261: .Li \&.Dp ,
        !           262: .Li \&.Op
        !           263: or
        !           264: .Li \&.Tp .
        !           265: .Ss Argument Request
        !           266: The
        !           267: .Li \&.Ar
        !           268: argument request may be used whenever
        !           269: a command line argument is referenced.
        !           270: .Pp
        !           271: .Dl Usage: .Ar argument ... \*(Pu
        !           272: .Dw Tx
        !           273: .Dp Li \&.Ar
        !           274: .Ar
        !           275: .Dp Li \&.Ar file1
        !           276: .Ar file1
        !           277: .Dp Li \&.Ar file1\ .
        !           278: .Ar file1 .
        !           279: .Dp Li \&.Ar file1 file2
        !           280: .Ar file1 file2
        !           281: .Dp Li \&.Ar f1 f2 f3\ :
        !           282: .Ar f1 f2 f3 :
        !           283: .Dp Li \&.Ar file\ )\ )\ ,
        !           284: .Ar file ) ) ,
        !           285: .Dp
        !           286: .Pp
        !           287: If
        !           288: .Li \&.Ar
        !           289: is called with no arguments
        !           290: .Ar
        !           291: is assumed. The
        !           292: .Li \&.Ar
        !           293: request cannot call other macros, but may
        !           294: be called by
        !           295: .Li \&.Cl ,
        !           296: .Li \&.Cx ,
        !           297: .Li \&.Dl ,
        !           298: .Li \&.Dp ,
        !           299: .Li \&.Op
        !           300: or
        !           301: .Li \&.Tp .
        !           302: See the
        !           303: .Li \&.Op
        !           304: request for an example of using
        !           305: .Li \&.Ar
        !           306: in combination with the
        !           307: .Li \&.Fl
        !           308: request.
        !           309: .Ss Double Quote Request
        !           310: The
        !           311: .Li \&.Dq
        !           312: double quote request may be used to surround
        !           313: a string with double quotes. Punctuation is
        !           314: placed after the edn quote.  To place punctuation
        !           315: in inside the quotes it must be escaped with
        !           316: .Li \&\e& .
        !           317: .Pp
        !           318: .Dl Usage: .Dq string ... \*(Pu
        !           319: .Dw \&.Dq\ fools\ and\ follies
        !           320: .Dp Li \&.Dq
        !           321: .Dq
        !           322: .Dp Li \&.Dq string
        !           323: .Dq string
        !           324: .Dp Li \&.Dq string\ .
        !           325: .Dq string .
        !           326: .Dp Li \&.Dq fools and follies
        !           327: .Dq fools and follies
        !           328: .Dp Li \&.Dq Ar pattern\ )\ )\ ,
        !           329: .Dq Ar pattern ) ) ,
        !           330: .Dp
        !           331: .Pp
        !           332: If
        !           333: .Li \&.Dq
        !           334: is called with no arguments
        !           335: .Dq
        !           336: is assumed. The
        !           337: .Li \&.Dq
        !           338: request may call or be called by
        !           339: .Li \&.Cl ,
        !           340: .Li \&.Cx ,
        !           341: .Li \&.Dl ,
        !           342: .Li \&.Dp ,
        !           343: .Li \&.Op
        !           344: .Li \&.Sq ,
        !           345: or
        !           346: .Li \&.Tp .
        !           347: .Pp
        !           348: The
        !           349: .Li \&.Sq
        !           350: provides single quotes
        !           351: in the same manner as
        !           352: .Li \&.Dq .
        !           353: Neither request can nest with in itself, but
        !           354: .Li \&.Dq
        !           355: and
        !           356: .Li \&.Sq
        !           357: can be nested with in each other.
        !           358: .Ss Emphasis Request
        !           359: A portion of text may be stressed or emphasized with the .Em
        !           360: request.  The font used is commonly italic.
        !           361: .Pp
        !           362: .Dl Usage: .Em argument ... \*(Pu
        !           363: .Dw \&.Em\ vide\ infra\ )\ )\ ,
        !           364: .Dp Li \&.Em does not
        !           365: .Em does not
        !           366: .Dp Li \&.Em exceed 1024\ .
        !           367: .Em exceed 1024 .
        !           368: .Dp Li \&.Em vide infra\ )\ )\ ,
        !           369: .Em vide infra ) ) ,
        !           370: .Dp
        !           371: .Pp
        !           372: It is an error to call
        !           373: .Li \&.Em
        !           374: without arguments.
        !           375: The request cannot call other macros, but
        !           376: may be invoked by
        !           377: .Li \&.Cl ,
        !           378: .Li \&.Cx ,
        !           379: .Li \&.Dl ,
        !           380: .Li \&.Dp ,
        !           381: .Li \&.Op
        !           382: or
        !           383: .Li \&.Tp .
        !           384: .Ss Errno's (Section's two and three only)
        !           385: The
        !           386: .Li \&.Er
        !           387: errno request specifies the error return value
        !           388: for section two and three library routines. The second example
        !           389: below shows
        !           390: .Li \&.Er
        !           391: used with the
        !           392: .Li \&.Op
        !           393: request, as it would be used in the error
        !           394: section of a section two manual page.
        !           395: .Pp
        !           396: .Dl Usage: .Er ERRNOTYPE ... \*(Pu
        !           397: .Dw Tx
        !           398: .Dp Li \&.Er ENOENT
        !           399: .Er ENOENT
        !           400: .Dp Li \&.Op \&Er ENOTDIR
        !           401: .Op Er ENOTDIR
        !           402: .Dp
        !           403: .Pp
        !           404: It is an error to call
        !           405: .Li \&.Er
        !           406: without arguments.
        !           407: The request cannot call other macros, but
        !           408: may be invoked by
        !           409: .Li \&.Cl ,
        !           410: .Li \&.Cx ,
        !           411: .Li \&.Dl ,
        !           412: .Li \&.Dp ,
        !           413: .Li \&.Op
        !           414: or
        !           415: .Li \&.Tp .
        !           416: .Ss Environment Variables
        !           417: The
        !           418: .Li \&.Ev
        !           419: request specifies a environment variable.
        !           420: .Pp
        !           421: .Dl Usage: .Ev argument ... \*(Pu
        !           422: .Dw \&.Ev\ PRINTER\ )\ )\ ,
        !           423: .Dp Li \&.Ev DISPLAY
        !           424: .Ev  DISPLAY
        !           425: .Dp Li \&.Ev PATH\ .
        !           426: .Ev PATH .
        !           427: .Dp Li \&.Ev PRINTER\ )\ )\ ,
        !           428: .Ev PRINTER ) ) ,
        !           429: .Dp
        !           430: .Pp
        !           431: It is an error to call
        !           432: .Li \&.Ev
        !           433: without arguments.
        !           434: The request cannot call other macros, but
        !           435: may be invoked by
        !           436: .Li \&.Cl ,
        !           437: .Li \&.Cx ,
        !           438: .Li \&.Dl ,
        !           439: .Li \&.Dp ,
        !           440: .Li \&.Op
        !           441: or
        !           442: .Li \&.Tp .
        !           443: .Ss Flags
        !           444: The
        !           445: .Li \&.Fl
        !           446: request handles command line flags. It prepends
        !           447: a dash,
        !           448: .Li \- ,
        !           449: to the flag. For interactive command flags, which
        !           450: are not prepended with a dash, the
        !           451: .Li \&.Cm
        !           452: request is identical, but with out the dash.
        !           453: The
        !           454: .Li \&.Cm
        !           455: stands for command modifier.
        !           456: .Pp
        !           457: .Dl Usage: .Fl argument ... \*(Pu
        !           458: .Dw Tx
        !           459: .Dp Li \&.Fl
        !           460: .Fl
        !           461: .Dp Li \&.Fl cfv
        !           462: .Fl cfv
        !           463: .Dp Li \&.Fl cfv\ .
        !           464: .Fl cfv .
        !           465: .Dp Li \&.Fl s v t
        !           466: .Fl s v t
        !           467: .Dp Li \&.Fl -\ ,
        !           468: .Fl - ,
        !           469: .Dp Li \&.Fl xyz\ )\ ,
        !           470: .Fl xyz ) ,
        !           471: .Dp
        !           472: .Pp
        !           473: The
        !           474: .Li \&.Fl
        !           475: request without any arguments results
        !           476: in a dash sign representing stdin/stdout.
        !           477: Note that giving
        !           478: .Li \&.Fl
        !           479: a single dash, will result in two dashes.
        !           480: The request cannot call other macros, but
        !           481: may be invoked by
        !           482: .Li \&.Cl ,
        !           483: .Li \&.Cx ,
        !           484: .Li \&.Dl ,
        !           485: .Li \&.Dp ,
        !           486: .Li \&.Op
        !           487: or
        !           488: .Li \&.Tp .
        !           489: .Pp
        !           490: .Ss Functions (library routines)
        !           491: The .Fn request is modeled on ANSI C conventions. It
        !           492: may fail on old style parameter lists.
        !           493: .Pp
        !           494: Usage: .Fn [type\e\ ] function [[type\e\ ] params ... \*(Pu
        !           495: .Dw \&.Fn\ void\e\ push\ int\e\ p\ int\e\ *ptr,
        !           496: .Di L
        !           497: .Dp Li \&.Fn getchar
        !           498: .Fn getchar
        !           499: .Dp Li \&.Fn strlen\ )\ ,
        !           500: .Fn strlen ) ,
        !           501: .Dp Li \&.Fn strcpy char\e\ *dst char\e\ *src
        !           502: .Fn strcpy char\ *dst char\ *src
        !           503: .Dp Li \&.Fn int\e\ align int\e\ word
        !           504: .Fn int\ align int\ word
        !           505: .Dp Li \&.Fn void\e\ push int\e\ p int\e\ *ptr\ ,
        !           506: .Fn void\ push int\ p int\ *ptr ,
        !           507: .Dp
        !           508: .Pp
        !           509: It is an error to call
        !           510: .Li \&.Fn
        !           511: without any arguments.
        !           512: At the moment,
        !           513: .Li \&.Fn
        !           514: does not check its word boundaries
        !           515: against troff line lengths.  It may split across a
        !           516: line ungracefully. This will be fixed in the near future.
        !           517: In the examples above, arguments with more than one word
        !           518: escape the blank spaces with a
        !           519: .Li \e .
        !           520: The
        !           521: .Li \&.Fn
        !           522: request cannot execute any macro
        !           523: names given as the first argument.
        !           524: It may be called by the
        !           525: .Li \&.Cl ,
        !           526: .Li \&.Cx ,
        !           527: .Li \&.Dl ,
        !           528: .Li \&.Dp ,
        !           529: .Li \&.Op
        !           530: or
        !           531: .Li \&.Tp .
        !           532: .Ss Literals
        !           533: The
        !           534: .Li \&.Li
        !           535: literal request may be used for special characters,
        !           536: variable constants, anything which should be displayed as it
        !           537: would be typed.
        !           538: .Pp
        !           539: .Dl Usage: .Li argument ... \*(Pu
        !           540: .Dw Tx
        !           541: .Dp Li \&.Li \een
        !           542: .Li \en
        !           543: .Dp Li \&.Li M1 M2 M3\ ;
        !           544: .Li M1 M2 M3 ;
        !           545: .Dp Li \&.Li cntrl-D\ )\ ,
        !           546: .Li cntrl-D ) ,
        !           547: .Dp Li \&.Li 1024\ ...
        !           548: .Li 1024 ...
        !           549: .Dp
        !           550: .Pp
        !           551: It is an error to call
        !           552: .Li \&.Li
        !           553: without arguments.
        !           554: The request cannot call other macros, but
        !           555: may be invoked by
        !           556: .Li \&.Cl ,
        !           557: .Li \&.Cx ,
        !           558: .Li \&.Dl ,
        !           559: .Li \&.Dp ,
        !           560: .Li \&.Op
        !           561: or
        !           562: .Li \&.Tp .
        !           563: .Ss Name Request
        !           564: The
        !           565: .Li \&.Nm
        !           566: request is used for the document title or subject name.
        !           567: It has the peculiarity of remembering  the first
        !           568: argument it was called with, which should
        !           569: always be the subject name of the page.  When called without
        !           570: arguments,
        !           571: .Li \&.Nm
        !           572: regurgitates this initial name for the sole purpose
        !           573: of making less work for the author.
        !           574: Beyond the NAME section of the man page, a section two
        !           575: or three document function name is addressed with the
        !           576: .Li \&Fn
        !           577: request, while
        !           578: .Li \&.Nm
        !           579: can continue to be used for any other sections.
        !           580: For interactive commands, such as the
        !           581: .Li while
        !           582: command keyword in
        !           583: .Xr csh 1 ,
        !           584: the
        !           585: .Li \&.Ic
        !           586: request should be used.
        !           587: While the
        !           588: .Li \&.Ic
        !           589: is nearly identical
        !           590: to
        !           591: .Li \&.Nm ,
        !           592: it can not recall the first argument it was invoked with.
        !           593: .Pp
        !           594: .Dl Usage: .Nm argument ... \*(Pu
        !           595: .Dw Tx
        !           596: .Dp Li \&.Nm mdoc.sample
        !           597: .Nm  mdoc.sample
        !           598: .Dp Li \&.Nm \-mdoc
        !           599: .Nm \-mdoc .
        !           600: .Dp Li \&.Nm foo\ )\ )\ ,
        !           601: .Nm foo ) ) ,
        !           602: .Dp Li \&.Nm
        !           603: .Nm
        !           604: .Dp
        !           605: .Pp
        !           606: The
        !           607: .Li \&.Nm
        !           608: request cannot call other macros, but
        !           609: may be called by
        !           610: .Li \&.Cl ,
        !           611: .Li \&.Cx ,
        !           612: .Li \&.Dl ,
        !           613: .Li \&.Dp ,
        !           614: .Li \&.Op
        !           615: or
        !           616: .Li \&.Tp .
        !           617: .Ss Pathnames
        !           618: The
        !           619: .Li \&.Pa
        !           620: request formats path or file names.  It has two
        !           621: different behaviours. In any section of the man page
        !           622: .Em except
        !           623: the section FILES, it
        !           624: expects at most one path or file name, and any amount
        !           625: of punctuation. In the section FILES,
        !           626: it is often desirable to have a column of pathnames
        !           627: and a column of pathname descriptions.
        !           628: .Pp
        !           629: .Dl Usage: .Pa pathname \*(Pu
        !           630: .Dw \&.Pa\ /tmp/fooXXXXX\ )\ .
        !           631: .Dp Li \&.Pa /usr/share
        !           632: .Pa /usr/share
        !           633: .Dp Li \&.Pa /tmp/fooXXXXX\ )\ .
        !           634: .Pa /tmp/fooXXXXX ) .
        !           635: .Dp
        !           636: .Pp
        !           637: From within section FILES, use the
        !           638: .Li \&.Dw
        !           639: and
        !           640: .Li \&.Dp
        !           641: requests to format the pathnames
        !           642: and their descriptions.
        !           643: .Li \&.Pa
        !           644: request cannot call other macros, but
        !           645: may be called by
        !           646: .Li \&.Cl ,
        !           647: .Li \&.Cx ,
        !           648: .Li \&.Dl ,
        !           649: .Li \&.Dp ,
        !           650: .Li \&.Op
        !           651: or
        !           652: .Li \&.Tp .
        !           653: .Ss Single Quotes
        !           654: See the request
        !           655: .Li \&.Dq
        !           656: above.  The single quoting request
        !           657: .Li \&.Sq
        !           658: works in the same manner as
        !           659: .Li \&.Dq.
        !           660: .Ss Symbolic
        !           661: The symbolic request is really a boldface request.
        !           662: The need for this macro has not been established,
        !           663: it is included 'just in case'.
        !           664: .Pp
        !           665: .Dl Usage: .Sy symbol ... \*(Pu
        !           666: .Dw \&.Sy\ something\ bold
        !           667: .Dp Li \&.Sy something bold
        !           668: .Sy something bold
        !           669: .Dp
        !           670: .Pp
        !           671: The
        !           672: .Li \&.Sy
        !           673: request cannot call other macros, but can be called
        !           674: by
        !           675: .Li \&.Cl ,
        !           676: .Li \&.Cx ,
        !           677: .Li \&.Dl ,
        !           678: .Li \&.Dp ,
        !           679: .Li \&.Op
        !           680: or
        !           681: .Li \&.Tp .
        !           682: .Ss Variables
        !           683: Generic variable reference:
        !           684: .Pp
        !           685: .Dl Usage: .Va variable ... \*(Pu
        !           686: .Dw \&.Va char\ s\ ]\ )\ )\ ,
        !           687: .Dp Li \&.Va count
        !           688: .Va count
        !           689: .Dp Li \&.Va settimer ,
        !           690: .Va settimer ,
        !           691: .Dp Li \&.Va int\ *prt\ )\ :
        !           692: .Va int\ *prt ) :
        !           693: .Dp Li \&.Va char\ s\ ]\ )\ )\ ,
        !           694: .Va char\ s ] ) ) ,
        !           695: .Dp
        !           696: .Pp
        !           697: .Ss Cross References
        !           698: The
        !           699: .Li \&.Xr
        !           700: request expects the first argument to be
        !           701: a manual page name, and the second argument, if it exists,
        !           702: to be either a section page number or punctuation.  Any
        !           703: remaining arguments are assumed to be punctuation.
        !           704: .Pp
        !           705: .Dl Usage: .Xr manpage [1,...,8] \*(Pu
        !           706: .Dw Tx
        !           707: .Dp Li \&.Xr mdoc
        !           708: .Xr mdoc
        !           709: .Dp Li \&.Xr mdoc\ ,
        !           710: .Xr mdoc ,
        !           711: .Dp Li \&.Xr mdoc 7
        !           712: .Xr mdoc 7
        !           713: .Dp Li \&.Xr mdoc 7\ )\ )\ ,
        !           714: .Xr mdoc 7 ) ) ,
        !           715: .Dp
        !           716: .Pp
        !           717: The
        !           718: .Li \&.Xr
        !           719: request cannot call other macros, but may be called
        !           720: by
        !           721: .Li \&.Cl ,
        !           722: .Li \&.Cx ,
        !           723: .Li \&.Dl ,
        !           724: .Li \&.Dp ,
        !           725: .Li \&.Op
        !           726: or
        !           727: .Li \&.Tp .
        !           728: It is an error to call
        !           729: .Li \&.Xr
        !           730: without
        !           731: any arguments.
        !           732: .Pp
        !           733: .\" ---
        !           734: .Sh PAGE LAYOUT MACROS
        !           735: .Ss Section Headers
        !           736: Several
        !           737: .Li \&.Sh
        !           738: section header requests are required in every
        !           739: man page. The
        !           740: .Li \&.Sh
        !           741: request can take up to nine arguments.
        !           742: .Tp \&.Sh NAME
        !           743: The
        !           744: .Li \&.Sh NAME
        !           745: request is mandatory. If not specified,
        !           746: the headers, footers and page layout defaults
        !           747: will not be set and things will be rather unpleasant.
        !           748: The NAME section consists of at least three items.
        !           749: The first is the
        !           750: .Li \&.Nm
        !           751: name request naming the subject of the man page.
        !           752: The second is the Name Description request,
        !           753: .Li \&.Nd ,
        !           754: which separates the subject
        !           755: name from the third item, which is the description. The
        !           756: description should be the most terse and lucid possible,
        !           757: as the space available is small.
        !           758: .Tp \&.Sh SYNOPSIS
        !           759: The SYNOPSIS section describes the typical usage of the
        !           760: subject of a man page. The  requests required
        !           761: are either
        !           762: .Li \&.Nm
        !           763: or
        !           764: .Li \&.Fn .
        !           765: The function name
        !           766: request
        !           767: .Li \&.Fn
        !           768: is required
        !           769: for manual page sections 2 and 3, the command and general
        !           770: name request
        !           771: .Li \&.Nm
        !           772: is required for the remaining sections 1, 4, 5, 6, 7, 8.
        !           773: Several other requests may be necessary to produce
        !           774: the synopsis line as shown below:
        !           775: .Pp
        !           776: .Nm cat
        !           777: .Op Fl benstuv
        !           778: .Op Fl
        !           779: .Ar
        !           780: .Pp
        !           781: The following requests were used:
        !           782: .Pp
        !           783: .Dl \&.Nm cat
        !           784: .Dl \&.Op Fl benstuv
        !           785: .Dl \&.Op Fl
        !           786: .Dl \&.Ar
        !           787: .Pp
        !           788: Note, the
        !           789: .Li \&.Op
        !           790: request has accepted as its first
        !           791: argument the name of another macro
        !           792: .Em \&Fl .
        !           793: Upon discovering the first argument is callable,
        !           794: .Li \&.Op
        !           795: calls it with the remaining arguments
        !           796: and returns the formatted text in option brackets.
        !           797: .Tp \&.Sh DESCRIPTION
        !           798: In most cases the first text in the DESCRIPTION section
        !           799: is a brief paragraph on the command, function or file,
        !           800: followed by a lexical list of options and respective
        !           801: explanations. To create such a list, the
        !           802: .Li \&.Tp
        !           803: request is used in conjunction with text macros, such
        !           804: as the
        !           805: .Li \&.Fl
        !           806: macro (see
        !           807: the EXAMPLES section below).
        !           808: .Tp
        !           809: .Pp
        !           810: Other user specified
        !           811: .Li \&.Sh
        !           812: sections may be added,
        !           813: for instance, in this manual page
        !           814: .Pp
        !           815: .Dl Li \&.Sh PAGE LAYOUT MACROS
        !           816: .Pp
        !           817: was used for this section.
        !           818: .Pp
        !           819: The following
        !           820: .Li \&.Sh
        !           821: section headers are part of the
        !           822: preferred manual page layout and must be used appropriately
        !           823: to maintain consistency. They are listed in the order
        !           824: in which they would be used.
        !           825: .Tp \&.Sh ENVIRONMENT
        !           826: The ENVIRONMENT section should reveal any related
        !           827: environment
        !           828: variables and clues to their behaviour and/or usage.
        !           829: .Tp \&.Sh EXAMPLES
        !           830: There are several ways to create examples. See
        !           831: the EXAMPLES section below
        !           832: for details.
        !           833: .Tp \&.Sh FILES
        !           834: Files which are used or created by the man page subject
        !           835: should be listed via the
        !           836: .Li \&.Pa
        !           837: request in the FILES section.
        !           838: .Tp \&.Sh SEE ALSO
        !           839: References to other material on the man page topic and
        !           840: cross references to other relevant man pages should
        !           841: be placed in the SEE ALSO section.  Cross references
        !           842: are specified using the
        !           843: .Li \&.Xr
        !           844: request.  At this time
        !           845: .Xr refer 1
        !           846: style references are not accommodated.
        !           847: .Tp \&.Sh STANDARDS
        !           848: If the command, library function or file adheres to a
        !           849: specific implementation such as POSIX 1003.1 or
        !           850: ANSI C X3.159-1989 this should be noted here.  If the
        !           851: command does not adhere to any standard, its history
        !           852: should be noted in the HISTORY section.
        !           853: .Tp \&.Sh HISTORY
        !           854: Any command which does not adhere to any specific standards
        !           855: should be outlined historically in this section.
        !           856: .Tp \&.Sh AUTHORS
        !           857: Credits, if need be, should be placed here.
        !           858: .Tp \&.Sh DIAGNOSTICS
        !           859: Diagnostics from a command should be placed in this section.
        !           860: .Tp \&.Sh ERRORS
        !           861: Specific error handling, especially from library functions
        !           862: (man page sections 2 and 3) should go here.  The
        !           863: .Li \&.Er
        !           864: request is used to specify an errno.
        !           865: .Tp \&.Sh BUGS
        !           866: Blatant problems with the topic go here...
        !           867: .Tp
        !           868: .Pp
        !           869: .Ss Paragraphs and Line Spacing.
        !           870: .Tp \&.Pp
        !           871: The \&.Pp paragraph command may
        !           872: be used to specify a line space where necessary.
        !           873: The request is not necessary after a
        !           874: .Li \&.Sh
        !           875: or
        !           876: .Li \&.Ss
        !           877: request or before
        !           878: a
        !           879: .Li \&.Tp
        !           880: or
        !           881: .Li \&.Dp
        !           882: request.
        !           883: .Tp
        !           884: .Ss Complex Expressions
        !           885: A complex expression is one combined of many
        !           886: different elements of text. It is usually only necessary
        !           887: in particularly nasty man pages, such as
        !           888: .Xr adb 1
        !           889: or
        !           890: .Xr ex 1 ,
        !           891: where combinations of commands, addresses and symbols
        !           892: may be needed.
        !           893: When pieces of text are processed,
        !           894: .Xr troff 1
        !           895: assumes
        !           896: that a space character will be desired after each word
        !           897: making it difficult to combine expressions where
        !           898: different requests are used.
        !           899: .Li \&.Cx
        !           900: merely glues text together without spaces.  Where
        !           901: a space is required, it must be specified.
        !           902: A few examples:
        !           903: .Pp
        !           904: This first example shows how to construct a simple
        !           905: expression with no spacing in between:
        !           906: .Pp
        !           907: .Ds I
        !           908: .Cw (ax+bx+c) \ is\ produced\ by\ \&
        !           909: .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\&
        !           910: .Cl Cx \t\t
        !           911: .Li \&.Cx\ (
        !           912: .Cx
        !           913: .Cl Cx \t\t
        !           914: .Li \&.Va ax
        !           915: .Cx
        !           916: .Cl Cx \t\t
        !           917: .Li \&.Sy \+
        !           918: .Cx
        !           919: .Cl Cx \&(\&
        !           920: .Va ax
        !           921: .Cx +
        !           922: .Va by
        !           923: .Cx +
        !           924: .Va c )
        !           925: .Cx \t
        !           926: .Em is produced by
        !           927: .Cx \t
        !           928: .Li \&.Va by
        !           929: .Cx
        !           930: .Cl Cx \t\t
        !           931: .Li \&.Sy \+
        !           932: .Cx
        !           933: .Cl Cx \t\t
        !           934: .Li \&.Va c )
        !           935: .Cx
        !           936: .Cl Cx \t\t
        !           937: .Li \&.Cx
        !           938: .Cx
        !           939: .Cw
        !           940: .De
        !           941: .Pp
        !           942: This example shows the same equation in a different format. The spaces
        !           943: around the
        !           944: .Li \&+
        !           945: signs were forced with
        !           946: .Li \e :
        !           947: .Pp
        !           948: .Ds I
        !           949: .Cw (ax\ +\ bx\ +\ c) \ is\ produced\ by\ \&
        !           950: .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\&
        !           951: .Cl Cx \t\t
        !           952: .Li \&.Cx\ (
        !           953: .Cx
        !           954: .Cl Cx \t\t
        !           955: .Li \&.Va a
        !           956: .Cx
        !           957: .Cl Cx \t\t
        !           958: .Li \&.Sy x
        !           959: .Cx
        !           960: .Cl Cx \t\t
        !           961: .Li \&.Cx \e\ +\e\ \e&
        !           962: .Cx
        !           963: .Cl Cx \&(\&
        !           964: .Va a
        !           965: .Sy x
        !           966: .Cx \ +\ \&
        !           967: .Va b
        !           968: .Sy y
        !           969: .Cx \ +\ \&
        !           970: .Va c )
        !           971: .Cx \t
        !           972: .Em is produced by
        !           973: .Cl Cx \t\t
        !           974: .Li \&.Va b
        !           975: .Cx
        !           976: .Cl Cx \t\t
        !           977: .Li \&.Sy y
        !           978: .Cx
        !           979: .Cl Cx \t\t
        !           980: .Li \&.Cx \e\ +\e\ \e&
        !           981: .Cx
        !           982: .Cl Cx \t\t
        !           983: .Li \&.Va c )
        !           984: .Cx
        !           985: .Cl Cx \t\t
        !           986: .Li \&.Cx
        !           987: .Cx
        !           988: .Cw
        !           989: .De
        !           990: .Pp
        !           991: The incantation below was
        !           992: lifted from the
        !           993: .Xr adb 1
        !           994: manual page:
        !           995: .Pp
        !           996: .Ds I
        !           997: .Cw \&[?/]m_b1_e1_f1[?/]\& is\ produced\ by
        !           998: .Cl Cx \t\t
        !           999: .Li \&.Cx Op Sy ?/
        !          1000: .Cx
        !          1001: .Cl Cx \t\t
        !          1002: .Li \&.Nm m
        !          1003: .Cx
        !          1004: .Cl Cx Op Sy ?/
        !          1005: .Nm m
        !          1006: .Ad \ b1 e1 f1
        !          1007: .Op Sy ?/
        !          1008: .Cx \t
        !          1009: .Em is produced by
        !          1010: .Cx \t
        !          1011: .Li \&.Ar \e\ b1 e1 f1
        !          1012: .Cx
        !          1013: .Cl Cx \t\t
        !          1014: .Li \&.Op Sy ?/
        !          1015: .Cx
        !          1016: .Cl Cx \t\t
        !          1017: .Li \&.Cx
        !          1018: .Cx
        !          1019: .Cw
        !          1020: .De
        !          1021: .Pp
        !          1022: .Ss Examples and Displays
        !          1023: There are three types of displays, an indented one line display
        !          1024: .Li \&.Dl ,
        !          1025: a non\-filled block display
        !          1026: .Li Ds
        !          1027: and a filled block display.
        !          1028: .Pp
        !          1029: .Tw \&.Dl
        !          1030: .Tp Li \&.Dl
        !          1031: Display one line of indented text.
        !          1032: The
        !          1033: .Li \&.Dl
        !          1034: example request has been used throughout this
        !          1035: file.  It's
        !          1036: basic use is to indent (display) one line of text for quick
        !          1037: one line examples. Its default font is set to
        !          1038: constant width, however,
        !          1039: .Li \&.Dl
        !          1040: checks the first argument to see if it is callable. It cannot process
        !          1041: more than nine arguments.
        !          1042: .Pp
        !          1043: .Ds I
        !          1044: .Li \&.Dl % ls -ldg /usr/local/bin
        !          1045: .Pp
        !          1046: produces:
        !          1047: .Dl % ls -ldg /usr/local/bin
        !          1048: .Pp
        !          1049: .Li \&.Dl Fl ldghfstru
        !          1050: .Pp
        !          1051: produces:
        !          1052: .Dl  Fl ldghfstru
        !          1053: .De
        !          1054: .Pp
        !          1055: Calling either the request
        !          1056: .Li \&.Tp
        !          1057: or
        !          1058: .Li \&.Dp
        !          1059: from
        !          1060: .Li \&.Dl
        !          1061: is redundant and may cause unpredictable errors.
        !          1062: .Tp Li \&.Ds
        !          1063: Display a block of text as typed,
        !          1064: right margin edges are left ragged.
        !          1065: Nesting
        !          1066: .Li \&.Ds
        !          1067: requests seems to work,
        !          1068: so they can be used outside and within
        !          1069: tagged paragraphs. Each
        !          1070: .Li \&.Ds
        !          1071: request must be ended with a
        !          1072: .Li \&De
        !          1073: request.
        !          1074: .Li \&.Ds
        !          1075: takes can be manipulated to indent
        !          1076: with the
        !          1077: .Li \&L , \&C , \&R ,
        !          1078: and
        !          1079: .Li \&I
        !          1080: flags.
        !          1081: .Dw 4n
        !          1082: .Dp Li L
        !          1083: Align block on the current left margin,
        !          1084: this is the default mode of
        !          1085: .Li \&.Ds
        !          1086: if called without arguments.
        !          1087: .Dp Li C
        !          1088: Supposedly center the block. At this time
        !          1089: unfortunately, the block merely gets
        !          1090: left aligned about an imaginary center margin.
        !          1091: This will be fixed some time inthe near future.
        !          1092: .Dp Li I
        !          1093: Indent from left margin default amount (usually
        !          1094: about a three quarters of an inch or eight
        !          1095: constant width characters).
        !          1096: .Dp Li R
        !          1097: This left aligns the block about two inches from
        !          1098: the right side of the page. It too, alas, needs
        !          1099: work.
        !          1100: .Dp
        !          1101: .Tp Li \&.De
        !          1102: Ends a
        !          1103: .Li \&.Ds
        !          1104: request.
        !          1105: .Tp Li \&.Df
        !          1106: Display a filled (formatted) block.  Identical to
        !          1107: .Li \&.Ds ,
        !          1108: except the block of text is formatted (the edges are
        !          1109: not left ragged).  Takes the same modifers as
        !          1110: .Li Ds .
        !          1111: .Tp
        !          1112: .Ss Tagged paragraphs and Columns
        !          1113: The commands
        !          1114: .Li \&.Tp
        !          1115: and
        !          1116: .Li \&.Dp
        !          1117: create tagged paragraph
        !          1118: lists.
        !          1119: Like the
        !          1120: .Li \&.Cx
        !          1121: request,
        !          1122: both require a begin and end.  When
        !          1123: .Li \&.Tp
        !          1124: or
        !          1125: .Li \&.Dp
        !          1126: are called with arguments, they collect and
        !          1127: create the tag portion from
        !          1128: the arguments.
        !          1129: Anything after the tag is placed in
        !          1130: the paragraph portion.
        !          1131: The
        !          1132: .Li \&.Dp
        !          1133: macro is essentially the same as
        !          1134: the \&.Tp
        !          1135: macro, but with a few added features.
        !          1136: These are discussed following the
        !          1137: .Li \&.Tp
        !          1138: example.
        !          1139: .Li \&.Tp
        !          1140: and
        !          1141: .Li \&.Dp
        !          1142: can call several macros,
        !          1143: these are:
        !          1144: .Pp
        !          1145: .Dl \&.Ad, \&.Ar, \&.Cm, \&.Em, \&.Er, \&.Ev, \&.Fl, \&.Fn, \&.Ic,
        !          1146: .Dl \&.Li, \&.Nm, \&.Sy, \&.Va and \&.Xr.
        !          1147: .Pp
        !          1148: The
        !          1149: .Li \&.Tp
        !          1150: request can be nested, and values for determining
        !          1151: the width of each tag are based on which macro
        !          1152: .Li \&.Tp
        !          1153: is calling, if it is calling one, or by specifying
        !          1154: a width with the
        !          1155: .Li \&.Tw
        !          1156: request.
        !          1157: The default width for an unknown tag type is set to just
        !          1158: about one and three quarter inches, or 20 characters in a
        !          1159: constant width font.
        !          1160: If the default width is unsatisfactory,
        !          1161: .Li \&.Tw
        !          1162: can be used as follows:
        !          1163: .Dp Li \&.Tw Fl
        !          1164: sets the width to the default flag width
        !          1165: .Li \&.Fl ,
        !          1166: which is
        !          1167: set to ten constant width characters or about five sixth of
        !          1168: an inch.
        !          1169: .Dp Li \&.Tw 24n
        !          1170: sets the width to 24 constant width characters or about two
        !          1171: inches.  The
        !          1172: .Li n
        !          1173: is absolutely necessary for the scaling to work correctly.
        !          1174: .Dp Li \&.Tw ENAMETOOLONG
        !          1175: sets the width to the constant width length of the
        !          1176: string given.
        !          1177: .Dp Li \&.Tw  int\e\ mkfifo
        !          1178: again, the width is set to the constant width of the string
        !          1179: given, and the space is protected with a preceding
        !          1180: .Li \e .
        !          1181: .Dp
        !          1182: .Pp
        !          1183: A nesting
        !          1184: .Li \&.Tp
        !          1185: Example:
        !          1186: .Pp
        !          1187: .Tp Nm Name1
        !          1188: This is the first call to
        !          1189: .Li \&.Tp
        !          1190: with
        !          1191: .Li \&.Nm .
        !          1192: .Tp Nm Name2
        !          1193: Another call with
        !          1194: .Li \&.Nm .
        !          1195: .Tp Va Variable1
        !          1196: An example of the
        !          1197: .Li \&.Va
        !          1198: request with
        !          1199: .Li \&.Tp .
        !          1200: Since the first argument was callable
        !          1201: and different from the last one, the
        !          1202: tag was indented.
        !          1203: .Tp Va Variable2
        !          1204: Another
        !          1205: .Li \&.Va
        !          1206: example.
        !          1207: .Tp Fl Flag1
        !          1208: A third nest (indent) using the
        !          1209: .Li \&.Fl
        !          1210: request.
        !          1211: .Tp Fl Flag2
        !          1212: Again the
        !          1213: .Li \&.Fl
        !          1214: .Tp
        !          1215: .Pp
        !          1216: A
        !          1217: .Li \&.Tp
        !          1218: with no arguments stops the current nest
        !          1219: and exdents back to the previous level.
        !          1220: .Tp Va Variable3
        !          1221: Another call with the
        !          1222: .Li \&.Va
        !          1223: request.
        !          1224: .Tp
        !          1225: .Pp
        !          1226: Again a
        !          1227: .Li \&.Tp
        !          1228: without arguments exdents.  This will put
        !          1229: us back at the first level.
        !          1230: .Tp Nm Name3
        !          1231: Another
        !          1232: .Li \&.Nm
        !          1233: request. This request is followed
        !          1234: by the last call to
        !          1235: .Li \&.Tp
        !          1236: without arguments.
        !          1237: .Tp
        !          1238: .Pp
        !          1239: The above was created from:
        !          1240: .Pp
        !          1241: .Ds I
        !          1242: \&.Tp Nm Name1
        !          1243: This is the first call to
        !          1244: \&.Li \&.Tp
        !          1245: with
        !          1246: \&.Li \&.Nm .
        !          1247: \&.Tp Nm Name2
        !          1248: Another call with
        !          1249: \&.Li \&.Nm .
        !          1250: \&.Tp Va Variable1
        !          1251: An example of the
        !          1252: \&.Li \&.Va
        !          1253: request with
        !          1254: \&.Li \&.Tp .
        !          1255: Since the first argument was callable and different from
        !          1256: the last one, the tag was indented.
        !          1257: \&.Tp Va Variable2
        !          1258: Another
        !          1259: \&.Li \&.Va
        !          1260: example.
        !          1261: \&.Tp Fl Flag1
        !          1262: A third nest (indent) using the
        !          1263: \&.Li \&.Fl
        !          1264: request.
        !          1265: \&.Tp Fl Flag2
        !          1266: Again the
        !          1267: \&.Li \&.Fl
        !          1268: \&.Tp
        !          1269: A
        !          1270: \&.Li \&.Tp
        !          1271: with no arguments stops the current nest
        !          1272: and exdents back to the previous level.
        !          1273: \&.Tp Va Variable3
        !          1274: Another call with the
        !          1275: \&.Li \&.Va
        !          1276: request.
        !          1277: \&.Tp
        !          1278: Again a
        !          1279: \&.Li \&.Tp
        !          1280: without argments exdents.
        !          1281: This will put us back at the first level.
        !          1282: \&.Tp Nm Name3
        !          1283: Another
        !          1284: \&.Li \&.Nm
        !          1285: request. This request is followed by the last call to
        !          1286: \&.Li \&.Tp
        !          1287: without arguments.
        !          1288: \&.Tp
        !          1289: .De
        !          1290: .Pp
        !          1291: An example of
        !          1292: .Li \&.Dp:
        !          1293: .Pp
        !          1294: .Dw PAGEIN\ 10
        !          1295: .Dp SL 10
        !          1296: sleep time of the process (seconds blocked)
        !          1297: .Dp PAGEIN 10
        !          1298: number of disk i/o's resulting from references by the process
        !          1299: to pages not loaded in core.
        !          1300: .Dp UID 10
        !          1301: numerical user-id of process owner
        !          1302: .Dp PPID 10
        !          1303: numerical id of parent of process
        !          1304: process priority (non-positive when in non-interruptible wait)
        !          1305: .Dp
        !          1306: .Pp
        !          1307: The raw text:
        !          1308: .Pp
        !          1309: .Ds I
        !          1310: .Li \&.Dw PAGEIN\ 10
        !          1311: .Li \&.Dp SL 10
        !          1312: sleep time of the process (seconds blocked)
        !          1313: .Li \&.Dp PAGEIN 10
        !          1314: number of disk i/o's resulting from references by the process
        !          1315: to pages not loaded in core.
        !          1316: .Li \&.Dp UID 10
        !          1317: numerical user-id of process owner
        !          1318: .Li \&.Dp PPID 10
        !          1319: numerical id of parent of process
        !          1320: process priority (non-positive when in non-interruptible wait)
        !          1321: .Li \&.Dp
        !          1322: .De
        !          1323: .Pp
        !          1324: The default behaviour of
        !          1325: .Li \&.Dp
        !          1326: is to indent a small amount from the current margin before
        !          1327: processing the tag.  This margin can be changed with the
        !          1328: request
        !          1329: .Li \&.Di
        !          1330: which takes as its first argument either a numerical
        !          1331: argument (e.g. a scaled number like 24n) or a letter
        !          1332: .Li \&L
        !          1333: or
        !          1334: .Li \&I .
        !          1335: The
        !          1336: .Li \&L
        !          1337: forces a left margin, which is useful if something doesn't
        !          1338: quite fit (as in the example for the
        !          1339: .Li \&.Fn
        !          1340: macro in the TEXT MACRO section above).
        !          1341: The
        !          1342: .Li \&I
        !          1343: is the default, but may be used for a return to the default
        !          1344: if necessary.  Like all the tagged widths, the indents
        !          1345: are pushed on a stack, and when that stack (or level)
        !          1346: is expired, the previous values are used (this happens
        !          1347: whenever a
        !          1348: .Li \&.Dp
        !          1349: or
        !          1350: .Li \&.Tp
        !          1351: is called without arguments).
        !          1352: In this example,
        !          1353: .Li \&.Dw
        !          1354: has been used to set the width of the tag.
        !          1355: It is identical to the request
        !          1356: .Li \&.Tw
        !          1357: discussed above.
        !          1358: .Ss Columns
        !          1359: The column request is made up of a width request,
        !          1360: .Li \&.Cw ,
        !          1361: and a column line request,
        !          1362: .Li \&.Cl .
        !          1363: From one to four simple columns can be created
        !          1364: and all but the last column, are simple
        !          1365: single entry style columns.
        !          1366: The last (rightmost) column can overflow into
        !          1367: a indented paragraph.
        !          1368: .Pp
        !          1369: The
        !          1370: .Li \&.Cw
        !          1371: request takes at most three arguments
        !          1372: as width indicators.  The number of columns is
        !          1373: always one more than given to
        !          1374: .Li \&.Cw .
        !          1375: the
        !          1376: .Li \&.Cl
        !          1377: request should have its arguments
        !          1378: on the next line and the columns should be
        !          1379: separated by a tab character.
        !          1380: .Pp
        !          1381: An example of two columns:
        !          1382: .Cw Macros
        !          1383: .Cl Macros     Description
        !          1384: .Cl \&.Tp      List Request
        !          1385: .Cl \&.Nm      Name Request
        !          1386: .Cw
        !          1387: .Pp
        !          1388: The requests used to format the
        !          1389: columns above (the jagged edges are from tabs which can
        !          1390: also be represented by
        !          1391: .Li \et ) :
        !          1392: .Pp
        !          1393: .Dl \&.Cw Macros
        !          1394: .Dl \&.Cl Macros       Description
        !          1395: .Dl \&.Cl \e&.Tp        List Request
        !          1396: .Dl \&.Cl \e&.Nm        Name Request
        !          1397: .Dl \&.Cw
        !          1398: .Pp
        !          1399: There some problems with columns at the moment, while they
        !          1400: work well in nested lists, they are otherwise difficult
        !          1401: to offset via example.
        !          1402: .Ss Options
        !          1403: The
        !          1404: .Li \&.Op
        !          1405: request ain't quite working perfectly.
        !          1406: The (eventual) goal of
        !          1407: .Li \&.Op
        !          1408: is to place brackets around the given arguments, and place any
        !          1409: punctuation outside the brackets.  In the case of
        !          1410: .Li \&.Cx,
        !          1411: trailing punctuation on the same request line as the
        !          1412: .Li \&.Op
        !          1413: should be placed outside the brackets.
        !          1414: The multiple macro calls are one of the reasons this request is so moody.
        !          1415: Is is the only macro which attempts to call other macros on the
        !          1416: request line. Its not doing too badly, just not perfect:
        !          1417: .Dw \&.Op\ Fl\ c\ Ar\ objfil\ Op\ Ar\ corfil\ ,
        !          1418: .Dp Li \&.Op
        !          1419: .Op
        !          1420: .Dp Li \&.Op Fl k
        !          1421: .Op Fl k
        !          1422: .Dp Li \&.Op Fl k\ )\ .
        !          1423: .Op Fl k ) .
        !          1424: .Dp Li \&.Op Fl k Ar kookfile
        !          1425: .Op Fl k Ar kookfile
        !          1426: .Dp Li \&.Op Fl k Ar kookfile\ ,
        !          1427: .Op Fl k Ar kookfile ,
        !          1428: .Dp Li \&.Op Ar objfil Op Ar corfil
        !          1429: .Op Ar objfil Op Ar corfil
        !          1430: .Dp Li \&.Op Fl c Ar objfil Op Ar corfil\ ,
        !          1431: .Op Fl c Ar objfil Op Ar corfil ,
        !          1432: .Dp Li \&.Op word1 word2
        !          1433: .Op word1 word2
        !          1434: .Dp
        !          1435: .Pp
        !          1436: The punctuation on the second to last example is
        !          1437: improperly placed and should be fixed some day.
        !          1438: .Sh FILES
        !          1439: .\" .Pa /usr/share/tmac/tmac.doc.style site specific layout
        !          1440: .Dw /usr/share/man0/template.doc
        !          1441: .Di L
        !          1442: .Dp Pa /usr/share/tmac/tmac.doc
        !          1443: manual macro package
        !          1444: .Dp Pa /usr/share/man0/template.doc
        !          1445: template for writing a man page
        !          1446: .Dp
        !          1447: .Sh HISTORY
        !          1448: 4.4 BSD
        !          1449: .Sh SEE ALSO
        !          1450: .Xr mdoc.samples 7 ,
        !          1451: .Xr man 1 ,
        !          1452: .Xr troff 1
        !          1453: .Sh BUGS
        !          1454: .Pp
        !          1455: Punctuation may be broken on
        !          1456: .Li \&.Op
        !          1457: again.
        !          1458: .Pp
        !          1459: Undesirable hyphenation on the dash of a flag
        !          1460: argument is not yet resolved, and causes
        !          1461: occasional mishaps in the DESCRIPTION section.
        !          1462: .Pp
        !          1463: Predefined strings are not declared in documentation.
        !          1464: .Pp
        !          1465: Section 3f has not been added to the header routines.
        !          1466: .Pp
        !          1467: .Li \&.Nm
        !          1468: font should be changed in NAME section.
        !          1469: .Pp
        !          1470: .Li \&.Fn
        !          1471: needs to have a check to prevent splitting up
        !          1472: if the line length is too short. Right now it
        !          1473: separates the last parenthesis, and sometimes
        !          1474: looks ridiculous if a line is in fill mode.
        !          1475: .Pp
        !          1476: The method used to prevent header and footer page
        !          1477: breaks (other than the initial header and footer) when using
        !          1478: nroff seems to be putting out a partially filled line
        !          1479: at the bottom of the page leaving an unsightly blank space.
        !          1480: .Pp
        !          1481: The tagged paragraph, display and column requests to not do any keeps
        !          1482: and certainly should be able to.
        !          1483: .Pp
        !          1484: Occasionally there maybe a problem with mathematical
        !          1485: or logical interpretation of characters from the
        !          1486: set
        !          1487: {+,\-,/,*,%,<,>,<=,>=,=,==,&}
        !          1488: found as the second
        !          1489: character in an argument string which may be checked for punctuation.
        !          1490: This is a relatively rare occurrence, as a lot of checking is
        !          1491: done to prevent it,
        !          1492: but if it should happen
        !          1493: escape the characters
        !          1494: with
        !          1495: .Li \e& .

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.