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 o4PMGxcF014528 for ; Tue, 25 May 2010 16:16:59 -0600 (MDT) Received: (from kristaps@localhost) by krisdoz.my.domain (8.14.3/8.14.3/Submit) id o4PMGxPg005763; Tue, 25 May 2010 18:16:59 -0400 (EDT) Date: Tue, 25 May 2010 18:16:59 -0400 (EDT) Message-Id: <201005252216.o4PMGxPg005763@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: Added roff.3, which documents the roff parser interface. X-Mailer: activitymail 1.26, http://search.cpan.org/dist/activitymail/ Content-Type: text/plain; charset=utf-8 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 +.\" +.\" 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