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

Annotation of mandoc/mandoc.1, Revision 1.69

1.69    ! kristaps    1: .\"    $Id: mandoc.1,v 1.68 2010/07/01 14:23:45 kristaps Exp $
1.1       kristaps    2: .\"
1.59      kristaps    3: .\" Copyright (c) 2009 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.69    ! kristaps   17: .Dd $Mdocdate: July 1 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.62      kristaps  195: .It Fl T Ns Cm ps
                    196: Produce PostScript output.
                    197: See
                    198: .Sx PostScript Output .
1.58      kristaps  199: .It Fl T Ns Cm tree
                    200: Produce an indented parse tree.
                    201: .It Fl T Ns Cm xhtml
1.57      kristaps  202: Produce strict XHTML-1.0 output, with a sane default style.
                    203: See
1.50      kristaps  204: .Sx XHTML Output .
1.1       kristaps  205: .El
1.13      kristaps  206: .Pp
                    207: If multiple input files are specified, these will be processed by the
                    208: corresponding filter in-order.
1.66      kristaps  209: .Ss ASCII Output
                    210: Output produced by
                    211: .Fl T Ns Cm ascii ,
                    212: which is the default, is rendered in standard 7-bit ASCII documented in
                    213: .Xr ascii 7 .
                    214: .Pp
                    215: Font styles are applied by using back-spaced encoding such that an
                    216: underlined character
                    217: .Sq c
                    218: is rendered as
                    219: .Sq _ Ns \e[bs] Ns c ,
                    220: where
                    221: .Sq \e[bs]
                    222: is the back-space character number 8.
                    223: Emboldened characters are rendered as
                    224: .Sq c Ns \e[bs] Ns c .
                    225: .Pp
                    226: The special characters documented in
                    227: .Xr mandoc_char 7
                    228: are rendered best-effort in an ASCII equivalent.
                    229: .Pp
                    230: Output width is limited to 78 visible columns unless literal input lines
                    231: exceed this limit.
                    232: .Pp
                    233: The following
                    234: .Fl O
                    235: arguments are accepted:
1.19      kristaps  236: .Bl -tag -width Ds
1.66      kristaps  237: .It Cm width Ns = Ns Ar width
                    238: The output width is set to
                    239: .Ar width ,
                    240: which will normalise to \(>=60.
1.1       kristaps  241: .El
1.66      kristaps  242: .Ss HTML Output
                    243: Output produced by
                    244: .Fl T Ns Cm html
                    245: conforms to HTML-4.01 strict.
                    246: .Pp
                    247: Font styles and page structure are applied using CSS2.
                    248: By default, no font style is applied to any text,
                    249: although CSS2 is hard-coded to format
                    250: the basic structure of output.
                    251: .Pp
1.61      kristaps  252: The
1.66      kristaps  253: .Pa example.style.css
                    254: file documents the range of styles applied to output and, if used, will
                    255: cause rendered documents to appear as they do in
                    256: .Fl T Ns Cm ascii .
                    257: .Pp
                    258: Special characters are rendered in decimal-encoded UTF-8.
                    259: .Pp
                    260: The following
1.64      kristaps  261: .Fl O
1.66      kristaps  262: arguments are accepted:
1.37      kristaps  263: .Bl -tag -width Ds
1.64      kristaps  264: .It Cm includes Ns = Ns Ar fmt
1.40      kristaps  265: The string
                    266: .Ar fmt ,
1.49      kristaps  267: for example,
1.40      kristaps  268: .Ar ../src/%I.html ,
                    269: is used as a template for linked header files (usually via the
                    270: .Sq \&In
1.57      kristaps  271: macro).
                    272: Instances of
1.43      kristaps  273: .Sq \&%I
1.57      kristaps  274: are replaced with the include filename.
                    275: The default is not to present a
1.40      kristaps  276: hyperlink.
1.64      kristaps  277: .It Cm man Ns = Ns Ar fmt
1.39      kristaps  278: The string
                    279: .Ar fmt ,
1.49      kristaps  280: for example,
1.39      kristaps  281: .Ar ../html%S/%N.%S.html ,
                    282: is used as a template for linked manuals (usually via the
1.37      kristaps  283: .Sq \&Xr
1.57      kristaps  284: macro).
                    285: Instances of
1.43      kristaps  286: .Sq \&%N
1.40      kristaps  287: and
                    288: .Sq %S
                    289: are replaced with the linked manual's name and section, respectively.
1.57      kristaps  290: If no section is included, section 1 is assumed.
                    291: The default is not to
1.40      kristaps  292: present a hyperlink.
1.64      kristaps  293: .It Cm style Ns = Ns Ar style.css
1.58      kristaps  294: The file
                    295: .Ar style.css
                    296: is used for an external style-sheet.
                    297: This must be a valid absolute or
                    298: relative URI.
1.61      kristaps  299: .El
1.62      kristaps  300: .Ss PostScript Output
1.65      kristaps  301: PostScript
                    302: .Qq Adobe-3.0
                    303: Level-2 pages may be generated by
1.62      kristaps  304: .Fl T Ns Cm ps .
1.67      kristaps  305: Output pages default to letter sized and are rendered in the Times font
1.69    ! kristaps  306: family, 11-point.  Margins are calculated as the maximum of either space
        !           307: left by page width minus text width (65
        !           308: .Sq m
        !           309: characters), or given default margins of 2 cm.
1.66      kristaps  310: .Pp
                    311: Special characters are rendered as in
                    312: .Sx ASCII Output .
                    313: .Pp
                    314: The following
                    315: .Fl O
                    316: arguments are accepted:
                    317: .Bl -tag -width Ds
                    318: .It Cm paper Ns = Ns Ar name
                    319: The paper size
                    320: .Ar name
                    321: may be one of
1.68      kristaps  322: .Ar a3 ,
                    323: .Ar a4 ,
                    324: .Ar a5 ,
                    325: .Ar legal ,
1.66      kristaps  326: or
                    327: .Ar letter .
1.68      kristaps  328: You may also manually specify dimensions as
                    329: .Ar NNxNN ,
                    330: width by height in millimetres.
                    331: If an unknown value is encountered,
                    332: .Ar letter
                    333: is used.
1.66      kristaps  334: .El
1.50      kristaps  335: .Ss XHTML Output
                    336: Output produced by
1.58      kristaps  337: .Fl T Ns Cm xhtml
1.50      kristaps  338: conforms to XHTML-1.0 strict.
                    339: .Pp
                    340: See
                    341: .Sx HTML Output
                    342: for details; beyond generating XHTML tags instead of HTML tags, these
                    343: output modes are identical.
1.1       kristaps  344: .Sh EXAMPLES
1.13      kristaps  345: To page manuals to the terminal:
1.1       kristaps  346: .Pp
1.58      kristaps  347: .D1 $ mandoc \-Wall,error \-fstrict mandoc.1 2\*(Gt&1 | less
                    348: .D1 $ mandoc mandoc.1 mdoc.3 mdoc.7 | less
1.28      kristaps  349: .Pp
1.41      kristaps  350: To produce HTML manuals with
                    351: .Ar style.css
                    352: as the style-sheet:
1.38      kristaps  353: .Pp
1.58      kristaps  354: .D1 $ mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html
1.38      kristaps  355: .Pp
1.28      kristaps  356: To check over a large set of manuals:
                    357: .Pp
1.58      kristaps  358: .Dl $ mandoc \-Tlint \-fign-errors `find /usr/src -name \e*\e.[1-9]`
1.66      kristaps  359: .Pp
                    360: To produce a series of PostScript manuals for A4 paper:
                    361: .Pp
                    362: .D1 $ mandoc \-Tps \-Opaper=a4 mdoc.7 man.7 \*(Gt manuals.ps
1.20      kristaps  363: .Sh COMPATIBILITY
1.26      kristaps  364: This section summarises
1.20      kristaps  365: .Nm
1.26      kristaps  366: compatibility with
1.20      kristaps  367: .Xr groff 1 .
1.32      kristaps  368: Each input and output format is separately noted.
1.48      kristaps  369: .Ss ASCII Compatibility
1.37      kristaps  370: .Bl -bullet -compact
1.29      kristaps  371: .It
1.49      kristaps  372: The
1.29      kristaps  373: .Sq \e~
1.49      kristaps  374: special character doesn't produce expected behaviour in
1.58      kristaps  375: .Fl T Ns Cm ascii .
1.32      kristaps  376: .It
1.49      kristaps  377: The
1.33      kristaps  378: .Sq \&Bd \-literal
1.49      kristaps  379: and
1.32      kristaps  380: .Sq \&Bd \-unfilled
                    381: macros of
                    382: .Xr mdoc 7
                    383: in
1.58      kristaps  384: .Fl T Ns Cm ascii
1.32      kristaps  385: are synonyms, as are \-filled and \-ragged.
1.26      kristaps  386: .It
1.49      kristaps  387: In
1.27      kristaps  388: .Xr groff 1 ,
                    389: the
                    390: .Sq \&Pa
1.32      kristaps  391: .Xr mdoc 7
                    392: macro does not underline when scoped under an
1.30      kristaps  393: .Sq \&It
1.57      kristaps  394: in the FILES section.
                    395: This behaves correctly in
1.27      kristaps  396: .Nm .
                    397: .It
1.58      kristaps  398: A list or display following the
1.27      kristaps  399: .Sq \&Ss
1.32      kristaps  400: .Xr mdoc 7
                    401: macro in
1.58      kristaps  402: .Fl T Ns Cm ascii
1.20      kristaps  403: does not assert a prior vertical break, just as it doesn't with
1.27      kristaps  404: .Sq \&Sh .
1.20      kristaps  405: .It
1.32      kristaps  406: The
                    407: .Sq \&na
                    408: .Xr man 7
1.34      kristaps  409: macro in
1.58      kristaps  410: .Fl T Ns Cm ascii
1.34      kristaps  411: has no effect.
1.20      kristaps  412: .It
                    413: Words aren't hyphenated.
1.22      kristaps  414: .It
                    415: In normal mode (not a literal block), blocks of spaces aren't preserved,
1.32      kristaps  416: so double spaces following sentence closure are reduced to a single space;
                    417: .Xr groff 1
                    418: retains spaces.
                    419: .It
                    420: Sentences are unilaterally monospaced.
1.20      kristaps  421: .El
1.50      kristaps  422: .Ss HTML/XHTML Compatibility
1.42      kristaps  423: .Bl -bullet -compact
                    424: .It
                    425: The
1.47      kristaps  426: .Sq \efP
                    427: escape will revert the font to the previous
                    428: .Sq \ef
                    429: escape, not to the last rendered decoration, which is now dictated by
1.57      kristaps  430: CSS instead of hard-coded.
                    431: It also will not span past the current scope,
                    432: for the same reason.
                    433: Note that in
1.47      kristaps  434: .Sx ASCII Output
                    435: mode, this will work fine.
                    436: .It
                    437: The
1.42      kristaps  438: .Xr mdoc 7
                    439: .Sq \&Bl \-hang
                    440: and
                    441: .Sq \&Bl \-tag
                    442: list types render similarly (no break following overreached left-hand
                    443: side) due to the expressive constraints of HTML.
                    444: .It
                    445: The
                    446: .Xr man 7
                    447: .Sq IP
                    448: and
                    449: .Sq TP
                    450: lists render similarly.
                    451: .El
1.1       kristaps  452: .Sh SEE ALSO
1.57      kristaps  453: .Xr man 7 ,
1.13      kristaps  454: .Xr mandoc_char 7 ,
1.57      kristaps  455: .Xr mdoc 7
1.1       kristaps  456: .Sh AUTHORS
                    457: The
                    458: .Nm
1.26      kristaps  459: utility was written by
1.59      kristaps  460: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
1.39      kristaps  461: .Sh CAVEATS
1.48      kristaps  462: The
1.58      kristaps  463: .Fl T Ns Cm html
1.50      kristaps  464: and
1.58      kristaps  465: .Fl T Ns Cm xhtml
1.48      kristaps  466: CSS2 styling used for
1.58      kristaps  467: .Fl m Ns Cm doc
1.51      kristaps  468: input lists does not render properly in older browsers, such as Internet
                    469: Explorer 6 and earlier.
1.48      kristaps  470: .Pp
1.39      kristaps  471: In
1.58      kristaps  472: .Fl T Ns Cm html
1.50      kristaps  473: and
1.58      kristaps  474: .Fl T Ns Cm xhtml ,
1.39      kristaps  475: the maximum size of an element attribute is determined by
                    476: .Dv BUFSIZ ,
1.57      kristaps  477: which is usually 1024 bytes.
                    478: Be aware of this when setting long link
1.58      kristaps  479: formats such as
                    480: .Fl O Ns Cm style Ns = Ns Ar really/long/link .
1.46      kristaps  481: .Pp
                    482: The
1.58      kristaps  483: .Fl T Ns Cm html
1.50      kristaps  484: and
1.58      kristaps  485: .Fl T Ns Cm xhtml
1.50      kristaps  486: output modes don't render the
1.46      kristaps  487: .Sq \es
1.47      kristaps  488: font size escape documented in
1.46      kristaps  489: .Xr mdoc 7
                    490: and
                    491: .Xr man 7 .
1.51      kristaps  492: .Pp
                    493: Nesting elements within next-line element scopes of
1.58      kristaps  494: .Fl m Ns Cm an ,
1.51      kristaps  495: such as
                    496: .Sq br
                    497: within an empty
                    498: .Sq B ,
                    499: will confuse
1.58      kristaps  500: .Fl T Ns Cm html
1.51      kristaps  501: and
1.58      kristaps  502: .Fl T Ns Cm xhtml
1.52      kristaps  503: and cause them to forget the formatting of the prior next-line scope.
1.53      kristaps  504: .Pp
                    505: The
                    506: .Sq i
                    507: macro in
1.58      kristaps  508: .Fl m Ns Cm an
1.53      kristaps  509: should italicise all subsequent text if a line argument is not provided.
                    510: This behaviour is not implemented.
1.54      kristaps  511: The
                    512: .Sq \(aq
1.55      kristaps  513: control character is an alias for the standard macro control character
                    514: and does not emit a line-break as stipulated in GNU troff.

CVSweb