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

Annotation of mandoc/mandoc.1, Revision 1.19

1.19    ! kristaps    1: .\"    $Id: mandoc.1,v 1.18 2009/06/11 07:26:35 kristaps Exp $
1.1       kristaps    2: .\"
1.17      kristaps    3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
1.1       kristaps    4: .\"
                      5: .\" Permission to use, copy, modify, and distribute this software for any
1.16      kristaps    6: .\" purpose with or without fee is hereby granted, provided that the above
                      7: .\" copyright notice and this permission notice appear in all copies.
1.1       kristaps    8: .\"
1.16      kristaps    9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
                     10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
                     11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
                     12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
                     13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
                     14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
                     15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
1.1       kristaps   16: .\"
                     17: .Dd $Mdocdate$
1.14      kristaps   18: .Dt MANDOC 1
1.1       kristaps   19: .Os
                     20: .\" SECTION
                     21: .Sh NAME
                     22: .Nm mandoc
1.8       kristaps   23: .Nd format and display UNIX manuals
1.1       kristaps   24: .\" SECTION
                     25: .Sh SYNOPSIS
                     26: .Nm mandoc
                     27: .Op Fl V
                     28: .Op Fl f Ns Ar option...
1.8       kristaps   29: .Op Fl m Ns Ar format
1.1       kristaps   30: .Op Fl W Ns Ar err...
                     31: .Op Fl T Ns Ar output
                     32: .Op Ar infile...
                     33: .\" SECTION
                     34: .Sh DESCRIPTION
                     35: The
                     36: .Nm
1.8       kristaps   37: utility formats
                     38: .Ux
                     39: manual pages for display.  The arguments are as follows:
1.19    ! kristaps   40: .Bl -tag -width Ds
1.1       kristaps   41: .\" ITEM
                     42: .It Fl f Ns Ar option...
                     43: Override default compiler behaviour.  See
                     44: .Sx Compiler Options
                     45: for details.
                     46: .\" ITEM
1.19    ! kristaps   47: .It Fl m Ns Ar format
1.8       kristaps   48: Input format.  See
                     49: .Sx Input Formats
                     50: for available formats.  Defaults to
1.12      kristaps   51: .Fl m Ns Ar andoc .
1.8       kristaps   52: .\" ITEM
1.19    ! kristaps   53: .It Fl T Ns Ar output
1.1       kristaps   54: Output format.  See
                     55: .Sx Output Formats
                     56: for available formats.  Defaults to
                     57: .Fl T Ns Ar ascii .
                     58: .\" ITEM
                     59: .It Fl V
                     60: Print version and exit.
                     61: .\" ITEM
                     62: .It Fl W Ns Ar err...
                     63: Print warning messages.  May be set to
                     64: .Fl W Ns Ar all
                     65: for all warnings,
                     66: .Ar compat
                     67: for groff/troff-compatibility warnings, or
                     68: .Ar syntax
                     69: for syntax warnings.  If
                     70: .Fl W Ns Ar error
                     71: is specified, warnings are considered errors and cause utility
                     72: termination.  Multiple
                     73: .Fl W
                     74: arguments may be comma-separated, such as
                     75: .Fl W Ns Ar error,all .
                     76: .\" ITEM
                     77: .It Ar infile...
                     78: Read input from zero or more
                     79: .Ar infile .
1.2       kristaps   80: If unspecified, reads from stdin.  If multiple files are specified,
                     81: .Nm
                     82: will halt with the first failed parse.
1.1       kristaps   83: .El
                     84: .\" PARAGRAPH
                     85: .Pp
                     86: By default,
                     87: .Nm
1.8       kristaps   88: reads
                     89: .Xr mdoc 7
1.12      kristaps   90: or
                     91: .Xr man 7
1.8       kristaps   92: text from stdin, implying
1.12      kristaps   93: .Fl m Ns Ar andoc ,
1.8       kristaps   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.13      kristaps  101: .Ss Punctuation
                    102: If punctuation is set apart from words, such as in the phrase
                    103: .Dq to be \&, or not to be ,
                    104: it's processed by
                    105: .Nm
                    106: according to the following rules.  Opening punctuation
1.4       kristaps  107: .Po
                    108: .Sq \&( ,
                    109: .Sq \&[ ,
                    110: and
                    111: .Sq \&{
1.13      kristaps  112: .Pc
                    113: is not followed by a space. Closing punctuation
1.4       kristaps  114: .Po
                    115: .Sq \&. ,
                    116: .Sq \&, ,
                    117: .Sq \&; ,
                    118: .Sq \&: ,
                    119: .Sq \&? ,
                    120: .Sq \&! ,
                    121: .Sq \&) ,
                    122: .Sq \&]
                    123: and
                    124: .Sq \&}
1.13      kristaps  125: .Pc
1.15      kristaps  126: is not preceded by whitespace.
1.4       kristaps  127: .Pp
1.13      kristaps  128: If the input is
                    129: .Xr mdoc 7 ,
                    130: these rules are also applied to macro arguments when appropriate.
1.4       kristaps  131: .\" SUB-SECTION
1.8       kristaps  132: .Ss Input Formats
                    133: The
                    134: .Nm
                    135: utility accepts
                    136: .Xr mdoc 7
                    137: and
                    138: .Xr man 7
                    139: input with
1.10      kristaps  140: .Fl m Ns Ar doc
1.8       kristaps  141: and
1.10      kristaps  142: .Fl m Ns Ar an ,
1.8       kristaps  143: respectively.  The
                    144: .Xr mdoc 7
                    145: format is
                    146: .Em strongly
                    147: recommended;
                    148: .Xr man 7
                    149: should only be used for legacy manuals.
1.11      kristaps  150: .Pp
1.12      kristaps  151: A third option,
                    152: .Fl m Ns Ar andoc ,
1.13      kristaps  153: which is also the default, determines encoding on-the-fly: if the first
                    154: non-comment macro is
                    155: .Sq \&.Dd
                    156: or
                    157: .Sq \&.Dt ,
                    158: the
                    159: .Xr mdoc 7
                    160: parser is used; otherwise, the
                    161: .Xr man 7
                    162: parser is used.
                    163: .Pp
                    164: If multiple
                    165: files are specified with
                    166: .Fl m Ns Ar andoc ,
                    167: each has its file-type determined this way.  If multiple files are
                    168: specified and
1.12      kristaps  169: .Fl m Ns Ar doc
                    170: or
                    171: .Fl m Ns Ar an
                    172: is specified, then this format is used exclusively.
1.13      kristaps  173: .\" .Pp
                    174: .\" The following escape sequences are recognised, although the per-format
                    175: .\" compiler may not allow certain sequences.
                    176: .\" .Bl -tag -width Ds -offset XXXX
                    177: .\" .It \efX
                    178: .\" sets the font mode to X (B, I, R or P, where P resets the font)
                    179: .\" .It \eX, \e(XX, \e[XN]
                    180: .\" queries the special-character table for a corresponding symbol
                    181: .\" .It \e*X, \e*(XX, \e*[XN]
                    182: .\" deprecated special-character format
                    183: .\" .El
1.8       kristaps  184: .\" SUB-SECTION
1.1       kristaps  185: .Ss Output Formats
                    186: The
                    187: .Nm
                    188: utility accepts the following
                    189: .Fl T
                    190: arguments:
1.19    ! kristaps  191: .Bl -tag -width Ds
1.13      kristaps  192: .It Fl T Ns Ar ascii
1.1       kristaps  193: Produce 7-bit ASCII output, backspace-encoded for bold and underline
                    194: styles.  This is the default.
1.13      kristaps  195: .It Fl T Ns Ar tree
1.1       kristaps  196: Produce an indented parse tree.
1.13      kristaps  197: .It Fl T Ns Ar lint
1.1       kristaps  198: Parse only: produce no output.
                    199: .El
1.13      kristaps  200: .Pp
                    201: If multiple input files are specified, these will be processed by the
                    202: corresponding filter in-order.
1.1       kristaps  203: .\" SUB-SECTION
                    204: .Ss Compiler Options
                    205: Default compiler behaviour may be overriden with the
                    206: .Fl f
                    207: flag.
1.19    ! kristaps  208: .Bl -tag -width Ds
1.1       kristaps  209: .It Fl f Ns Ar ign-scope
                    210: When rewinding the scope of a block macro, forces the compiler to ignore
                    211: scope violations.  This can seriously mangle the resulting tree.
1.8       kristaps  212: .Pq mdoc only
1.1       kristaps  213: .It Fl f Ns Ar ign-escape
                    214: Ignore invalid escape sequences.
                    215: .It Fl f Ns Ar ign-macro
1.12      kristaps  216: Ignore unknown macros at the start of input lines (default for
                    217: .Xr man 7
                    218: parsing).
                    219: .It Fl f Ns Ar no-ign-macro
                    220: Do not ignore unknown macros at the start of input lines (default for
                    221: .Xr mdoc 7
                    222: parsing).
1.1       kristaps  223: .El
                    224: .\" PARAGRAPH
                    225: .Pp
                    226: As with the
                    227: .Fl W
                    228: flag, multiple
                    229: .Fl f
                    230: options may be grouped and delimited with a comma.  Using
                    231: .Fl f Ns Ar ign-scope,ign-escape ,
                    232: for example, will try to ignore scope and character-escape errors.
                    233: .\" SECTION
                    234: .Sh EXAMPLES
1.13      kristaps  235: To page manuals to the terminal:
1.1       kristaps  236: .\" PARAGRAPH
                    237: .Pp
                    238: .D1 % mandoc \-Wall,error mandoc.1 2>&1 | less
1.13      kristaps  239: .Pp
                    240: .D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
1.1       kristaps  241: .\" SECTION
                    242: .Sh SEE ALSO
1.13      kristaps  243: .Xr mandoc_char 7 ,
1.9       kristaps  244: .Xr mdoc 7 ,
                    245: .Xr man 7
1.1       kristaps  246: .\"
                    247: .Sh AUTHORS
                    248: The
                    249: .Nm
                    250: utility was written by
1.18      kristaps  251: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.1       kristaps  252: .\" SECTION
                    253: .Sh CAVEATS
                    254: The
                    255: .Nm
1.5       kristaps  256: utility in
                    257: .Fl T Ns Ar ascii
                    258: mode doesn't yet know how to display the following:
1.1       kristaps  259: .Pp
                    260: .Bl -bullet -compact
                    261: .It
                    262: The \-hang
1.10      kristaps  263: .Sq \&.Bl
1.1       kristaps  264: list is not yet supported.
1.7       kristaps  265: .El
                    266: .Pp
                    267: Other macros still aren't supported by virtue of nobody complaining
                    268: about their absence.  Please report any omissions: this is a work in
                    269: progress.
                    270: .Pp
                    271: The following list documents differences between traditional
                    272: .Xr nroff 1
                    273: output and
                    274: .Nm :
                    275: .Pp
                    276: .Bl -bullet -compact
                    277: .It
                    278: A list of display following
1.10      kristaps  279: .Sq \&.Ss
1.7       kristaps  280: does not assert a prior vertical break, just as it doesn't with
1.10      kristaps  281: .Sq \&.Sh .
1.7       kristaps  282: .It
                    283: Special characters don't follow the current font style.
1.5       kristaps  284: .\" LIST-ITEM
1.1       kristaps  285: .It
                    286: The \-literal and \-unfilled
1.10      kristaps  287: .Sq \&.Bd
1.3       kristaps  288: displays types are synonyms, as are \-filled and \-ragged.
1.1       kristaps  289: .El

CVSweb