mandoc.1

   1 .\" $Id: mandoc.1,v 1.8 2009/03/23 15:41:09 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 23 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 mdoc .
  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 mdoc
 154 and
 155 .Fl m Ns Ar man ,
 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 Note that the
 165 .Fl m Ns Ar man
 166 option is experimental and only works with
 167 .Fl T Ns Ar tree .
 168 .\" SUB-SECTION
 169 .Ss Output Formats
 170 The
 171 .Nm
 172 utility accepts the following
 173 .Fl T
 174 arguments:
 175 .Bl -tag -width XXXXXXXXXXXX -offset XXXX
 176 .It Ar ascii
 177 Produce 7-bit ASCII output, backspace-encoded for bold and underline
 178 styles.  This is the default.
 179 .It Ar tree
 180 Produce an indented parse tree.
 181 .It Ar lint
 182 Parse only: produce no output.
 183 .El
 184 .\" SUB-SECTION
 185 .Ss Compiler Options
 186 Default compiler behaviour may be overriden with the
 187 .Fl f
 188 flag.
 189 .Bl -tag -width XXXXXXXXXXXX -offset XXXX
 190 .It Fl f Ns Ar ign-scope
 191 When rewinding the scope of a block macro, forces the compiler to ignore
 192 scope violations.  This can seriously mangle the resulting tree.
 193 .Pq mdoc only
 194 .It Fl f Ns Ar ign-escape
 195 Ignore invalid escape sequences.
 196 .It Fl f Ns Ar ign-macro
 197 Ignore unknown macros at the start of input lines.
 198 .El
 199 .\" PARAGRAPH
 200 .Pp
 201 As with the
 202 .Fl W
 203 flag, multiple
 204 .Fl f
 205 options may be grouped and delimited with a comma.  Using
 206 .Fl f Ns Ar ign-scope,ign-escape ,
 207 for example, will try to ignore scope and character-escape errors.
 208 .\" SECTION
 209 .Sh EXAMPLES
 210 To page this manual page on the terminal:
 211 .\" PARAGRAPH
 212 .Pp
 213 .D1 % mandoc \-Wall,error mandoc.1 2>&1 | less
 214 .\" SECTION
 215 .Sh SEE ALSO
 216 .Xr mdoc 7
 217 .\"
 218 .Sh AUTHORS
 219 The
 220 .Nm
 221 utility was written by
 222 .An Kristaps Dzonsons Aq kristaps@openbsd.org .
 223 .\" SECTION
 224 .Sh CAVEATS
 225 The
 226 .Nm
 227 utility in
 228 .Fl T Ns Ar ascii
 229 mode doesn't yet know how to display the following:
 230 .Pp
 231 .Bl -bullet -compact
 232 .It
 233 The \-hang
 234 .Sq \&Bl
 235 list is not yet supported.
 236 .El
 237 .Pp
 238 Other macros still aren't supported by virtue of nobody complaining
 239 about their absence.  Please report any omissions: this is a work in
 240 progress.
 241 .Pp
 242 The following list documents differences between traditional
 243 .Xr nroff 1
 244 output and
 245 .Nm :
 246 .Pp
 247 .Bl -bullet -compact
 248 .It
 249 A list of display following
 250 .Sq \&Ss
 251 does not assert a prior vertical break, just as it doesn't with
 252 .Sq \&Sh .
 253 .It
 254 Special characters don't follow the current font style.
 255 .\" LIST-ITEM
 256 .It
 257 The \-literal and \-unfilled
 258 .Sq \&Bd
 259 displays types are synonyms, as are \-filled and \-ragged.
 260 .El