roff.3

   1 .\"     $Id: roff.3,v 1.8 2010/08/20 01:02:07 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .Dd $Mdocdate: August 20 2010 $
  18 .Dt ROFF 3
  19 .Os
  20 .Sh NAME
  21 .Nm roff ,
  22 .Nm roff_alloc ,
  23 .Nm roff_endparse ,
  24 .Nm roff_free ,
  25 .Nm roff_parseln ,
  26 .Nm roff_reset
  27 .Nd roff macro compiler library
  28 .Sh SYNOPSIS
  29 .In mandoc.h
  30 .In roff.h
  31 .Ft "struct roff *"
  32 .Fo roff_alloc
  33 .Fa "struct regset *regs"
  34 .Fa "void *data"
  35 .Fa "mandocmsg msgs"
  36 .Fc
  37 .Ft int
  38 .Fn roff_endparse "struct roff *roff"
  39 .Ft void
  40 .Fn roff_free "struct roff *roff"
  41 .Ft "enum rofferr"
  42 .Fo roff_parseln
  43 .Fa "struct roff *roff"
  44 .Fa "int line"
  45 .Fa "char **bufp"
  46 .Fa "size_t *bufsz"
  47 .Fa "int pos"
  48 .Fa "int *offs"
  49 .Fc
  50 .Ft void
  51 .Fn roff_reset "struct roff *roff"
  52 .Sh DESCRIPTION
  53 The
  54 .Nm
  55 library processes lines of
  56 .Xr roff 7
  57 input.
  58 .Pp
  59 In general, applications initiate a parsing sequence with
  60 .Fn roff_alloc ,
  61 parse each line in a document with
  62 .Fn roff_parseln ,
  63 close the parsing session with
  64 .Fn roff_endparse ,
  65 and finally free all allocated memory with
  66 .Fn roff_free .
  67 The
  68 .Fn roff_reset
  69 function may be used in order to reset the parser for another input
  70 sequence.
  71 .Pp
  72 The
  73 .Fn roff_parseln
  74 function should be invoked before passing a line into the
  75 .Xr mdoc 3
  76 or
  77 .Xr man 3
  78 libraries.
  79 .Pp
  80 See the
  81 .Sx EXAMPLES
  82 section for a full example.
  83 .Sh REFERENCE
  84 This section further defines the
  85 .Sx Types
  86 and
  87 .Sx Functions
  88 available to programmers.
  89 .Ss Types
  90 Functions (see
  91 .Sx Functions )
  92 may use the following types:
  93 .Bl -ohang
  94 .It Vt "enum rofferr"
  95 Instructions for further processing to the caller of
  96 .Fn roff_parseln .
  97 .It Vt struct roff
  98 An opaque type defined in
  99 .Pa roff.c .
 100 Its values are only used privately within the library.
 101 .It Vt mandocmsg
 102 A function callback type defined in
 103 .Pa mandoc.h .
 104 .El
 105 .Ss Functions
 106 Function descriptions follow:
 107 .Bl -ohang
 108 .It Fn roff_alloc
 109 Allocates a parsing structure.
 110 The
 111 .Fa data
 112 pointer is passed to
 113 .Fa msgs .
 114 Returns NULL on failure.
 115 If non-NULL, the pointer must be freed with
 116 .Fn roff_free .
 117 .It Fn roff_reset
 118 Reset the parser for another parse routine.
 119 After its use,
 120 .Fn roff_parseln
 121 behaves as if invoked for the first time.
 122 .It Fn roff_free
 123 Free all resources of a parser.
 124 The pointer is no longer valid after invocation.
 125 .It Fn roff_parseln
 126 Parse a nil-terminated line of input.
 127 The character array
 128 .Fa bufp
 129 may be modified or reallocated within this function.
 130 In the latter case,
 131 .Fa bufsz
 132 will be modified accordingly.
 133 The
 134 .Fa offs
 135 pointer will be modified if the line start during subsequent processing
 136 of the line is not at the zeroth index.
 137 This line should not contain the trailing newline.
 138 Returns 0 on failure, 1 on success.
 139 .It Fn roff_endparse
 140 Signals that the parse is complete.
 141 Returns 0 on failure, 1 on success.
 142 .El
 143 .Sh EXAMPLES
 144 See
 145 .Pa main.c
 146 in the source distribution for an example of usage.
 147 .Sh SEE ALSO
 148 .Xr mandoc 1 ,
 149 .Xr man 3 ,
 150 .Xr mdoc 3 ,
 151 .Xr roff 7
 152 .Sh AUTHORS
 153 The
 154 .Nm
 155 library was written by
 156 .An Kristaps Dzonsons Aq kristaps@bsd.lv .
 157 .Sh BUGS
 158 The implementation of user-defined strings needs improvement:
 159 .Bl -dash
 160 .It
 161 String values are taken literally and are not interpreted.
 162 .It
 163 Parsing of quoted strings is incomplete.
 164 .It
 165 The stings are stored internally using a singly linked list,
 166 which is fine for small numbers of strings,
 167 but ineffient when handling many strings.
 168 .El