mandoc.1

   1 .\" $Id: mandoc.1,v 1.11 2009/03/26 16:44: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: March 26 2009 $
  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 V
  30 .Op Fl f Ns Ar option...
  31 .Op Fl m Ns Ar format
  32 .Op Fl W Ns Ar err...
  33 .Op Fl T Ns Ar output
  34 .Op Ar infile...
  35 .\" SECTION
  36 .Sh DESCRIPTION
  37 The
  38 .Nm
  39 utility formats
  40 .Ux
  41 manual pages for display.  The arguments are as follows:
  42 .Bl -tag -width XXXXXXXXXXXX
  43 .\" ITEM
  44 .It Fl f Ns Ar option...
  45 Override default compiler behaviour.  See
  46 .Sx Compiler Options
  47 for details.
  48 .\" ITEM
  49 .It Fl m
  50 Input format.  See
  51 .Sx Input Formats
  52 for available formats.  Defaults to
  53 .Fl m Ns Ar doc .
  54 .\" ITEM
  55 .It Fl T
  56 Output format.  See
  57 .Sx Output Formats
  58 for available formats.  Defaults to
  59 .Fl T Ns Ar ascii .
  60 .\" ITEM
  61 .It Fl V
  62 Print version and exit.
  63 .\" ITEM
  64 .It Fl W Ns Ar err...
  65 Print warning messages.  May be set to
  66 .Fl W Ns Ar all
  67 for all warnings,
  68 .Ar compat
  69 for groff/troff-compatibility warnings, or
  70 .Ar syntax
  71 for syntax warnings.  If
  72 .Fl W Ns Ar error
  73 is specified, warnings are considered errors and cause utility
  74 termination.  Multiple
  75 .Fl W
  76 arguments may be comma-separated, such as
  77 .Fl W Ns Ar error,all .
  78 .\" ITEM
  79 .It Ar infile...
  80 Read input from zero or more
  81 .Ar infile .
  82 If unspecified, reads from stdin.  If multiple files are specified,
  83 .Nm
  84 will halt with the first failed parse.
  85 .El
  86 .\" PARAGRAPH
  87 .Pp
  88 By default,
  89 .Nm
  90 reads
  91 .Xr mdoc 7
  92 text from stdin, implying
  93 .Fl m Ns Ar mdoc ,
  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 Reserved Words (mdoc only)
 102 The reserved words described in
 103 .Xr mdoc 7
 104 are handled according to the following rules:
 105 .Bl -enum -offset XXX
 106 .It
 107 Opening delimiters
 108 .Po
 109 .Sq \&( ,
 110 .Sq \&[ ,
 111 and
 112 .Sq \&{
 113 .Pc are not followed by whitespace.
 114 .It
 115 Closing delimiters
 116 .Po
 117 .Sq \&. ,
 118 .Sq \&, ,
 119 .Sq \&; ,
 120 .Sq \&: ,
 121 .Sq \&? ,
 122 .Sq \&! ,
 123 .Sq \&) ,
 124 .Sq \&]
 125 and
 126 .Sq \&}
 127 .Pc are not preceeded by whitespace.
 128 .El
 129 .\" PARAGRAPH
 130 .Pp
 131 Note that reserved words only register as such as if they appear as
 132 standalone tokens, either in parsed lines or streams of text.  Thus, the
 133 following fragment:
 134 .Bd -literal -offset XXXX
 135 this self is not that of the waking , empirically real man
 136 .Ed
 137 .\" PARAGRAPH
 138 .Pp
 139 \&...correctly adjusts the comma spacing to
 140 .Dq this self is not that of the waking , empirically real man .
 141 However, if the comma were part of
 142 .Dq ,empirically ,
 143 it would not.
 144 .\" SUB-SECTION
 145 .Ss Input Formats
 146 The
 147 .Nm
 148 utility accepts
 149 .Xr mdoc 7
 150 and
 151 .Xr man 7
 152 input with
 153 .Fl m Ns Ar doc
 154 and
 155 .Fl m Ns Ar an ,
 156 respectively.  The
 157 .Xr mdoc 7
 158 format is
 159 .Em strongly
 160 recommended;
 161 .Xr man 7
 162 should only be used for legacy manuals.
 163 .Pp
 164 The following escape sequences are recognised, although the per-format
 165 compiler may not allow certain sequences.
 166 .Bl -tag -width Ds -offset XXXX
 167 .It \efX
 168 sets the font mode to X (B, I, R or P, where P resets the font)
 169 .It \eX, \e(XX, \e[XN]
 170 queries the special-character table for a corresponding symbol
 171 .It \e*X, \e*(XX, \e*[XN]
 172 deprecated special-character format
 173 .El
 174 .\" SUB-SECTION
 175 .Ss Output Formats
 176 The
 177 .Nm
 178 utility accepts the following
 179 .Fl T
 180 arguments:
 181 .Bl -tag -width XXXXXXXXXXXX -offset XXXX
 182 .It Ar ascii
 183 Produce 7-bit ASCII output, backspace-encoded for bold and underline
 184 styles.  This is the default.
 185 .It Ar tree
 186 Produce an indented parse tree.
 187 .It Ar lint
 188 Parse only: produce no output.
 189 .El
 190 .\" SUB-SECTION
 191 .Ss Compiler Options
 192 Default compiler behaviour may be overriden with the
 193 .Fl f
 194 flag.
 195 .Bl -tag -width XXXXXXXXXXXX -offset XXXX
 196 .It Fl f Ns Ar ign-scope
 197 When rewinding the scope of a block macro, forces the compiler to ignore
 198 scope violations.  This can seriously mangle the resulting tree.
 199 .Pq mdoc only
 200 .It Fl f Ns Ar ign-escape
 201 Ignore invalid escape sequences.
 202 .It Fl f Ns Ar ign-macro
 203 Ignore unknown macros at the start of input lines.
 204 .El
 205 .\" PARAGRAPH
 206 .Pp
 207 As with the
 208 .Fl W
 209 flag, multiple
 210 .Fl f
 211 options may be grouped and delimited with a comma.  Using
 212 .Fl f Ns Ar ign-scope,ign-escape ,
 213 for example, will try to ignore scope and character-escape errors.
 214 .\" SECTION
 215 .Sh EXAMPLES
 216 To page this manual page on the terminal:
 217 .\" PARAGRAPH
 218 .Pp
 219 .D1 % mandoc \-Wall,error mandoc.1 2>&1 | less
 220 .\" SECTION
 221 .Sh SEE ALSO
 222 .Xr mdoc 7 ,
 223 .Xr man 7
 224 .\"
 225 .Sh AUTHORS
 226 The
 227 .Nm
 228 utility was written by
 229 .An Kristaps Dzonsons Aq kristaps@openbsd.org .
 230 .\" SECTION
 231 .Sh CAVEATS
 232 The
 233 .Nm
 234 utility in
 235 .Fl T Ns Ar ascii
 236 mode doesn't yet know how to display the following:
 237 .Pp
 238 .Bl -bullet -compact
 239 .It
 240 The \-hang
 241 .Sq \&.Bl
 242 list is not yet supported.
 243 .El
 244 .Pp
 245 Other macros still aren't supported by virtue of nobody complaining
 246 about their absence.  Please report any omissions: this is a work in
 247 progress.
 248 .Pp
 249 The following list documents differences between traditional
 250 .Xr nroff 1
 251 output and
 252 .Nm :
 253 .Pp
 254 .Bl -bullet -compact
 255 .It
 256 A list of display following
 257 .Sq \&.Ss
 258 does not assert a prior vertical break, just as it doesn't with
 259 .Sq \&.Sh .
 260 .It
 261 Special characters don't follow the current font style.
 262 .\" LIST-ITEM
 263 .It
 264 The \-literal and \-unfilled
 265 .Sq \&.Bd
 266 displays types are synonyms, as are \-filled and \-ragged.
 267 .El