mandoc.1

   1 .\"     $Id: mandoc.1,v 1.30 2009/08/19 09:14:50 kristaps Exp $
   2 .\"
   3 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
   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 above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   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.
  16 .\"
  17 .Dd $Mdocdate: August 19 2009 $
  18 .Dt MANDOC 1
  19 .Os
  20 .\" SECTION
  21 .Sh NAME
  22 .Nm mandoc
  23 .Nd format and display UNIX manuals
  24 .\" SECTION
  25 .Sh SYNOPSIS
  26 .Nm mandoc
  27 .Op Fl V
  28 .Op Fl f Ns Ar option...
  29 .Op Fl m Ns Ar format
  30 .Op Fl W Ns Ar err...
  31 .Op Fl T Ns Ar output
  32 .Op Ar infile...
  33 .\" SECTION
  34 .Sh DESCRIPTION
  35 The
  36 .Nm
  37 utility formats
  38 .Ux
  39 manual pages for display.  The arguments are as follows:
  40 .Bl -tag -width Ds
  41 .\" ITEM
  42 .It Fl f Ns Ar option...
  43 Override default compiler behaviour.  See
  44 .Sx Compiler Options
  45 for details.
  46 .\" ITEM
  47 .It Fl m Ns Ar format
  48 Input format.  See
  49 .Sx Input Formats
  50 for available formats.  Defaults to
  51 .Fl m Ns Ar andoc .
  52 .\" ITEM
  53 .It Fl T Ns Ar output
  54 Output format.  See
  55 .Sx Output Formats
  56 for available formats.  Defaults to
  57 .Fl T Ns Ar ascii .
  58 .\" ITEM
  59 .It Fl V
  60 Print version and exit.
  61 .\" ITEM
  62 .It Fl W Ns Ar err...
  63 Configure warning messages.  Use
  64 .Fl W Ns Ar all
  65 to print warnings,
  66 .Fl W Ns Ar error
  67 for warnings to be considered errors and cause utility
  68 termination.  Multiple
  69 .Fl W
  70 arguments may be comma-separated, such as
  71 .Fl W Ns Ar error,all .
  72 .\" ITEM
  73 .It Ar infile...
  74 Read input from zero or more
  75 .Ar infile .
  76 If unspecified, reads from stdin.  If multiple files are specified,
  77 .Nm
  78 will halt with the first failed parse.
  79 .El
  80 .\" PARAGRAPH
  81 .Pp
  82 By default,
  83 .Nm
  84 reads
  85 .Xr mdoc 7
  86 or
  87 .Xr man 7
  88 text from stdin, implying
  89 .Fl m Ns Ar andoc ,
  90 and prints 78-column backspace-encoded output to stdout as if
  91 .Fl T Ns Ar ascii
  92 were provided.
  93 .\" PARAGRAPH
  94 .Pp
  95 .Ex -std mandoc
  96 .\" SUB-SECTION
  97 .Ss Punctuation and Spacing
  98 If punctuation is set apart from words, such as in the phrase
  99 .Dq to be \&, or not to be ,
 100 it's processed by
 101 .Nm
 102 according to the following rules:  opening punctuation
 103 .Po
 104 .Sq \&( ,
 105 .Sq \&[ ,
 106 and
 107 .Sq \&{
 108 .Pc
 109 is not followed by a space; closing punctuation
 110 .Po
 111 .Sq \&. ,
 112 .Sq \&, ,
 113 .Sq \&; ,
 114 .Sq \&: ,
 115 .Sq \&? ,
 116 .Sq \&! ,
 117 .Sq \&) ,
 118 .Sq \&]
 119 and
 120 .Sq \&}
 121 .Pc
 122 is not preceded by whitespace.
 123 .Pp
 124 If the input is
 125 .Xr mdoc 7 ,
 126 these rules are also applied to macro arguments when appropriate.
 127 .Pp
 128 White-space, in non-literal (normal) mode, is stripped from input and
 129 replaced on output by a single space.  Thus, if you wish to preserve
 130 multiple spaces, they must be space-escaped
 131 .Sq \e\
 132 or used in a literal display mode, e.g.,
 133 .Sq \&Bd \-literal
 134 in
 135 .Xr mdoc 7 .
 136 .\" SUB-SECTION
 137 .Ss Input Formats
 138 The
 139 .Nm
 140 utility accepts
 141 .Xr mdoc 7
 142 and
 143 .Xr man 7
 144 input with
 145 .Fl m Ns Ar doc
 146 and
 147 .Fl m Ns Ar an ,
 148 respectively.  The
 149 .Xr mdoc 7
 150 format is
 151 .Em strongly
 152 recommended;
 153 .Xr man 7
 154 should only be used for legacy manuals.
 155 .Pp
 156 A third option,
 157 .Fl m Ns Ar andoc ,
 158 which is also the default, determines encoding on-the-fly: if the first
 159 non-comment macro is
 160 .Sq \&Dd
 161 or
 162 .Sq \&Dt ,
 163 the
 164 .Xr mdoc 7
 165 parser is used; otherwise, the
 166 .Xr man 7
 167 parser is used.
 168 .Pp
 169 If multiple
 170 files are specified with
 171 .Fl m Ns Ar andoc ,
 172 each has its file-type determined this way.  If multiple files are
 173 specified and
 174 .Fl m Ns Ar doc
 175 or
 176 .Fl m Ns Ar an
 177 is specified, then this format is used exclusively.
 178 .\" .Pp
 179 .\" The following escape sequences are recognised, although the per-format
 180 .\" compiler may not allow certain sequences.
 181 .\" .Bl -tag -width Ds -offset XXXX
 182 .\" .It \efX
 183 .\" sets the font mode to X (B, I, R or P, where P resets the font)
 184 .\" .It \eX, \e(XX, \e[XN]
 185 .\" queries the special-character table for a corresponding symbol
 186 .\" .It \e*X, \e*(XX, \e*[XN]
 187 .\" deprecated special-character format
 188 .\" .El
 189 .\" SUB-SECTION
 190 .Ss Output Formats
 191 The
 192 .Nm
 193 utility accepts the following
 194 .Fl T
 195 arguments:
 196 .Bl -tag -width Ds
 197 .It Fl T Ns Ar ascii
 198 Produce 7-bit ASCII output, backspace-encoded for bold and underline
 199 styles.  This is the default.
 200 .It Fl T Ns Ar tree
 201 Produce an indented parse tree.
 202 .It Fl T Ns Ar lint
 203 Parse only: produce no output.
 204 .El
 205 .Pp
 206 If multiple input files are specified, these will be processed by the
 207 corresponding filter in-order.
 208 .\" SUB-SECTION
 209 .Ss Compiler Options
 210 Default compiler behaviour may be overriden with the
 211 .Fl f
 212 flag.
 213 .Bl -tag -width Ds
 214 .It Fl f Ns Ar ign-scope
 215 When rewinding the scope of a block macro, forces the compiler to ignore
 216 scope violations.  This can seriously mangle the resulting tree.
 217 .Pq mdoc only
 218 .It Fl f Ns Ar no-ign-escape
 219 Don't ignore invalid escape sequences.
 220 .It Fl f Ns Ar no-ign-macro
 221 Do not ignore unknown macros at the start of input lines.
 222 .It Fl f Ns Ar no-ign-chars
 223 Do not ignore disallowed characters.
 224 .It Fl f Ns Ar strict
 225 Implies
 226 .Fl f Ns Ar no-ign-escape ,
 227 .Fl f Ns Ar no-ign-macro
 228 and
 229 .Fl f Ns Ar no-ign-chars .
 230 .It Fl f Ns Ar ign-errors
 231 Don't halt when encountering parse errors.  Useful with
 232 .Fl T Ns Ar lint
 233 over a large set of manuals passed on the command line.
 234 .El
 235 .\" PARAGRAPH
 236 .Pp
 237 As with the
 238 .Fl W
 239 flag, multiple
 240 .Fl f
 241 options may be grouped and delimited with a comma.  Using
 242 .Fl f Ns Ar ign-scope,no-ign-escape ,
 243 for example, will try to ignore scope and not ignore character-escape
 244 errors.
 245 .\" SECTION
 246 .Sh EXAMPLES
 247 To page manuals to the terminal:
 248 .\" PARAGRAPH
 249 .Pp
 250 .D1 % mandoc \-Wall,error \-fstrict mandoc.1 2>&1 | less
 251 .D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
 252 .\" PARAGRAPH
 253 .Pp
 254 To check over a large set of manuals:
 255 .\" PARAGRAPH
 256 .Pp
 257 .Dl % mandoc \-Tlint \-fign-errors `find /usr/src -name \e*\e.[1-9]`
 258 .\" SECTION
 259 .Sh COMPATIBILITY
 260 This section summarises
 261 .Nm
 262 compatibility with
 263 .Xr groff 1 .
 264 .Pp
 265 .Bl -bullet -compact
 266 .\" LIST-ITEM
 267 .It
 268 The
 269 .Sq \e~
 270 special character doesn't produce expected behaviour.
 271 .\" LIST-ITEM
 272 .It
 273 In
 274 .Xr groff 1 ,
 275 the
 276 .Sq \&Pa
 277 macro does not underline when under a
 278 .Sq \&It
 279 in the FILES section.  This behaves correctly in
 280 .Nm .
 281 .\" LIST-ITEM
 282 .It
 283 A list or display following
 284 .Sq \&Ss
 285 does not assert a prior vertical break, just as it doesn't with
 286 .Sq \&Sh .
 287 .It
 288 The \-literal and \-unfilled
 289 .Sq \&Bd
 290 displays types are synonyms, as are \-filled and \-ragged.
 291 .\" LIST-ITEM
 292 .It
 293 Words aren't hyphenated.
 294 .\" LIST-ITEM
 295 .It
 296 In normal mode (not a literal block), blocks of spaces aren't preserved,
 297 so double spaces following sentence closure are reduced to a single space.
 298 .El
 299 .\" SECTION
 300 .Sh SEE ALSO
 301 .Xr mandoc_char 7 ,
 302 .Xr mdoc 7 ,
 303 .Xr man 7
 304 .\" SECTION
 305 .Sh AUTHORS
 306 The
 307 .Nm
 308 utility was written by
 309 .An Kristaps Dzonsons Aq kristaps@kth.se .