=================================================================== RCS file: /cvs/mandoc/mandoc.1,v retrieving revision 1.4 retrieving revision 1.17 diff -u -p -r1.4 -r1.17 --- mandoc/mandoc.1 2009/03/21 13:09:29 1.4 +++ mandoc/mandoc.1 2009/06/10 20:18:43 1.17 @@ -1,33 +1,32 @@ -.\" $Id: mandoc.1,v 1.4 2009/03/21 13:09:29 kristaps Exp $ +.\" $Id: mandoc.1,v 1.17 2009/06/10 20:18:43 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 copyright notice and this permission notice appear in all -.\" copies. +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. .\" -.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL -.\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE -.\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL -.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR -.\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER -.\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR -.\" PERFORMANCE OF THIS SOFTWARE. +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: March 21 2009 $ -.Dt mandoc 1 +.Dd $Mdocdate: June 10 2009 $ +.Dt MANDOC 1 .Os .\" SECTION .Sh NAME .Nm mandoc -.Nd format and display BSD manuals +.Nd format and display UNIX manuals .\" SECTION .Sh SYNOPSIS .Nm mandoc .Op Fl V .Op Fl f Ns Ar option... +.Op Fl m Ns Ar format .Op Fl W Ns Ar err... .Op Fl T Ns Ar output .Op Ar infile... @@ -35,9 +34,9 @@ .Sh DESCRIPTION The .Nm -utility formats a BSD -.Dq mdoc -manual page for display. The arguments are as follows: +utility formats +.Ux +manual pages for display. The arguments are as follows: .Bl -tag -width XXXXXXXXXXXX .\" ITEM .It Fl f Ns Ar option... @@ -45,6 +44,12 @@ Override default compiler behaviour. See .Sx Compiler Options for details. .\" ITEM +.It Fl m +Input format. See +.Sx Input Formats +for available formats. Defaults to +.Fl m Ns Ar andoc . +.\" ITEM .It Fl T Output format. See .Sx Output Formats @@ -80,29 +85,32 @@ will halt with the first failed parse. .Pp By default, .Nm -reads from stdin and prints 78-column backspace-encoded output to stdout -as if +reads +.Xr mdoc 7 +or +.Xr man 7 +text from stdin, implying +.Fl m Ns Ar andoc , +and prints 78-column backspace-encoded output to stdout as if .Fl T Ns Ar ascii were provided. .\" PARAGRAPH .Pp .Ex -std mandoc .\" SUB-SECTION -.Ss Reserved Words -The reserved words described in -.Xr mdoc 7 -are handled according to the following rules: -.Bl -enum -offset XXX -.It -Opening delimiters +.Ss Punctuation +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 .Po .Sq \&( , .Sq \&[ , and .Sq \&{ -.Pc are not followed by whitespace. -.It -Closing delimiters +.Pc +is not followed by a space. Closing punctuation .Po .Sq \&. , .Sq \&, , @@ -114,18 +122,65 @@ Closing delimiters .Sq \&] and .Sq \&} -.Pc are not preceeded by whitespace. -.El -.\" PARAGRAPH +.Pc +is not preceded by whitespace. .Pp -Note that reserved words may occur in streams of text, so the following: -.Bd -literal -offset XXXX -this self is not that of the waking , empirically real man -.Ed -.\" PARAGRAPH +If the input is +.Xr mdoc 7 , +these rules are also applied to macro arguments when appropriate. +.\" SUB-SECTION +.Ss Input Formats +The +.Nm +utility accepts +.Xr mdoc 7 +and +.Xr man 7 +input with +.Fl m Ns Ar doc +and +.Fl m Ns Ar an , +respectively. The +.Xr mdoc 7 +format is +.Em strongly +recommended; +.Xr man 7 +should only be used for legacy manuals. .Pp -\&...correctly adjusts the comma spacing to -.Qq this self is not that of the waking , empirically real man . +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 +or +.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 , +each has its file-type determined this way. If multiple files are +specified and +.Fl m Ns Ar doc +or +.Fl m Ns Ar an +is specified, then this format is used exclusively. +.\" .Pp +.\" The following escape sequences are recognised, although the per-format +.\" compiler may not allow certain sequences. +.\" .Bl -tag -width Ds -offset XXXX +.\" .It \efX +.\" sets the font mode to X (B, I, R or P, where P resets the font) +.\" .It \eX, \e(XX, \e[XN] +.\" queries the special-character table for a corresponding symbol +.\" .It \e*X, \e*(XX, \e*[XN] +.\" deprecated special-character format +.\" .El .\" SUB-SECTION .Ss Output Formats The @@ -133,28 +188,38 @@ The utility accepts the following .Fl T arguments: -.Bl -tag -width XXXXXXXXXXXX -offset XXXX -.It Ar ascii +.Bl -tag -width XXXXXXXXXXXX +.It Fl T Ns Ar ascii Produce 7-bit ASCII output, backspace-encoded for bold and underline styles. This is the default. -.It Ar tree +.It Fl T Ns Ar tree Produce an indented parse tree. -.It Ar lint +.It Fl T Ns Ar lint Parse only: produce no output. .El +.Pp +If multiple input files are specified, these will be processed by the +corresponding filter in-order. .\" SUB-SECTION .Ss Compiler Options Default compiler behaviour may be overriden with the .Fl f flag. -.Bl -tag -width XXXXXXXXXXXX -offset XXXX +.Bl -tag -width XXXXXXXXXXXXXX .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. +Ignore unknown macros at the start of input lines (default for +.Xr man 7 +parsing). +.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). .El .\" PARAGRAPH .Pp @@ -167,13 +232,17 @@ options may be grouped and delimited with a comma. Us for example, will try to ignore scope and character-escape errors. .\" SECTION .Sh EXAMPLES -To page this manual page on the terminal: +To page manuals to the terminal: .\" PARAGRAPH .Pp .D1 % mandoc \-Wall,error mandoc.1 2>&1 | less +.Pp +.D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less .\" SECTION .Sh SEE ALSO -.Xr mdoc 7 +.Xr mandoc_char 7 , +.Xr mdoc 7 , +.Xr man 7 .\" .Sh AUTHORS The @@ -184,23 +253,37 @@ utility was written by .Sh CAVEATS The .Nm -utility doesn't yet know how to display the following: +utility in +.Fl T Ns Ar ascii +mode doesn't yet know how to display the following: .Pp .Bl -bullet -compact .It The \-hang -.Sq \&Bl +.Sq \&.Bl list is not yet supported. -.It -The \-literal and \-unfilled -.Sq \&Bd -displays types are synonyms, as are \-filled and \-ragged. -.It -The -.Sq \&Xo/Xc -pair isn't 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 +does not assert a prior vertical break, just as it doesn't with +.Sq \&.Sh . +.It +Special characters don't follow the current font style. +.\" LIST-ITEM +.It +The \-literal and \-unfilled +.Sq \&.Bd +displays types are synonyms, as are \-filled and \-ragged. +.El