=================================================================== RCS file: /cvs/mandoc/Attic/mdocterm.1,v retrieving revision 1.3 retrieving revision 1.22 diff -u -p -r1.3 -r1.22 --- mandoc/Attic/mdocterm.1 2009/02/23 13:05:06 1.3 +++ mandoc/Attic/mdocterm.1 2009/03/15 10:34:11 1.22 @@ -1,4 +1,4 @@ -.\" $Id: mdocterm.1,v 1.3 2009/02/23 13:05:06 kristaps Exp $ +.\" $Id: mdocterm.1,v 1.22 2009/03/15 10:34:11 kristaps Exp $ .\" .\" Copyright (c) 2009 Kristaps Dzonsons .\" @@ -16,19 +16,29 @@ .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: February 23 2009 $ -.Dt mdocmterm 1 +.Dd $Mdocdate: March 15 2009 $ +.Dt mdocterm 1 .Os .\" SECTION .Sh NAME -.Nm mdocmterm +.Nm mdocterm .Nd mdoc macro compiler .\" SECTION .Sh SYNOPSIS -.Nm mdocmterm -.Op Fl v +.Nm mdocterm +.Op Fl vV +.Op Fl f Ns Ar option... +.Op Fl O Ns Ar option... .Op Fl W Ns Ar err... .Op Ar infile +.Nm mdocterm +.Op Fl hi +.Op Fl m Ns Ar name +.Op Fl n Ns Ar num +.Op Fl o Ns Ar list +.Op Fl r Ns Ar cn +.Op Fl T Ns Ar name +.Op Ar infile .\" SECTION .Sh DESCRIPTION The @@ -36,11 +46,24 @@ The utility formats a BSD .Dq mdoc manual page for display on the terminal. The arguments are as follows: -.Bl -tag -width "\-Werr... " +.Bl -tag -width XXXXXXXXXXXX .\" ITEM .It Fl v Print verbose parsing output. .\" ITEM +.It Fl v +Print version and exit. +.\" ITEM +.It Fl f Ns Ar option... +Override default compiler behaviour. See +.Sx Compiler Options +for details. +.\" ITEM +.It Fl O Ns Ar option... +Front-end options. See +.Sx Front-end Options +for details. +.\" ITEM .It Fl W Ns Ar err... Print warning messages. May be set to .Fl W Ns Ar all @@ -65,6 +88,15 @@ for stdin. .El .\" PARAGRAPH .Pp +If +.Xr nroff 1 +arguments are supplied on the command line +.Pq Fl himnorT , +these are ignored unless +.Xr nroff 1 +is invoked on parse failure. +.\" PARAGRAPH +.Pp The .Nm utility is a formatting front-end for @@ -75,36 +107,206 @@ input, documented at .Xr mdoc 7 and .Xr mdoc.samples 7 , -into an abstract syntax tree. +into an abstract syntax tree. .\" PARAGRAPH .Pp -By default, -.Nm -reads from stdin and prints terminal-encoded output to stdout. +By default, +.Nm +reads from stdin and prints nroff +.Qq backspace +terminal-encoded output to stdout, at this time to a fixed column with +of 78 characters. If +.Ar infile +can't be parsed (isn't valid mdoc, doesn't contain valid syntax, etc.), +.Xr nroff 1 +is invoked. If no +.Xr nroff 1 +command-line argumnets aren't provided, +.Fl m Ar Ns andoc +is implied. .\" PARAGRAPH .Pp -.Ex -std mdocmterm +.Ex -std mdocterm +.\" SUB-SECTION +.Ss Front-end Options +The default behaviour may be overriden with the +.Fl O +flag. The available options are as follows: +.Bl -tag -width XXXXXXXXXXXX -offset XXXX +.It Fl O Ns Ar nopunt +Don't punt to +.Xr nroff 1 +if +.Ar infile +may not be parsed. +.El +.\" SUB-SECTION +.Ss Compiler Options +Default compiler behaviour may be overriden with the +.Fl f +flag. The available options are as follows: +.Bl -tag -width XXXXXXXXXXXX -offset XXXX +.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. +.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. +.El .\" PARAGRAPH .Pp -.Nm -is -.Ud +As with the +.Fl W +flag, multiple +.Fl f +and +.Fl O +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. +.\" SUB-SECTION +.Ss Character Escapes +The following table shows all +.Xr mdoc 7 +character escapes rendered by +.Nm . +Note that the +.Em Output +column will render differently whether executed with +.Xr mdocterm 1 +or another output filter. +.\" PARAGRAPH +.Pp +Grammatic: +.Pp +.Bl -tag -width "OutputXXXX" -offset "XXXX" -compact +.It Em Output +.Em Input (Name) +.It \(em +\\(em (em-dash) +.It \(en +\\(en (en-dash) +.It \- +\\- (hyphen) +.It \\ +\\\\ (back-slash) +.El +.\" PARAGRAPH +.Pp +Enclosures: +.Pp +.Bl -tag -width "OutputXXXX" -offset "XXXX" -compact +.It Em Output +.Em Input (Name) +.It \(rC +\\(rC (right brace) +.It \(lC +\\(lC (left brace) +.It \(ra +\\(ra (right angle) +.It \(la +\\(la (left angle) +.It \(rB +\\(rB (right bracket) +.It \(lB +\\(lB (left bracket) +.It \q +\\q (double-quote) +.It \(lq +\\(lq (left double-quote) +.It \(rq +\\(rq (right double-quote) +.It \(oq +\\(oq, \\` (left single-quote) +.It \(aq +\\(aq, \\' (right single-quote, apostrophe) +.El +.\" PARAGRAPH +.Pp +Indicatives: +.Pp +.Bl -tag -width "OutputXXXX" -offset "XXXX" -compact +.It Em Output +.Em Input (Name) +.It \(<- +\\(<- (left arrow) +.It \(-> +\\(-> (right arrow) +.It \(ua +\\(ua (up arrow) +.It \(da +\\(da (down arrow) +.El +.\" PARAGRAPH +.Pp +Mathematical: +.Pp +.Bl -tag -width "OutputXXXX" -offset "XXXX" -compact +.It Em Output +.Em Input (Name) +.It \(<= +\\(<= (less-than-equal) +.It \(>= +\\(>= (greater-than-equal) +.It \(== +\\(== (equal) +.It \(!= +\\(!= (not equal) +.It \(if +\\(if (infinity) +.It \(na +\\(na (NaN)* +.It \(+- +\\(+- (plus-minus) +.It \(** +\\(** (asterisk) +.El +.\" PARAGRAPH +.Pp +Diacritics: +.Pp +.Bl -tag -width "OutputXXXX" -offset "XXXX" -compact +.It Em Output +.Em Input (Name) +.It \(ga +\\(ga (accent grave) +.It \(aa +\\(aa (accent accute) +.El +.\" PARAGRAPH +.Pp +Special symbols: +.Pp +.Bl -tag -width "OutputXXXX" -offset "XXXX" -compact +.It Em Output +.Em Input (Name) +.It \(bu +\\(bu (bullet) +.It \(ba +\\(ba (bar) +.It \(co +\\(co (copyright) +.El +.Pp +*This is a deviation from the standard, as NaN is usually rendered as +\\*(Na, which is a deprecated form. We introduce \\(na, which follows +the more general syntax. .\" SECTION .Sh EXAMPLES To display this manual page: .\" PARAGRAPH .Pp -.D1 % mdocmterm \-Wall,error mdocmterm.1 +.D1 % mdocterm \-Wall,error mdocterm.1 .\" PARAGRAPH .Pp To pipe a manual page to the pager: .Pp -.D1 % mdocterm mdocterm.1 | less -R +.D1 % mdocterm mdocterm.1 | less .\" SECTION .Sh SEE ALSO .Xr mdoctree 1 , .Xr mdoclint 1 , -.Xr mdoc.samples 7 , .Xr mdoc 7 , .Xr mdoc 3 .\" @@ -117,4 +319,28 @@ utility was written by .Sh CAVEATS See .Xr mdoc 3 -for a list of bugs, caveats, and incomplete macros. +for a list of bugs, caveats, and incomplete macros regarding the +document parse. +.Pp +The +.Nm +utility doesn't yet know how to display the following: +.Pp +.Bl -bullet -compact +.It +The \-hang +.Sq \&Bl +list is not yet supported. +.It +The \-literal and \-unfilled +.Sq \&Bd +displays only accept text contents. +.It +The +.Sq \&Xo/Xc +pair isn't supported (and never will be). +.It +The +.Sq \&Sm +macro has no effect, yet. +.El