roff.3

   1 .\"     $Id: roff.3,v 1.7 2010/07/13 23:53:20 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: July 13 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 "mandocmsg msgs"
  35 .Fa "void *data"
  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 The
 115 .Fa pflags
 116 arguments are defined in
 117 .Pa roff.h .
 118 Returns NULL on failure.
 119 If non-NULL, the pointer must be freed with
 120 .Fn roff_free .
 121 .It Fn roff_reset
 122 Reset the parser for another parse routine.
 123 After its use,
 124 .Fn roff_parseln
 125 behaves as if invoked for the first time.
 126 .It Fn roff_free
 127 Free all resources of a parser.
 128 The pointer is no longer valid after invocation.
 129 .It Fn roff_parseln
 130 Parse a nil-terminated line of input.
 131 The character array
 132 .Fa bufp
 133 may be modified or reallocated within this function.
 134 In the latter case,
 135 .Fa bufsz
 136 will be modified accordingly.
 137 The
 138 .Fa offs
 139 pointer will be modified if the line start during subsequent processing
 140 of the line is not at the zeroth index.
 141 This line should not contain the trailing newline.
 142 Returns 0 on failure, 1 on success.
 143 .It Fn roff_endparse
 144 Signals that the parse is complete.
 145 Returns 0 on failure, 1 on success.
 146 .El
 147 .Sh EXAMPLES
 148 See
 149 .Pa main.c
 150 in the source distribution for an example of usage.
 151 .Sh SEE ALSO
 152 .Xr mandoc 1 ,
 153 .Xr man 3 ,
 154 .Xr mdoc 3 ,
 155 .Xr roff 7
 156 .Sh AUTHORS
 157 The
 158 .Nm
 159 library was written by
 160 .An Kristaps Dzonsons Aq kristaps@bsd.lv .
 161 .Sh BUGS
 162 The implementation of user-defined strings needs improvement:
 163 .Bl -dash
 164 .It
 165 String values are taken literally and are not interpreted.
 166 .It
 167 Parsing of quoted strings is incomplete.
 168 .It
 169 The stings are stored internally using a singly linked list,
 170 which is fine for small numbers of strings,
 171 but ineffient when handling many strings.
 172 .El