=================================================================== RCS file: /cvs/mandoc/Attic/mdocterm.1,v retrieving revision 1.17 retrieving revision 1.24 diff -u -p -r1.17 -r1.24 --- mandoc/Attic/mdocterm.1 2009/03/11 00:39:58 1.17 +++ mandoc/Attic/mdocterm.1 2009/03/16 23:37:28 1.24 @@ -1,6 +1,6 @@ -.\" $Id: mdocterm.1,v 1.17 2009/03/11 00:39:58 kristaps Exp $ +.\" $Id: mdocterm.1,v 1.24 2009/03/16 23:37:28 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 @@ -16,20 +16,29 @@ .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: March 11 2009 $ +.Dd $Mdocdate: March 16 2009 $ .Dt mdocterm 1 .Os .\" SECTION .Sh NAME -.Nm mdocmterm +.Nm mdocterm .Nd mdoc macro compiler .\" SECTION .Sh SYNOPSIS -.Nm mdocmterm +.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 @@ -50,6 +59,11 @@ 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 @@ -74,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 @@ -85,17 +108,39 @@ input, documented at and .Xr mdoc.samples 7 , into an abstract syntax tree. +.\" PARAGRAPH .Pp By default, .Nm -reads from stdin and prints ANSI -.Qq raw +reads from stdin and prints nroff +.Qq backspace terminal-encoded output to stdout, at this time to a fixed column with -of 78 characters. +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 @@ -115,169 +160,42 @@ 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 Input Encoding +.Ss Character Escapes The .Nm -utility expects its input to be 7-bit ASCII as defined in -.Xr ascii 7 . -The only non-graphing characters accepted are spaces, -.Sq \ , -and tabs, -.Sq \et . -Tabs are only accepted in literal block-displays and as column -delimiters. +utility correctly renders all +.Sx Special Characters +in +.Xr mdoc 7 +in 7-bit ASCII. .Pp -Only Unix-style newlines (\en) are accepted; if the newline is escaped, -the line is concatenated with the next. -.\" SUB-SECTION -.Ss Character Escapes -This section documents the character-escapes accepted by -.Xr mdocterm 1 . -Note that the \\x, \\(xx and \\[n] forms are described here; the \\*(xx, -\\*[n] and \\*x forms described in -.Xr mdoc.samples 7 -are deprecated, but still rendered. All one- and two-character -sequences may be used in the n-character sequence \\[n]. -.Pp -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 \(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. +In the general sense, +.Nm +will make a +.Pq best-effort +to render complex characters; however, if a manual is using considerable +special characters, some meaning may be lost in translation. .\" 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 2>&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 .\" @@ -285,7 +203,7 @@ To pipe a manual page to the pager: The .Nm utility was written by -.An Kristaps Dzonsons Aq kristaps@kth.se . +.An Kristaps Dzonsons Aq kristaps@openbsd.org . .\" SECTION .Sh CAVEATS See @@ -299,9 +217,9 @@ utility doesn't yet know how to display the following: .Pp .Bl -bullet -compact .It -The \-hang and \-column +The \-hang .Sq \&Bl -lists are not yet supported. +list is not yet supported. .It The \-literal and \-unfilled .Sq \&Bd