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