From dd296a1678ea613037cf62e6186201645adb26dc Mon Sep 17 00:00:00 2001 From: Kristaps Dzonsons Date: Sat, 14 Mar 2009 05:21:58 +0000 Subject: mdoc.3 refers to local mdoc.7. mdoc.7 includes its compatibility with system-dependent roff installations. --- argv.c | 8 +-- mdoc.3 | 203 +++++++++++------------------------------------------------------ mdoc.7 | 174 ++++++++++++++++++++++++++++++++++++++++--------------- 3 files changed, 166 insertions(+), 219 deletions(-) diff --git a/argv.c b/argv.c index fa9f5cf5..572d9590 100644 --- a/argv.c +++ b/argv.c @@ -1,4 +1,4 @@ -/* $Id: argv.c,v 1.50 2009/03/12 16:30:50 kristaps Exp $ */ +/* $Id: argv.c,v 1.51 2009/03/14 05:21:58 kristaps Exp $ */ /* * Copyright (c) 2008 Kristaps Dzonsons * @@ -60,7 +60,7 @@ enum merr { static int argv_a2arg(int, const char *); static int args(struct mdoc *, int, int *, char *, int, char **); -static int argv(struct mdoc *, int, int, +static int argv(struct mdoc *, int, struct mdoc_argv *, int *, char *); static int argv_single(struct mdoc *, int, struct mdoc_argv *, int *, char *); @@ -292,7 +292,7 @@ mdoc_argv(struct mdoc *mdoc, int line, int tok, /* FIXME: whitespace if no value. */ - if ( ! argv(mdoc, tok, line, &tmp, pos, buf)) + if ( ! argv(mdoc, line, &tmp, pos, buf)) return(ARGV_ERROR); if (NULL == (arg = *v)) { @@ -841,7 +841,7 @@ argv_single(struct mdoc *mdoc, int line, * multiple parameters. */ static int -argv(struct mdoc *mdoc, int tok, int line, +argv(struct mdoc *mdoc, int line, struct mdoc_argv *v, int *pos, char *buf) { diff --git a/mdoc.3 b/mdoc.3 index 973e86fb..7b858397 100644 --- a/mdoc.3 +++ b/mdoc.3 @@ -1,4 +1,4 @@ -.\" $Id: mdoc.3,v 1.16 2009/03/12 23:05:21 kristaps Exp $ +.\" $Id: mdoc.3,v 1.17 2009/03/14 05:21:58 kristaps Exp $ .\" .\" Copyright (c) 2009 Kristaps Dzonsons .\" @@ -16,7 +16,7 @@ .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: March 12 2009 $ +.Dd $Mdocdate: March 14 2009 $ .Dt mdoc 3 .Os .\" SECTION @@ -49,25 +49,18 @@ .Sh DESCRIPTION The .Nm mdoc -library parses lines of mdoc input into an abstract syntax tree. -.Dq mdoc , -which is used to format BSD manual pages, is a macro package of the -.Dq roff -language. The -.Nm -library implements only those macros documented in the +library parses lines of .Xr mdoc 7 -and -.Xr mdoc.samples 7 -manuals. Documents with -.Xr refer 1 , -.Xr eqn 1 -and other pre-processor sections aren't accomodated. -.\" PARAGRAPH -.Pp +input (and +.Em only +mdoc) into an abstract syntax tree that generalises the semantic +annotation of its input. Common front-ends for .Nm -is -.Ud +are +.Xr mdocterm 1 , +.Xr mdoclint 1 +and +.Xr mdoctree 1 . .\" PARAGRAPH .Pp In general, applications initiate a parsing sequence with @@ -92,11 +85,9 @@ This section further defines the .Sx Functions and .Sx Variables -available to programmers. Following that, -.Sx Character Encoding -describes input format. Lastly, -.Sx Abstract Syntax Tree , -documents the output tree. +available to programmers. Following that, the +.Sx Abstract Syntax Tree +section documents the output tree. .\" SUBSECTION .Ss Types Both functions (see @@ -179,68 +170,11 @@ An array of string-ified token names. An array of string-ified token argument names. .El .\" SUBSECTION -.Ss Character Encoding -The -.Xr mdoc 3 -library accepts only printable ASCII characters as defined by -.Xr isprint 3 . -Non-ASCII character sequences are delimited in various ways. All are -preceeded by an escape character -.Sq \\ -and followed by either an open-parenthesis -.Sq \&( -for two-character sequences; an open-bracket -.Sq \&[ -for n-character sequences (terminated at a close-bracket -.Sq \&] ) ; -an asterisk and open-parenthesis -.Sq \&*( -for two-character sequences; -an asterisk and non-open-parenthesis -.Sq \&* -for single-character sequences; or one of a small set of standalone -single characters for other escapes. -.\" PARAGRAPH -.Pp -Examples: -.Pp -.Bl -tag -width "XXXXXXXX" -offset "XXXX" -compact -.\" LIST-ITEM -.It \\*(<= -prints -.Dq \*(<= -.Pq greater-equal -.\" LIST-ITEM -.It \\(<- -prints -.Dq \(<- -.Pq left-arrow -.\" LIST-ITEM -.It \\[<-] -also prints -.Dq \(<- -.Pq left-arrow -.\" LIST-ITEM -.It \\*(Ba -prints -.Dq \*(Ba -.Pq bar -.\" LIST-ITEM -.It \\*q -prints -.Dq \*q -.Pq double-quote -.El -.\" PARAGRAPH -.Pp -All escaped sequences are syntax-checked, but it's up to the front-end -system to correctly render them to the output device. -.\" SUBSECTION .Ss Abstract Syntax Tree The .Nm -functions produce an abstract syntax tree (AST) describing the input -lines in a regular form. It may be reviewed at any time with +functions produce an abstract syntax tree (AST) describing input in a +regular form. It may be reviewed at any time with .Fn mdoc_nodes ; however, if called before .Fn mdoc_endparse , @@ -248,7 +182,15 @@ or after .Fn mdoc_endparse or .Fn mdoc_parseln -fail, it may be incomplete. +fail, it may be incomplete. This AST is governed by the ontological +rules dictated in +.Xr mdoc 7 +and derives its terminology accordingly. +.Qq In-line +elements described in +.Xr mdoc 7 +are described simply as +.Qq elements . .\" PARAGRAPH .Pp The AST is composed of @@ -304,27 +246,6 @@ although a TEXT node will generally have a non-zero-length string, in the specific case of .Sq \&.Bd \-literal , an empty line will produce a zero-length string. -.\" PARAGRAPH -.Pp -The rule-of-thumb for mapping node types to macros follows. In-line -elements, such as -.Sq \&.Em foo , -are classified as ELEMENT nodes, which can only contain text. -Multi-line elements, such as -.Sq \&.Sh , -are BLOCK elements, where the HEAD constitutes line contents and the -BODY constitutes subsequent lines. In-line elements with matching -pairs, such as -.Sq \&.So -and -.Sq \&.Sc , -are BLOCK elements with no HEAD tag. The only exception to this is -.Sq \&.Eo -and -.Sq \&.Ec , -which has a HEAD and TAIL node corresponding to the enclosure string. -TEXT nodes, obviously, constitute text, and the ROOT node is the -document's root. .\" SECTION .Sh EXAMPLES The following example reads lines from stdin and parses them, operating @@ -360,67 +281,11 @@ parsed(mdoc, node); mdoc_free(mdoc); .Ed .\" SECTION -.Sh COMPATIBILITY -In general, only those macros specified by -.Xr mdoc.samples 7 -and -.Xr mdoc 7 -for -.Ox -and -.Nx -are supported; support for other -.Bx -systems is in progress. -.Bl -bullet -.\" LIST-ITEM -.It -.Sq \&Cd -isn't labelled as callable but is. -.\" LIST-ITEM -.It -NetBSD -.Sq \&It \-nested -is assumed for all lists: any list may be nested and -.Sq \-enum -lists will restart the sequence only for the sub-list. -.\" LIST-ITEM -.It -Newer NetBSD-style -.Sq \&It \-column -syntax, where column widths may be preceeded by other arguments (instead -of proceeded), is not supported. -.\" LIST-ITEM -.It -The -.Sq \&At -macro only accepts a single parameter. -.\" LIST-ITEM -.It -Some manuals use -.Sq \&Li -incorrectly by following it with a delimeter (see -.Xr mdoc.samples 7 ) -and expecting the delimiter to render. This is not supported. -.\" LIST-ITEM -.It -The system-name macros ( -.Ns Sq \&At , -.Sq \&Bsx , -.Sq \&Bx , -.Sq \&Fx , -.Sq \&Nx , -.Sq \&Ox , -and -.Sq \&Ux ) -are callable. -.El -.\" SECTION .Sh SEE ALSO -.Xr mdoc 7 , -.Xr mdoc.samples 7 , -.Xr groff 1 , -.Xr mdocml 1 +.Xr mdocterm 1 , +.Xr mdoclint 1 , +.Xr mdoctree 1 , +.Xr mdoc 7 .\" SECTION .Sh AUTHORS The @@ -429,7 +294,7 @@ utility was written by .An Kristaps Dzonsons Aq kristaps@kth.se . .\" SECTION .Sh CAVEATS -.Bl -bullet +.Bl -dash -compact .\" LIST-ITEM .It The @@ -438,12 +303,10 @@ and .Sq \&Xo macros aren't handled when used to span lines for the .Sq \&It -macro. Such usage is specifically discouraged in -.Xr mdoc.samples 7 . +macro. .\" LIST-ITEM .It The .Sq \&Bsx -macro doesn't understand yet the arguments as dictated for -.Nx . +macro doesn't yet understand version arguments. .El diff --git a/mdoc.7 b/mdoc.7 index 72ad225c..2d66c1f0 100644 --- a/mdoc.7 +++ b/mdoc.7 @@ -1,4 +1,4 @@ -.\" $Id: mdoc.7,v 1.3 2009/03/13 13:56:13 kristaps Exp $ +.\" $Id: mdoc.7,v 1.4 2009/03/14 05:21:58 kristaps Exp $ .\" .\" Copyright (c) 2009 Kristaps Dzonsons .\" @@ -16,7 +16,7 @@ .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: March 13 2009 $ +.Dd $Mdocdate: March 14 2009 $ .Dt mdoc 7 .Os .\" SECTION @@ -78,12 +78,13 @@ Within a macro line, the following characters are reserved: Use of these characters must either be escaped with a non-breaking space .Pq Sq \e& or, if applicable, an appropriate escape-sequence used. Use of reserved -characters is described later in this document. +characters is described in +.Sx Closure . .\" SUB-SECTION .Ss Special Characters Special character sequences begin with the escape character .Sq \\ -and followed by either an open-parenthesis +followed by either an open-parenthesis .Sq \&( for two-character sequences; an open-bracket .Sq \&[ @@ -93,9 +94,9 @@ or a single one-character sequence. .Pp Characters may alternatively be escaped by a slash-asterisk, .Sq \\* , -with the same combinations as described above. This form, however, is -deprecated. The following is a table of all available escapes, arranged -by classification. +with the same combinations as described above. This form is deprecated. +.Pp +The following is a table of all available escapes. .Pp Grammatic: .Bl -tag -width 12n -offset "XXXX" -compact @@ -228,16 +229,13 @@ Special symbols: .\" SECTION .Sh ONTOLOGY Macros are classified in an ontology described by scope rules. +.\" SUB-SECTION +.Ss Scope .Bl -inset .\" LIST-ITEM .It Em Block macros enclose other block macros, in-line macros or text, and -may span multiple lines. -.Qq Implicit -block scope is closed by a subsequent invocation of the same macro, -one of a set of corresponding closure macros or end-of-file. -.Qq Explicit -block scope is closed by a corresponding closure macro. +may span multiple lines. .Bl -inset -offset XXXX .\" LIST-ITEM .It Em Full-block @@ -259,16 +257,56 @@ text or macros following the head on the same and subsequent lines; and optionally a .Qq tail , text immediately following closure. -.El .\" LIST-ITEM .It Em In-line -macros may only enclose text and span at most a single line. If -a macro is parsable, its scope may be closed by subsequent macros or -delimiting punctuation. In-line macros follow different conventions for -closure; see -.Sx MACROS -for per-macro details. +macros may only enclose text and span at most a single line. +.El +.El +.\" SUB-SECTION +.Ss Closure +Closure of a macro's scope depends first on its classification, then +on whether it's parsable. In this table, +.Sq BFE +refers to block full-explicit and so on. +.\" PARAGRAPH +.Pp +.Bl -tag -width 12n -offset XXXX -compact +.It BPE , BFE +corresponding explicit closure macro +.It BFI +end-of-file or a corresponding implicit closure macro +.It BPI +end-of-line (body may be closed by >0 space-separated +.Sx Reserved Characters , +although block scope will still be open) +.It INL +end-of-line .El +.\" PARAGRAPH +.Pp +If a macro (block or in-line) is parsable, it may also be closed out by +one of the following scenarios (unless specifically noted otherwise): +.\" PARAGRAPH +.Pp +.Bl -dash -offset XXXX -compact +.It +a sequence of >0 space-separated +.Sx Reserved Characters , +.It +another macro, +.It +end-of-line, or +.It +completion of a set number of arguments. +.El +.\" PARAGRAPH +.Pp +If >0 space-separated +.Sx Reserved Characters +are followed by non-reserved characters, the behaviour differs per +macro. In general, scope of the macro is closed and re-opened: +subsequent tokens are interpreted as if the scope had just been opened. +In other circumstances, scope is simply closed out. .\" .\" SUB-SECTION .\" .Ss Examples .\" The following examples illustrate each macro classification. @@ -369,44 +407,47 @@ In these illustrations, opens the scope of a macro, and if specified, .Sq \&.Yc closes it out (closure may be implicit at end-of-line or end-of-file). +.\" PARAGRAPH .Pp -Block full-explicit (may contain head, body, tail): +Block full-explicit (may contain head, body, tail). .Bd -literal -offset XXXX -\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB -\(lBbody...\(rB -\&.Yc \(lBtail...\(rB +\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB +\(lBbody...\(rB +\&.Yc \(lBtail...\(rB .Ed +.\" PARAGRAPH .Pp -Block full-implicit (may contain zero or more heads, body, no tail): +Block full-implicit (may contain zero or more heads, body, no tail). .Bd -literal -offset XXXX -\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB -\(lBbody...\(rB +\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB +\(lBbody...\(rB \&.Yc .Ed +.\" PARAGRAPH .Pp -Block partial-explicit (may contain head, multi-line body, tail): +Block partial-explicit (may contain head, multi-line body, tail). .Bd -literal -offset XXXX \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB -\(lBbody...\(rB -\&.Yc \(lBtail...\(rB +\(lBbody...\(rB +\&.Yc \(lBtail...\(rB \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB \ -\(lBbody...\(rB \&Yc \(lBtail...\(rB +\(lBbody...\(rB \&Yc \(lBtail...\(rB .Ed +.\" PARAGRAPH .Pp -Block partial-implicit (no head, body, no tail): +Block partial-implicit (no head, body, no tail). Note that the body +section may be followed by zero or more +.Sx Reserved Words . +These are in the block scope, but not in the body scope. .Bd -literal -offset XXXX -\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB +\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBreserved...\(rB .Ed +.\" PARAGRAPH .Pp -In-line (may be closed by end-of-line, reserved character, subsequent -macro invocation or finite number of arguments): +In-lines have \(>=0 scoped arguments. .Bd -literal -offset XXX -\&.Yy \(lB\-arg \(lBval...\(rB\(rB args... - -\&.Yy \(lB\-arg \(lBval...\(rB\(rB args... ; - -\&.Yy \(lB\-arg \(lBval...\(rB\(rB args... Xx +\&.Yy \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN .Ed @@ -589,17 +630,60 @@ then the macro accepts an arbitrary number of arguments. .It \&.Mt Ta \&No Ta Yes Ta >0 .El .\" SECTION +.Sh COMPATIBILITY +The mdoc language was traditionally a +.Qq roff +macro package; most existing manuals were written with mdoc syntax +dictated by system-dependent roff installations. This section documents +compatibility with these systems. +.Pp +.Bl -dash -compact +.\" LIST-ITEM +.It +.Sq \&It \-nested +is assumed for all lists: any list may be nested and +.Sq \-enum +lists will restart the sequence only for the sub-list. +.\" LIST-ITEM +.It +.Sq \&It \-column +syntax where column widths may be preceeded by other arguments (instead +of proceeded) is not supported. +.\" LIST-ITEM +.It +The +.Sq \&At +macro only accepts a single parameter. +.\" LIST-ITEM +.It +The system-name macros ( +.Ns Sq \&At , +.Sq \&Bsx , +.Sq \&Bx , +.Sq \&Fx , +.Sq \&Nx , +.Sq \&Ox , +and +.Sq \&Ux ) +are callable. +.\" LIST-ITEM +.It +Some manuals use +.Sq \&Li +incorrectly by following it with a reserved character and expecting the +delimiter to render. This is not supported. +.\" LIST-ITEM +.It +.Sq \&Cd +is callable. +.El +.\" SECTION .Sh SEE ALSO .Xr mdoctree 1 , .Xr mdoclint 1 , .Xr mdocterm 1 , .Xr mdoc 3 .\" SECTION -.Sh HISTORY -This manual describes the language accepted by -.Xr mdoc 3 , -which implements the roff-mdoc macro package. -.\" SECTION .Sh AUTHORS The .Nm -- cgit v1.2.3-56-ge451