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

Annotation of mandoc/mandoc.1, Revision 1.66

1.66    ! kristaps    1: .\"    $Id: mandoc.1,v 1.65 2010/06/29 14:18:05 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.66    ! kristaps   17: .Dd $Mdocdate: June 29 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.66    ! kristaps  305: Output pages are US-letter sized and rendered in fixed, 10-point Courier
        !           306: font.
        !           307: .Pp
        !           308: Special characters are rendered as in
        !           309: .Sx ASCII Output .
        !           310: .Pp
        !           311: The following
        !           312: .Fl O
        !           313: arguments are accepted:
        !           314: .Bl -tag -width Ds
        !           315: .It Cm paper Ns = Ns Ar name
        !           316: The paper size
        !           317: .Ar name
        !           318: may be one of
        !           319: .Ar a4
        !           320: or
        !           321: .Ar letter .
        !           322: .El
1.50      kristaps  323: .Ss XHTML Output
                    324: Output produced by
1.58      kristaps  325: .Fl T Ns Cm xhtml
1.50      kristaps  326: conforms to XHTML-1.0 strict.
                    327: .Pp
                    328: See
                    329: .Sx HTML Output
                    330: for details; beyond generating XHTML tags instead of HTML tags, these
                    331: output modes are identical.
1.1       kristaps  332: .Sh EXAMPLES
1.13      kristaps  333: To page manuals to the terminal:
1.1       kristaps  334: .Pp
1.58      kristaps  335: .D1 $ mandoc \-Wall,error \-fstrict mandoc.1 2\*(Gt&1 | less
                    336: .D1 $ mandoc mandoc.1 mdoc.3 mdoc.7 | less
1.28      kristaps  337: .Pp
1.41      kristaps  338: To produce HTML manuals with
                    339: .Ar style.css
                    340: as the style-sheet:
1.38      kristaps  341: .Pp
1.58      kristaps  342: .D1 $ mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html
1.38      kristaps  343: .Pp
1.28      kristaps  344: To check over a large set of manuals:
                    345: .Pp
1.58      kristaps  346: .Dl $ mandoc \-Tlint \-fign-errors `find /usr/src -name \e*\e.[1-9]`
1.66    ! kristaps  347: .Pp
        !           348: To produce a series of PostScript manuals for A4 paper:
        !           349: .Pp
        !           350: .D1 $ mandoc \-Tps \-Opaper=a4 mdoc.7 man.7 \*(Gt manuals.ps
1.20      kristaps  351: .Sh COMPATIBILITY
1.26      kristaps  352: This section summarises
1.20      kristaps  353: .Nm
1.26      kristaps  354: compatibility with
1.20      kristaps  355: .Xr groff 1 .
1.32      kristaps  356: Each input and output format is separately noted.
1.48      kristaps  357: .Ss ASCII Compatibility
1.37      kristaps  358: .Bl -bullet -compact
1.29      kristaps  359: .It
1.49      kristaps  360: The
1.29      kristaps  361: .Sq \e~
1.49      kristaps  362: special character doesn't produce expected behaviour in
1.58      kristaps  363: .Fl T Ns Cm ascii .
1.32      kristaps  364: .It
1.49      kristaps  365: The
1.33      kristaps  366: .Sq \&Bd \-literal
1.49      kristaps  367: and
1.32      kristaps  368: .Sq \&Bd \-unfilled
                    369: macros of
                    370: .Xr mdoc 7
                    371: in
1.58      kristaps  372: .Fl T Ns Cm ascii
1.32      kristaps  373: are synonyms, as are \-filled and \-ragged.
1.26      kristaps  374: .It
1.49      kristaps  375: In
1.27      kristaps  376: .Xr groff 1 ,
                    377: the
                    378: .Sq \&Pa
1.32      kristaps  379: .Xr mdoc 7
                    380: macro does not underline when scoped under an
1.30      kristaps  381: .Sq \&It
1.57      kristaps  382: in the FILES section.
                    383: This behaves correctly in
1.27      kristaps  384: .Nm .
                    385: .It
1.58      kristaps  386: A list or display following the
1.27      kristaps  387: .Sq \&Ss
1.32      kristaps  388: .Xr mdoc 7
                    389: macro in
1.58      kristaps  390: .Fl T Ns Cm ascii
1.20      kristaps  391: does not assert a prior vertical break, just as it doesn't with
1.27      kristaps  392: .Sq \&Sh .
1.20      kristaps  393: .It
1.32      kristaps  394: The
                    395: .Sq \&na
                    396: .Xr man 7
1.34      kristaps  397: macro in
1.58      kristaps  398: .Fl T Ns Cm ascii
1.34      kristaps  399: has no effect.
1.20      kristaps  400: .It
                    401: Words aren't hyphenated.
1.22      kristaps  402: .It
                    403: In normal mode (not a literal block), blocks of spaces aren't preserved,
1.32      kristaps  404: so double spaces following sentence closure are reduced to a single space;
                    405: .Xr groff 1
                    406: retains spaces.
                    407: .It
                    408: Sentences are unilaterally monospaced.
1.20      kristaps  409: .El
1.50      kristaps  410: .Ss HTML/XHTML Compatibility
1.42      kristaps  411: .Bl -bullet -compact
                    412: .It
                    413: The
1.47      kristaps  414: .Sq \efP
                    415: escape will revert the font to the previous
                    416: .Sq \ef
                    417: escape, not to the last rendered decoration, which is now dictated by
1.57      kristaps  418: CSS instead of hard-coded.
                    419: It also will not span past the current scope,
                    420: for the same reason.
                    421: Note that in
1.47      kristaps  422: .Sx ASCII Output
                    423: mode, this will work fine.
                    424: .It
                    425: The
1.42      kristaps  426: .Xr mdoc 7
                    427: .Sq \&Bl \-hang
                    428: and
                    429: .Sq \&Bl \-tag
                    430: list types render similarly (no break following overreached left-hand
                    431: side) due to the expressive constraints of HTML.
                    432: .It
                    433: The
                    434: .Xr man 7
                    435: .Sq IP
                    436: and
                    437: .Sq TP
                    438: lists render similarly.
                    439: .El
1.1       kristaps  440: .Sh SEE ALSO
1.57      kristaps  441: .Xr man 7 ,
1.13      kristaps  442: .Xr mandoc_char 7 ,
1.57      kristaps  443: .Xr mdoc 7
1.1       kristaps  444: .Sh AUTHORS
                    445: The
                    446: .Nm
1.26      kristaps  447: utility was written by
1.59      kristaps  448: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
1.39      kristaps  449: .Sh CAVEATS
1.48      kristaps  450: The
1.58      kristaps  451: .Fl T Ns Cm html
1.50      kristaps  452: and
1.58      kristaps  453: .Fl T Ns Cm xhtml
1.48      kristaps  454: CSS2 styling used for
1.58      kristaps  455: .Fl m Ns Cm doc
1.51      kristaps  456: input lists does not render properly in older browsers, such as Internet
                    457: Explorer 6 and earlier.
1.48      kristaps  458: .Pp
1.39      kristaps  459: In
1.58      kristaps  460: .Fl T Ns Cm html
1.50      kristaps  461: and
1.58      kristaps  462: .Fl T Ns Cm xhtml ,
1.39      kristaps  463: the maximum size of an element attribute is determined by
                    464: .Dv BUFSIZ ,
1.57      kristaps  465: which is usually 1024 bytes.
                    466: Be aware of this when setting long link
1.58      kristaps  467: formats such as
                    468: .Fl O Ns Cm style Ns = Ns Ar really/long/link .
1.46      kristaps  469: .Pp
                    470: The
1.58      kristaps  471: .Fl T Ns Cm html
1.50      kristaps  472: and
1.58      kristaps  473: .Fl T Ns Cm xhtml
1.50      kristaps  474: output modes don't render the
1.46      kristaps  475: .Sq \es
1.47      kristaps  476: font size escape documented in
1.46      kristaps  477: .Xr mdoc 7
                    478: and
                    479: .Xr man 7 .
1.51      kristaps  480: .Pp
                    481: Nesting elements within next-line element scopes of
1.58      kristaps  482: .Fl m Ns Cm an ,
1.51      kristaps  483: such as
                    484: .Sq br
                    485: within an empty
                    486: .Sq B ,
                    487: will confuse
1.58      kristaps  488: .Fl T Ns Cm html
1.51      kristaps  489: and
1.58      kristaps  490: .Fl T Ns Cm xhtml
1.52      kristaps  491: and cause them to forget the formatting of the prior next-line scope.
1.53      kristaps  492: .Pp
                    493: The
                    494: .Sq i
                    495: macro in
1.58      kristaps  496: .Fl m Ns Cm an
1.53      kristaps  497: should italicise all subsequent text if a line argument is not provided.
                    498: This behaviour is not implemented.
1.54      kristaps  499: The
                    500: .Sq \(aq
1.55      kristaps  501: control character is an alias for the standard macro control character
                    502: and does not emit a line-break as stipulated in GNU troff.

CVSweb