Annotation of src/usr.bin/mandoc/mandoc.1, Revision 1.1
1.1 ! kristaps 1: .\" $Id: mandoc.1,v 1.13 2009/04/05 16:34:22 kristaps Exp $
! 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 UNIX manuals
! 26: .\" SECTION
! 27: .Sh SYNOPSIS
! 28: .Nm mandoc
! 29: .Op Fl f Ns Ar option...
! 30: .Op Fl m Ns Ar format
! 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
! 39: .Ux
! 40: manual pages 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 m Ns Ar format
! 49: Input format. See
! 50: .Sx Input Formats
! 51: for available formats. Defaults to
! 52: .Fl m Ns Ar andoc .
! 53: .\" ITEM
! 54: .It Fl T Ns Ar output
! 55: Output format. See
! 56: .Sx Output Formats
! 57: for available formats. Defaults to
! 58: .Fl T Ns Ar ascii .
! 59: .\" ITEM
! 60: .It Fl W Ns Ar err...
! 61: Print warning messages. May be set to
! 62: .Fl W Ns Ar all
! 63: for all warnings,
! 64: .Ar compat
! 65: for groff/troff-compatibility warnings, or
! 66: .Ar syntax
! 67: for syntax warnings. If
! 68: .Fl W Ns Ar error
! 69: is specified, warnings are considered errors and cause utility
! 70: termination. Multiple
! 71: .Fl W
! 72: arguments may be comma-separated, such as
! 73: .Fl W Ns Ar error,all .
! 74: .\" ITEM
! 75: .It Ar infile...
! 76: Read input from zero or more
! 77: .Ar infile .
! 78: If unspecified, reads from stdin. If multiple files are specified,
! 79: .Nm
! 80: will halt with the first failed parse.
! 81: .El
! 82: .\" PARAGRAPH
! 83: .Pp
! 84: By default,
! 85: .Nm
! 86: reads
! 87: .Xr mdoc 7
! 88: or
! 89: .Xr man 7
! 90: text from stdin, implying
! 91: .Fl m Ns Ar andoc ,
! 92: and prints 78-column backspace-encoded output to stdout as if
! 93: .Fl T Ns Ar ascii
! 94: were provided.
! 95: .\" PARAGRAPH
! 96: .Pp
! 97: .Ex -std mandoc
! 98: .\" SUB-SECTION
! 99: .Ss Punctuation
! 100: If punctuation is set apart from words, such as in the phrase
! 101: .Dq to be \&, or not to be ,
! 102: it's processed by
! 103: .Nm
! 104: according to the following rules. Opening punctuation
! 105: .Po
! 106: .Sq \&( ,
! 107: .Sq \&[ ,
! 108: and
! 109: .Sq \&{
! 110: .Pc
! 111: is not followed by a space. Closing punctuation
! 112: .Po
! 113: .Sq \&. ,
! 114: .Sq \&, ,
! 115: .Sq \&; ,
! 116: .Sq \&: ,
! 117: .Sq \&? ,
! 118: .Sq \&! ,
! 119: .Sq \&) ,
! 120: .Sq \&]
! 121: and
! 122: .Sq \&}
! 123: .Pc
! 124: is not preceeded by whitespace.
! 125: .Pp
! 126: If the input is
! 127: .Xr mdoc 7 ,
! 128: these rules are also applied to macro arguments when appropriate.
! 129: .\" SUB-SECTION
! 130: .Ss Input Formats
! 131: The
! 132: .Nm
! 133: utility accepts
! 134: .Xr mdoc 7
! 135: and
! 136: .Xr man 7
! 137: input with
! 138: .Fl m Ns Ar doc
! 139: and
! 140: .Fl m Ns Ar an ,
! 141: respectively. The
! 142: .Xr mdoc 7
! 143: format is
! 144: .Em strongly
! 145: recommended;
! 146: .Xr man 7
! 147: should only be used for legacy manuals.
! 148: .Pp
! 149: A third option,
! 150: .Fl m Ns Ar andoc ,
! 151: which is also the default, determines encoding on-the-fly: if the first
! 152: non-comment macro is
! 153: .Sq \&.Dd
! 154: or
! 155: .Sq \&.Dt ,
! 156: the
! 157: .Xr mdoc 7
! 158: parser is used; otherwise, the
! 159: .Xr man 7
! 160: parser is used.
! 161: .Pp
! 162: If multiple
! 163: files are specified with
! 164: .Fl m Ns Ar andoc ,
! 165: each has its file-type determined this way. If multiple files are
! 166: specified and
! 167: .Fl m Ns Ar doc
! 168: or
! 169: .Fl m Ns Ar an
! 170: is specified, then this format is used exclusively.
! 171: .\" .Pp
! 172: .\" The following escape sequences are recognised, although the per-format
! 173: .\" compiler may not allow certain sequences.
! 174: .\" .Bl -tag -width Ds -offset XXXX
! 175: .\" .It \efX
! 176: .\" sets the font mode to X (B, I, R or P, where P resets the font)
! 177: .\" .It \eX, \e(XX, \e[XN]
! 178: .\" queries the special-character table for a corresponding symbol
! 179: .\" .It \e*X, \e*(XX, \e*[XN]
! 180: .\" deprecated special-character format
! 181: .\" .El
! 182: .\" SUB-SECTION
! 183: .Ss Output Formats
! 184: The
! 185: .Nm
! 186: utility accepts the following
! 187: .Fl T
! 188: arguments:
! 189: .Bl -tag -width XXXXXXXXXXXX
! 190: .It Fl T Ns Ar ascii
! 191: Produce 7-bit ASCII output, backspace-encoded for bold and underline
! 192: styles. This is the default.
! 193: .It Fl T Ns Ar tree
! 194: Produce an indented parse tree.
! 195: .It Fl T Ns Ar lint
! 196: Parse only: produce no output.
! 197: .El
! 198: .Pp
! 199: If multiple input files are specified, these will be processed by the
! 200: corresponding filter in-order.
! 201: .\" SUB-SECTION
! 202: .Ss Compiler Options
! 203: Default compiler behaviour may be overriden with the
! 204: .Fl f
! 205: flag.
! 206: .Bl -tag -width XXXXXXXXXXXXXXXXXXXX
! 207: .It Fl f Ns Ar ign-scope
! 208: When rewinding the scope of a block macro, forces the compiler to ignore
! 209: scope violations. This can seriously mangle the resulting tree.
! 210: .Pq mdoc only
! 211: .It Fl f Ns Ar no-ign-escape
! 212: Don't ignore invalid escape sequences.
! 213: .It Fl f Ns Ar no-ign-macro
! 214: Do not ignore unknown macros at the start of input lines.
! 215: .It Fl f Ns Ar no-ign-chars
! 216: Do not ignore disallowed characters.
! 217: .It Fl f Ns Ar strict
! 218: Implies
! 219: .Fl f Ns Ar no-ign-escape ,
! 220: .Fl f Ns Ar no-ign-macro
! 221: and
! 222: .Fl f Ns Ar no-ign-chars .
! 223: .El
! 224: .\" PARAGRAPH
! 225: .Pp
! 226: As with the
! 227: .Fl W
! 228: flag, multiple
! 229: .Fl f
! 230: options may be grouped and delimited with a comma. Using
! 231: .Fl f Ns Ar ign-scope,no-ign-escape ,
! 232: for example, will try to ignore scope and not ignore character-escape
! 233: errors.
! 234: .\" SECTION
! 235: .Sh EXAMPLES
! 236: To page manuals to the terminal:
! 237: .\" PARAGRAPH
! 238: .Pp
! 239: .D1 % mandoc \-Wall,error \-fstrict mandoc.1 2>&1 | less
! 240: .D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
! 241: .\" SECTION
! 242: .Sh SEE ALSO
! 243: .Xr mandoc_char 7 ,
! 244: .Xr mdoc 7 ,
! 245: .Xr man 7
! 246: .\"
! 247: .Sh AUTHORS
! 248: The
! 249: .Nm
! 250: utility was written by
! 251: .An Kristaps Dzonsons Aq kristaps@openbsd.org .
! 252: .\" SECTION
! 253: .Sh CAVEATS
! 254: The
! 255: .Nm
! 256: utility in
! 257: .Fl T Ns Ar ascii
! 258: mode doesn't yet know how to display the following:
! 259: .Pp
! 260: .Bl -bullet -compact
! 261: .It
! 262: The \-hang
! 263: .Sq \&.Bl
! 264: list is not yet supported.
! 265: .El
! 266: .Pp
! 267: Other macros still aren't supported by virtue of nobody complaining
! 268: about their absence. Please report any omissions: this is a work in
! 269: progress.
! 270: .Pp
! 271: The following list documents differences between traditional
! 272: .Xr nroff 1
! 273: output and
! 274: .Nm :
! 275: .Pp
! 276: .Bl -bullet -compact
! 277: .It
! 278: A list of display following
! 279: .Sq \&.Ss
! 280: does not assert a prior vertical break, just as it doesn't with
! 281: .Sq \&.Sh .
! 282: .It
! 283: Special characters don't follow the current font style.
! 284: .\" LIST-ITEM
! 285: .It
! 286: The \-literal and \-unfilled
! 287: .Sq \&.Bd
! 288: displays types are synonyms, as are \-filled and \-ragged.
! 289: .El
![[BACK]](/icons/back.gif){kind=icon}
Return to mandoc.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / mandoc