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

Annotation of mandoc/mandoc.1, Revision 1.31

1.31    ! kristaps    1: .\"    $Id: mandoc.1,v 1.30 2009/08/19 09:14:50 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.26      kristaps   37: utility formats
1.8       kristaps   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...
1.26      kristaps   43: Override default compiler behaviour.  See
1.1       kristaps   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...
1.24      kristaps   63: Configure warning messages.  Use
1.1       kristaps   64: .Fl W Ns Ar all
1.24      kristaps   65: to print warnings,
1.26      kristaps   66: .Fl W Ns Ar error
1.24      kristaps   67: for warnings to be considered errors and cause utility
1.26      kristaps   68: termination.  Multiple
1.1       kristaps   69: .Fl W
                     70: arguments may be comma-separated, such as
                     71: .Fl W Ns Ar error,all .
                     72: .\" ITEM
                     73: .It Ar infile...
                     74: Read input from zero or more
                     75: .Ar infile .
1.2       kristaps   76: If unspecified, reads from stdin.  If multiple files are specified,
                     77: .Nm
                     78: will halt with the first failed parse.
1.1       kristaps   79: .El
                     80: .\" PARAGRAPH
                     81: .Pp
1.26      kristaps   82: By default,
                     83: .Nm
                     84: reads
1.8       kristaps   85: .Xr mdoc 7
1.12      kristaps   86: or
                     87: .Xr man 7
1.8       kristaps   88: text from stdin, implying
1.12      kristaps   89: .Fl m Ns Ar andoc ,
1.8       kristaps   90: and prints 78-column backspace-encoded output to stdout as if
1.1       kristaps   91: .Fl T Ns Ar ascii
                     92: were provided.
                     93: .\" PARAGRAPH
                     94: .Pp
                     95: .Ex -std mandoc
                     96: .\" SUB-SECTION
1.22      kristaps   97: .Ss Punctuation and Spacing
1.13      kristaps   98: If punctuation is set apart from words, such as in the phrase
                     99: .Dq to be \&, or not to be ,
                    100: it's processed by
                    101: .Nm
1.22      kristaps  102: according to the following rules:  opening punctuation
1.4       kristaps  103: .Po
1.26      kristaps  104: .Sq \&( ,
                    105: .Sq \&[ ,
1.4       kristaps  106: and
                    107: .Sq \&{
1.26      kristaps  108: .Pc
1.22      kristaps  109: is not followed by a space; closing punctuation
1.4       kristaps  110: .Po
1.26      kristaps  111: .Sq \&. ,
                    112: .Sq \&, ,
                    113: .Sq \&; ,
                    114: .Sq \&: ,
                    115: .Sq \&? ,
                    116: .Sq \&! ,
                    117: .Sq \&) ,
                    118: .Sq \&]
1.4       kristaps  119: and
                    120: .Sq \&}
1.26      kristaps  121: .Pc
1.15      kristaps  122: is not preceded by whitespace.
1.4       kristaps  123: .Pp
1.13      kristaps  124: If the input is
                    125: .Xr mdoc 7 ,
                    126: these rules are also applied to macro arguments when appropriate.
1.22      kristaps  127: .Pp
                    128: White-space, in non-literal (normal) mode, is stripped from input and
                    129: replaced on output by a single space.  Thus, if you wish to preserve
                    130: multiple spaces, they must be space-escaped
1.26      kristaps  131: .Sq \e\
                    132: or used in a literal display mode, e.g.,
1.27      kristaps  133: .Sq \&Bd \-literal
1.26      kristaps  134: in
1.22      kristaps  135: .Xr mdoc 7 .
1.4       kristaps  136: .\" SUB-SECTION
1.8       kristaps  137: .Ss Input Formats
                    138: The
                    139: .Nm
                    140: utility accepts
                    141: .Xr mdoc 7
                    142: and
                    143: .Xr man 7
                    144: input with
1.10      kristaps  145: .Fl m Ns Ar doc
1.8       kristaps  146: and
1.10      kristaps  147: .Fl m Ns Ar an ,
1.8       kristaps  148: respectively.  The
                    149: .Xr mdoc 7
                    150: format is
                    151: .Em strongly
1.26      kristaps  152: recommended;
1.8       kristaps  153: .Xr man 7
                    154: should only be used for legacy manuals.
1.11      kristaps  155: .Pp
1.12      kristaps  156: A third option,
                    157: .Fl m Ns Ar andoc ,
1.13      kristaps  158: which is also the default, determines encoding on-the-fly: if the first
1.26      kristaps  159: non-comment macro is
1.27      kristaps  160: .Sq \&Dd
1.13      kristaps  161: or
1.27      kristaps  162: .Sq \&Dt ,
1.26      kristaps  163: the
1.13      kristaps  164: .Xr mdoc 7
                    165: parser is used; otherwise, the
                    166: .Xr man 7
                    167: parser is used.
                    168: .Pp
                    169: If multiple
1.26      kristaps  170: files are specified with
                    171: .Fl m Ns Ar andoc ,
1.13      kristaps  172: each has its file-type determined this way.  If multiple files are
                    173: specified and
1.12      kristaps  174: .Fl m Ns Ar doc
                    175: or
                    176: .Fl m Ns Ar an
                    177: is specified, then this format is used exclusively.
1.13      kristaps  178: .\" .Pp
                    179: .\" The following escape sequences are recognised, although the per-format
                    180: .\" compiler may not allow certain sequences.
                    181: .\" .Bl -tag -width Ds -offset XXXX
                    182: .\" .It \efX
                    183: .\" sets the font mode to X (B, I, R or P, where P resets the font)
                    184: .\" .It \eX, \e(XX, \e[XN]
                    185: .\" queries the special-character table for a corresponding symbol
                    186: .\" .It \e*X, \e*(XX, \e*[XN]
                    187: .\" deprecated special-character format
                    188: .\" .El
1.8       kristaps  189: .\" SUB-SECTION
1.1       kristaps  190: .Ss Output Formats
                    191: The
                    192: .Nm
                    193: utility accepts the following
                    194: .Fl T
                    195: arguments:
1.19      kristaps  196: .Bl -tag -width Ds
1.13      kristaps  197: .It Fl T Ns Ar ascii
1.1       kristaps  198: Produce 7-bit ASCII output, backspace-encoded for bold and underline
                    199: styles.  This is the default.
1.13      kristaps  200: .It Fl T Ns Ar tree
1.1       kristaps  201: Produce an indented parse tree.
1.13      kristaps  202: .It Fl T Ns Ar lint
1.1       kristaps  203: Parse only: produce no output.
                    204: .El
1.13      kristaps  205: .Pp
                    206: If multiple input files are specified, these will be processed by the
                    207: corresponding filter in-order.
1.1       kristaps  208: .\" SUB-SECTION
                    209: .Ss Compiler Options
                    210: Default compiler behaviour may be overriden with the
                    211: .Fl f
                    212: flag.
1.19      kristaps  213: .Bl -tag -width Ds
1.1       kristaps  214: .It Fl f Ns Ar ign-scope
                    215: When rewinding the scope of a block macro, forces the compiler to ignore
                    216: scope violations.  This can seriously mangle the resulting tree.
1.8       kristaps  217: .Pq mdoc only
1.21      kristaps  218: .It Fl f Ns Ar no-ign-escape
                    219: Don't ignore invalid escape sequences.
1.12      kristaps  220: .It Fl f Ns Ar no-ign-macro
1.21      kristaps  221: Do not ignore unknown macros at the start of input lines.
                    222: .It Fl f Ns Ar no-ign-chars
                    223: Do not ignore disallowed characters.
                    224: .It Fl f Ns Ar strict
1.26      kristaps  225: Implies
1.21      kristaps  226: .Fl f Ns Ar no-ign-escape ,
1.26      kristaps  227: .Fl f Ns Ar no-ign-macro
1.21      kristaps  228: and
1.26      kristaps  229: .Fl f Ns Ar no-ign-chars .
1.28      kristaps  230: .It Fl f Ns Ar ign-errors
                    231: Don't halt when encountering parse errors.  Useful with
                    232: .Fl T Ns Ar lint
                    233: over a large set of manuals passed on the command line.
1.1       kristaps  234: .El
                    235: .\" PARAGRAPH
                    236: .Pp
                    237: As with the
                    238: .Fl W
                    239: flag, multiple
                    240: .Fl f
                    241: options may be grouped and delimited with a comma.  Using
1.21      kristaps  242: .Fl f Ns Ar ign-scope,no-ign-escape ,
                    243: for example, will try to ignore scope and not ignore character-escape
                    244: errors.
1.1       kristaps  245: .\" SECTION
                    246: .Sh EXAMPLES
1.13      kristaps  247: To page manuals to the terminal:
1.1       kristaps  248: .\" PARAGRAPH
                    249: .Pp
1.21      kristaps  250: .D1 % mandoc \-Wall,error \-fstrict mandoc.1 2>&1 | less
1.13      kristaps  251: .D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
1.28      kristaps  252: .\" PARAGRAPH
                    253: .Pp
                    254: To check over a large set of manuals:
                    255: .\" PARAGRAPH
                    256: .Pp
                    257: .Dl % mandoc \-Tlint \-fign-errors `find /usr/src -name \e*\e.[1-9]`
1.1       kristaps  258: .\" SECTION
1.20      kristaps  259: .Sh COMPATIBILITY
1.31    ! kristaps  260: .\" FIXME: libman `na' and `DT' have no effect.
1.26      kristaps  261: This section summarises
1.20      kristaps  262: .Nm
1.26      kristaps  263: compatibility with
1.20      kristaps  264: .Xr groff 1 .
                    265: .Pp
                    266: .Bl -bullet -compact
1.29      kristaps  267: .\" LIST-ITEM
                    268: .It
                    269: The
                    270: .Sq \e~
                    271: special character doesn't produce expected behaviour.
                    272: .\" LIST-ITEM
1.26      kristaps  273: .It
1.27      kristaps  274: In
                    275: .Xr groff 1 ,
                    276: the
                    277: .Sq \&Pa
                    278: macro does not underline when under a
1.30      kristaps  279: .Sq \&It
                    280: in the FILES section.  This behaves correctly in
1.27      kristaps  281: .Nm .
1.29      kristaps  282: .\" LIST-ITEM
1.27      kristaps  283: .It
1.20      kristaps  284: A list or display following
1.27      kristaps  285: .Sq \&Ss
1.20      kristaps  286: does not assert a prior vertical break, just as it doesn't with
1.27      kristaps  287: .Sq \&Sh .
1.20      kristaps  288: .It
1.26      kristaps  289: The \-literal and \-unfilled
1.27      kristaps  290: .Sq \&Bd
1.20      kristaps  291: displays types are synonyms, as are \-filled and \-ragged.
1.29      kristaps  292: .\" LIST-ITEM
1.20      kristaps  293: .It
                    294: Words aren't hyphenated.
1.29      kristaps  295: .\" LIST-ITEM
1.22      kristaps  296: .It
                    297: In normal mode (not a literal block), blocks of spaces aren't preserved,
1.29      kristaps  298: so double spaces following sentence closure are reduced to a single space.
1.20      kristaps  299: .El
                    300: .\" SECTION
1.1       kristaps  301: .Sh SEE ALSO
1.13      kristaps  302: .Xr mandoc_char 7 ,
1.9       kristaps  303: .Xr mdoc 7 ,
                    304: .Xr man 7
1.20      kristaps  305: .\" SECTION
1.1       kristaps  306: .Sh AUTHORS
                    307: The
                    308: .Nm
1.26      kristaps  309: utility was written by
1.18      kristaps  310: .An Kristaps Dzonsons Aq kristaps@kth.se .

CVSweb