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

Annotation of mandoc/mandoc.1, Revision 1.6

1.6     ! kristaps    1: .\" $Id: mandoc.1,v 1.5 2009/03/21 21:09:00 kristaps Exp $
1.1       kristaps    2: .\"
                      3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
                      4: .\"
                      5: .\" Permission to use, copy, modify, and distribute this software for any
                      6: .\" purpose with or without fee is hereby granted, provided that the
                      7: .\" above copyright notice and this permission notice appear in all
                      8: .\" copies.
                      9: .\"
                     10: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
                     11: .\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
                     12: .\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
                     13: .\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
                     14: .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
                     15: .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
                     16: .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
                     17: .\" PERFORMANCE OF THIS SOFTWARE.
                     18: .\"
                     19: .Dd $Mdocdate$
                     20: .Dt mandoc 1
                     21: .Os
                     22: .\" SECTION
                     23: .Sh NAME
                     24: .Nm mandoc
                     25: .Nd format and display BSD manuals
                     26: .\" SECTION
                     27: .Sh SYNOPSIS
                     28: .Nm mandoc
                     29: .Op Fl V
                     30: .Op Fl f Ns Ar option...
                     31: .Op Fl W Ns Ar err...
                     32: .Op Fl T Ns Ar output
                     33: .Op Ar infile...
                     34: .\" SECTION
                     35: .Sh DESCRIPTION
                     36: The
                     37: .Nm
                     38: utility formats a BSD
                     39: .Dq mdoc
                     40: manual page for display.  The arguments are as follows:
                     41: .Bl -tag -width XXXXXXXXXXXX
                     42: .\" ITEM
                     43: .It Fl f Ns Ar option...
                     44: Override default compiler behaviour.  See
                     45: .Sx Compiler Options
                     46: for details.
                     47: .\" ITEM
                     48: .It Fl T
                     49: Output format.  See
                     50: .Sx Output Formats
                     51: for available formats.  Defaults to
                     52: .Fl T Ns Ar ascii .
                     53: .\" ITEM
                     54: .It Fl V
                     55: Print version and exit.
                     56: .\" ITEM
                     57: .It Fl W Ns Ar err...
                     58: Print warning messages.  May be set to
                     59: .Fl W Ns Ar all
                     60: for all warnings,
                     61: .Ar compat
                     62: for groff/troff-compatibility warnings, or
                     63: .Ar syntax
                     64: for syntax warnings.  If
                     65: .Fl W Ns Ar error
                     66: is specified, warnings are considered errors and cause utility
                     67: termination.  Multiple
                     68: .Fl W
                     69: arguments may be comma-separated, such as
                     70: .Fl W Ns Ar error,all .
                     71: .\" ITEM
                     72: .It Ar infile...
                     73: Read input from zero or more
                     74: .Ar infile .
1.2       kristaps   75: If unspecified, reads from stdin.  If multiple files are specified,
                     76: .Nm
                     77: will halt with the first failed parse.
1.1       kristaps   78: .El
                     79: .\" PARAGRAPH
                     80: .Pp
                     81: By default,
                     82: .Nm
                     83: reads from stdin and prints 78-column backspace-encoded output to stdout
                     84: as if
                     85: .Fl T Ns Ar ascii
                     86: were provided.
                     87: .\" PARAGRAPH
                     88: .Pp
                     89: .Ex -std mandoc
                     90: .\" SUB-SECTION
1.4       kristaps   91: .Ss Reserved Words
                     92: The reserved words described in
                     93: .Xr mdoc 7
                     94: are handled according to the following rules:
                     95: .Bl -enum -offset XXX
                     96: .It
                     97: Opening delimiters
                     98: .Po
                     99: .Sq \&( ,
                    100: .Sq \&[ ,
                    101: and
                    102: .Sq \&{
                    103: .Pc are not followed by whitespace.
                    104: .It
                    105: Closing delimiters
                    106: .Po
                    107: .Sq \&. ,
                    108: .Sq \&, ,
                    109: .Sq \&; ,
                    110: .Sq \&: ,
                    111: .Sq \&? ,
                    112: .Sq \&! ,
                    113: .Sq \&) ,
                    114: .Sq \&]
                    115: and
                    116: .Sq \&}
                    117: .Pc are not preceeded by whitespace.
                    118: .El
                    119: .\" PARAGRAPH
                    120: .Pp
                    121: Note that reserved words may occur in streams of text, so the following:
                    122: .Bd -literal -offset XXXX
                    123: this self is not that of the waking , empirically real man
                    124: .Ed
                    125: .\" PARAGRAPH
                    126: .Pp
                    127: \&...correctly adjusts the comma spacing to
                    128: .Qq this self is not that of the waking , empirically real man .
                    129: .\" SUB-SECTION
1.1       kristaps  130: .Ss Output Formats
                    131: The
                    132: .Nm
                    133: utility accepts the following
                    134: .Fl T
                    135: arguments:
                    136: .Bl -tag -width XXXXXXXXXXXX -offset XXXX
                    137: .It Ar ascii
                    138: Produce 7-bit ASCII output, backspace-encoded for bold and underline
                    139: styles.  This is the default.
                    140: .It Ar tree
                    141: Produce an indented parse tree.
                    142: .It Ar lint
                    143: Parse only: produce no output.
                    144: .El
                    145: .\" SUB-SECTION
                    146: .Ss Compiler Options
                    147: Default compiler behaviour may be overriden with the
                    148: .Fl f
                    149: flag.
                    150: .Bl -tag -width XXXXXXXXXXXX -offset XXXX
                    151: .It Fl f Ns Ar ign-scope
                    152: When rewinding the scope of a block macro, forces the compiler to ignore
                    153: scope violations.  This can seriously mangle the resulting tree.
                    154: .It Fl f Ns Ar ign-escape
                    155: Ignore invalid escape sequences.
                    156: .It Fl f Ns Ar ign-macro
                    157: Ignore unknown macros at the start of input lines.
                    158: .El
                    159: .\" PARAGRAPH
                    160: .Pp
                    161: As with the
                    162: .Fl W
                    163: flag, multiple
                    164: .Fl f
                    165: options may be grouped and delimited with a comma.  Using
                    166: .Fl f Ns Ar ign-scope,ign-escape ,
                    167: for example, will try to ignore scope and character-escape errors.
                    168: .\" SECTION
                    169: .Sh EXAMPLES
                    170: To page this manual page on the terminal:
                    171: .\" PARAGRAPH
                    172: .Pp
                    173: .D1 % mandoc \-Wall,error mandoc.1 2>&1 | less
                    174: .\" SECTION
                    175: .Sh SEE ALSO
                    176: .Xr mdoc 7
                    177: .\"
                    178: .Sh AUTHORS
                    179: The
                    180: .Nm
                    181: utility was written by
                    182: .An Kristaps Dzonsons Aq kristaps@openbsd.org .
                    183: .\" SECTION
                    184: .Sh CAVEATS
                    185: The
                    186: .Nm
1.5       kristaps  187: utility in
                    188: .Fl T Ns Ar ascii
                    189: mode doesn't yet know how to display the following:
1.1       kristaps  190: .Pp
                    191: .Bl -bullet -compact
                    192: .It
                    193: The \-hang
                    194: .Sq \&Bl
                    195: list is not yet supported.
1.5       kristaps  196: .\" LIST-ITEM
1.1       kristaps  197: .It
                    198: The \-literal and \-unfilled
                    199: .Sq \&Bd
1.3       kristaps  200: displays types are synonyms, as are \-filled and \-ragged.
1.5       kristaps  201: .\" LIST-ITEM
1.1       kristaps  202: .It
                    203: The
1.5       kristaps  204: .Sq \&Bd
                    205: macro doesn't process \-compact .
1.1       kristaps  206: .El
                    207: .Pp
                    208: Other macros still aren't supported by virtue of nobody complaining
                    209: about their absence.  Please report any omissions: this is a work in
                    210: progress.

CVSweb