summaryrefslogtreecommitdiffstats
path: root/mdoc.3
diff options
context:
space:
mode:
authorKristaps Dzonsons <kristaps@bsd.lv>2009-03-14 05:21:58 +0000
committerKristaps Dzonsons <kristaps@bsd.lv>2009-03-14 05:21:58 +0000
commit87db307812249df3244dcee240f1c1684d76014e (patch)
treebe7ea0c02e483030175e6ec26d72268912542f75 /mdoc.3
parentd3e4f39bf606f28bf5d6a1e1297e356883082b27 (diff)
downloadmandoc-87db307812249df3244dcee240f1c1684d76014e.tar.gz
mdoc.3 refers to local mdoc.7.
mdoc.7 includes its compatibility with system-dependent roff installations.
Diffstat (limited to 'mdoc.3')
-rw-r--r--mdoc.3199
1 files changed, 31 insertions, 168 deletions
diff --git a/mdoc.3 b/mdoc.3
index 2feb6d98..6d7ba0e7 100644
--- a/mdoc.3
+++ b/mdoc.3
@@ -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