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

Annotation of mandoc/mandoc.1, Revision 1.47

1.47    ! kristaps    1: .\"    $Id: mandoc.1,v 1.46 2009/11/05 10:16:01 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 f Ns Ar option...
1.8       kristaps   30: .Op Fl m Ns Ar format
1.44      kristaps   31: .Op Fl O Ns Ar option...
1.37      kristaps   32: .Op Fl T Ns Ar output
                     33: .Op Fl V
1.1       kristaps   34: .Op Fl W Ns Ar err...
                     35: .Op Ar infile...
1.32      kristaps   36: .
                     37: .
1.1       kristaps   38: .Sh DESCRIPTION
                     39: The
                     40: .Nm
1.26      kristaps   41: utility formats
1.8       kristaps   42: .Ux
                     43: manual pages for display.  The arguments are as follows:
1.32      kristaps   44: .
1.19      kristaps   45: .Bl -tag -width Ds
1.1       kristaps   46: .It Fl f Ns Ar option...
1.37      kristaps   47: Comma-separated compiler options.  See
1.1       kristaps   48: .Sx Compiler Options
                     49: for details.
1.32      kristaps   50: .
1.19      kristaps   51: .It Fl m Ns Ar format
1.8       kristaps   52: Input format.  See
                     53: .Sx Input Formats
                     54: for available formats.  Defaults to
1.12      kristaps   55: .Fl m Ns Ar andoc .
1.32      kristaps   56: .
1.44      kristaps   57: .It Fl O Ns Ar option...
1.37      kristaps   58: Comma-separated output options.  See
                     59: .Sx Output Options
                     60: for details.
                     61: .
1.19      kristaps   62: .It Fl T Ns Ar output
1.1       kristaps   63: Output format.  See
                     64: .Sx Output Formats
                     65: for available formats.  Defaults to
                     66: .Fl T Ns Ar ascii .
1.32      kristaps   67: .
1.1       kristaps   68: .It Fl V
                     69: Print version and exit.
1.32      kristaps   70: .
1.1       kristaps   71: .It Fl W Ns Ar err...
1.37      kristaps   72: Comma-separated warning options.  Use
1.1       kristaps   73: .Fl W Ns Ar all
1.24      kristaps   74: to print warnings,
1.26      kristaps   75: .Fl W Ns Ar error
1.24      kristaps   76: for warnings to be considered errors and cause utility
1.26      kristaps   77: termination.  Multiple
1.1       kristaps   78: .Fl W
                     79: arguments may be comma-separated, such as
                     80: .Fl W Ns Ar error,all .
1.32      kristaps   81: .
1.1       kristaps   82: .It Ar infile...
                     83: Read input from zero or more
                     84: .Ar infile .
1.2       kristaps   85: If unspecified, reads from stdin.  If multiple files are specified,
                     86: .Nm
                     87: will halt with the first failed parse.
1.1       kristaps   88: .El
1.32      kristaps   89: .
1.1       kristaps   90: .Pp
1.26      kristaps   91: By default,
                     92: .Nm
                     93: reads
1.8       kristaps   94: .Xr mdoc 7
1.12      kristaps   95: or
                     96: .Xr man 7
1.8       kristaps   97: text from stdin, implying
1.12      kristaps   98: .Fl m Ns Ar andoc ,
1.8       kristaps   99: and prints 78-column backspace-encoded output to stdout as if
1.1       kristaps  100: .Fl T Ns Ar ascii
                    101: were provided.
1.32      kristaps  102: .
1.1       kristaps  103: .Pp
                    104: .Ex -std mandoc
1.32      kristaps  105: .
                    106: .
1.22      kristaps  107: .Ss Punctuation and Spacing
1.13      kristaps  108: If punctuation is set apart from words, such as in the phrase
                    109: .Dq to be \&, or not to be ,
                    110: it's processed by
                    111: .Nm
1.22      kristaps  112: according to the following rules:  opening punctuation
1.4       kristaps  113: .Po
1.26      kristaps  114: .Sq \&( ,
                    115: .Sq \&[ ,
1.4       kristaps  116: and
                    117: .Sq \&{
1.26      kristaps  118: .Pc
1.22      kristaps  119: is not followed by a space; closing punctuation
1.4       kristaps  120: .Po
1.26      kristaps  121: .Sq \&. ,
                    122: .Sq \&, ,
                    123: .Sq \&; ,
                    124: .Sq \&: ,
                    125: .Sq \&? ,
                    126: .Sq \&! ,
                    127: .Sq \&) ,
                    128: .Sq \&]
1.4       kristaps  129: and
                    130: .Sq \&}
1.26      kristaps  131: .Pc
1.15      kristaps  132: is not preceded by whitespace.
1.32      kristaps  133: .
1.4       kristaps  134: .Pp
1.13      kristaps  135: If the input is
                    136: .Xr mdoc 7 ,
                    137: these rules are also applied to macro arguments when appropriate.
1.32      kristaps  138: .
1.22      kristaps  139: .Pp
                    140: White-space, in non-literal (normal) mode, is stripped from input and
1.33      kristaps  141: replaced on output by a single space.  Thus, if you wish to preserve multiple
                    142: spaces, they must be space-escaped or used in a literal display mode, e.g.,
1.27      kristaps  143: .Sq \&Bd \-literal
1.26      kristaps  144: in
1.22      kristaps  145: .Xr mdoc 7 .
1.32      kristaps  146: .
                    147: .
1.8       kristaps  148: .Ss Input Formats
                    149: The
                    150: .Nm
                    151: utility accepts
                    152: .Xr mdoc 7
                    153: and
                    154: .Xr man 7
                    155: input with
1.10      kristaps  156: .Fl m Ns Ar doc
1.8       kristaps  157: and
1.10      kristaps  158: .Fl m Ns Ar an ,
1.8       kristaps  159: respectively.  The
                    160: .Xr mdoc 7
                    161: format is
                    162: .Em strongly
1.26      kristaps  163: recommended;
1.8       kristaps  164: .Xr man 7
                    165: should only be used for legacy manuals.
1.32      kristaps  166: .
1.11      kristaps  167: .Pp
1.12      kristaps  168: A third option,
                    169: .Fl m Ns Ar andoc ,
1.13      kristaps  170: which is also the default, determines encoding on-the-fly: if the first
1.26      kristaps  171: non-comment macro is
1.27      kristaps  172: .Sq \&Dd
1.13      kristaps  173: or
1.27      kristaps  174: .Sq \&Dt ,
1.26      kristaps  175: the
1.13      kristaps  176: .Xr mdoc 7
                    177: parser is used; otherwise, the
                    178: .Xr man 7
                    179: parser is used.
1.32      kristaps  180: .
1.13      kristaps  181: .Pp
                    182: If multiple
1.26      kristaps  183: files are specified with
                    184: .Fl m Ns Ar andoc ,
1.13      kristaps  185: each has its file-type determined this way.  If multiple files are
                    186: specified and
1.12      kristaps  187: .Fl m Ns Ar doc
                    188: or
                    189: .Fl m Ns Ar an
                    190: is specified, then this format is used exclusively.
1.32      kristaps  191: .
                    192: .
1.1       kristaps  193: .Ss Output Formats
                    194: The
                    195: .Nm
                    196: utility accepts the following
                    197: .Fl T
                    198: arguments:
1.32      kristaps  199: .
1.19      kristaps  200: .Bl -tag -width Ds
1.13      kristaps  201: .It Fl T Ns Ar ascii
1.1       kristaps  202: Produce 7-bit ASCII output, backspace-encoded for bold and underline
                    203: styles.  This is the default.
1.32      kristaps  204: .
1.37      kristaps  205: .It Fl T Ns Ar html
                    206: Produce strict HTML-4.01 output, with a sane default style.
                    207: .
1.13      kristaps  208: .It Fl T Ns Ar tree
1.1       kristaps  209: Produce an indented parse tree.
1.32      kristaps  210: .
1.13      kristaps  211: .It Fl T Ns Ar lint
1.1       kristaps  212: Parse only: produce no output.
                    213: .El
1.32      kristaps  214: .
1.13      kristaps  215: .Pp
                    216: If multiple input files are specified, these will be processed by the
                    217: corresponding filter in-order.
1.32      kristaps  218: .
                    219: .
1.1       kristaps  220: .Ss Compiler Options
1.35      kristaps  221: Default compiler behaviour may be overridden with the
1.1       kristaps  222: .Fl f
                    223: flag.
1.32      kristaps  224: .
1.19      kristaps  225: .Bl -tag -width Ds
1.1       kristaps  226: .It Fl f Ns Ar ign-scope
                    227: When rewinding the scope of a block macro, forces the compiler to ignore
                    228: scope violations.  This can seriously mangle the resulting tree.
1.8       kristaps  229: .Pq mdoc only
1.32      kristaps  230: .
1.45      kristaps  231: .It Fl f Ns Ar ign-escape
                    232: Ignore invalid escape sequences.
                    233: This is the default, but the option can be used to override an earlier
                    234: .Fl f Ns Ar strict .
                    235: .
1.21      kristaps  236: .It Fl f Ns Ar no-ign-escape
                    237: Don't ignore invalid escape sequences.
1.32      kristaps  238: .
1.12      kristaps  239: .It Fl f Ns Ar no-ign-macro
1.21      kristaps  240: Do not ignore unknown macros at the start of input lines.
1.32      kristaps  241: .
1.21      kristaps  242: .It Fl f Ns Ar no-ign-chars
                    243: Do not ignore disallowed characters.
1.32      kristaps  244: .
1.21      kristaps  245: .It Fl f Ns Ar strict
1.26      kristaps  246: Implies
1.21      kristaps  247: .Fl f Ns Ar no-ign-escape ,
1.26      kristaps  248: .Fl f Ns Ar no-ign-macro
1.21      kristaps  249: and
1.26      kristaps  250: .Fl f Ns Ar no-ign-chars .
1.32      kristaps  251: .
1.28      kristaps  252: .It Fl f Ns Ar ign-errors
                    253: Don't halt when encountering parse errors.  Useful with
                    254: .Fl T Ns Ar lint
                    255: over a large set of manuals passed on the command line.
1.1       kristaps  256: .El
1.32      kristaps  257: .
1.37      kristaps  258: .Ss Output Options
                    259: For the time being, only
                    260: .Fl T Ns Ar html
                    261: is the only mode with output options:
                    262: .Bl -tag -width Ds
1.44      kristaps  263: .It Fl O Ns Ar style=style.css
1.37      kristaps  264: The file
                    265: .Ar style.css
                    266: is used for an external style-sheet.  This must be a valid absolute or
                    267: relative URI.
1.44      kristaps  268: .It Fl O Ns Ar includes=fmt
1.40      kristaps  269: The string
                    270: .Ar fmt ,
                    271: for example,
                    272: .Ar ../src/%I.html ,
                    273: is used as a template for linked header files (usually via the
                    274: .Sq \&In
                    275: macro).  Instances of
1.43      kristaps  276: .Sq \&%I
1.40      kristaps  277: are replaced with the include filename.  The default is not to present a
                    278: hyperlink.
1.44      kristaps  279: .It Fl O Ns Ar man=fmt
1.39      kristaps  280: The string
                    281: .Ar fmt ,
                    282: for example,
                    283: .Ar ../html%S/%N.%S.html ,
                    284: is used as a template for linked manuals (usually via the
1.37      kristaps  285: .Sq \&Xr
1.40      kristaps  286: macro).  Instances of
1.43      kristaps  287: .Sq \&%N
1.40      kristaps  288: and
                    289: .Sq %S
                    290: are replaced with the linked manual's name and section, respectively.
                    291: If no section is included, section 1 is assumed.  The default is not to
                    292: present a hyperlink.
1.37      kristaps  293: .El
1.32      kristaps  294: .
1.1       kristaps  295: .Sh EXAMPLES
1.13      kristaps  296: To page manuals to the terminal:
1.32      kristaps  297: .
1.1       kristaps  298: .Pp
1.21      kristaps  299: .D1 % mandoc \-Wall,error \-fstrict mandoc.1 2>&1 | less
1.13      kristaps  300: .D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
1.32      kristaps  301: .
1.28      kristaps  302: .Pp
1.41      kristaps  303: To produce HTML manuals with
                    304: .Ar style.css
                    305: as the style-sheet:
1.38      kristaps  306: .Pp
1.41      kristaps  307: .D1 % mandoc \-Thtml -ostyle=style.css mdoc.7 > mdoc.7.html
1.38      kristaps  308: .Pp
1.28      kristaps  309: To check over a large set of manuals:
1.32      kristaps  310: .
1.28      kristaps  311: .Pp
                    312: .Dl % mandoc \-Tlint \-fign-errors `find /usr/src -name \e*\e.[1-9]`
1.32      kristaps  313: .
                    314: .
1.20      kristaps  315: .Sh COMPATIBILITY
1.26      kristaps  316: This section summarises
1.20      kristaps  317: .Nm
1.26      kristaps  318: compatibility with
1.20      kristaps  319: .Xr groff 1 .
1.32      kristaps  320: Each input and output format is separately noted.
                    321: .
                    322: .
                    323: .Ss ASCII output
1.37      kristaps  324: .Bl -bullet -compact
1.29      kristaps  325: .It
                    326: The
                    327: .Sq \e~
1.32      kristaps  328: special character doesn't produce expected behaviour in
                    329: .Fl T Ns Ar ascii .
                    330: .
                    331: .It
                    332: The
1.33      kristaps  333: .Sq \&Bd \-literal
1.32      kristaps  334: and
                    335: .Sq \&Bd \-unfilled
                    336: macros of
                    337: .Xr mdoc 7
                    338: in
                    339: .Fl T Ns Ar ascii
                    340: are synonyms, as are \-filled and \-ragged.
                    341: .
1.26      kristaps  342: .It
1.27      kristaps  343: In
                    344: .Xr groff 1 ,
                    345: the
                    346: .Sq \&Pa
1.32      kristaps  347: .Xr mdoc 7
                    348: macro does not underline when scoped under an
1.30      kristaps  349: .Sq \&It
                    350: in the FILES section.  This behaves correctly in
1.27      kristaps  351: .Nm .
1.32      kristaps  352: .
1.27      kristaps  353: .It
1.20      kristaps  354: A list or display following
1.27      kristaps  355: .Sq \&Ss
1.32      kristaps  356: .Xr mdoc 7
                    357: macro in
                    358: .Fl T Ns Ar ascii
1.20      kristaps  359: does not assert a prior vertical break, just as it doesn't with
1.27      kristaps  360: .Sq \&Sh .
1.32      kristaps  361: .
1.20      kristaps  362: .It
1.32      kristaps  363: The
                    364: .Sq \&na
                    365: .Xr man 7
1.34      kristaps  366: macro in
1.32      kristaps  367: .Fl T Ns Ar ascii
1.34      kristaps  368: has no effect.
1.32      kristaps  369: .
1.20      kristaps  370: .It
                    371: Words aren't hyphenated.
1.32      kristaps  372: .
1.22      kristaps  373: .It
                    374: In normal mode (not a literal block), blocks of spaces aren't preserved,
1.32      kristaps  375: so double spaces following sentence closure are reduced to a single space;
                    376: .Xr groff 1
                    377: retains spaces.
                    378: .
                    379: .It
                    380: Sentences are unilaterally monospaced.
1.20      kristaps  381: .El
1.42      kristaps  382: .
                    383: .Ss HTML output
                    384: .Bl -bullet -compact
                    385: .It
                    386: The
1.47    ! kristaps  387: .Sq \efP
        !           388: escape will revert the font to the previous
        !           389: .Sq \ef
        !           390: escape, not to the last rendered decoration, which is now dictated by
        !           391: CSS instead of hard-coded.  It also will not span past the current
        !           392: scope, for the same reason.  Note that in
        !           393: .Sx ASCII Output
        !           394: mode, this will work fine.
        !           395: .It
        !           396: The
1.42      kristaps  397: .Xr mdoc 7
                    398: .Sq \&Bl \-hang
                    399: and
                    400: .Sq \&Bl \-tag
                    401: list types render similarly (no break following overreached left-hand
                    402: side) due to the expressive constraints of HTML.
                    403: .
                    404: .It
                    405: The
                    406: .Xr man 7
                    407: .Sq IP
                    408: and
                    409: .Sq TP
                    410: lists render similarly.
                    411: .El
1.20      kristaps  412: .\" SECTION
1.1       kristaps  413: .Sh SEE ALSO
1.13      kristaps  414: .Xr mandoc_char 7 ,
1.9       kristaps  415: .Xr mdoc 7 ,
                    416: .Xr man 7
1.39      kristaps  417: .
1.1       kristaps  418: .Sh AUTHORS
                    419: The
                    420: .Nm
1.26      kristaps  421: utility was written by
1.18      kristaps  422: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.39      kristaps  423: .
                    424: .Sh CAVEATS
                    425: In
                    426: .Fl T Ns Ar html ,
                    427: the maximum size of an element attribute is determined by
                    428: .Dv BUFSIZ ,
                    429: which is usually 1024 bytes.  Be aware of this when setting long link
                    430: formats with
1.44      kristaps  431: .Fl O Ns Ar man=fmt .
1.46      kristaps  432: .Pp
                    433: The
                    434: .Fl T Ns Ar html
1.47    ! kristaps  435: utility doesn't yet render the
1.46      kristaps  436: .Sq \es
1.47    ! kristaps  437: font size escape documented in
1.46      kristaps  438: .Xr mdoc 7
                    439: and
                    440: .Xr man 7 .

CVSweb