mandoc.1

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