ROFF(3)

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

SYNOPSIS
#include <mandoc.h>
#include <roff.h>
struct roff *
roff_alloc(struct regset *regs, void *data, mandocmsg msgs);
void
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);
const struct tbl_span *
roff_span(const 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. 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.

roff_span()
If roff_parseln() returned ROFF_TBL, return the last parsed table row. Returns NULL otherwise.

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.