From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from krisdoz.my.domain (kristaps@localhost [127.0.0.1]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id p2MA2pFn004188 for ; Tue, 22 Mar 2011 06:02:51 -0400 (EDT) Received: (from kristaps@localhost) by krisdoz.my.domain (8.14.3/8.14.3/Submit) id p2MA2p9w015930; Tue, 22 Mar 2011 06:02:51 -0400 (EDT) Date: Tue, 22 Mar 2011 06:02:51 -0400 (EDT) Message-Id: <201103221002.p2MA2p9w015930@krisdoz.my.domain> X-Mailinglist: mdocml-source Reply-To: source@mdocml.bsd.lv MIME-Version: 1.0 From: kristaps@mdocml.bsd.lv To: source@mdocml.bsd.lv Subject: mdocml: Step 3: consolidate manuals. X-Mailer: activitymail 1.26, http://search.cpan.org/dist/activitymail/ Content-Type: text/plain; charset=utf-8 Log Message: ----------- Step 3: consolidate manuals. The parse functions in mdoc.h, roff.h, and man.h are now part of libmandoc.h, so remove these from their respective manuals (they're no longer public-facing and we don't need a libmandoc.3 (yet?)). Before that, move the juicy data (parse tree syntax) into new-born mandoc.3. Peck around in Makefile and index.sgml to reflect reality. Modified Files: -------------- mdocml: Makefile index.sgml libmandoc.h Added Files: ----------- mdocml: mandoc.3 Removed Files: ------------- mdocml: man.3 mdoc.3 roff.3 Revision Data ------------- --- roff.3 +++ /dev/null @@ -1,177 +0,0 @@ -.\" $Id: roff.3,v 1.10 2011/01/01 16:18:39 kristaps Exp $ -.\" -.\" Copyright (c) 2010 Kristaps Dzonsons -.\" -.\" Permission to use, copy, modify, and distribute this software for any -.\" purpose with or without fee is hereby granted, provided that the above -.\" copyright notice and this permission notice appear in all copies. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES -.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF -.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR -.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN -.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF -.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -.\" -.Dd $Mdocdate: January 1 2011 $ -.Dt ROFF 3 -.Os -.Sh NAME -.Nm roff , -.Nm roff_alloc , -.Nm roff_endparse , -.Nm roff_free , -.Nm roff_parseln , -.Nm roff_reset , -.Nm roff_span -.Nd roff macro compiler library -.Sh SYNOPSIS -.In mandoc.h -.In roff.h -.Ft "struct roff *" -.Fo roff_alloc -.Fa "struct regset *regs" -.Fa "void *data" -.Fa "mandocmsg msgs" -.Fc -.Ft void -.Fn roff_endparse "struct roff *roff" -.Ft void -.Fn roff_free "struct roff *roff" -.Ft "enum rofferr" -.Fo roff_parseln -.Fa "struct roff *roff" -.Fa "int line" -.Fa "char **bufp" -.Fa "size_t *bufsz" -.Fa "int pos" -.Fa "int *offs" -.Fc -.Ft void -.Fn roff_reset "struct roff *roff" -.Ft "const struct tbl_span *" -.Fn roff_span "const struct roff *roff" -.Sh DESCRIPTION -The -.Nm -library processes lines of -.Xr roff 7 -input. -.Pp -In general, applications initiate a parsing sequence with -.Fn roff_alloc , -parse each line in a document with -.Fn roff_parseln , -close the parsing session with -.Fn roff_endparse , -and finally free all allocated memory with -.Fn roff_free . -The -.Fn roff_reset -function may be used in order to reset the parser for another input -sequence. -.Pp -The -.Fn roff_parseln -function should be invoked before passing a line into the -.Xr mdoc 3 -or -.Xr man 3 -libraries. -.Pp -See the -.Sx EXAMPLES -section for a full example. -.Sh REFERENCE -This section further defines the -.Sx Types -and -.Sx Functions -available to programmers. -.Ss Types -Functions (see -.Sx Functions ) -may use the following types: -.Bl -ohang -.It Vt "enum rofferr" -Instructions for further processing to the caller of -.Fn roff_parseln . -.It Vt struct roff -An opaque type defined in -.Pa roff.c . -Its values are only used privately within the library. -.It Vt mandocmsg -A function callback type defined in -.Pa mandoc.h . -.El -.Ss Functions -Function descriptions follow: -.Bl -ohang -.It Fn roff_alloc -Allocates a parsing structure. -The -.Fa data -pointer is passed to -.Fa msgs . -Returns NULL on failure. -If non-NULL, the pointer must be freed with -.Fn roff_free . -.It Fn roff_reset -Reset the parser for another parse routine. -After its use, -.Fn roff_parseln -behaves as if invoked for the first time. -.It Fn roff_free -Free all resources of a parser. -The pointer is no longer valid after invocation. -.It Fn roff_parseln -Parse a nil-terminated line of input. -The character array -.Fa bufp -may be modified or reallocated within this function. -In the latter case, -.Fa bufsz -will be modified accordingly. -The -.Fa offs -pointer will be modified if the line start during subsequent processing -of the line is not at the zeroth index. -This line should not contain the trailing newline. -Returns 0 on failure, 1 on success. -.It Fn roff_endparse -Signals that the parse is complete. -.It Fn roff_span -If -.Fn roff_parseln -returned -.Va ROFF_TBL , -return the last parsed table row. -Returns NULL otherwise. -.El -.Sh EXAMPLES -See -.Pa main.c -in the source distribution for an example of usage. -.Sh SEE ALSO -.Xr mandoc 1 , -.Xr man 3 , -.Xr mdoc 3 , -.Xr roff 7 -.Sh AUTHORS -The -.Nm -library was written by -.An Kristaps Dzonsons Aq kristaps@bsd.lv . -.Sh BUGS -The implementation of user-defined strings needs improvement: -.Bl -dash -.It -String values are taken literally and are not interpreted. -.It -Parsing of quoted strings is incomplete. -.It -The stings are stored internally using a singly linked list, -which is fine for small numbers of strings, -but ineffient when handling many strings. -.El --- /dev/null +++ mandoc.3 @@ -0,0 +1,323 @@ +.\" $Id: mandoc.3,v 1.1 2011/03/22 10:02:50 kristaps Exp $ +.\" +.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons +.\" Copyright (c) 2010 Ingo Schwarze +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: March 22 2011 $ +.Dt MANDOC 3 +.Os +.Sh NAME +.Nm mandoc , +.Nm man_meta , +.Nm man_node , +.Nm mdoc_meta , +.Nm mdoc_node , +.Nm mparse_alloc , +.Nm mparse_free , +.Nm mparse_readfd , +.Nm mparse_reset , +.Nm mparse_result +.Nd mandoc macro compiler library +.Sh SYNOPSIS +.In man.h +.In mdoc.h +.In mandoc.h +.Ft "const struct man_meta *" +.Fo man_meta +.Fa "const struct man *man" +.Fc +.Ft "const struct man_node *" +.Fo man_node +.Fa "const struct man *man" +.Fc +.Ft "const struct mdoc_meta *" +.Fo mdoc_meta +.Fa "const struct mdoc *mdoc" +.Fc +.Ft "const struct mdoc_node *" +.Fo mdoc_node +.Fa "const struct mdoc *mdoc" +.Fc +.Ft void +.Fo mparse_alloc +.Fa "enum mparset type" +.Fa "enum mandoclevel wlevel" +.Fa "mandocmsg msg" +.Fa "void *msgarg" +.Fc +.Ft void +.Fo mparse_free +.Fa "struct mparse *parse" +.Fc +.Ft "enum mandoclevel" +.Fo mparse_readfd +.Fa "struct mparse *parse" +.Fa "int fd" +.Fa "const char *fname" +.Fc +.Ft void +.Fo mparse_reset +.Fa "struct mparse *parse" +.Fc +.Ft void +.Fo mparse_result +.Fa "struct mparse *parse" +.Fa "struct mdoc **mdoc" +.Fa "struct man **man" +.Fc +.Vt extern const char * const * man_macronames; +.Vt extern const char * const * mdoc_argnames; +.Vt extern const char * const * mdoc_macronames; +.Sh DESCRIPTION +The +.Nm mandoc +library parses a +.Ux +manual into an abstract syntax tree (AST). +.Ux +manuals are composed of +.Xr mdoc 7 +or +.Xr man 7 , +and may be mixed with +.Xr roff 7 , +.Xr tbl 7 , +and +.Xr eqn 7 +invocations. +.Pp +The following describes a general parse sequence: +.Bl -enum +.It +initiate a parsing sequence with +.Fn mparse_alloc ; +.It +parse files or file descriptors with +.Fn mparse_readfd ; +.It +retrieve a parsed syntax tree, if the parse was successful, with +.Fn mparse_result ; +.It +iterate over parse nodes with +.Fn mdoc_node +or +.Fn man_node ; +.It +free all allocated memory with +.Fn mparse_free , +or invoke +.Fn mparse_reset +and parse new files. +.El +.Sh IMPLEMENTATION NOTES +This section consists of structural documentation for +.Xr mdoc 7 +and +.Xr man 7 +syntax trees. +.Ss Man Abstract Syntax Tree +This AST is governed by the ontological rules dictated in +.Xr man 7 +and derives its terminology accordingly. +.Pp +The AST is composed of +.Vt struct man_node +nodes with element, root and text types as declared by the +.Va type +field. +Each node also provides its parse point (the +.Va line , +.Va sec , +and +.Va pos +fields), its position in the tree (the +.Va parent , +.Va child , +.Va next +and +.Va prev +fields) and some type-specific data. +.Pp +The tree itself is arranged according to the following normal form, +where capitalised non-terminals represent nodes. +.Pp +.Bl -tag -width "ELEMENTXX" -compact +.It ROOT +\(<- mnode+ +.It mnode +\(<- ELEMENT | TEXT | BLOCK +.It BLOCK +\(<- HEAD BODY +.It HEAD +\(<- mnode* +.It BODY +\(<- mnode* +.It ELEMENT +\(<- ELEMENT | TEXT* +.It TEXT +\(<- [[:alpha:]]* +.El +.Pp +The only elements capable of nesting other elements are those with +next-lint scope as documented in +.Xr man 7 . +.Ss Mdoc Abstract Syntax Tree +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 . +.Pp +The AST is composed of +.Vt struct mdoc_node +nodes with block, head, body, element, root and text types as declared +by the +.Va type +field. +Each node also provides its parse point (the +.Va line , +.Va sec , +and +.Va pos +fields), its position in the tree (the +.Va parent , +.Va child , +.Va nchild , +.Va next +and +.Va prev +fields) and some type-specific data, in particular, for nodes generated +from macros, the generating macro in the +.Va tok +field. +.Pp +The tree itself is arranged according to the following normal form, +where capitalised non-terminals represent nodes. +.Pp +.Bl -tag -width "ELEMENTXX" -compact +.It ROOT +\(<- mnode+ +.It mnode +\(<- BLOCK | ELEMENT | TEXT +.It BLOCK +\(<- HEAD [TEXT] (BODY [TEXT])+ [TAIL [TEXT]] +.It ELEMENT +\(<- TEXT* +.It HEAD +\(<- mnode* +.It BODY +\(<- mnode* [ENDBODY mnode*] +.It TAIL +\(<- mnode* +.It TEXT +\(<- [[:printable:],0x1e]* +.El +.Pp +Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of +the BLOCK production: these refer to punctuation marks. +Furthermore, 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. +Multiple body parts are only found in invocations of +.Sq \&Bl \-column , +where a new body introduces a new phrase. +.Pp +The +.Xr mdoc 7 +syntax tree accomodates for broken block structures as well. +The ENDBODY node is available to end the formatting associated +with a given block before the physical end of that block. +It has a non-null +.Va end +field, is of the BODY +.Va type , +has the same +.Va tok +as the BLOCK it is ending, and has a +.Va pending +field pointing to that BLOCK's BODY node. +It is an indirect child of that BODY node +and has no children of its own. +.Pp +An ENDBODY node is generated when a block ends while one of its child +blocks is still open, like in the following example: +.Bd -literal -offset indent +\&.Ao ao +\&.Bo bo ac +\&.Ac bc +\&.Bc end +.Ed +.Pp +This example results in the following block structure: +.Bd -literal -offset indent +BLOCK Ao + HEAD Ao + BODY Ao + TEXT ao + BLOCK Bo, pending -> Ao + HEAD Bo + BODY Bo + TEXT bo + TEXT ac + ENDBODY Ao, pending -> Ao + TEXT bc +TEXT end +.Ed +.Pp +Here, the formatting of the +.Sq \&Ao +block extends from TEXT ao to TEXT ac, +while the formatting of the +.Sq \&Bo +block extends from TEXT bo to TEXT bc. +It renders as follows in +.Fl T Ns Cm ascii +mode: +.Pp +.Dl bc] end +.Pp +Support for badly-nested blocks is only provided for backward +compatibility with some older +.Xr mdoc 7 +implementations. +Using badly-nested blocks is +.Em strongly discouraged ; +for example, the +.Fl T Ns Cm html +and +.Fl T Ns Cm xhtml +front-ends to +.Xr mandoc 1 +are unable to render them in any meaningful way. +Furthermore, behaviour when encountering badly-nested blocks is not +consistent across troff implementations, especially when using multiple +levels of badly-nested blocks. +.Sh SEE ALSO +.Xr mandoc 1 , +.Xr eqn 7 , +.Xr man 7 , +.Xr mdoc 7 , +.Xr roff 7 , +.Xr tbl 7 +.Sh AUTHORS +The +.Nm +library was written by +.An Kristaps Dzonsons Aq kristaps@bsd.lv . --- mdoc.3 +++ /dev/null @@ -1,359 +0,0 @@ -.\" $Id: mdoc.3,v 1.57 2011/02/09 09:18:15 kristaps Exp $ -.\" -.\" Copyright (c) 2009, 2010 Kristaps Dzonsons -.\" Copyright (c) 2010 Ingo Schwarze -.\" -.\" Permission to use, copy, modify, and distribute this software for any -.\" purpose with or without fee is hereby granted, provided that the above -.\" copyright notice and this permission notice appear in all copies. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES -.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF -.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR -.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN -.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF -.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -.\" -.Dd $Mdocdate: February 9 2011 $ -.Dt MDOC 3 -.Os -.Sh NAME -.Nm mdoc , -.Nm mdoc_addeqn , -.Nm mdoc_addspan , -.Nm mdoc_alloc , -.Nm mdoc_endparse , -.Nm mdoc_free , -.Nm mdoc_meta , -.Nm mdoc_node , -.Nm mdoc_parseln , -.Nm mdoc_reset -.Nd mdoc macro compiler library -.Sh SYNOPSIS -.In mandoc.h -.In mdoc.h -.Vt extern const char * const * mdoc_macronames; -.Vt extern const char * const * mdoc_argnames; -.Ft int -.Fo mdoc_addeqn -.Fa "struct mdoc *mdoc" -.Fa "const struct eqn *eqn" -.Fc -.Ft int -.Fo mdoc_addspan -.Fa "struct mdoc *mdoc" -.Fa "const struct tbl_span *span" -.Fc -.Ft "struct mdoc *" -.Fo mdoc_alloc -.Fa "struct regset *regs" -.Fa "void *data" -.Fa "mandocmsg msgs" -.Fc -.Ft int -.Fn mdoc_endparse "struct mdoc *mdoc" -.Ft void -.Fn mdoc_free "struct mdoc *mdoc" -.Ft "const struct mdoc_meta *" -.Fn mdoc_meta "const struct mdoc *mdoc" -.Ft "const struct mdoc_node *" -.Fn mdoc_node "const struct mdoc *mdoc" -.Ft int -.Fo mdoc_parseln -.Fa "struct mdoc *mdoc" -.Fa "int line" -.Fa "char *buf" -.Fc -.Ft int -.Fn mdoc_reset "struct mdoc *mdoc" -.Sh DESCRIPTION -The -.Nm mdoc -library parses lines of -.Xr mdoc 7 -input -into an abstract syntax tree (AST). -.Pp -In general, applications initiate a parsing sequence with -.Fn mdoc_alloc , -parse each line in a document with -.Fn mdoc_parseln , -close the parsing session with -.Fn mdoc_endparse , -operate over the syntax tree returned by -.Fn mdoc_node -and -.Fn mdoc_meta , -then free all allocated memory with -.Fn mdoc_free . -The -.Fn mdoc_reset -function may be used in order to reset the parser for another input -sequence. -.Ss Types -.Bl -ohang -.It Vt struct mdoc -An opaque type. -Its values are only used privately within the library. -.It Vt struct mdoc_node -A parsed node. -See -.Sx Abstract Syntax Tree -for details. -.El -.Ss Functions -If -.Fn mdoc_addeqn , -.Fn mdoc_addspan , -.Fn mdoc_parseln , -or -.Fn mdoc_endparse -return 0, calls to any function but -.Fn mdoc_reset -or -.Fn mdoc_free -will raise an assertion. -.Bl -ohang -.It Fn mdoc_addeqn -Add an equation to the parsing stream. -Returns 0 on failure, 1 on success. -.It Fn mdoc_addspan -Add a table span to the parsing stream. -Returns 0 on failure, 1 on success. -.It Fn mdoc_alloc -Allocates a parsing structure. -The -.Fa data -pointer is passed to -.Fa msgs . -Always returns a valid pointer. -The pointer must be freed with -.Fn mdoc_free . -.It Fn mdoc_reset -Reset the parser for another parse routine. -After its use, -.Fn mdoc_parseln -behaves as if invoked for the first time. -If it returns 0, memory could not be allocated. -.It Fn mdoc_free -Free all resources of a parser. -The pointer is no longer valid after invocation. -.It Fn mdoc_parseln -Parse a nil-terminated line of input. -This line should not contain the trailing newline. -Returns 0 on failure, 1 on success. -The input buffer -.Fa buf -is modified by this function. -.It Fn mdoc_endparse -Signals that the parse is complete. -Returns 0 on failure, 1 on success. -.It Fn mdoc_node -Returns the first node of the parse. -.It Fn mdoc_meta -Returns the document's parsed meta-data. -.El -.Ss Variables -.Bl -ohang -.It Va mdoc_macronames -An array of string-ified token names. -.It Va mdoc_argnames -An array of string-ified token argument names. -.El -.Ss Abstract Syntax Tree -The -.Nm -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 , -or after -.Fn mdoc_endparse -or -.Fn mdoc_parseln -fail, it may be incomplete. -.Pp -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 . -.Pp -The AST is composed of -.Vt struct mdoc_node -nodes with block, head, body, element, root and text types as declared -by the -.Va type -field. -Each node also provides its parse point (the -.Va line , -.Va sec , -and -.Va pos -fields), its position in the tree (the -.Va parent , -.Va child , -.Va nchild , -.Va next -and -.Va prev -fields) and some type-specific data, in particular, for nodes generated -from macros, the generating macro in the -.Va tok -field. -.Pp -The tree itself is arranged according to the following normal form, -where capitalised non-terminals represent nodes. -.Pp -.Bl -tag -width "ELEMENTXX" -compact -.It ROOT -\(<- mnode+ -.It mnode -\(<- BLOCK | ELEMENT | TEXT -.It BLOCK -\(<- HEAD [TEXT] (BODY [TEXT])+ [TAIL [TEXT]] -.It ELEMENT -\(<- TEXT* -.It HEAD -\(<- mnode* -.It BODY -\(<- mnode* [ENDBODY mnode*] -.It TAIL -\(<- mnode* -.It TEXT -\(<- [[:printable:],0x1e]* -.El -.Pp -Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of -the BLOCK production: these refer to punctuation marks. -Furthermore, 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. -Multiple body parts are only found in invocations of -.Sq \&Bl \-column , -where a new body introduces a new phrase. -.Ss Badly-nested Blocks -The ENDBODY node is available to end the formatting associated -with a given block before the physical end of that block. -It has a non-null -.Va end -field, is of the BODY -.Va type , -has the same -.Va tok -as the BLOCK it is ending, and has a -.Va pending -field pointing to that BLOCK's BODY node. -It is an indirect child of that BODY node -and has no children of its own. -.Pp -An ENDBODY node is generated when a block ends while one of its child -blocks is still open, like in the following example: -.Bd -literal -offset indent -\&.Ao ao -\&.Bo bo ac -\&.Ac bc -\&.Bc end -.Ed -.Pp -This example results in the following block structure: -.Bd -literal -offset indent -BLOCK Ao - HEAD Ao - BODY Ao - TEXT ao - BLOCK Bo, pending -> Ao - HEAD Bo - BODY Bo - TEXT bo - TEXT ac - ENDBODY Ao, pending -> Ao - TEXT bc -TEXT end -.Ed -.Pp -Here, the formatting of the -.Sq \&Ao -block extends from TEXT ao to TEXT ac, -while the formatting of the -.Sq \&Bo -block extends from TEXT bo to TEXT bc. -It renders as follows in -.Fl T Ns Cm ascii -mode: -.Pp -.Dl bc] end -.Pp -Support for badly-nested blocks is only provided for backward -compatibility with some older -.Xr mdoc 7 -implementations. -Using badly-nested blocks is -.Em strongly discouraged : -the -.Fl T Ns Cm html -and -.Fl T Ns Cm xhtml -front-ends are unable to render them in any meaningful way. -Furthermore, behaviour when encountering badly-nested blocks is not -consistent across troff implementations, especially when using multiple -levels of badly-nested blocks. -.Sh EXAMPLES -The following example reads lines from stdin and parses them, operating -on the finished parse tree with -.Fn parsed . -This example does not error-check nor free memory upon failure. -.Bd -literal -offset indent -struct regset regs; -struct mdoc *mdoc; -const struct mdoc_node *node; -char *buf; -size_t len; -int line; - -bzero(®s, sizeof(struct regset)); -line = 1; -mdoc = mdoc_alloc(®s, NULL, NULL); -buf = NULL; -alloc_len = 0; - -while ((len = getline(&buf, &alloc_len, stdin)) >= 0) { - if (len && buflen[len - 1] = '\en') - buf[len - 1] = '\e0'; - if ( ! mdoc_parseln(mdoc, line, buf)) - errx(1, "mdoc_parseln"); - line++; -} - -if ( ! mdoc_endparse(mdoc)) - errx(1, "mdoc_endparse"); -if (NULL == (node = mdoc_node(mdoc))) - errx(1, "mdoc_node"); - -parsed(mdoc, node); -mdoc_free(mdoc); -.Ed -.Pp -To compile this, execute -.Pp -.Dl % cc main.c libmdoc.a libmandoc.a -.Pp -where -.Pa main.c -is the example file. -.Sh SEE ALSO -.Xr mandoc 1 , -.Xr mdoc 7 -.Sh AUTHORS -The -.Nm -library was written by -.An Kristaps Dzonsons Aq kristaps@bsd.lv . Index: index.sgml =================================================================== RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/index.sgml,v retrieving revision 1.105 retrieving revision 1.106 diff -Lindex.sgml -Lindex.sgml -u -p -r1.105 -r1.106 --- index.sgml +++ index.sgml @@ -39,10 +39,9 @@

- mdocml consists of the libmdoc, libman, and libroff validating compilers; and mandoc, which interfaces with the compiler libraries to format output for UNIX - terminals, XHTML, HTML, PostScript, and PDF. It is a mdocml consists of the libmandoc validating + compilers and mandoc, which interfaces with the compiler library to format + output for UNIX terminals, XHTML, HTML, PostScript, and PDF. It is a BSD.lv project.

@@ -60,8 +59,7 @@

mdocml is architecture- and system-neutral, written in plain-old C. The most - current version is @VERSION@, dated @VDATE@. A full - ChangeLog (txt) is written with each release. + current version is @VERSION@, dated @VDATE@.

@@ -172,38 +170,14 @@ - man(3) + mandoc(3) - man macro compiler library + mandoc macro compiler library - (text | - xhtml | - pdf | - postscript) - - - - - mdoc(3) - - mdoc macro compiler library - - (text | - xhtml | - pdf | - postscript) - - - - - roff(3) - - roff macro compiler library - - (text | - xhtml | - pdf | - postscript) + (text | + xhtml | + pdf | + postscript) @@ -220,6 +194,18 @@ + eqn(7) + + eqn-mandoc language reference + + (text | + xhtml | + pdf | + postscript) + + + + mandoc_char(7) mandoc special characters @@ -348,7 +334,7 @@ still minimal, especially for -Thtml and -Txhtml, but manages to at least display data. This means that mandoc now has built-in support for two troff preprocessors via - libroff: soelim and tbl. + libroff: soelim and tbl.

@@ -375,7 +361,7 @@ HREF="#documentation">DOCUMENTATION section for examples. Attention: available style-sheet classes have been considerably changed! See the example.style.css file for details. - Lastly, libmdoc and libman have been + Lastly, libmdoc and libman have been cleaned up and reduced in size and complexity.

Index: Makefile =================================================================== RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/Makefile,v retrieving revision 1.316 retrieving revision 1.317 diff -LMakefile -LMakefile -u -p -r1.316 -r1.317 --- Makefile +++ Makefile @@ -97,32 +97,32 @@ HEADS = mdoc.h libmdoc.h man.h libman libmandoc.h html.h chars.h out.h main.h \ mandoc.h libroff.h -GSGMLS = mandoc.1.sgml mdoc.3.sgml mdoc.7.sgml \ - mandoc_char.7.sgml man.7.sgml man.3.sgml roff.7.sgml \ - roff.3.sgml tbl.7.sgml eqn.7.sgml +GSGMLS = mandoc.1.sgml mdoc.7.sgml \ + mandoc_char.7.sgml man.7.sgml mandoc.3.sgml roff.7.sgml \ + tbl.7.sgml eqn.7.sgml SGMLS = index.sgml -XHTMLS = mandoc.1.xhtml mdoc.3.xhtml \ - man.3.xhtml mdoc.7.xhtml man.7.xhtml mandoc_char.7.xhtml \ - roff.7.xhtml roff.3.xhtml tbl.7.xhtml eqn.7.xhtml +XHTMLS = mandoc.1.xhtml \ + mandoc.3.xhtml mdoc.7.xhtml man.7.xhtml mandoc_char.7.xhtml \ + roff.7.xhtml tbl.7.xhtml eqn.7.xhtml HTMLS = ChangeLog.html index.html man.h.html mdoc.h.html \ - mandoc.h.html mandoc.1.html mdoc.3.html \ - man.3.html mdoc.7.html man.7.html mandoc_char.7.html \ - roff.7.html roff.3.html tbl.7.html eqn.7.html + mandoc.h.html mandoc.1.html \ + mandoc.3.html mdoc.7.html man.7.html mandoc_char.7.html \ + roff.7.html tbl.7.html eqn.7.html -PSS = mandoc.1.ps mdoc.3.ps man.3.ps mdoc.7.ps man.7.ps \ - mandoc_char.7.ps roff.7.ps roff.3.ps tbl.7.ps eqn.7.ps +PSS = mandoc.1.ps mandoc.3.ps mdoc.7.ps man.7.ps \ + mandoc_char.7.ps roff.7.ps tbl.7.ps eqn.7.ps -PDFS = mandoc.1.pdf mdoc.3.pdf man.3.pdf mdoc.7.pdf man.7.pdf \ - mandoc_char.7.pdf roff.7.pdf roff.3.pdf tbl.7.pdf eqn.7.pdf +PDFS = mandoc.1.pdf mandoc.3.pdf mdoc.7.pdf man.7.pdf \ + mandoc_char.7.pdf roff.7.pdf tbl.7.pdf eqn.7.pdf XSLS = ChangeLog.xsl -TEXTS = mandoc.1.txt mdoc.3.txt man.3.txt mdoc.7.txt man.7.txt \ +TEXTS = mandoc.1.txt mandoc.3.txt mdoc.7.txt man.7.txt \ mandoc_char.7.txt ChangeLog.txt \ - roff.7.txt roff.3.txt tbl.7.txt eqn.7.txt + roff.7.txt tbl.7.txt eqn.7.txt EXAMPLES = example.style.css @@ -134,8 +134,8 @@ MD5S = mdocml-$(VERSION).md5 TARGZS = mdocml-$(VERSION).tar.gz -MANS = mandoc.1 mdoc.3 mdoc.7 mandoc_char.7 man.7 \ - man.3 roff.7 roff.3 tbl.7 eqn.7 +MANS = mandoc.1 mdoc.7 mandoc_char.7 man.7 \ + mandoc.3 roff.7 tbl.7 eqn.7 BINS = mandoc --- man.3 +++ /dev/null @@ -1,283 +0,0 @@ -.\" $Id: man.3,v 1.30 2011/02/09 09:18:15 kristaps Exp $ -.\" -.\" Copyright (c) 2009-2010 Kristaps Dzonsons -.\" -.\" Permission to use, copy, modify, and distribute this software for any -.\" purpose with or without fee is hereby granted, provided that the above -.\" copyright notice and this permission notice appear in all copies. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES -.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF -.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR -.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN -.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF -.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -.\" -.Dd $Mdocdate: February 9 2011 $ -.Dt MAN 3 -.Os -.Sh NAME -.Nm man , -.Nm man_addeqn , -.Nm man_addspan , -.Nm man_alloc , -.Nm man_endparse , -.Nm man_free , -.Nm man_meta , -.Nm man_node , -.Nm man_parseln , -.Nm man_reset -.Nd man macro compiler library -.Sh SYNOPSIS -.In mandoc.h -.In man.h -.Vt extern const char * const * man_macronames; -.Ft int -.Fo man_addeqn -.Fa "struct man *man" -.Fa "const struct eqn *eqn" -.Fc -.Ft int -.Fo man_addspan -.Fa "struct man *man" -.Fa "const struct tbl_span *span" -.Fc -.Ft "struct man *" -.Fo man_alloc -.Fa "struct regset *regs" -.Fa "void *data" -.Fa "mandocmsg msgs" -.Fc -.Ft int -.Fn man_endparse "struct man *man" -.Ft void -.Fn man_free "struct man *man" -.Ft "const struct man_meta *" -.Fn man_meta "const struct man *man" -.Ft "const struct man_node *" -.Fn man_node "const struct man *man" -.Ft int -.Fo man_parseln -.Fa "struct man *man" -.Fa "int line" -.Fa "char *buf" -.Fc -.Ft void -.Fn man_reset "struct man *man" -.Sh DESCRIPTION -The -.Nm -library parses lines of -.Xr man 7 -input into an abstract syntax tree (AST). -.Pp -In general, applications initiate a parsing sequence with -.Fn man_alloc , -parse each line in a document with -.Fn man_parseln , -close the parsing session with -.Fn man_endparse , -operate over the syntax tree returned by -.Fn man_node -and -.Fn man_meta , -then free all allocated memory with -.Fn man_free . -The -.Fn man_reset -function may be used in order to reset the parser for another input -sequence. -.Pp -Beyond the full set of macros defined in -.Xr man 7 , -the -.Nm -library also accepts the following macro: -.Pp -.Bl -tag -width Ds -compact -.It PD -Has no effect. -Handled as a current-scope line macro. -.El -.Ss Types -.Bl -ohang -.It Vt struct man -An opaque type. -Its values are only used privately within the library. -.It Vt struct man_node -A parsed node. -See -.Sx Abstract Syntax Tree -for details. -.El -.Ss Functions -If -.Fn man_addeqn , -.Fn man_addspan , -.Fn man_parseln , -or -.Fn man_endparse -return 0, calls to any function but -.Fn man_reset -or -.Fn man_free -will raise an assertion. -.Bl -ohang -.It Fn man_addeqn -Add an equation to the parsing stream. -Returns 0 on failure, 1 on success. -.It Fn man_addspan -Add a table span to the parsing stream. -Returns 0 on failure, 1 on success. -.It Fn man_alloc -Allocates a parsing structure. -The -.Fa data -pointer is passed to -.Fa msgs . -Always returns a valid pointer. -The pointer must be freed with -.Fn man_free . -.It Fn man_reset -Reset the parser for another parse routine. -After its use, -.Fn man_parseln -behaves as if invoked for the first time. -.It Fn man_free -Free all resources of a parser. -The pointer is no longer valid after invocation. -.It Fn man_parseln -Parse a nil-terminated line of input. -This line should not contain the trailing newline. -Returns 0 on failure, 1 on success. -The input buffer -.Fa buf -is modified by this function. -.It Fn man_endparse -Signals that the parse is complete. -Returns 0 on failure, 1 on success. -.It Fn man_node -Returns the first node of the parse. -.It Fn man_meta -Returns the document's parsed meta-data. -.El -.Ss Variables -The following variables are also defined: -.Bl -ohang -.It Va man_macronames -An array of string-ified token names. -.El -.Ss Abstract Syntax Tree -The -.Nm -functions produce an abstract syntax tree (AST) describing input in a -regular form. -It may be reviewed at any time with -.Fn man_nodes ; -however, if called before -.Fn man_endparse , -or after -.Fn man_endparse -or -.Fn man_parseln -fail, it may be incomplete. -.Pp -This AST is governed by the ontological rules dictated in -.Xr man 7 -and derives its terminology accordingly. -.Pp -The AST is composed of -.Vt struct man_node -nodes with element, root and text types as declared by the -.Va type -field. -Each node also provides its parse point (the -.Va line , -.Va sec , -and -.Va pos -fields), its position in the tree (the -.Va parent , -.Va child , -.Va next -and -.Va prev -fields) and some type-specific data. -.Pp -The tree itself is arranged according to the following normal form, -where capitalised non-terminals represent nodes. -.Pp -.Bl -tag -width "ELEMENTXX" -compact -.It ROOT -\(<- mnode+ -.It mnode -\(<- ELEMENT | TEXT | BLOCK -.It BLOCK -\(<- HEAD BODY -.It HEAD -\(<- mnode* -.It BODY -\(<- mnode* -.It ELEMENT -\(<- ELEMENT | TEXT* -.It TEXT -\(<- [[:alpha:]]* -.El -.Pp -The only elements capable of nesting other elements are those with -next-lint scope as documented in -.Xr man 7 . -.Sh EXAMPLES -The following example reads lines from stdin and parses them, operating -on the finished parse tree with -.Fn parsed . -This example does not error-check nor free memory upon failure. -.Bd -literal -offset indent -struct regset regs; -struct man *man; -struct man_node *node; -char *buf; -size_t len; -int line; - -bzero(®s, sizeof(struct regset)); -line = 1; -man = man_alloc(®s, NULL, NULL); -buf = NULL; -alloc_len = 0; - -while ((len = getline(&buf, &alloc_len, stdin)) >= 0) { - if (len && buflen[len - 1] = '\en') - buf[len - 1] = '\e0'; - if ( ! man_parseln(man, line, buf)) - errx(1, "man_parseln"); - line++; -} - -free(buf); - -if ( ! man_endparse(man)) - errx(1, "man_endparse"); -if (NULL == (node = man_node(man))) - errx(1, "man_node"); - -parsed(man, node); -man_free(man); -.Ed -.Pp -To compile this, execute -.Pp -.Dl % cc main.c libman.a libmandoc.a -.Pp -where -.Pa main.c -is the example file. -.Sh SEE ALSO -.Xr mandoc 1 , -.Xr man 7 -.Sh AUTHORS -The -.Nm -library was written by -.An Kristaps Dzonsons Aq kristaps@bsd.lv . Index: libmandoc.h =================================================================== RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/libmandoc.h,v retrieving revision 1.14 retrieving revision 1.15 diff -Llibmandoc.h -Llibmandoc.h -u -p -r1.14 -r1.15 --- libmandoc.h +++ libmandoc.h @@ -1,6 +1,6 @@ /* $Id$ */ /* - * Copyright (c) 2009, 2010 Kristaps Dzonsons + * Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above -- To unsubscribe send an email to source+unsubscribe@mdocml.bsd.lv