=================================================================== RCS file: /cvs/mandoc/mandoc.1,v retrieving revision 1.9 retrieving revision 1.18 diff -u -p -r1.9 -r1.18 --- mandoc/mandoc.1 2009/03/23 16:02:56 1.9 +++ mandoc/mandoc.1 2009/06/11 07:26:35 1.18 @@ -1,23 +1,21 @@ -.\" $Id: mandoc.1,v 1.9 2009/03/23 16:02:56 kristaps Exp $ +.\" $Id: mandoc.1,v 1.18 2009/06/11 07:26:35 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 23 2009 $ -.Dt mandoc 1 +.Dd $Mdocdate: June 11 2009 $ +.Dt MANDOC 1 .Os .\" SECTION .Sh NAME @@ -50,7 +48,7 @@ for details. Input format. See .Sx Input Formats for available formats. Defaults to -.Fl m Ns Ar mdoc . +.Fl m Ns Ar andoc . .\" ITEM .It Fl T Output format. See @@ -89,8 +87,10 @@ By default, .Nm reads .Xr mdoc 7 +or +.Xr man 7 text from stdin, implying -.Fl m Ns Ar mdoc , +.Fl m Ns Ar andoc , and prints 78-column backspace-encoded output to stdout as if .Fl T Ns Ar ascii were provided. @@ -98,21 +98,19 @@ were provided. .Pp .Ex -std mandoc .\" SUB-SECTION -.Ss Reserved Words (mdoc only) -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 \&, , @@ -124,23 +122,12 @@ Closing delimiters .Sq \&] and .Sq \&} -.Pc are not preceeded by whitespace. -.El -.\" PARAGRAPH +.Pc +is not preceded by whitespace. .Pp -Note that reserved words only register as such as if they appear as -standalone tokens, either in parsed lines or streams of text. Thus, the -following fragment: -.Bd -literal -offset XXXX -this self is not that of the waking , empirically real man -.Ed -.\" PARAGRAPH -.Pp -\&...correctly adjusts the comma spacing to -.Dq this self is not that of the waking , empirically real man . -However, if the comma were part of -.Dq ,empirically , -it would not. +If the input is +.Xr mdoc 7 , +these rules are also applied to macro arguments when appropriate. .\" SUB-SECTION .Ss Input Formats The @@ -150,9 +137,9 @@ utility accepts and .Xr man 7 input with -.Fl m Ns Ar mdoc +.Fl m Ns Ar doc and -.Fl m Ns Ar man , +.Fl m Ns Ar an , respectively. The .Xr mdoc 7 format is @@ -161,10 +148,39 @@ recommended; .Xr man 7 should only be used for legacy manuals. .Pp -Note that the -.Fl m Ns Ar man -option is experimental and only works with -.Fl T Ns Ar tree . +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 @@ -172,21 +188,24 @@ 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. @@ -194,7 +213,13 @@ scope violations. This can seriously mangle the resul .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 @@ -207,12 +232,15 @@ 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 mandoc_char 7 , .Xr mdoc 7 , .Xr man 7 .\" @@ -220,7 +248,7 @@ To page this manual page on the terminal: The .Nm utility was written by -.An Kristaps Dzonsons Aq kristaps@openbsd.org . +.An Kristaps Dzonsons Aq kristaps@kth.se . .\" SECTION .Sh CAVEATS The @@ -232,7 +260,7 @@ mode doesn't yet know how to display the following: .Bl -bullet -compact .It The \-hang -.Sq \&Bl +.Sq \&.Bl list is not yet supported. .El .Pp @@ -248,14 +276,14 @@ output and .Bl -bullet -compact .It A list of display following -.Sq \&Ss +.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 +.Sq \&.Bd displays types are synonyms, as are \-filled and \-ragged. .El