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

Annotation of mandoc/mandoc.1, Revision 1.15

1.15    ! kristaps    1: .\" $Id: mandoc.1,v 1.14 2009/04/12 19:19:57 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$
1.14      kristaps   20: .Dt MANDOC 1
1.1       kristaps   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
1.12      kristaps   53: .Fl m Ns Ar andoc .
1.8       kristaps   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
1.12      kristaps   92: or
                     93: .Xr man 7
1.8       kristaps   94: text from stdin, implying
1.12      kristaps   95: .Fl m Ns Ar andoc ,
1.8       kristaps   96: and prints 78-column backspace-encoded output to stdout as if
1.1       kristaps   97: .Fl T Ns Ar ascii
                     98: were provided.
                     99: .\" PARAGRAPH
                    100: .Pp
                    101: .Ex -std mandoc
                    102: .\" SUB-SECTION
1.13      kristaps  103: .Ss Punctuation
                    104: If punctuation is set apart from words, such as in the phrase
                    105: .Dq to be \&, or not to be ,
                    106: it's processed by
                    107: .Nm
                    108: according to the following rules.  Opening punctuation
1.4       kristaps  109: .Po
                    110: .Sq \&( ,
                    111: .Sq \&[ ,
                    112: and
                    113: .Sq \&{
1.13      kristaps  114: .Pc
                    115: is not followed by a space. Closing punctuation
1.4       kristaps  116: .Po
                    117: .Sq \&. ,
                    118: .Sq \&, ,
                    119: .Sq \&; ,
                    120: .Sq \&: ,
                    121: .Sq \&? ,
                    122: .Sq \&! ,
                    123: .Sq \&) ,
                    124: .Sq \&]
                    125: and
                    126: .Sq \&}
1.13      kristaps  127: .Pc
1.15    ! kristaps  128: is not preceded by whitespace.
1.4       kristaps  129: .Pp
1.13      kristaps  130: If the input is
                    131: .Xr mdoc 7 ,
                    132: these rules are also applied to macro arguments when appropriate.
1.4       kristaps  133: .\" SUB-SECTION
1.8       kristaps  134: .Ss Input Formats
                    135: The
                    136: .Nm
                    137: utility accepts
                    138: .Xr mdoc 7
                    139: and
                    140: .Xr man 7
                    141: input with
1.10      kristaps  142: .Fl m Ns Ar doc
1.8       kristaps  143: and
1.10      kristaps  144: .Fl m Ns Ar an ,
1.8       kristaps  145: respectively.  The
                    146: .Xr mdoc 7
                    147: format is
                    148: .Em strongly
                    149: recommended;
                    150: .Xr man 7
                    151: should only be used for legacy manuals.
1.11      kristaps  152: .Pp
1.12      kristaps  153: A third option,
                    154: .Fl m Ns Ar andoc ,
1.13      kristaps  155: which is also the default, determines encoding on-the-fly: if the first
                    156: non-comment macro is
                    157: .Sq \&.Dd
                    158: or
                    159: .Sq \&.Dt ,
                    160: the
                    161: .Xr mdoc 7
                    162: parser is used; otherwise, the
                    163: .Xr man 7
                    164: parser is used.
                    165: .Pp
                    166: If multiple
                    167: files are specified with
                    168: .Fl m Ns Ar andoc ,
                    169: each has its file-type determined this way.  If multiple files are
                    170: specified and
1.12      kristaps  171: .Fl m Ns Ar doc
                    172: or
                    173: .Fl m Ns Ar an
                    174: is specified, then this format is used exclusively.
1.13      kristaps  175: .\" .Pp
                    176: .\" The following escape sequences are recognised, although the per-format
                    177: .\" compiler may not allow certain sequences.
                    178: .\" .Bl -tag -width Ds -offset XXXX
                    179: .\" .It \efX
                    180: .\" sets the font mode to X (B, I, R or P, where P resets the font)
                    181: .\" .It \eX, \e(XX, \e[XN]
                    182: .\" queries the special-character table for a corresponding symbol
                    183: .\" .It \e*X, \e*(XX, \e*[XN]
                    184: .\" deprecated special-character format
                    185: .\" .El
1.8       kristaps  186: .\" SUB-SECTION
1.1       kristaps  187: .Ss Output Formats
                    188: The
                    189: .Nm
                    190: utility accepts the following
                    191: .Fl T
                    192: arguments:
1.13      kristaps  193: .Bl -tag -width XXXXXXXXXXXX
                    194: .It Fl T Ns Ar ascii
1.1       kristaps  195: Produce 7-bit ASCII output, backspace-encoded for bold and underline
                    196: styles.  This is the default.
1.13      kristaps  197: .It Fl T Ns Ar tree
1.1       kristaps  198: Produce an indented parse tree.
1.13      kristaps  199: .It Fl T Ns Ar lint
1.1       kristaps  200: Parse only: produce no output.
                    201: .El
1.13      kristaps  202: .Pp
                    203: If multiple input files are specified, these will be processed by the
                    204: corresponding filter in-order.
1.1       kristaps  205: .\" SUB-SECTION
                    206: .Ss Compiler Options
                    207: Default compiler behaviour may be overriden with the
                    208: .Fl f
                    209: flag.
1.13      kristaps  210: .Bl -tag -width XXXXXXXXXXXXXX
1.1       kristaps  211: .It Fl f Ns Ar ign-scope
                    212: When rewinding the scope of a block macro, forces the compiler to ignore
                    213: scope violations.  This can seriously mangle the resulting tree.
1.8       kristaps  214: .Pq mdoc only
1.1       kristaps  215: .It Fl f Ns Ar ign-escape
                    216: Ignore invalid escape sequences.
                    217: .It Fl f Ns Ar ign-macro
1.12      kristaps  218: Ignore unknown macros at the start of input lines (default for
                    219: .Xr man 7
                    220: parsing).
                    221: .It Fl f Ns Ar no-ign-macro
                    222: Do not ignore unknown macros at the start of input lines (default for
                    223: .Xr mdoc 7
                    224: parsing).
1.1       kristaps  225: .El
                    226: .\" PARAGRAPH
                    227: .Pp
                    228: As with the
                    229: .Fl W
                    230: flag, multiple
                    231: .Fl f
                    232: options may be grouped and delimited with a comma.  Using
                    233: .Fl f Ns Ar ign-scope,ign-escape ,
                    234: for example, will try to ignore scope and character-escape errors.
                    235: .\" SECTION
                    236: .Sh EXAMPLES
1.13      kristaps  237: To page manuals to the terminal:
1.1       kristaps  238: .\" PARAGRAPH
                    239: .Pp
                    240: .D1 % mandoc \-Wall,error mandoc.1 2>&1 | less
1.13      kristaps  241: .Pp
                    242: .D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
1.1       kristaps  243: .\" SECTION
                    244: .Sh SEE ALSO
1.13      kristaps  245: .Xr mandoc_char 7 ,
1.9       kristaps  246: .Xr mdoc 7 ,
                    247: .Xr man 7
1.1       kristaps  248: .\"
                    249: .Sh AUTHORS
                    250: The
                    251: .Nm
                    252: utility was written by
                    253: .An Kristaps Dzonsons Aq kristaps@openbsd.org .
                    254: .\" SECTION
                    255: .Sh CAVEATS
                    256: The
                    257: .Nm
1.5       kristaps  258: utility in
                    259: .Fl T Ns Ar ascii
                    260: mode doesn't yet know how to display the following:
1.1       kristaps  261: .Pp
                    262: .Bl -bullet -compact
                    263: .It
                    264: The \-hang
1.10      kristaps  265: .Sq \&.Bl
1.1       kristaps  266: list is not yet supported.
1.7       kristaps  267: .El
                    268: .Pp
                    269: Other macros still aren't supported by virtue of nobody complaining
                    270: about their absence.  Please report any omissions: this is a work in
                    271: progress.
                    272: .Pp
                    273: The following list documents differences between traditional
                    274: .Xr nroff 1
                    275: output and
                    276: .Nm :
                    277: .Pp
                    278: .Bl -bullet -compact
                    279: .It
                    280: A list of display following
1.10      kristaps  281: .Sq \&.Ss
1.7       kristaps  282: does not assert a prior vertical break, just as it doesn't with
1.10      kristaps  283: .Sq \&.Sh .
1.7       kristaps  284: .It
                    285: Special characters don't follow the current font style.
1.5       kristaps  286: .\" LIST-ITEM
1.1       kristaps  287: .It
                    288: The \-literal and \-unfilled
1.10      kristaps  289: .Sq \&.Bd
1.3       kristaps  290: displays types are synonyms, as are \-filled and \-ragged.
1.1       kristaps  291: .El

CVSweb