[BACK]Return to mandoc.1 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/mandoc.1, Revision 1.8

1.8     ! kristaps    1: .\" $Id: mandoc.1,v 1.7 2009/03/23 09:42:43 kristaps Exp $
1.1       kristaps    2: .\"
                      3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
                      4: .\"
                      5: .\" Permission to use, copy, modify, and distribute this software for any
                      6: .\" purpose with or without fee is hereby granted, provided that the
                      7: .\" above copyright notice and this permission notice appear in all
                      8: .\" copies.
                      9: .\"
                     10: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
                     11: .\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
                     12: .\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
                     13: .\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
                     14: .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
                     15: .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
                     16: .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
                     17: .\" PERFORMANCE OF THIS SOFTWARE.
                     18: .\"
                     19: .Dd $Mdocdate$
                     20: .Dt mandoc 1
                     21: .Os
                     22: .\" SECTION
                     23: .Sh NAME
                     24: .Nm mandoc
1.8     ! kristaps   25: .Nd format and display UNIX manuals
1.1       kristaps   26: .\" SECTION
                     27: .Sh SYNOPSIS
                     28: .Nm mandoc
                     29: .Op Fl V
                     30: .Op Fl f Ns Ar option...
1.8     ! kristaps   31: .Op Fl m Ns Ar format
1.1       kristaps   32: .Op Fl W Ns Ar err...
                     33: .Op Fl T Ns Ar output
                     34: .Op Ar infile...
                     35: .\" SECTION
                     36: .Sh DESCRIPTION
                     37: The
                     38: .Nm
1.8     ! kristaps   39: utility formats
        !            40: .Ux
        !            41: manual pages for display.  The arguments are as follows:
1.1       kristaps   42: .Bl -tag -width XXXXXXXXXXXX
                     43: .\" ITEM
                     44: .It Fl f Ns Ar option...
                     45: Override default compiler behaviour.  See
                     46: .Sx Compiler Options
                     47: for details.
                     48: .\" ITEM
1.8     ! kristaps   49: .It Fl m
        !            50: Input format.  See
        !            51: .Sx Input Formats
        !            52: for available formats.  Defaults to
        !            53: .Fl m Ns Ar mdoc .
        !            54: .\" ITEM
1.1       kristaps   55: .It Fl T
                     56: Output format.  See
                     57: .Sx Output Formats
                     58: for available formats.  Defaults to
                     59: .Fl T Ns Ar ascii .
                     60: .\" ITEM
                     61: .It Fl V
                     62: Print version and exit.
                     63: .\" ITEM
                     64: .It Fl W Ns Ar err...
                     65: Print warning messages.  May be set to
                     66: .Fl W Ns Ar all
                     67: for all warnings,
                     68: .Ar compat
                     69: for groff/troff-compatibility warnings, or
                     70: .Ar syntax
                     71: for syntax warnings.  If
                     72: .Fl W Ns Ar error
                     73: is specified, warnings are considered errors and cause utility
                     74: termination.  Multiple
                     75: .Fl W
                     76: arguments may be comma-separated, such as
                     77: .Fl W Ns Ar error,all .
                     78: .\" ITEM
                     79: .It Ar infile...
                     80: Read input from zero or more
                     81: .Ar infile .
1.2       kristaps   82: If unspecified, reads from stdin.  If multiple files are specified,
                     83: .Nm
                     84: will halt with the first failed parse.
1.1       kristaps   85: .El
                     86: .\" PARAGRAPH
                     87: .Pp
                     88: By default,
                     89: .Nm
1.8     ! kristaps   90: reads
        !            91: .Xr mdoc 7
        !            92: text from stdin, implying
        !            93: .Fl m Ns Ar mdoc ,
        !            94: and prints 78-column backspace-encoded output to stdout as if
1.1       kristaps   95: .Fl T Ns Ar ascii
                     96: were provided.
                     97: .\" PARAGRAPH
                     98: .Pp
                     99: .Ex -std mandoc
                    100: .\" SUB-SECTION
1.8     ! kristaps  101: .Ss Reserved Words (mdoc only)
1.4       kristaps  102: The reserved words described in
                    103: .Xr mdoc 7
                    104: are handled according to the following rules:
                    105: .Bl -enum -offset XXX
                    106: .It
                    107: Opening delimiters
                    108: .Po
                    109: .Sq \&( ,
                    110: .Sq \&[ ,
                    111: and
                    112: .Sq \&{
                    113: .Pc are not followed by whitespace.
                    114: .It
                    115: Closing delimiters
                    116: .Po
                    117: .Sq \&. ,
                    118: .Sq \&, ,
                    119: .Sq \&; ,
                    120: .Sq \&: ,
                    121: .Sq \&? ,
                    122: .Sq \&! ,
                    123: .Sq \&) ,
                    124: .Sq \&]
                    125: and
                    126: .Sq \&}
                    127: .Pc are not preceeded by whitespace.
                    128: .El
                    129: .\" PARAGRAPH
                    130: .Pp
1.7       kristaps  131: Note that reserved words only register as such as if they appear as
                    132: standalone tokens, either in parsed lines or streams of text.  Thus, the
                    133: following fragment:
1.4       kristaps  134: .Bd -literal -offset XXXX
                    135: this self is not that of the waking , empirically real man
                    136: .Ed
                    137: .\" PARAGRAPH
                    138: .Pp
                    139: \&...correctly adjusts the comma spacing to
1.7       kristaps  140: .Dq this self is not that of the waking , empirically real man .
                    141: However, if the comma were part of
                    142: .Dq ,empirically ,
                    143: it would not.
1.4       kristaps  144: .\" SUB-SECTION
1.8     ! kristaps  145: .Ss Input Formats
        !           146: The
        !           147: .Nm
        !           148: utility accepts
        !           149: .Xr mdoc 7
        !           150: and
        !           151: .Xr man 7
        !           152: input with
        !           153: .Fl m Ns Ar mdoc
        !           154: and
        !           155: .Fl m Ns Ar man ,
        !           156: respectively.  The
        !           157: .Xr mdoc 7
        !           158: format is
        !           159: .Em strongly
        !           160: recommended;
        !           161: .Xr man 7
        !           162: should only be used for legacy manuals.
        !           163: .Pp
        !           164: Note that the
        !           165: .Fl m Ns Ar man
        !           166: option is experimental and only works with
        !           167: .Fl T Ns Ar tree .
        !           168: .\" SUB-SECTION
1.1       kristaps  169: .Ss Output Formats
                    170: The
                    171: .Nm
                    172: utility accepts the following
                    173: .Fl T
                    174: arguments:
                    175: .Bl -tag -width XXXXXXXXXXXX -offset XXXX
                    176: .It Ar ascii
                    177: Produce 7-bit ASCII output, backspace-encoded for bold and underline
                    178: styles.  This is the default.
                    179: .It Ar tree
                    180: Produce an indented parse tree.
                    181: .It Ar lint
                    182: Parse only: produce no output.
                    183: .El
                    184: .\" SUB-SECTION
                    185: .Ss Compiler Options
                    186: Default compiler behaviour may be overriden with the
                    187: .Fl f
                    188: flag.
                    189: .Bl -tag -width XXXXXXXXXXXX -offset XXXX
                    190: .It Fl f Ns Ar ign-scope
                    191: When rewinding the scope of a block macro, forces the compiler to ignore
                    192: scope violations.  This can seriously mangle the resulting tree.
1.8     ! kristaps  193: .Pq mdoc only
1.1       kristaps  194: .It Fl f Ns Ar ign-escape
                    195: Ignore invalid escape sequences.
                    196: .It Fl f Ns Ar ign-macro
                    197: Ignore unknown macros at the start of input lines.
                    198: .El
                    199: .\" PARAGRAPH
                    200: .Pp
                    201: As with the
                    202: .Fl W
                    203: flag, multiple
                    204: .Fl f
                    205: options may be grouped and delimited with a comma.  Using
                    206: .Fl f Ns Ar ign-scope,ign-escape ,
                    207: for example, will try to ignore scope and character-escape errors.
                    208: .\" SECTION
                    209: .Sh EXAMPLES
                    210: To page this manual page on the terminal:
                    211: .\" PARAGRAPH
                    212: .Pp
                    213: .D1 % mandoc \-Wall,error mandoc.1 2>&1 | less
                    214: .\" SECTION
                    215: .Sh SEE ALSO
                    216: .Xr mdoc 7
                    217: .\"
                    218: .Sh AUTHORS
                    219: The
                    220: .Nm
                    221: utility was written by
                    222: .An Kristaps Dzonsons Aq kristaps@openbsd.org .
                    223: .\" SECTION
                    224: .Sh CAVEATS
                    225: The
                    226: .Nm
1.5       kristaps  227: utility in
                    228: .Fl T Ns Ar ascii
                    229: mode doesn't yet know how to display the following:
1.1       kristaps  230: .Pp
                    231: .Bl -bullet -compact
                    232: .It
                    233: The \-hang
                    234: .Sq \&Bl
                    235: list is not yet supported.
1.7       kristaps  236: .El
                    237: .Pp
                    238: Other macros still aren't supported by virtue of nobody complaining
                    239: about their absence.  Please report any omissions: this is a work in
                    240: progress.
                    241: .Pp
                    242: The following list documents differences between traditional
                    243: .Xr nroff 1
                    244: output and
                    245: .Nm :
                    246: .Pp
                    247: .Bl -bullet -compact
                    248: .It
                    249: A list of display following
                    250: .Sq \&Ss
                    251: does not assert a prior vertical break, just as it doesn't with
                    252: .Sq \&Sh .
                    253: .It
                    254: Special characters don't follow the current font style.
1.5       kristaps  255: .\" LIST-ITEM
1.1       kristaps  256: .It
                    257: The \-literal and \-unfilled
                    258: .Sq \&Bd
1.3       kristaps  259: displays types are synonyms, as are \-filled and \-ragged.
1.1       kristaps  260: .El

CVSweb