Annotation of mandoc/mandoc.1, Revision 1.7
1.7 ! kristaps 1: .\" $Id: mandoc.1,v 1.6 2009/03/22 19:08:53 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
1.7 ! kristaps 121: Note that reserved words only register as such as if they appear as
! 122: standalone tokens, either in parsed lines or streams of text. Thus, the
! 123: following fragment:
1.4 kristaps 124: .Bd -literal -offset XXXX
125: this self is not that of the waking , empirically real man
126: .Ed
127: .\" PARAGRAPH
128: .Pp
129: \&...correctly adjusts the comma spacing to
1.7 ! kristaps 130: .Dq this self is not that of the waking , empirically real man .
! 131: However, if the comma were part of
! 132: .Dq ,empirically ,
! 133: it would not.
1.4 kristaps 134: .\" SUB-SECTION
1.1 kristaps 135: .Ss Output Formats
136: The
137: .Nm
138: utility accepts the following
139: .Fl T
140: arguments:
141: .Bl -tag -width XXXXXXXXXXXX -offset XXXX
142: .It Ar ascii
143: Produce 7-bit ASCII output, backspace-encoded for bold and underline
144: styles. This is the default.
145: .It Ar tree
146: Produce an indented parse tree.
147: .It Ar lint
148: Parse only: produce no output.
149: .El
150: .\" SUB-SECTION
151: .Ss Compiler Options
152: Default compiler behaviour may be overriden with the
153: .Fl f
154: flag.
155: .Bl -tag -width XXXXXXXXXXXX -offset XXXX
156: .It Fl f Ns Ar ign-scope
157: When rewinding the scope of a block macro, forces the compiler to ignore
158: scope violations. This can seriously mangle the resulting tree.
159: .It Fl f Ns Ar ign-escape
160: Ignore invalid escape sequences.
161: .It Fl f Ns Ar ign-macro
162: Ignore unknown macros at the start of input lines.
163: .El
164: .\" PARAGRAPH
165: .Pp
166: As with the
167: .Fl W
168: flag, multiple
169: .Fl f
170: options may be grouped and delimited with a comma. Using
171: .Fl f Ns Ar ign-scope,ign-escape ,
172: for example, will try to ignore scope and character-escape errors.
173: .\" SECTION
174: .Sh EXAMPLES
175: To page this manual page on the terminal:
176: .\" PARAGRAPH
177: .Pp
178: .D1 % mandoc \-Wall,error mandoc.1 2>&1 | less
179: .\" SECTION
180: .Sh SEE ALSO
181: .Xr mdoc 7
182: .\"
183: .Sh AUTHORS
184: The
185: .Nm
186: utility was written by
187: .An Kristaps Dzonsons Aq kristaps@openbsd.org .
188: .\" SECTION
189: .Sh CAVEATS
190: The
191: .Nm
1.5 kristaps 192: utility in
193: .Fl T Ns Ar ascii
194: mode doesn't yet know how to display the following:
1.1 kristaps 195: .Pp
196: .Bl -bullet -compact
197: .It
198: The \-hang
199: .Sq \&Bl
200: list is not yet supported.
1.7 ! kristaps 201: .El
! 202: .Pp
! 203: Other macros still aren't supported by virtue of nobody complaining
! 204: about their absence. Please report any omissions: this is a work in
! 205: progress.
! 206: .Pp
! 207: The following list documents differences between traditional
! 208: .Xr nroff 1
! 209: output and
! 210: .Nm :
! 211: .Pp
! 212: .Bl -bullet -compact
! 213: .It
! 214: A list of display following
! 215: .Sq \&Ss
! 216: does not assert a prior vertical break, just as it doesn't with
! 217: .Sq \&Sh .
! 218: .It
! 219: Special characters don't follow the current font style.
1.5 kristaps 220: .\" LIST-ITEM
1.1 kristaps 221: .It
222: The \-literal and \-unfilled
223: .Sq \&Bd
1.3 kristaps 224: displays types are synonyms, as are \-filled and \-ragged.
1.1 kristaps 225: .El
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to mandoc.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc