=================================================================== RCS file: /cvs/mandoc/mandoc.1,v retrieving revision 1.19 retrieving revision 1.27 diff -u -p -r1.19 -r1.27 --- mandoc/mandoc.1 2009/06/15 09:35:16 1.19 +++ mandoc/mandoc.1 2009/07/21 15:52:41 1.27 @@ -1,4 +1,4 @@ -.\" $Id: mandoc.1,v 1.19 2009/06/15 09:35:16 kristaps Exp $ +.\" $Id: mandoc.1,v 1.27 2009/07/21 15:52:41 kristaps Exp $ .\" .\" Copyright (c) 2009 Kristaps Dzonsons .\" @@ -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: June 15 2009 $ +.Dd $Mdocdate: July 21 2009 $ .Dt MANDOC 1 .Os .\" SECTION @@ -34,13 +34,13 @@ .Sh DESCRIPTION The .Nm -utility formats +utility formats .Ux manual pages for display. The arguments are as follows: .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 @@ -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 @@ -210,16 +215,18 @@ flag. 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@kth.se . -.\" 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 .