#include "mandoc.h"
-#include "roff.h"
#include "libmandoc.h"
#include "libroff.h"
Index: index.sgml
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/index.sgml,v
retrieving revision 1.105
diff -u -r1.105 index.sgml
--- index.sgml 7 Jan 2011 15:22:21 -0000 1.105
+++ index.sgml 21 Mar 2011 17:23:13 -0000
@@ -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)
|
@@ -216,6 +190,18 @@
xhtml |
pdf |
postscript)
+
+
+
+
+ | eqn(7) |
+
+ eqn-mandoc language reference
+
+ (text |
+ xhtml |
+ pdf |
+ postscript)
|
Index: libman.h
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/libman.h,v
retrieving revision 1.47
diff -u -r1.47 libman.h
--- libman.h 20 Mar 2011 16:02:05 -0000 1.47
+++ libman.h 21 Mar 2011 17:23:13 -0000
@@ -17,8 +17,6 @@
#ifndef LIBMAN_H
#define LIBMAN_H
-#include "man.h"
-
enum man_next {
MAN_NEXT_SIBLING = 0,
MAN_NEXT_CHILD
Index: libmandoc.h
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/libmandoc.h,v
retrieving revision 1.13
diff -u -r1.13 libmandoc.h
--- libmandoc.h 20 Mar 2011 16:02:05 -0000 1.13
+++ libmandoc.h 21 Mar 2011 17:23:13 -0000
@@ -17,18 +17,58 @@
#ifndef LIBMANDOC_H
#define LIBMANDOC_H
+enum rofferr {
+ ROFF_CONT, /* continue processing line */
+ ROFF_RERUN, /* re-run roff interpreter with offset */
+ ROFF_APPEND, /* re-run main parser, appending next line */
+ ROFF_REPARSE, /* re-run main parser on the result */
+ ROFF_SO, /* include another file */
+ ROFF_IGN, /* ignore current line */
+ ROFF_TBL, /* a table row was successfully parsed */
+ ROFF_EQN, /* an equation was successfully parsed */
+ ROFF_ERR /* badness: puke and stop */
+};
+
+struct roff;
+
__BEGIN_DECLS
-void mandoc_msg(enum mandocerr, struct mparse *,
- int, int, const char *);
-void mandoc_vmsg(enum mandocerr, struct mparse *,
- int, int, const char *, ...);
-int mandoc_special(char *);
-char *mandoc_strdup(const char *);
-char *mandoc_getarg(struct mparse *, char **, int, int *);
-char *mandoc_normdate(struct mparse *, char *, int, int);
-int mandoc_eos(const char *, size_t, int);
-int mandoc_hyph(const char *, const char *);
+void mandoc_msg(enum mandocerr, struct mparse *,
+ int, int, const char *);
+void mandoc_vmsg(enum mandocerr, struct mparse *,
+ int, int, const char *, ...);
+int mandoc_special(char *);
+char *mandoc_strdup(const char *);
+char *mandoc_getarg(struct mparse *, char **, int, int *);
+char *mandoc_normdate(struct mparse *, char *, int, int);
+int mandoc_eos(const char *, size_t, int);
+int mandoc_hyph(const char *, const char *);
+
+void mdoc_free(struct mdoc *);
+struct mdoc *mdoc_alloc(struct regset *, struct mparse *);
+void mdoc_reset(struct mdoc *);
+int mdoc_parseln(struct mdoc *, int, char *, int);
+int mdoc_endparse(struct mdoc *);
+int mdoc_addspan(struct mdoc *, const struct tbl_span *);
+int mdoc_addeqn(struct mdoc *, const struct eqn *);
+
+void man_free(struct man *);
+struct man *man_alloc(struct regset *, struct mparse *);
+void man_reset(struct man *);
+int man_parseln(struct man *, int, char *, int);
+int man_endparse(struct man *);
+int man_addspan(struct man *, const struct tbl_span *);
+int man_addeqn(struct man *, const struct eqn *);
+
+void roff_free(struct roff *);
+struct roff *roff_alloc(struct regset *, struct mparse *);
+void roff_reset(struct roff *);
+enum rofferr roff_parseln(struct roff *, int,
+ char **, size_t *, int, int *);
+void roff_endparse(struct roff *);
+
+const struct tbl_span *roff_span(const struct roff *);
+const struct eqn *roff_eqn(const struct roff *);
__END_DECLS
Index: libmdoc.h
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/libmdoc.h,v
retrieving revision 1.69
diff -u -r1.69 libmdoc.h
--- libmdoc.h 20 Mar 2011 16:02:05 -0000 1.69
+++ libmdoc.h 21 Mar 2011 17:23:13 -0000
@@ -17,8 +17,6 @@
#ifndef LIBMDOC_H
#define LIBMDOC_H
-#include "mdoc.h"
-
enum mdoc_next {
MDOC_NEXT_SIBLING = 0,
MDOC_NEXT_CHILD
Index: main.c
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/main.c,v
retrieving revision 1.157
diff -u -r1.157 main.c
--- main.c 21 Mar 2011 12:04:26 -0000 1.157
+++ main.c 21 Mar 2011 17:23:13 -0000
@@ -28,8 +28,6 @@
#include "mandoc.h"
#include "main.h"
-#include "mdoc.h"
-#include "man.h"
#if !defined(__GNUC__) || (__GNUC__ < 2)
# if !defined(lint)
Index: man.3
===================================================================
RCS file: man.3
diff -N man.3
--- man.3 9 Feb 2011 09:18:15 -0000 1.30
+++ /dev/null 1 Jan 1970 00:00:00 -0000
@@ -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: man.h
===================================================================
RCS file: man.h
diff -N man.h
--- man.h 20 Mar 2011 16:02:05 -0000 1.55
+++ /dev/null 1 Jan 1970 00:00:00 -0000
@@ -1,133 +0,0 @@
-/* $Id: man.h,v 1.55 2011/03/20 16:02:05 kristaps Exp $ */
-/*
- * 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
- * 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.
- */
-#ifndef MAN_H
-#define MAN_H
-
-/*
- * What follows is a list of ALL possible macros.
- */
-enum mant {
- MAN_br = 0,
- MAN_TH,
- MAN_SH,
- MAN_SS,
- MAN_TP,
- MAN_LP,
- MAN_PP,
- MAN_P,
- MAN_IP,
- MAN_HP,
- MAN_SM,
- MAN_SB,
- MAN_BI,
- MAN_IB,
- MAN_BR,
- MAN_RB,
- MAN_R,
- MAN_B,
- MAN_I,
- MAN_IR,
- MAN_RI,
- MAN_na,
- MAN_sp,
- MAN_nf,
- MAN_fi,
- MAN_RE,
- MAN_RS,
- MAN_DT,
- MAN_UC,
- MAN_PD,
- MAN_AT,
- MAN_in,
- MAN_ft,
- MAN_MAX
-};
-
-/*
- * Type of a syntax node.
- */
-enum man_type {
- MAN_TEXT,
- MAN_ELEM,
- MAN_ROOT,
- MAN_BLOCK,
- MAN_HEAD,
- MAN_BODY,
- MAN_TBL,
- MAN_EQN
-};
-
-/*
- * Information from prologue.
- */
-struct man_meta {
- char *msec; /* `TH' section (1, 3p, etc.) */
- char *date; /* `TH' normalised date */
- char *vol; /* `TH' volume */
- char *title; /* `TH' title (e.g., FOO) */
- char *source; /* `TH' source (e.g., GNU) */
-};
-
-/*
- * Single node in tree-linked AST.
- */
-struct man_node {
- struct man_node *parent; /* parent AST node */
- struct man_node *child; /* first child AST node */
- struct man_node *next; /* sibling AST node */
- struct man_node *prev; /* prior sibling AST node */
- int nchild; /* number children */
- int line;
- int pos;
- enum mant tok; /* tok or MAN__MAX if none */
- int flags;
-#define MAN_VALID (1 << 0) /* has been validated */
-#define MAN_EOS (1 << 2) /* at sentence boundary */
-#define MAN_LINE (1 << 3) /* first macro/text on line */
- enum man_type type; /* AST node type */
- char *string; /* TEXT node argument */
- struct man_node *head; /* BLOCK node HEAD ptr */
- struct man_node *body; /* BLOCK node BODY ptr */
- const struct tbl_span *span; /* TBL */
- const struct eqn *eqn; /* EQN */
-};
-
-/*
- * Names of macros. Index is enum mant. Indexing into this returns
- * the normalised name, e.g., man_macronames[MAN_SH] -> "SH".
- */
-extern const char *const *man_macronames;
-
-__BEGIN_DECLS
-
-struct man;
-
-void man_free(struct man *);
-struct man *man_alloc(struct regset *, struct mparse *);
-void man_reset(struct man *);
-int man_parseln(struct man *, int, char *, int);
-int man_endparse(struct man *);
-int man_addspan(struct man *,
- const struct tbl_span *);
-int man_addeqn(struct man *, const struct eqn *);
-
-const struct man_node *man_node(const struct man *);
-const struct man_meta *man_meta(const struct man *);
-
-__END_DECLS
-
-#endif /*!MAN_H*/
Index: man_html.c
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/man_html.c,v
retrieving revision 1.70
diff -u -r1.70 man_html.c
--- man_html.c 7 Mar 2011 01:35:51 -0000 1.70
+++ man_html.c 21 Mar 2011 17:23:13 -0000
@@ -29,7 +29,6 @@
#include "mandoc.h"
#include "out.h"
#include "html.h"
-#include "man.h"
#include "main.h"
/* TODO: preserve ident widths. */
Index: man_term.c
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/man_term.c,v
retrieving revision 1.104
diff -u -r1.104 man_term.c
--- man_term.c 7 Mar 2011 01:35:51 -0000 1.104
+++ man_term.c 21 Mar 2011 17:23:13 -0000
@@ -29,7 +29,6 @@
#include "mandoc.h"
#include "out.h"
-#include "man.h"
#include "term.h"
#include "chars.h"
#include "main.h"
Index: mandoc.3
===================================================================
RCS file: mandoc.3
diff -N mandoc.3
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ mandoc.3 21 Mar 2011 17:23:13 -0000
@@ -0,0 +1,321 @@
+.\" $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 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 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 .
Index: mandoc.h
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mandoc.h,v
retrieving revision 1.64
diff -u -r1.64 mandoc.h
--- mandoc.h 20 Mar 2011 16:05:21 -0000 1.64
+++ mandoc.h 21 Mar 2011 17:23:13 -0000
@@ -27,7 +27,7 @@
* threshold).
*/
enum mandoclevel {
- MANDOCLEVEL_OK = 0,
+ MANDOCLEVEL_OK = 0, /* everything's ok */
MANDOCLEVEL_RESERVED,
MANDOCLEVEL_WARNING, /* warnings: syntax, whitespace, etc. */
MANDOCLEVEL_ERROR, /* input has been thrown away */
@@ -277,7 +277,7 @@
};
/*
- * Available registers (set in libroff, accessed elsewhere).
+ * Available roff registers.
*/
enum regs {
REG_nS = 0,
@@ -328,6 +328,436 @@
DELIM_CLOSE
};
+enum mdoct {
+ MDOC_Ap = 0,
+ MDOC_Dd,
+ MDOC_Dt,
+ MDOC_Os,
+ MDOC_Sh,
+ MDOC_Ss,
+ MDOC_Pp,
+ MDOC_D1,
+ MDOC_Dl,
+ MDOC_Bd,
+ MDOC_Ed,
+ MDOC_Bl,
+ MDOC_El,
+ MDOC_It,
+ MDOC_Ad,
+ MDOC_An,
+ MDOC_Ar,
+ MDOC_Cd,
+ MDOC_Cm,
+ MDOC_Dv,
+ MDOC_Er,
+ MDOC_Ev,
+ MDOC_Ex,
+ MDOC_Fa,
+ MDOC_Fd,
+ MDOC_Fl,
+ MDOC_Fn,
+ MDOC_Ft,
+ MDOC_Ic,
+ MDOC_In,
+ MDOC_Li,
+ MDOC_Nd,
+ MDOC_Nm,
+ MDOC_Op,
+ MDOC_Ot,
+ MDOC_Pa,
+ MDOC_Rv,
+ MDOC_St,
+ MDOC_Va,
+ MDOC_Vt,
+ MDOC_Xr,
+ MDOC__A,
+ MDOC__B,
+ MDOC__D,
+ MDOC__I,
+ MDOC__J,
+ MDOC__N,
+ MDOC__O,
+ MDOC__P,
+ MDOC__R,
+ MDOC__T,
+ MDOC__V,
+ MDOC_Ac,
+ MDOC_Ao,
+ MDOC_Aq,
+ MDOC_At,
+ MDOC_Bc,
+ MDOC_Bf,
+ MDOC_Bo,
+ MDOC_Bq,
+ MDOC_Bsx,
+ MDOC_Bx,
+ MDOC_Db,
+ MDOC_Dc,
+ MDOC_Do,
+ MDOC_Dq,
+ MDOC_Ec,
+ MDOC_Ef,
+ MDOC_Em,
+ MDOC_Eo,
+ MDOC_Fx,
+ MDOC_Ms,
+ MDOC_No,
+ MDOC_Ns,
+ MDOC_Nx,
+ MDOC_Ox,
+ MDOC_Pc,
+ MDOC_Pf,
+ MDOC_Po,
+ MDOC_Pq,
+ MDOC_Qc,
+ MDOC_Ql,
+ MDOC_Qo,
+ MDOC_Qq,
+ MDOC_Re,
+ MDOC_Rs,
+ MDOC_Sc,
+ MDOC_So,
+ MDOC_Sq,
+ MDOC_Sm,
+ MDOC_Sx,
+ MDOC_Sy,
+ MDOC_Tn,
+ MDOC_Ux,
+ MDOC_Xc,
+ MDOC_Xo,
+ MDOC_Fo,
+ MDOC_Fc,
+ MDOC_Oo,
+ MDOC_Oc,
+ MDOC_Bk,
+ MDOC_Ek,
+ MDOC_Bt,
+ MDOC_Hf,
+ MDOC_Fr,
+ MDOC_Ud,
+ MDOC_Lb,
+ MDOC_Lp,
+ MDOC_Lk,
+ MDOC_Mt,
+ MDOC_Brq,
+ MDOC_Bro,
+ MDOC_Brc,
+ MDOC__C,
+ MDOC_Es,
+ MDOC_En,
+ MDOC_Dx,
+ MDOC__Q,
+ MDOC_br,
+ MDOC_sp,
+ MDOC__U,
+ MDOC_Ta,
+ MDOC_MAX
+};
+
+enum mdocargt {
+ MDOC_Split,
+ MDOC_Nosplit,
+ MDOC_Ragged,
+ MDOC_Unfilled,
+ MDOC_Literal,
+ MDOC_File,
+ MDOC_Offset,
+ MDOC_Bullet,
+ MDOC_Dash,
+ MDOC_Hyphen,
+ MDOC_Item,
+ MDOC_Enum,
+ MDOC_Tag,
+ MDOC_Diag,
+ MDOC_Hang,
+ MDOC_Ohang,
+ MDOC_Inset,
+ MDOC_Column,
+ MDOC_Width,
+ MDOC_Compact,
+ MDOC_Std,
+ MDOC_Filled,
+ MDOC_Words,
+ MDOC_Emphasis,
+ MDOC_Symbolic,
+ MDOC_Nested,
+ MDOC_Centred,
+ MDOC_ARG_MAX
+};
+
+enum mdoc_type {
+ MDOC_TEXT, /* text */
+ MDOC_ELEM, /* in-line element */
+ MDOC_HEAD, /* block head */
+ MDOC_TAIL, /* block tail */
+ MDOC_BODY, /* block body */
+ MDOC_BLOCK, /* block enclosure */
+ MDOC_TBL, /* table */
+ MDOC_EQN, /* equation */
+ MDOC_ROOT /* root of document */
+};
+
+/*
+ * Section (named/unnamed) of mdoc(7) `Sh'. Note that these appear in
+ * the conventional order imposed by mdoc(7).
+ */
+enum mdoc_sec {
+ SEC_NONE = 0, /* No section, yet. */
+ SEC_NAME,
+ SEC_LIBRARY,
+ SEC_SYNOPSIS,
+ SEC_DESCRIPTION,
+ SEC_IMPLEMENTATION,
+ SEC_RETURN_VALUES,
+ SEC_ENVIRONMENT,
+ SEC_FILES,
+ SEC_EXIT_STATUS,
+ SEC_EXAMPLES,
+ SEC_DIAGNOSTICS,
+ SEC_COMPATIBILITY,
+ SEC_ERRORS,
+ SEC_SEE_ALSO,
+ SEC_STANDARDS,
+ SEC_HISTORY,
+ SEC_AUTHORS,
+ SEC_CAVEATS,
+ SEC_BUGS,
+ SEC_SECURITY,
+ SEC_CUSTOM, /* User-defined. */
+ SEC__MAX
+};
+
+struct mdoc_meta {
+ char *msec; /* `Dt' section (1, 3p, etc.) */
+ char *vol; /* `Dt' volume (implied) */
+ char *arch; /* `Dt' arch (i386, etc.) */
+ char *date; /* `Dd' normalised date */
+ char *title; /* `Dt' title (FOO, etc.) */
+ char *os; /* `Os' system (OpenBSD, etc.) */
+ char *name; /* leading `Nm' name */
+};
+
+/*
+ * An argument to a mdoc(7) macro (multiple values = `-column xxx yyy').
+ */
+struct mdoc_argv {
+ enum mdocargt arg; /* type of argument */
+ int line;
+ int pos;
+ size_t sz; /* elements in "value" */
+ char **value; /* argument strings */
+};
+
+/*
+ * Reference-counted macro arguments. These are refcounted because
+ * blocks have multiple instances of the same arguments spread across
+ * the HEAD, BODY, TAIL, and BLOCK node types.
+ */
+struct mdoc_arg {
+ size_t argc;
+ struct mdoc_argv *argv;
+ unsigned int refcnt;
+};
+
+/*
+ * Indicates that a BODY's formatting has ended, but the scope is still
+ * open. Used for syntax-broken blocks.
+ */
+enum mdoc_endbody {
+ ENDBODY_NOT = 0,
+ ENDBODY_SPACE, /* is broken: append a space */
+ ENDBODY_NOSPACE /* is broken: don't append a space */
+};
+
+enum mdoc_list {
+ LIST__NONE = 0,
+ LIST_bullet, /* -bullet argument */
+ LIST_column, /* -column argument */
+ LIST_dash, /* -dash argument */
+ LIST_diag, /* -diag argument */
+ LIST_enum, /* -enum argument */
+ LIST_hang, /* -hang argument */
+ LIST_hyphen, /* -hyphen argument */
+ LIST_inset, /* -inset argument */
+ LIST_item, /* -item argument */
+ LIST_ohang, /* -ohang argument */
+ LIST_tag, /* -tag argument */
+ LIST_MAX
+};
+
+enum mdoc_disp {
+ DISP__NONE = 0,
+ DISP_centred, /* -centred argument */
+ DISP_ragged, /* -ragged argument */
+ DISP_unfilled, /* -unfilled argument */
+ DISP_filled, /* -filled argument */
+ DISP_literal /* -literal argument */
+};
+
+enum mdoc_auth {
+ AUTH__NONE = 0,
+ AUTH_split, /* -split argument */
+ AUTH_nosplit /* -nosplit argument */
+};
+
+enum mdoc_font {
+ FONT__NONE = 0,
+ FONT_Em, /* "Em" or -emphasis */
+ FONT_Li, /* "Li" or -literal */
+ FONT_Sy /* "Sy" or -symbolic */
+};
+
+struct mdoc_bd {
+ const char *offs; /* -offset */
+ enum mdoc_disp type; /* -ragged, etc. */
+ int comp; /* -compact */
+};
+
+struct mdoc_bl {
+ const char *width; /* -width */
+ const char *offs; /* -offset */
+ enum mdoc_list type; /* -tag, -enum, etc. */
+ int comp; /* -compact */
+ size_t ncols; /* -column arg count */
+ const char **cols; /* -column val ptr */
+};
+
+struct mdoc_bf {
+ enum mdoc_font font; /* font */
+};
+
+struct mdoc_an {
+ enum mdoc_auth auth; /* -split, etc. */
+};
+
+struct mdoc_rs {
+ int quote_T; /* whether to quote %T */
+};
+
+/*
+ * Consists of normalised node arguments. These should be used instead
+ * of iterating through the mdoc_arg pointers of a node: defaults are
+ * provided, etc.
+ */
+union mdoc_data {
+ struct mdoc_an An; /* An arguments */
+ struct mdoc_bd Bd; /* Bd arguments */
+ struct mdoc_bf Bf; /* Bf arguments */
+ struct mdoc_bl Bl; /* Bl arguments */
+ struct mdoc_rs Rs; /* Rs arguments */
+};
+
+/*
+ * Single node in tree-linked AST.
+ */
+struct mdoc_node {
+ struct mdoc_node *parent; /* parent AST node */
+ struct mdoc_node *child; /* first child AST node */
+ struct mdoc_node *last; /* last child AST node */
+ struct mdoc_node *next; /* sibling AST node */
+ struct mdoc_node *prev; /* prior sibling AST node */
+ int nchild; /* number children */
+ int line; /* parse line */
+ int pos; /* parse column */
+ enum mdoct tok; /* tok or MDOC__MAX if none */
+ int flags;
+#define MDOC_VALID (1 << 0) /* has been validated */
+#define MDOC_EOS (1 << 2) /* at sentence boundary */
+#define MDOC_LINE (1 << 3) /* first macro/text on line */
+#define MDOC_SYNPRETTY (1 << 4) /* SYNOPSIS-style formatting */
+#define MDOC_ENDED (1 << 5) /* rendering has been ended */
+ enum mdoc_type type; /* AST node type */
+ enum mdoc_sec sec; /* current named section */
+ union mdoc_data *norm; /* normalised args */
+ /* FIXME: these can be union'd to shave a few bytes. */
+ struct mdoc_arg *args; /* BLOCK/ELEM */
+ struct mdoc_node *pending; /* BLOCK */
+ struct mdoc_node *head; /* BLOCK */
+ struct mdoc_node *body; /* BLOCK */
+ struct mdoc_node *tail; /* BLOCK */
+ char *string; /* TEXT */
+ const struct tbl_span *span; /* TBL */
+ const struct eqn *eqn; /* EQN */
+ enum mdoc_endbody end; /* BODY */
+};
+
+enum mant {
+ MAN_br = 0,
+ MAN_TH,
+ MAN_SH,
+ MAN_SS,
+ MAN_TP,
+ MAN_LP,
+ MAN_PP,
+ MAN_P,
+ MAN_IP,
+ MAN_HP,
+ MAN_SM,
+ MAN_SB,
+ MAN_BI,
+ MAN_IB,
+ MAN_BR,
+ MAN_RB,
+ MAN_R,
+ MAN_B,
+ MAN_I,
+ MAN_IR,
+ MAN_RI,
+ MAN_na,
+ MAN_sp,
+ MAN_nf,
+ MAN_fi,
+ MAN_RE,
+ MAN_RS,
+ MAN_DT,
+ MAN_UC,
+ MAN_PD,
+ MAN_AT,
+ MAN_in,
+ MAN_ft,
+ MAN_MAX
+};
+
+enum man_type {
+ MAN_TEXT,
+ MAN_ELEM,
+ MAN_ROOT,
+ MAN_BLOCK,
+ MAN_HEAD,
+ MAN_BODY,
+ MAN_TBL,
+ MAN_EQN
+};
+
+struct man_meta {
+ char *msec; /* `TH' section (1, 3p, etc.) */
+ char *date; /* `TH' normalised date */
+ char *vol; /* `TH' volume */
+ char *title; /* `TH' title (e.g., FOO) */
+ char *source; /* `TH' source (e.g., GNU) */
+};
+
+struct man_node {
+ struct man_node *parent; /* parent AST node */
+ struct man_node *child; /* first child AST node */
+ struct man_node *next; /* sibling AST node */
+ struct man_node *prev; /* prior sibling AST node */
+ int nchild; /* number children */
+ int line;
+ int pos;
+ enum mant tok; /* tok or MAN__MAX if none */
+ int flags;
+#define MAN_VALID (1 << 0) /* has been validated */
+#define MAN_EOS (1 << 2) /* at sentence boundary */
+#define MAN_LINE (1 << 3) /* first macro/text on line */
+ enum man_type type; /* AST node type */
+ char *string; /* TEXT node argument */
+ struct man_node *head; /* BLOCK node HEAD ptr */
+ struct man_node *body; /* BLOCK node BODY ptr */
+ const struct tbl_span *span; /* TBL */
+ const struct eqn *eqn; /* EQN */
+};
+
/*
* The type of parse sequence. This value is usually passed via the
* mandoc(1) command line of -man and -mdoc. It's almost exclusively
@@ -342,12 +772,22 @@
typedef void (*mandocmsg)(enum mandocerr, enum mandoclevel,
const char *, int, int, const char *);
+/* Names of macros. Index is enum mdoct. */
+extern const char * const *mdoc_macronames;
+
+/* Names of macro args. Index is enum mdocargt. */
+extern const char * const *mdoc_argnames;
+
+/* Names of macros. Index is enum mant. */
+extern const char * const *man_macronames;
+
+
+__BEGIN_DECLS
+
struct mparse;
struct mdoc;
struct man;
-__BEGIN_DECLS
-
void mparse_free(struct mparse *);
void mparse_reset(struct mparse *);
struct mparse *mparse_alloc(enum mparset,
@@ -360,6 +800,11 @@
void *mandoc_realloc(void *, size_t);
#define DELIMSZ 6 /* hint: max possible size of a delimiter */
enum mdelim mandoc_isdelim(const char *);
+
+const struct man_node *man_node(const struct man *);
+const struct man_meta *man_meta(const struct man *);
+const struct mdoc_node *mdoc_node(const struct mdoc *);
+const struct mdoc_meta *mdoc_meta(const struct mdoc *);
__END_DECLS
Index: mdoc.3
===================================================================
RCS file: mdoc.3
diff -N mdoc.3
--- mdoc.3 9 Feb 2011 09:18:15 -0000 1.57
+++ /dev/null 1 Jan 1970 00:00:00 -0000
@@ -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: mdoc.h
===================================================================
RCS file: mdoc.h
diff -N mdoc.h
--- mdoc.h 20 Mar 2011 16:02:05 -0000 1.119
+++ /dev/null 1 Jan 1970 00:00:00 -0000
@@ -1,440 +0,0 @@
-/* $Id: mdoc.h,v 1.119 2011/03/20 16:02:05 kristaps Exp $ */
-/*
- * Copyright (c) 2008, 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
- * 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.
- */
-#ifndef MDOC_H
-#define MDOC_H
-
-/*
- * What follows is a list of ALL possible macros.
- */
-enum mdoct {
- MDOC_Ap = 0,
- MDOC_Dd,
- MDOC_Dt,
- MDOC_Os,
- MDOC_Sh,
- MDOC_Ss,
- MDOC_Pp,
- MDOC_D1,
- MDOC_Dl,
- MDOC_Bd,
- MDOC_Ed,
- MDOC_Bl,
- MDOC_El,
- MDOC_It,
- MDOC_Ad,
- MDOC_An,
- MDOC_Ar,
- MDOC_Cd,
- MDOC_Cm,
- MDOC_Dv,
- MDOC_Er,
- MDOC_Ev,
- MDOC_Ex,
- MDOC_Fa,
- MDOC_Fd,
- MDOC_Fl,
- MDOC_Fn,
- MDOC_Ft,
- MDOC_Ic,
- MDOC_In,
- MDOC_Li,
- MDOC_Nd,
- MDOC_Nm,
- MDOC_Op,
- MDOC_Ot,
- MDOC_Pa,
- MDOC_Rv,
- MDOC_St,
- MDOC_Va,
- MDOC_Vt,
- MDOC_Xr,
- MDOC__A,
- MDOC__B,
- MDOC__D,
- MDOC__I,
- MDOC__J,
- MDOC__N,
- MDOC__O,
- MDOC__P,
- MDOC__R,
- MDOC__T,
- MDOC__V,
- MDOC_Ac,
- MDOC_Ao,
- MDOC_Aq,
- MDOC_At,
- MDOC_Bc,
- MDOC_Bf,
- MDOC_Bo,
- MDOC_Bq,
- MDOC_Bsx,
- MDOC_Bx,
- MDOC_Db,
- MDOC_Dc,
- MDOC_Do,
- MDOC_Dq,
- MDOC_Ec,
- MDOC_Ef,
- MDOC_Em,
- MDOC_Eo,
- MDOC_Fx,
- MDOC_Ms,
- MDOC_No,
- MDOC_Ns,
- MDOC_Nx,
- MDOC_Ox,
- MDOC_Pc,
- MDOC_Pf,
- MDOC_Po,
- MDOC_Pq,
- MDOC_Qc,
- MDOC_Ql,
- MDOC_Qo,
- MDOC_Qq,
- MDOC_Re,
- MDOC_Rs,
- MDOC_Sc,
- MDOC_So,
- MDOC_Sq,
- MDOC_Sm,
- MDOC_Sx,
- MDOC_Sy,
- MDOC_Tn,
- MDOC_Ux,
- MDOC_Xc,
- MDOC_Xo,
- MDOC_Fo,
- MDOC_Fc,
- MDOC_Oo,
- MDOC_Oc,
- MDOC_Bk,
- MDOC_Ek,
- MDOC_Bt,
- MDOC_Hf,
- MDOC_Fr,
- MDOC_Ud,
- MDOC_Lb,
- MDOC_Lp,
- MDOC_Lk,
- MDOC_Mt,
- MDOC_Brq,
- MDOC_Bro,
- MDOC_Brc,
- MDOC__C,
- MDOC_Es,
- MDOC_En,
- MDOC_Dx,
- MDOC__Q,
- MDOC_br,
- MDOC_sp,
- MDOC__U,
- MDOC_Ta,
- MDOC_MAX
-};
-
-/*
- * What follows is a list of ALL possible macro arguments.
- */
-enum mdocargt {
- MDOC_Split,
- MDOC_Nosplit,
- MDOC_Ragged,
- MDOC_Unfilled,
- MDOC_Literal,
- MDOC_File,
- MDOC_Offset,
- MDOC_Bullet,
- MDOC_Dash,
- MDOC_Hyphen,
- MDOC_Item,
- MDOC_Enum,
- MDOC_Tag,
- MDOC_Diag,
- MDOC_Hang,
- MDOC_Ohang,
- MDOC_Inset,
- MDOC_Column,
- MDOC_Width,
- MDOC_Compact,
- MDOC_Std,
- MDOC_Filled,
- MDOC_Words,
- MDOC_Emphasis,
- MDOC_Symbolic,
- MDOC_Nested,
- MDOC_Centred,
- MDOC_ARG_MAX
-};
-
-/*
- * Type of a syntax node.
- */
-enum mdoc_type {
- MDOC_TEXT,
- MDOC_ELEM,
- MDOC_HEAD,
- MDOC_TAIL,
- MDOC_BODY,
- MDOC_BLOCK,
- MDOC_TBL,
- MDOC_EQN,
- MDOC_ROOT
-};
-
-/*
- * Section (named/unnamed) of `Sh'. Note that these appear in the
- * conventional order imposed by mdoc.7.
- */
-enum mdoc_sec {
- SEC_NONE = 0, /* No section, yet. */
- SEC_NAME,
- SEC_LIBRARY,
- SEC_SYNOPSIS,
- SEC_DESCRIPTION,
- SEC_IMPLEMENTATION,
- SEC_RETURN_VALUES,
- SEC_ENVIRONMENT,
- SEC_FILES,
- SEC_EXIT_STATUS,
- SEC_EXAMPLES,
- SEC_DIAGNOSTICS,
- SEC_COMPATIBILITY,
- SEC_ERRORS,
- SEC_SEE_ALSO,
- SEC_STANDARDS,
- SEC_HISTORY,
- SEC_AUTHORS,
- SEC_CAVEATS,
- SEC_BUGS,
- SEC_SECURITY,
- SEC_CUSTOM, /* User-defined. */
- SEC__MAX
-};
-
-/*
- * Information from prologue.
- */
-struct mdoc_meta {
- char *msec; /* `Dt' section (1, 3p, etc.) */
- char *vol; /* `Dt' volume (implied) */
- char *arch; /* `Dt' arch (i386, etc.) */
- char *date; /* `Dd' normalised date */
- char *title; /* `Dt' title (FOO, etc.) */
- char *os; /* `Os' system (OpenBSD, etc.) */
- char *name; /* leading `Nm' name */
-};
-
-/*
- * An argument to a macro (multiple values = `-column xxx yyy').
- */
-struct mdoc_argv {
- enum mdocargt arg; /* type of argument */
- int line;
- int pos;
- size_t sz; /* elements in "value" */
- char **value; /* argument strings */
-};
-
-/*
- * Reference-counted macro arguments. These are refcounted because
- * blocks have multiple instances of the same arguments spread across
- * the HEAD, BODY, TAIL, and BLOCK node types.
- */
-struct mdoc_arg {
- size_t argc;
- struct mdoc_argv *argv;
- unsigned int refcnt;
-};
-
-/*
- * Indicates that a BODY's formatting has ended, but the scope is still
- * open. Used for syntax-broken blocks.
- */
-enum mdoc_endbody {
- ENDBODY_NOT = 0,
- ENDBODY_SPACE, /* is broken: append a space */
- ENDBODY_NOSPACE /* is broken: don't append a space */
-};
-
-/*
- * Normalised `Bl' list type.
- */
-enum mdoc_list {
- LIST__NONE = 0,
- LIST_bullet,
- LIST_column,
- LIST_dash,
- LIST_diag,
- LIST_enum,
- LIST_hang,
- LIST_hyphen,
- LIST_inset,
- LIST_item,
- LIST_ohang,
- LIST_tag,
- LIST_MAX
-};
-
-/*
- * Normalised `Bd' display type.
- */
-enum mdoc_disp {
- DISP__NONE = 0,
- DISP_centred,
- DISP_ragged,
- DISP_unfilled,
- DISP_filled,
- DISP_literal
-};
-
-/*
- * Normalised `An' splitting argument.
- */
-enum mdoc_auth {
- AUTH__NONE = 0,
- AUTH_split,
- AUTH_nosplit
-};
-
-/*
- * Normalised `Bf' font type.
- */
-enum mdoc_font {
- FONT__NONE = 0,
- FONT_Em,
- FONT_Li,
- FONT_Sy
-};
-
-/*
- * Normalised arguments for `Bd'.
- */
-struct mdoc_bd {
- const char *offs; /* -offset */
- enum mdoc_disp type; /* -ragged, etc. */
- int comp; /* -compact */
-};
-
-/*
- * Normalised arguments for `Bl'.
- */
-struct mdoc_bl {
- const char *width; /* -width */
- const char *offs; /* -offset */
- enum mdoc_list type; /* -tag, -enum, etc. */
- int comp; /* -compact */
- size_t ncols; /* -column arg count */
- const char **cols; /* -column val ptr */
-};
-
-/*
- * Normalised arguments for `Bf'.
- */
-struct mdoc_bf {
- enum mdoc_font font; /* font */
-};
-
-/*
- * Normalised arguments for `An'.
- */
-struct mdoc_an {
- enum mdoc_auth auth; /* -split, etc. */
-};
-
-struct mdoc_rs {
- int quote_T; /* whether to quote %T */
-};
-
-/*
- * Consists of normalised node arguments. These should be used instead
- * of iterating through the mdoc_arg pointers of a node: defaults are
- * provided, etc.
- */
-union mdoc_data {
- struct mdoc_an An;
- struct mdoc_bd Bd;
- struct mdoc_bf Bf;
- struct mdoc_bl Bl;
- struct mdoc_rs Rs;
-};
-
-/*
- * Single node in tree-linked AST.
- */
-struct mdoc_node {
- struct mdoc_node *parent; /* parent AST node */
- struct mdoc_node *child; /* first child AST node */
- struct mdoc_node *last; /* last child AST node */
- struct mdoc_node *next; /* sibling AST node */
- struct mdoc_node *prev; /* prior sibling AST node */
- int nchild; /* number children */
- int line; /* parse line */
- int pos; /* parse column */
- enum mdoct tok; /* tok or MDOC__MAX if none */
- int flags;
-#define MDOC_VALID (1 << 0) /* has been validated */
-#define MDOC_EOS (1 << 2) /* at sentence boundary */
-#define MDOC_LINE (1 << 3) /* first macro/text on line */
-#define MDOC_SYNPRETTY (1 << 4) /* SYNOPSIS-style formatting */
-#define MDOC_ENDED (1 << 5) /* rendering has been ended */
- enum mdoc_type type; /* AST node type */
- enum mdoc_sec sec; /* current named section */
- union mdoc_data *norm; /* normalised args */
- /* FIXME: these can be union'd to shave a few bytes. */
- struct mdoc_arg *args; /* BLOCK/ELEM */
- struct mdoc_node *pending; /* BLOCK */
- struct mdoc_node *head; /* BLOCK */
- struct mdoc_node *body; /* BLOCK */
- struct mdoc_node *tail; /* BLOCK */
- char *string; /* TEXT */
- const struct tbl_span *span; /* TBL */
- const struct eqn *eqn; /* EQN */
- enum mdoc_endbody end; /* BODY */
-};
-
-/*
- * Names of macros. Index is enum mdoct. Indexing into this returns
- * the normalised name, e.g., mdoc_macronames[MDOC_Sh] -> "Sh".
- */
-extern const char *const *mdoc_macronames;
-
-/*
- * Names of macro args. Index is enum mdocargt. Indexing into this
- * returns the normalised name, e.g., mdoc_argnames[MDOC_File] ->
- * "file".
- */
-extern const char *const *mdoc_argnames;
-
-__BEGIN_DECLS
-
-struct mdoc;
-
-void mdoc_free(struct mdoc *);
-struct mdoc *mdoc_alloc(struct regset *, struct mparse *);
-void mdoc_reset(struct mdoc *);
-int mdoc_parseln(struct mdoc *, int, char *, int);
-const struct mdoc_node *mdoc_node(const struct mdoc *);
-const struct mdoc_meta *mdoc_meta(const struct mdoc *);
-int mdoc_endparse(struct mdoc *);
-int mdoc_addspan(struct mdoc *,
- const struct tbl_span *);
-int mdoc_addeqn(struct mdoc *,
- const struct eqn *);
-
-__END_DECLS
-
-#endif /*!MDOC_H*/
Index: mdoc_html.c
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mdoc_html.c,v
retrieving revision 1.154
diff -u -r1.154 mdoc_html.c
--- mdoc_html.c 7 Mar 2011 01:35:51 -0000 1.154
+++ mdoc_html.c 21 Mar 2011 17:23:14 -0000
@@ -30,7 +30,6 @@
#include "mandoc.h"
#include "out.h"
#include "html.h"
-#include "mdoc.h"
#include "main.h"
#define INDENT 5
Index: mdoc_term.c
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mdoc_term.c,v
retrieving revision 1.220
diff -u -r1.220 mdoc_term.c
--- mdoc_term.c 7 Mar 2011 01:35:51 -0000 1.220
+++ mdoc_term.c 21 Mar 2011 17:23:14 -0000
@@ -31,7 +31,6 @@
#include "mandoc.h"
#include "out.h"
#include "term.h"
-#include "mdoc.h"
#include "chars.h"
#include "main.h"
Index: read.c
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/read.c,v
retrieving revision 1.4
diff -u -r1.4 read.c
--- read.c 20 Mar 2011 16:05:21 -0000 1.4
+++ read.c 21 Mar 2011 17:23:14 -0000
@@ -29,9 +29,6 @@
#include "mandoc.h"
#include "libmandoc.h"
-#include "mdoc.h"
-#include "man.h"
-#include "roff.h"
#ifndef MAP_FILE
#define MAP_FILE 0
Index: roff.3
===================================================================
RCS file: roff.3
diff -N roff.3
--- roff.3 1 Jan 2011 16:18:39 -0000 1.10
+++ /dev/null 1 Jan 1970 00:00:00 -0000
@@ -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
Index: roff.c
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/roff.c,v
retrieving revision 1.128
diff -u -r1.128 roff.c
--- roff.c 20 Mar 2011 16:02:05 -0000 1.128
+++ roff.c 21 Mar 2011 17:23:14 -0000
@@ -28,7 +28,6 @@
#include
#include "mandoc.h"
-#include "roff.h"
#include "libroff.h"
#include "libmandoc.h"
Index: roff.h
===================================================================
RCS file: roff.h
diff -N roff.h
--- roff.h 20 Mar 2011 16:02:05 -0000 1.25
+++ /dev/null 1 Jan 1970 00:00:00 -0000
@@ -1,47 +0,0 @@
-/* $Id: roff.h,v 1.25 2011/03/20 16:02:05 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.
- */
-#ifndef ROFF_H
-#define ROFF_H
-
-enum rofferr {
- ROFF_CONT, /* continue processing line */
- ROFF_RERUN, /* re-run roff interpreter with offset */
- ROFF_APPEND, /* re-run main parser, appending next line */
- ROFF_REPARSE, /* re-run main parser on the result */
- ROFF_SO, /* include another file */
- ROFF_IGN, /* ignore current line */
- ROFF_TBL, /* a table row was successfully parsed */
- ROFF_EQN, /* an equation was successfully parsed */
- ROFF_ERR /* badness: puke and stop */
-};
-
-__BEGIN_DECLS
-
-struct roff;
-
-void roff_free(struct roff *);
-struct roff *roff_alloc(struct regset *, struct mparse *);
-void roff_reset(struct roff *);
-enum rofferr roff_parseln(struct roff *, int,
- char **, size_t *, int, int *);
-void roff_endparse(struct roff *);
-const struct tbl_span *roff_span(const struct roff *);
-const struct eqn *roff_eqn(const struct roff *);
-
-__END_DECLS
-
-#endif /*!ROFF_H*/
Index: tbl.c
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/tbl.c,v
retrieving revision 1.23
diff -u -r1.23 tbl.c
--- tbl.c 20 Mar 2011 16:02:05 -0000 1.23
+++ tbl.c 21 Mar 2011 17:23:14 -0000
@@ -22,7 +22,6 @@
#include
#include "mandoc.h"
-#include "roff.h"
#include "libmandoc.h"
#include "libroff.h"
Index: tree.c
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/tree.c,v
retrieving revision 1.36
diff -u -r1.36 tree.c
--- tree.c 9 Feb 2011 09:18:15 -0000 1.36
+++ tree.c 21 Mar 2011 17:23:14 -0000
@@ -24,8 +24,6 @@
#include
#include "mandoc.h"
-#include "mdoc.h"
-#include "man.h"
#include "main.h"
static void print_mdoc(const struct mdoc_node *, int);