mandoc.1

   1 .\"     $Id: mandoc.1,v 1.23 2009/06/25 10:51:55 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: June 25 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 Print warning messages.  May be set to
  64 .Fl W Ns Ar all
  65 for all warnings,
  66 .Ar compat
  67 for groff/troff-compatibility warnings, or
  68 .Ar syntax
  69 for syntax warnings.  If
  70 .Fl W Ns Ar error
  71 is specified, warnings are considered errors and cause utility
  72 termination.  Multiple
  73 .Fl W
  74 arguments may be comma-separated, such as
  75 .Fl W Ns Ar error,all .
  76 .\" ITEM
  77 .It Ar infile...
  78 Read input from zero or more
  79 .Ar infile .
  80 If unspecified, reads from stdin.  If multiple files are specified,
  81 .Nm
  82 will halt with the first failed parse.
  83 .El
  84 .\" PARAGRAPH
  85 .Pp
  86 By default,
  87 .Nm
  88 reads
  89 .Xr mdoc 7
  90 or
  91 .Xr man 7
  92 text from stdin, implying
  93 .Fl m Ns Ar andoc ,
  94 and prints 78-column backspace-encoded output to stdout as if
  95 .Fl T Ns Ar ascii
  96 were provided.
  97 .\" PARAGRAPH
  98 .Pp
  99 .Ex -std mandoc
 100 .\" SUB-SECTION
 101 .Ss Punctuation and Spacing
 102 If punctuation is set apart from words, such as in the phrase
 103 .Dq to be \&, or not to be ,
 104 it's processed by
 105 .Nm
 106 according to the following rules:  opening punctuation
 107 .Po
 108 .Sq \&( ,
 109 .Sq \&[ ,
 110 and
 111 .Sq \&{
 112 .Pc
 113 is not followed by a space; closing punctuation
 114 .Po
 115 .Sq \&. ,
 116 .Sq \&, ,
 117 .Sq \&; ,
 118 .Sq \&: ,
 119 .Sq \&? ,
 120 .Sq \&! ,
 121 .Sq \&) ,
 122 .Sq \&]
 123 and
 124 .Sq \&}
 125 .Pc
 126 is not preceded by whitespace.
 127 .Pp
 128 If the input is
 129 .Xr mdoc 7 ,
 130 these rules are also applied to macro arguments when appropriate.
 131 .Pp
 132 White-space, in non-literal (normal) mode, is stripped from input and
 133 replaced on output by a single space.  Thus, if you wish to preserve
 134 multiple spaces, they must be space-escaped
 135 .Sq \e\
 136 or used in a literal display mode, e.g.,
 137 .Sq \&.Bd \-literal
 138 in
 139 .Xr mdoc 7 .
 140 .\" SUB-SECTION
 141 .Ss Input Formats
 142 The
 143 .Nm
 144 utility accepts
 145 .Xr mdoc 7
 146 and
 147 .Xr man 7
 148 input with
 149 .Fl m Ns Ar doc
 150 and
 151 .Fl m Ns Ar an ,
 152 respectively.  The
 153 .Xr mdoc 7
 154 format is
 155 .Em strongly
 156 recommended;
 157 .Xr man 7
 158 should only be used for legacy manuals.
 159 .Pp
 160 A third option,
 161 .Fl m Ns Ar andoc ,
 162 which is also the default, determines encoding on-the-fly: if the first
 163 non-comment macro is
 164 .Sq \&.Dd
 165 or
 166 .Sq \&.Dt ,
 167 the
 168 .Xr mdoc 7
 169 parser is used; otherwise, the
 170 .Xr man 7
 171 parser is used.
 172 .Pp
 173 If multiple
 174 files are specified with
 175 .Fl m Ns Ar andoc ,
 176 each has its file-type determined this way.  If multiple files are
 177 specified and
 178 .Fl m Ns Ar doc
 179 or
 180 .Fl m Ns Ar an
 181 is specified, then this format is used exclusively.
 182 .\" .Pp
 183 .\" The following escape sequences are recognised, although the per-format
 184 .\" compiler may not allow certain sequences.
 185 .\" .Bl -tag -width Ds -offset XXXX
 186 .\" .It \efX
 187 .\" sets the font mode to X (B, I, R or P, where P resets the font)
 188 .\" .It \eX, \e(XX, \e[XN]
 189 .\" queries the special-character table for a corresponding symbol
 190 .\" .It \e*X, \e*(XX, \e*[XN]
 191 .\" deprecated special-character format
 192 .\" .El
 193 .\" SUB-SECTION
 194 .Ss Output Formats
 195 The
 196 .Nm
 197 utility accepts the following
 198 .Fl T
 199 arguments:
 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 .It Fl T Ns Ar tree
 205 Produce an indented parse tree.
 206 .It Fl T Ns Ar lint
 207 Parse only: produce no output.
 208 .El
 209 .Pp
 210 If multiple input files are specified, these will be processed by the
 211 corresponding filter in-order.
 212 .\" SUB-SECTION
 213 .Ss Compiler Options
 214 Default compiler behaviour may be overriden with the
 215 .Fl f
 216 flag.
 217 .Bl -tag -width Ds
 218 .It Fl f Ns Ar ign-scope
 219 When rewinding the scope of a block macro, forces the compiler to ignore
 220 scope violations.  This can seriously mangle the resulting tree.
 221 .Pq mdoc only
 222 .It Fl f Ns Ar no-ign-escape
 223 Don't ignore invalid escape sequences.
 224 .It Fl f Ns Ar no-ign-macro
 225 Do not ignore unknown macros at the start of input lines.
 226 .It Fl f Ns Ar no-ign-chars
 227 Do not ignore disallowed characters.
 228 .It Fl f Ns Ar strict
 229 Implies
 230 .Fl f Ns Ar no-ign-escape ,
 231 .Fl f Ns Ar no-ign-macro
 232 and
 233 .Fl f Ns Ar no-ign-chars .
 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 .\" SECTION
 253 .Sh COMPATIBILITY
 254 This section summarises
 255 .Nm
 256 compatibility with
 257 .Xr groff 1 .
 258 .Pp
 259 .Bl -bullet -compact
 260 .It
 261 A list or display following
 262 .Sq \&.Ss
 263 does not assert a prior vertical break, just as it doesn't with
 264 .Sq \&.Sh .
 265 .It
 266 The \-literal and \-unfilled
 267 .Sq \&.Bd
 268 displays types are synonyms, as are \-filled and \-ragged.
 269 .It
 270 Words aren't hyphenated.
 271 .It
 272 In normal mode (not a literal block), blocks of spaces aren't preserved,
 273 so double spaces following sentence closure are reduced to a single space
 274 .Pq Dq French spacing .
 275 .El
 276 .\" SECTION
 277 .Sh SEE ALSO
 278 .Xr mandoc_char 7 ,
 279 .Xr mdoc 7 ,
 280 .Xr man 7
 281 .\" SECTION
 282 .Sh AUTHORS
 283 The
 284 .Nm
 285 utility was written by
 286 .An Kristaps Dzonsons Aq kristaps@kth.se .
 287 .\" SECTION
 288 .Sh CAVEATS
 289 The
 290 .Nm
 291 utility doesn't yet know how to display \-hang lists.
 292 .Pp
 293 Other macros still aren't supported by virtue of nobody complaining
 294 about their absence.