=================================================================== RCS file: /cvs/mandoc/mandoc.1,v retrieving revision 1.16 retrieving revision 1.27 diff -u -p -r1.16 -r1.27 --- mandoc/mandoc.1 2009/04/12 19:45:26 1.16 +++ mandoc/mandoc.1 2009/07/21 15:52:41 1.27 @@ -1,6 +1,6 @@ -.\" $Id: mandoc.1,v 1.16 2009/04/12 19:45:26 kristaps Exp $ +.\" $Id: mandoc.1,v 1.27 2009/07/21 15:52:41 kristaps Exp $ .\" -.\" Copyright (c) 2009 Kristaps Dzonsons +.\" Copyright (c) 2009 Kristaps Dzonsons .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above @@ -14,7 +14,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: April 12 2009 $ +.Dd $Mdocdate: July 21 2009 $ .Dt MANDOC 1 .Os .\" SECTION @@ -34,23 +34,23 @@ .Sh DESCRIPTION The .Nm -utility formats +utility formats .Ux manual pages for display. The arguments are as follows: -.Bl -tag -width XXXXXXXXXXXX +.Bl -tag -width Ds .\" ITEM .It Fl f Ns Ar option... -Override default compiler behaviour. See +Override default compiler behaviour. See .Sx Compiler Options for details. .\" ITEM -.It Fl m +.It Fl m Ns Ar format Input format. See .Sx Input Formats for available formats. Defaults to .Fl m Ns Ar andoc . .\" ITEM -.It Fl T +.It Fl T Ns Ar output Output format. See .Sx Output Formats for available formats. Defaults to @@ -60,16 +60,12 @@ for available formats. Defaults to Print version and exit. .\" ITEM .It Fl W Ns Ar err... -Print warning messages. May be set to +Configure warning messages. Use .Fl W Ns Ar all -for all warnings, -.Ar compat -for groff/troff-compatibility warnings, or -.Ar syntax -for syntax warnings. If -.Fl W Ns Ar error -is specified, warnings are considered errors and cause utility -termination. Multiple +to print warnings, +.Fl W Ns Ar error +for warnings to be considered errors and cause utility +termination. Multiple .Fl W arguments may be comma-separated, such as .Fl W Ns Ar error,all . @@ -83,9 +79,9 @@ will halt with the first failed parse. .El .\" PARAGRAPH .Pp -By default, -.Nm -reads +By default, +.Nm +reads .Xr mdoc 7 or .Xr man 7 @@ -98,36 +94,45 @@ were provided. .Pp .Ex -std mandoc .\" SUB-SECTION -.Ss Punctuation +.Ss Punctuation and Spacing If punctuation is set apart from words, such as in the phrase .Dq to be \&, or not to be , it's processed by .Nm -according to the following rules. Opening punctuation +according to the following rules: opening punctuation .Po -.Sq \&( , -.Sq \&[ , +.Sq \&( , +.Sq \&[ , and .Sq \&{ -.Pc -is not followed by a space. Closing punctuation +.Pc +is not followed by a space; closing punctuation .Po -.Sq \&. , -.Sq \&, , -.Sq \&; , -.Sq \&: , -.Sq \&? , -.Sq \&! , -.Sq \&) , -.Sq \&] +.Sq \&. , +.Sq \&, , +.Sq \&; , +.Sq \&: , +.Sq \&? , +.Sq \&! , +.Sq \&) , +.Sq \&] and .Sq \&} -.Pc +.Pc is not preceded by whitespace. .Pp If the input is .Xr mdoc 7 , these rules are also applied to macro arguments when appropriate. +.Pp +White-space, in non-literal (normal) mode, is stripped from input and +replaced on output by a single space. Thus, if you wish to preserve +multiple spaces, they must be space-escaped +.Sq \e\ +or used in a literal display mode, e.g., +.Sq \&Bd \-literal +in +.Xr mdoc 7 . .\" SUB-SECTION .Ss Input Formats The @@ -144,26 +149,26 @@ respectively. The .Xr mdoc 7 format is .Em strongly -recommended; +recommended; .Xr man 7 should only be used for legacy manuals. .Pp A third option, .Fl m Ns Ar andoc , which is also the default, determines encoding on-the-fly: if the first -non-comment macro is -.Sq \&.Dd +non-comment macro is +.Sq \&Dd or -.Sq \&.Dt , -the +.Sq \&Dt , +the .Xr mdoc 7 parser is used; otherwise, the .Xr man 7 parser is used. .Pp If multiple -files are specified with -.Fl m Ns Ar andoc , +files are specified with +.Fl m Ns Ar andoc , each has its file-type determined this way. If multiple files are specified and .Fl m Ns Ar doc @@ -188,7 +193,7 @@ The utility accepts the following .Fl T arguments: -.Bl -tag -width XXXXXXXXXXXX +.Bl -tag -width Ds .It Fl T Ns Ar ascii Produce 7-bit ASCII output, backspace-encoded for bold and underline styles. This is the default. @@ -205,21 +210,23 @@ corresponding filter in-order. Default compiler behaviour may be overriden with the .Fl f flag. -.Bl -tag -width XXXXXXXXXXXXXX +.Bl -tag -width Ds .It Fl f Ns Ar ign-scope When rewinding the scope of a block macro, forces the compiler to ignore scope violations. This can seriously mangle the resulting tree. .Pq mdoc only -.It Fl f Ns Ar ign-escape -Ignore invalid escape sequences. -.It Fl f Ns Ar ign-macro -Ignore unknown macros at the start of input lines (default for -.Xr man 7 -parsing). +.It Fl f Ns Ar no-ign-escape +Don't ignore invalid escape sequences. .It Fl f Ns Ar no-ign-macro -Do not ignore unknown macros at the start of input lines (default for -.Xr mdoc 7 -parsing). +Do not ignore unknown macros at the start of input lines. +.It Fl f Ns Ar no-ign-chars +Do not ignore disallowed characters. +.It Fl f Ns Ar strict +Implies +.Fl f Ns Ar no-ign-escape , +.Fl f Ns Ar no-ign-macro +and +.Fl f Ns Ar no-ign-chars . .El .\" PARAGRAPH .Pp @@ -228,62 +235,57 @@ As with the flag, multiple .Fl f options may be grouped and delimited with a comma. Using -.Fl f Ns Ar ign-scope,ign-escape , -for example, will try to ignore scope and character-escape errors. +.Fl f Ns Ar ign-scope,no-ign-escape , +for example, will try to ignore scope and not ignore character-escape +errors. .\" SECTION .Sh EXAMPLES To page manuals to the terminal: .\" PARAGRAPH .Pp -.D1 % mandoc \-Wall,error mandoc.1 2>&1 | less -.Pp +.D1 % mandoc \-Wall,error \-fstrict mandoc.1 2>&1 | less .D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less .\" SECTION -.Sh SEE ALSO -.Xr mandoc_char 7 , -.Xr mdoc 7 , -.Xr man 7 -.\" -.Sh AUTHORS -The +.Sh COMPATIBILITY +This section summarises .Nm -utility was written by -.An Kristaps Dzonsons Aq kristaps@openbsd.org . -.\" SECTION -.Sh CAVEATS -The -.Nm -utility in -.Fl T Ns Ar ascii -mode doesn't yet know how to display the following: +compatibility with +.Xr groff 1 . .Pp .Bl -bullet -compact .It -The \-hang -.Sq \&.Bl -list is not yet supported. -.El -.Pp -Other macros still aren't supported by virtue of nobody complaining -about their absence. Please report any omissions: this is a work in -progress. -.Pp -The following list documents differences between traditional -.Xr nroff 1 -output and -.Nm : -.Pp -.Bl -bullet -compact -.It -A list of display following -.Sq \&.Ss +In +.Xr groff 1 , +the +.Sq \&Pa +macro does not underline when under a +.Sq \&It . +This behaves correctly in +.Nm . +.It +A list or display following +.Sq \&Ss does not assert a prior vertical break, just as it doesn't with -.Sq \&.Sh . +.Sq \&Sh . .It -Special characters don't follow the current font style. -.\" LIST-ITEM -.It -The \-literal and \-unfilled -.Sq \&.Bd +The \-literal and \-unfilled +.Sq \&Bd displays types are synonyms, as are \-filled and \-ragged. +.It +Words aren't hyphenated. +.It +In normal mode (not a literal block), blocks of spaces aren't preserved, +so double spaces following sentence closure are reduced to a single space +.Pq Dq French spacing . .El +.\" SECTION +.Sh SEE ALSO +.Xr mandoc_char 7 , +.Xr mdoc 7 , +.Xr man 7 +.\" SECTION +.Sh AUTHORS +The +.Nm +utility was written by +.An Kristaps Dzonsons Aq kristaps@kth.se .