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

Annotation of mandoc/mandoc.1, Revision 1.73

1.73    ! kristaps    1: .\"    $Id: mandoc.1,v 1.72 2010/07/13 23:53:20 schwarze Exp $
1.1       kristaps    2: .\"
1.72      schwarze    3: .\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
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: .\"
1.73    ! kristaps   17: .Dd $Mdocdate: July 13 2010 $
1.14      kristaps   18: .Dt MANDOC 1
1.1       kristaps   19: .Os
                     20: .Sh NAME
                     21: .Nm mandoc
1.8       kristaps   22: .Nd format and display UNIX manuals
1.1       kristaps   23: .Sh SYNOPSIS
                     24: .Nm mandoc
1.58      kristaps   25: .Op Fl V
                     26: .Op Fl f Ns Ar option
1.8       kristaps   27: .Op Fl m Ns Ar format
1.58      kristaps   28: .Op Fl O Ns Ar option
1.37      kristaps   29: .Op Fl T Ns Ar output
1.58      kristaps   30: .Op Fl W Ns Ar err
                     31: .Op Ar file...
1.1       kristaps   32: .Sh DESCRIPTION
                     33: The
                     34: .Nm
1.26      kristaps   35: utility formats
1.8       kristaps   36: .Ux
1.57      kristaps   37: manual pages for display.
                     38: The arguments are as follows:
1.19      kristaps   39: .Bl -tag -width Ds
1.58      kristaps   40: .It Fl f Ns Ar option
1.57      kristaps   41: Comma-separated compiler options.
                     42: See
1.1       kristaps   43: .Sx Compiler Options
                     44: for details.
1.19      kristaps   45: .It Fl m Ns Ar format
1.57      kristaps   46: Input format.
                     47: See
1.8       kristaps   48: .Sx Input Formats
1.57      kristaps   49: for available formats.
                     50: Defaults to
1.58      kristaps   51: .Fl m Ns Cm andoc .
                     52: .It Fl O Ns Ar option
1.57      kristaps   53: Comma-separated output options.
1.19      kristaps   54: .It Fl T Ns Ar output
1.57      kristaps   55: Output format.
                     56: See
1.1       kristaps   57: .Sx Output Formats
1.57      kristaps   58: for available formats.
                     59: Defaults to
1.58      kristaps   60: .Fl T Ns Cm ascii .
1.1       kristaps   61: .It Fl V
                     62: Print version and exit.
1.58      kristaps   63: .It Fl W Ns Ar err
1.57      kristaps   64: Comma-separated warning options.
                     65: Use
1.58      kristaps   66: .Fl W Ns Cm all
1.24      kristaps   67: to print warnings,
1.58      kristaps   68: .Fl W Ns Cm error
1.24      kristaps   69: for warnings to be considered errors and cause utility
1.57      kristaps   70: termination.
                     71: Multiple
1.1       kristaps   72: .Fl W
                     73: arguments may be comma-separated, such as
1.58      kristaps   74: .Fl W Ns Cm error , Ns Cm all .
                     75: .It Ar file
                     76: Read input from zero or more files.
1.57      kristaps   77: If unspecified, reads from stdin.
                     78: If multiple files are specified,
1.2       kristaps   79: .Nm
                     80: will halt with the first failed parse.
1.1       kristaps   81: .El
                     82: .Pp
1.26      kristaps   83: By default,
                     84: .Nm
                     85: reads
1.8       kristaps   86: .Xr mdoc 7
1.12      kristaps   87: or
                     88: .Xr man 7
1.8       kristaps   89: text from stdin, implying
1.58      kristaps   90: .Fl m Ns Cm andoc ,
1.48      kristaps   91: and produces
1.58      kristaps   92: .Fl T Ns Cm ascii
1.48      kristaps   93: output.
1.1       kristaps   94: .Pp
                     95: .Ex -std mandoc
1.8       kristaps   96: .Ss Input Formats
                     97: The
                     98: .Nm
                     99: utility accepts
                    100: .Xr mdoc 7
                    101: and
                    102: .Xr man 7
                    103: input with
1.58      kristaps  104: .Fl m Ns Cm doc
1.8       kristaps  105: and
1.58      kristaps  106: .Fl m Ns Cm an ,
1.57      kristaps  107: respectively.
                    108: The
1.8       kristaps  109: .Xr mdoc 7
                    110: format is
                    111: .Em strongly
1.26      kristaps  112: recommended;
1.8       kristaps  113: .Xr man 7
                    114: should only be used for legacy manuals.
1.11      kristaps  115: .Pp
1.12      kristaps  116: A third option,
1.58      kristaps  117: .Fl m Ns Cm andoc ,
1.13      kristaps  118: which is also the default, determines encoding on-the-fly: if the first
1.26      kristaps  119: non-comment macro is
1.27      kristaps  120: .Sq \&Dd
1.13      kristaps  121: or
1.27      kristaps  122: .Sq \&Dt ,
1.26      kristaps  123: the
1.13      kristaps  124: .Xr mdoc 7
                    125: parser is used; otherwise, the
                    126: .Xr man 7
                    127: parser is used.
                    128: .Pp
                    129: If multiple
1.26      kristaps  130: files are specified with
1.58      kristaps  131: .Fl m Ns Cm andoc ,
1.57      kristaps  132: each has its file-type determined this way.
                    133: If multiple files are
1.13      kristaps  134: specified and
1.58      kristaps  135: .Fl m Ns Cm doc
1.12      kristaps  136: or
1.58      kristaps  137: .Fl m Ns Cm an
1.12      kristaps  138: is specified, then this format is used exclusively.
1.66      kristaps  139: .Ss Compiler Options
                    140: Default
                    141: .Xr mdoc 7
                    142: and
                    143: .Xr man 7
                    144: compilation behaviour may be overridden with the
                    145: .Fl f
                    146: flag.
                    147: .Bl -tag -width Ds
                    148: .It Fl f Ns Cm ign-errors
                    149: When parsing multiple files, don't halt when one errors out.
                    150: Useful with
                    151: .Fl T Ns Cm lint
                    152: over a large set of manuals passed on the command line.
                    153: .It Fl f Ns Cm ign-escape
                    154: Ignore invalid escape sequences.
                    155: This is the default, but the option can be used to override an earlier
                    156: .Fl f Ns Cm strict .
                    157: .It Fl f Ns Cm ign-scope
                    158: When rewinding the scope of a block macro, forces the compiler to ignore
                    159: scope violations.
                    160: This can seriously mangle the resulting tree.
                    161: .Pq mdoc only
                    162: .It Fl f Ns Cm no-ign-escape
                    163: Do not ignore invalid escape sequences.
                    164: .It Fl f Ns Cm no-ign-macro
                    165: Do not ignore unknown macros at the start of input lines.
                    166: .It Fl f Ns Cm strict
                    167: Implies
                    168: .Fl f Ns Cm no-ign-escape
                    169: and
                    170: .Fl f Ns Cm no-ign-macro .
                    171: .El
1.1       kristaps  172: .Ss Output Formats
                    173: The
                    174: .Nm
                    175: utility accepts the following
                    176: .Fl T
1.66      kristaps  177: arguments, which correspond to output modes:
1.19      kristaps  178: .Bl -tag -width Ds
1.58      kristaps  179: .It Fl T Ns Cm ascii
1.1       kristaps  180: Produce 7-bit ASCII output, backspace-encoded for bold and underline
1.57      kristaps  181: styles.
                    182: This is the default.
                    183: See
1.48      kristaps  184: .Sx ASCII Output .
1.58      kristaps  185: .It Fl T Ns Cm html
1.57      kristaps  186: Produce strict HTML-4.01 output, with a sane default style.
                    187: See
1.48      kristaps  188: .Sx HTML Output .
1.58      kristaps  189: .It Fl T Ns Cm lint
                    190: Parse only: produce no output.
                    191: Implies
                    192: .Fl W Ns Cm all
                    193: and
                    194: .Fl f Ns Cm strict .
1.73    ! kristaps  195: .It Fl T Ns Cm pdf
        !           196: Produce PDF output.
        !           197: See
        !           198: .Sx PDF Output .
1.62      kristaps  199: .It Fl T Ns Cm ps
                    200: Produce PostScript output.
                    201: See
                    202: .Sx PostScript Output .
1.58      kristaps  203: .It Fl T Ns Cm tree
                    204: Produce an indented parse tree.
                    205: .It Fl T Ns Cm xhtml
1.57      kristaps  206: Produce strict XHTML-1.0 output, with a sane default style.
                    207: See
1.50      kristaps  208: .Sx XHTML Output .
1.1       kristaps  209: .El
1.13      kristaps  210: .Pp
                    211: If multiple input files are specified, these will be processed by the
                    212: corresponding filter in-order.
1.66      kristaps  213: .Ss ASCII Output
                    214: Output produced by
                    215: .Fl T Ns Cm ascii ,
                    216: which is the default, is rendered in standard 7-bit ASCII documented in
                    217: .Xr ascii 7 .
                    218: .Pp
                    219: Font styles are applied by using back-spaced encoding such that an
                    220: underlined character
                    221: .Sq c
                    222: is rendered as
                    223: .Sq _ Ns \e[bs] Ns c ,
                    224: where
                    225: .Sq \e[bs]
                    226: is the back-space character number 8.
                    227: Emboldened characters are rendered as
                    228: .Sq c Ns \e[bs] Ns c .
                    229: .Pp
                    230: The special characters documented in
                    231: .Xr mandoc_char 7
                    232: are rendered best-effort in an ASCII equivalent.
                    233: .Pp
                    234: Output width is limited to 78 visible columns unless literal input lines
                    235: exceed this limit.
                    236: .Pp
                    237: The following
                    238: .Fl O
                    239: arguments are accepted:
1.19      kristaps  240: .Bl -tag -width Ds
1.66      kristaps  241: .It Cm width Ns = Ns Ar width
                    242: The output width is set to
                    243: .Ar width ,
                    244: which will normalise to \(>=60.
1.1       kristaps  245: .El
1.66      kristaps  246: .Ss HTML Output
                    247: Output produced by
                    248: .Fl T Ns Cm html
                    249: conforms to HTML-4.01 strict.
                    250: .Pp
                    251: Font styles and page structure are applied using CSS2.
                    252: By default, no font style is applied to any text,
                    253: although CSS2 is hard-coded to format
                    254: the basic structure of output.
                    255: .Pp
1.61      kristaps  256: The
1.66      kristaps  257: .Pa example.style.css
                    258: file documents the range of styles applied to output and, if used, will
                    259: cause rendered documents to appear as they do in
                    260: .Fl T Ns Cm ascii .
                    261: .Pp
                    262: Special characters are rendered in decimal-encoded UTF-8.
                    263: .Pp
                    264: The following
1.64      kristaps  265: .Fl O
1.66      kristaps  266: arguments are accepted:
1.37      kristaps  267: .Bl -tag -width Ds
1.64      kristaps  268: .It Cm includes Ns = Ns Ar fmt
1.40      kristaps  269: The string
                    270: .Ar fmt ,
1.49      kristaps  271: for example,
1.40      kristaps  272: .Ar ../src/%I.html ,
                    273: is used as a template for linked header files (usually via the
                    274: .Sq \&In
1.57      kristaps  275: macro).
                    276: Instances of
1.43      kristaps  277: .Sq \&%I
1.57      kristaps  278: are replaced with the include filename.
                    279: The default is not to present a
1.40      kristaps  280: hyperlink.
1.64      kristaps  281: .It Cm man Ns = Ns Ar fmt
1.39      kristaps  282: The string
                    283: .Ar fmt ,
1.49      kristaps  284: for example,
1.39      kristaps  285: .Ar ../html%S/%N.%S.html ,
                    286: is used as a template for linked manuals (usually via the
1.37      kristaps  287: .Sq \&Xr
1.57      kristaps  288: macro).
                    289: Instances of
1.43      kristaps  290: .Sq \&%N
1.40      kristaps  291: and
                    292: .Sq %S
                    293: are replaced with the linked manual's name and section, respectively.
1.57      kristaps  294: If no section is included, section 1 is assumed.
                    295: The default is not to
1.40      kristaps  296: present a hyperlink.
1.64      kristaps  297: .It Cm style Ns = Ns Ar style.css
1.58      kristaps  298: The file
                    299: .Ar style.css
                    300: is used for an external style-sheet.
                    301: This must be a valid absolute or
                    302: relative URI.
1.61      kristaps  303: .El
1.62      kristaps  304: .Ss PostScript Output
1.65      kristaps  305: PostScript
                    306: .Qq Adobe-3.0
                    307: Level-2 pages may be generated by
1.62      kristaps  308: .Fl T Ns Cm ps .
1.67      kristaps  309: Output pages default to letter sized and are rendered in the Times font
1.70      kristaps  310: family, 11-point.
                    311: Margins are calculated as 1/9 the page length and width.
1.71      kristaps  312: Line-height is 1.4m.
1.66      kristaps  313: .Pp
                    314: Special characters are rendered as in
                    315: .Sx ASCII Output .
                    316: .Pp
                    317: The following
                    318: .Fl O
                    319: arguments are accepted:
                    320: .Bl -tag -width Ds
                    321: .It Cm paper Ns = Ns Ar name
                    322: The paper size
                    323: .Ar name
                    324: may be one of
1.68      kristaps  325: .Ar a3 ,
                    326: .Ar a4 ,
                    327: .Ar a5 ,
                    328: .Ar legal ,
1.66      kristaps  329: or
                    330: .Ar letter .
1.68      kristaps  331: You may also manually specify dimensions as
                    332: .Ar NNxNN ,
                    333: width by height in millimetres.
                    334: If an unknown value is encountered,
                    335: .Ar letter
                    336: is used.
1.66      kristaps  337: .El
1.73    ! kristaps  338: .Ss PDF Output
        !           339: PDF-1.1 output may be generated by
        !           340: .Fl T Ns Cm pdf .
        !           341: See
        !           342: .Sx PostScript Output
        !           343: for
        !           344: .Fl O
        !           345: arguments and defaults.
1.50      kristaps  346: .Ss XHTML Output
                    347: Output produced by
1.58      kristaps  348: .Fl T Ns Cm xhtml
1.50      kristaps  349: conforms to XHTML-1.0 strict.
                    350: .Pp
                    351: See
                    352: .Sx HTML Output
                    353: for details; beyond generating XHTML tags instead of HTML tags, these
                    354: output modes are identical.
1.1       kristaps  355: .Sh EXAMPLES
1.13      kristaps  356: To page manuals to the terminal:
1.1       kristaps  357: .Pp
1.58      kristaps  358: .D1 $ mandoc \-Wall,error \-fstrict mandoc.1 2\*(Gt&1 | less
                    359: .D1 $ mandoc mandoc.1 mdoc.3 mdoc.7 | less
1.28      kristaps  360: .Pp
1.41      kristaps  361: To produce HTML manuals with
                    362: .Ar style.css
                    363: as the style-sheet:
1.38      kristaps  364: .Pp
1.58      kristaps  365: .D1 $ mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html
1.38      kristaps  366: .Pp
1.28      kristaps  367: To check over a large set of manuals:
                    368: .Pp
1.58      kristaps  369: .Dl $ mandoc \-Tlint \-fign-errors `find /usr/src -name \e*\e.[1-9]`
1.66      kristaps  370: .Pp
                    371: To produce a series of PostScript manuals for A4 paper:
                    372: .Pp
                    373: .D1 $ mandoc \-Tps \-Opaper=a4 mdoc.7 man.7 \*(Gt manuals.ps
1.20      kristaps  374: .Sh COMPATIBILITY
1.26      kristaps  375: This section summarises
1.20      kristaps  376: .Nm
1.26      kristaps  377: compatibility with
1.20      kristaps  378: .Xr groff 1 .
1.32      kristaps  379: Each input and output format is separately noted.
1.48      kristaps  380: .Ss ASCII Compatibility
1.37      kristaps  381: .Bl -bullet -compact
1.29      kristaps  382: .It
1.49      kristaps  383: The
1.29      kristaps  384: .Sq \e~
1.49      kristaps  385: special character doesn't produce expected behaviour in
1.58      kristaps  386: .Fl T Ns Cm ascii .
1.32      kristaps  387: .It
1.49      kristaps  388: The
1.33      kristaps  389: .Sq \&Bd \-literal
1.49      kristaps  390: and
1.32      kristaps  391: .Sq \&Bd \-unfilled
                    392: macros of
                    393: .Xr mdoc 7
                    394: in
1.58      kristaps  395: .Fl T Ns Cm ascii
1.32      kristaps  396: are synonyms, as are \-filled and \-ragged.
1.26      kristaps  397: .It
1.49      kristaps  398: In
1.27      kristaps  399: .Xr groff 1 ,
                    400: the
                    401: .Sq \&Pa
1.32      kristaps  402: .Xr mdoc 7
                    403: macro does not underline when scoped under an
1.30      kristaps  404: .Sq \&It
1.57      kristaps  405: in the FILES section.
                    406: This behaves correctly in
1.27      kristaps  407: .Nm .
                    408: .It
1.58      kristaps  409: A list or display following the
1.27      kristaps  410: .Sq \&Ss
1.32      kristaps  411: .Xr mdoc 7
                    412: macro in
1.58      kristaps  413: .Fl T Ns Cm ascii
1.20      kristaps  414: does not assert a prior vertical break, just as it doesn't with
1.27      kristaps  415: .Sq \&Sh .
1.20      kristaps  416: .It
1.32      kristaps  417: The
                    418: .Sq \&na
                    419: .Xr man 7
1.34      kristaps  420: macro in
1.58      kristaps  421: .Fl T Ns Cm ascii
1.34      kristaps  422: has no effect.
1.20      kristaps  423: .It
                    424: Words aren't hyphenated.
1.22      kristaps  425: .It
                    426: In normal mode (not a literal block), blocks of spaces aren't preserved,
1.32      kristaps  427: so double spaces following sentence closure are reduced to a single space;
                    428: .Xr groff 1
                    429: retains spaces.
                    430: .It
                    431: Sentences are unilaterally monospaced.
1.20      kristaps  432: .El
1.50      kristaps  433: .Ss HTML/XHTML Compatibility
1.42      kristaps  434: .Bl -bullet -compact
                    435: .It
                    436: The
1.47      kristaps  437: .Sq \efP
                    438: escape will revert the font to the previous
                    439: .Sq \ef
                    440: escape, not to the last rendered decoration, which is now dictated by
1.57      kristaps  441: CSS instead of hard-coded.
                    442: It also will not span past the current scope,
                    443: for the same reason.
                    444: Note that in
1.47      kristaps  445: .Sx ASCII Output
                    446: mode, this will work fine.
                    447: .It
                    448: The
1.42      kristaps  449: .Xr mdoc 7
                    450: .Sq \&Bl \-hang
                    451: and
                    452: .Sq \&Bl \-tag
                    453: list types render similarly (no break following overreached left-hand
                    454: side) due to the expressive constraints of HTML.
                    455: .It
                    456: The
                    457: .Xr man 7
                    458: .Sq IP
                    459: and
                    460: .Sq TP
                    461: lists render similarly.
                    462: .El
1.1       kristaps  463: .Sh SEE ALSO
1.57      kristaps  464: .Xr man 7 ,
1.13      kristaps  465: .Xr mandoc_char 7 ,
1.57      kristaps  466: .Xr mdoc 7
1.1       kristaps  467: .Sh AUTHORS
                    468: The
                    469: .Nm
1.26      kristaps  470: utility was written by
1.59      kristaps  471: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
1.39      kristaps  472: .Sh CAVEATS
1.48      kristaps  473: The
1.58      kristaps  474: .Fl T Ns Cm html
1.50      kristaps  475: and
1.58      kristaps  476: .Fl T Ns Cm xhtml
1.48      kristaps  477: CSS2 styling used for
1.58      kristaps  478: .Fl m Ns Cm doc
1.51      kristaps  479: input lists does not render properly in older browsers, such as Internet
                    480: Explorer 6 and earlier.
1.48      kristaps  481: .Pp
1.39      kristaps  482: In
1.58      kristaps  483: .Fl T Ns Cm html
1.50      kristaps  484: and
1.58      kristaps  485: .Fl T Ns Cm xhtml ,
1.39      kristaps  486: the maximum size of an element attribute is determined by
                    487: .Dv BUFSIZ ,
1.57      kristaps  488: which is usually 1024 bytes.
                    489: Be aware of this when setting long link
1.58      kristaps  490: formats such as
                    491: .Fl O Ns Cm style Ns = Ns Ar really/long/link .
1.46      kristaps  492: .Pp
                    493: The
1.58      kristaps  494: .Fl T Ns Cm html
1.50      kristaps  495: and
1.58      kristaps  496: .Fl T Ns Cm xhtml
1.50      kristaps  497: output modes don't render the
1.46      kristaps  498: .Sq \es
1.47      kristaps  499: font size escape documented in
1.46      kristaps  500: .Xr mdoc 7
                    501: and
                    502: .Xr man 7 .
1.51      kristaps  503: .Pp
                    504: Nesting elements within next-line element scopes of
1.58      kristaps  505: .Fl m Ns Cm an ,
1.51      kristaps  506: such as
                    507: .Sq br
                    508: within an empty
                    509: .Sq B ,
                    510: will confuse
1.58      kristaps  511: .Fl T Ns Cm html
1.51      kristaps  512: and
1.58      kristaps  513: .Fl T Ns Cm xhtml
1.52      kristaps  514: and cause them to forget the formatting of the prior next-line scope.
1.53      kristaps  515: .Pp
                    516: The
                    517: .Sq i
                    518: macro in
1.58      kristaps  519: .Fl m Ns Cm an
1.53      kristaps  520: should italicise all subsequent text if a line argument is not provided.
                    521: This behaviour is not implemented.
1.54      kristaps  522: The
                    523: .Sq \(aq
1.55      kristaps  524: control character is an alias for the standard macro control character
                    525: and does not emit a line-break as stipulated in GNU troff.

CVSweb