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

Annotation of mandoc/mandoc.1, Revision 1.32

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

CVSweb