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