mdocml: Added roff.3, which documents the roff parser interface.

mdocml: Added roff.3, which documents the roff parser interface.

[kristaps]

Log Message:
-----------
Added roff.3, which documents the roff parser interface.

Small fix in mdoc.3 and man.3 pointing to old mdoc_cb and man_cb.

Fix in Makefile adding mandoc.h to HEADS.

Collapsed all HTML files into HTMLS variable (too confusing otherwise).

Removed "htmls" command from Makefile (only I used it and it's just
taking up space).

Modified Files:
--------------
    mdocml:
        man.3
        mdoc.3
        Makefile

Added Files:
-----------
    mdocml:
        roff.3

Revision Data
-------------
--- /dev/null
+++ roff.3
@@ -0,0 +1,156 @@
+.\"	$Id: roff.3,v 1.1 2010/05/25 22:16:59 kristaps Exp $
+.\"
+.\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
+.\"
+.\" 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: May 25 2010 $
+.Dt ROFF 3
+.Os
+.Sh NAME
+.Nm roff ,
+.Nm roff_alloc ,
+.Nm roff_endparse ,
+.Nm roff_free ,
+.Nm roff_parseln ,
+.Nm roff_reset
+.Nd roff macro compiler library
+.Sh SYNOPSIS
+.In mandoc.h
+.In roff.h
+.Ft "struct roff *"
+.Fn roff_alloc "mandocmsg msgs" "void *data"
+.Ft int
+.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"
+.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 .
+The
+.Fa pflags
+arguments are defined in
+.Pa roff.h .
+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.
+Returns 0 on failure, 1 on success.
+.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 .
Index: mdoc.3
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mdoc.3,v
retrieving revision 1.39
retrieving revision 1.40
diff -Lmdoc.3 -Lmdoc.3 -u -p -r1.39 -r1.40
--- mdoc.3
+++ mdoc.3
@@ -112,9 +112,8 @@ Function descriptions follow:
 Allocates a parsing structure.
 The
 .Fa data
-pointer is passed to callbacks in
-.Fa cb ,
-which are documented further in the header file.
+pointer is passed to
+.Fa msgs .
 The
 .Fa pflags
 arguments are defined in
Index: Makefile
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/Makefile,v
retrieving revision 1.271
retrieving revision 1.272
diff -LMakefile -LMakefile -u -p -r1.271 -r1.272
--- Makefile
+++ Makefile
@@ -93,22 +93,25 @@ DATAS	   = arch.in att.in lib.in msec.in
 	     vol.in chars.in
 
 HEADS	   = mdoc.h libmdoc.h man.h libman.h term.h \
-	     libmandoc.h html.h chars.h out.h main.h roff.h
+	     libmandoc.h html.h chars.h out.h main.h roff.h \
+	     mandoc.h
 
 GSGMLS	   = mandoc.1.sgml mdoc.3.sgml mdoc.7.sgml manuals.7.sgml \
-	     mandoc_char.7.sgml man.7.sgml man.3.sgml roff.7.sgml
+	     mandoc_char.7.sgml man.7.sgml man.3.sgml roff.7.sgml \
+	     roff.3.sgml
 
 SGMLS	   = index.sgml
 
-HTMLS	   = ChangeLog.html index.html man.h.html mdoc.h.html
+HTMLS	   = ChangeLog.html index.html man.h.html mdoc.h.html \
+	     mandoc.h.html roff.h.html mandoc.1.html mdoc.3.html \
+	     man.3.html mdoc.7.html man.7.html mandoc_char.7.html \
+	     manuals.7.html roff.7.html roff.3.html
 
 XSLS	   = ChangeLog.xsl
 
-GHTMLS	   = mandoc.1.html mdoc.3.html man.3.html mdoc.7.html \
-	     man.7.html mandoc_char.7.html manuals.7.html roff.7.html
-
 TEXTS	   = mandoc.1.txt mdoc.3.txt man.3.txt mdoc.7.txt man.7.txt \
-	     mandoc_char.7.txt manuals.7.txt ChangeLog.txt roff.7.txt
+	     mandoc_char.7.txt manuals.7.txt ChangeLog.txt \
+	     roff.7.txt roff.3.txt
 
 EXAMPLES   = example.style.css
 
@@ -121,7 +124,7 @@ MD5S	   = mdocml-$(VERSION).md5 
 TARGZS	   = mdocml-$(VERSION).tar.gz
 
 MANS	   = mandoc.1 mdoc.3 mdoc.7 manuals.7 mandoc_char.7 man.7 \
-	     man.3 roff.7
+	     man.3 roff.7 roff.3
 
 BINS	   = mandoc
 
@@ -131,7 +134,7 @@ CONFIGS	   = config.h.pre config.h.post
 
 DOCLEAN	   = $(BINS) $(LNS) $(LLNS) $(LIBS) $(OBJS) $(HTMLS) \
 	     $(TARGZS) tags $(MD5S) $(XMLS) $(TEXTS) $(GSGMLS) \
-	     $(GHTMLS) config.h config.log
+	     config.h config.log
 
 DOINSTALL  = $(SRCS) $(HEADS) Makefile $(MANS) $(SGMLS) $(STATICS) \
 	     $(DATAS) $(XSLS) $(EXAMPLES) $(TESTS) $(CONFIGS)
@@ -147,16 +150,14 @@ cleanlint:
 	rm -f $(LNS) $(LLNS)
 
 cleanhtml:
-	rm -f $(HTMLS) $(GSGMLS) $(GHTMLS)
+	rm -f $(HTMLS) $(GSGMLS)
 
 dist:	mdocml-$(VERSION).tar.gz
 
-www:	all $(GSGMLS) $(GHTMLS) $(HTMLS) $(TEXTS) $(MD5S) $(TARGZS)
-
-htmls:	all $(GSGMLS) $(GHTMLS)
+www:	all $(GSGMLS) $(HTMLS) $(TEXTS) $(MD5S) $(TARGZS)
 
 installwww: www
-	$(INSTALL_DATA) $(GHTMLS) $(HTMLS) $(TEXTS) $(STATICS) $(DESTDIR)$(PREFIX)/
+	$(INSTALL_DATA) $(HTMLS) $(TEXTS) $(STATICS) $(DESTDIR)$(PREFIX)/
 	$(INSTALL_DATA) mdocml-$(VERSION).tar.gz $(DESTDIR)$(PREFIX)/snapshots/
 	$(INSTALL_DATA) mdocml-$(VERSION).md5 $(DESTDIR)$(PREFIX)/snapshots/
 	$(INSTALL_DATA) mdocml-$(VERSION).tar.gz $(DESTDIR)$(PREFIX)/snapshots/mdocml.tar.gz
Index: man.3
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/man.3,v
retrieving revision 1.17
retrieving revision 1.18
diff -Lman.3 -Lman.3 -u -p -r1.17 -r1.18
--- man.3
+++ man.3
@@ -162,9 +162,8 @@ Function descriptions follow:
 Allocates a parsing structure.
 The
 .Fa data
-pointer is passed to callbacks in
-.Fa cb ,
-which are documented further in the header file.
+pointer is passed to
+.Fa msgs .
 The
 .Fa pflags
 arguments are defined in
--
 To unsubscribe send an email to source+unsubscribe@mdocml.bsd.lv