From: kristaps@mdocml.bsd.lv
To: source@mdocml.bsd.lv
Subject: mdocml: Add more documentation for libmandoc.
Date: Wed, 22 Jun 2011 18:10:02 -0400 (EDT) [thread overview]
Message-ID: <201106222210.p5MMA2TI003595@krisdoz.my.domain> (raw)
Log Message:
-----------
Add more documentation for libmandoc.
Modified Files:
--------------
mdocml:
mandoc.3
Revision Data
-------------
Index: mandoc.3
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mandoc.3,v
retrieving revision 1.10
retrieving revision 1.11
diff -Lmandoc.3 -Lmandoc.3 -u -p -r1.10 -r1.11
--- mandoc.3
+++ mandoc.3
@@ -177,9 +177,6 @@ library also contains routines for trans
.Pq see Fn mchars_alloc
and parsing escape sequences from strings
.Pq see Fn mandoc_escape .
-.Pp
-This library is
-.Ud
.Sh REFERENCE
This section documents the functions, types, and variables available
via
@@ -187,16 +184,35 @@ via
.Ss Types
.Bl -ohang
.It Vt "enum mandoc_esc"
+An escape sequence classification.
.It Vt "enum mandocerr"
+A fatal error, error, or warning message during parsing.
.It Vt "enum mandoclevel"
+A classification of an
+.Vt "enum mandoclevel"
+as regards system operation.
.It Vt "struct mchars"
An opaque pointer to an object allowing for translation between
character strings and glyphs.
See
.Fn mchars_alloc .
.It Vt "enum mparset"
+The type of parser when reading input.
+This should usually be
+.Va MPARSE_AUTO
+for auto-detection.
.It Vt "struct mparse"
+An opaque pointer to a running parse sequence.
+Created with
+.Fn mparse_alloc
+and freed with
+.Fn mparse_free .
+This may be used across parsed input if
+.Fn mparse_reset
+is called between parses.
.It Vt "mandocmsg"
+A prototype for a function to handle fatal error, error, and warning
+messages emitted by the parser.
.El
.Ss Functions
.Bl -ohang
@@ -320,7 +336,36 @@ This section consists of structural docu
.Xr mdoc 7
and
.Xr man 7
-syntax trees.
+syntax trees and strings.
+.Ss Man and Mdoc Strings
+Strings may be extracted from mdoc and man meta-data, or from text
+nodes (MDOC_TEXT and MAN_TEXT, respectively).
+These strings have special non-printing formatting cues embedded in the
+text itself, as well as
+.Xr roff 7
+escapes preserved from input.
+Implementing systems will need to handle both situations to produce
+human-readable text.
+In general, strings may be assumed to consist of 7-bit ASCII characters.
+.Pp
+The following non-printing characters may be embedded in text strings:
+.Bl -tag -width Ds
+.It Dv ASCII_NBRSP
+A non-breaking space character.
+.It Dv ASCII_HYPH
+A soft hyphen.
+.El
+.Pp
+Escape characters are also passed verbatim into text strings.
+An escape character is a sequence of characters beginning with the
+backslash
+.Pq Sq \e .
+To construct human-readable text, these should be intercepted with
+.Fn mandoc_escape
+and converted with one of
+.Fn mchars_num2char ,
+.Fn mchars_spec2str ,
+and so on.
.Ss Man Abstract Syntax Tree
This AST is governed by the ontological rules dictated in
.Xr man 7
@@ -361,7 +406,7 @@ where capitalised non-terminals represen
.It ELEMENT
\(<- ELEMENT | TEXT*
.It TEXT
-\(<- [[:alpha:]]*
+\(<- [[:ascii:]]*
.El
.Pp
The only elements capable of nesting other elements are those with
@@ -420,7 +465,7 @@ where capitalised non-terminals represen
.It TAIL
\(<- mnode*
.It TEXT
-\(<- [[:printable:],0x1e]*
+\(<- [[:ascii:]]*
.El
.Pp
Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
--
To unsubscribe send an email to source+unsubscribe@mdocml.bsd.lv
reply other threads:[~2011-06-22 22:10 UTC|newest]
Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=201106222210.p5MMA2TI003595@krisdoz.my.domain \
--to=kristaps@mdocml.bsd.lv \
--cc=source@mdocml.bsd.lv \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).