ROFF(3)			   Library Functions Manual		       ROFF(3)

NAME
     roff, roff_alloc, roff_endparse, roff_free, roff_parseln, roff_reset -
     roff macro compiler library

SYNOPSIS
     #include <mandoc.h>
     #include <roff.h>

     struct roff *
     roff_alloc(struct regset *regs, mandocmsg msgs, void *data);

     int
     roff_endparse(struct roff *roff);

     void
     roff_free(struct roff *roff);

     enum rofferr
     roff_parseln(struct roff *roff, int line, char **bufp, size_t *bufsz, int
     pos, int *offs);

     void
     roff_reset(struct roff *roff);

DESCRIPTION
     The roff library processes lines of roff(7) input.

     In general, applications initiate a parsing sequence with roff_alloc(),
     parse each line in a document with roff_parseln(), close the parsing
     session with roff_endparse(), and finally free all allocated memory with
     roff_free().  The roff_reset() function may be used in order to reset the
     parser for another input sequence.

     The roff_parseln() function should be invoked before passing a line into
     the mdoc(3) or man(3) libraries.

     See the EXAMPLES section for a full example.

REFERENCE
     This section further defines the Types and Functions available to
     programmers.

   Types
     Functions (see Functions) may use the following types:

     enum rofferr
     Instructions for further processing to the caller of roff_parseln().

     struct roff
     An opaque type defined in roff.c.	Its values are only used privately
     within the library.

     mandocmsg
     A function callback type defined in mandoc.h.

   Functions
     Function descriptions follow:

     roff_alloc()
     Allocates a parsing structure.  The data pointer is passed to msgs.  The
     pflags arguments are defined in roff.h.  Returns NULL on failure.	If
     non-NULL, the pointer must be freed with roff_free().

     roff_reset()
     Reset the parser for another parse routine.  After its use,
     roff_parseln() behaves as if invoked for the first time.

     roff_free()
     Free all resources of a parser.  The pointer is no longer valid after
     invocation.

     roff_parseln()
     Parse a nil-terminated line of input.  The character array bufp may be
     modified or reallocated within this function.  In the latter case, bufsz
     will be modified accordingly.  The 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.

     roff_endparse()
     Signals that the parse is complete.  Returns 0 on failure, 1 on success.

EXAMPLES
     See main.c in the source distribution for an example of usage.

SEE ALSO
     mandoc(1), man(3), mdoc(3), roff(7)

AUTHORS
     The roff library was written by Kristaps Dzonsons <kristaps@bsd.lv>.

BUGS
     The implementation of user-defined strings needs improvement:

     -	 String values are taken literally and are not interpreted.

     -	 Parsing of quoted strings is incomplete.

     -	 The stings are stored internally using a singly linked list, which is
	 fine for small numbers of strings, but ineffient when handling many
	 strings.

OpenBSD 4.6			 July 13, 2010			   OpenBSD 4.6