roff.3

   1 .\"     $Id: roff.3,v 1.5 2010/07/04 22:04:04 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
   4 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .Dd $Mdocdate: July 4 2010 $
  19 .Dt ROFF 3
  20 .Os
  21 .Sh NAME
  22 .Nm roff ,
  23 .Nm roff_alloc ,
  24 .Nm roff_endparse ,
  25 .Nm roff_free ,
  26 .Nm roff_parseln ,
  27 .Nm roff_reset
  28 .Nd roff macro compiler library
  29 .Sh SYNOPSIS
  30 .In mandoc.h
  31 .In regs.h
  32 .In roff.h
  33 .Ft "struct roff *"
  34 .Fo roff_alloc
  35 .Fa "struct regset *regs"
  36 .Fa "mandocmsg msgs"
  37 .Fa "void *data"
  38 .Fc
  39 .Ft int
  40 .Fn roff_endparse "struct roff *roff"
  41 .Ft void
  42 .Fn roff_free "struct roff *roff"
  43 .Ft "enum rofferr"
  44 .Fo roff_parseln
  45 .Fa "struct roff *roff"
  46 .Fa "int line"
  47 .Fa "char **bufp"
  48 .Fa "size_t *bufsz"
  49 .Fa "int pos"
  50 .Fa "int *offs"
  51 .Fc
  52 .Ft void
  53 .Fn roff_reset "struct roff *roff"
  54 .In regs.h
  55 .Ft "char *"
  56 .Fn roff_setstr "const char *name" "const char *string"
  57 .Ft "char *"
  58 .Fn roff_getstr "const char *name"
  59 .Ft "char *"
  60 .Fn roff_getstrn "const char *name" "size_t len"
  61 .Ft void
  62 .Fn roff_freestr void
  63 .Sh DESCRIPTION
  64 The
  65 .Nm
  66 library processes lines of
  67 .Xr roff 7
  68 input.
  69 .Pp
  70 In general, applications initiate a parsing sequence with
  71 .Fn roff_alloc ,
  72 parse each line in a document with
  73 .Fn roff_parseln ,
  74 close the parsing session with
  75 .Fn roff_endparse ,
  76 and finally free all allocated memory with
  77 .Fn roff_free .
  78 The
  79 .Fn roff_reset
  80 function may be used in order to reset the parser for another input
  81 sequence.
  82 .Pp
  83 The
  84 .Fn roff_parseln
  85 function should be invoked before passing a line into the
  86 .Xr mdoc 3
  87 or
  88 .Xr man 3
  89 libraries.
  90 .Pp
  91 See the
  92 .Sx EXAMPLES
  93 section for a full example.
  94 .Sh REFERENCE
  95 This section further defines the
  96 .Sx Types
  97 and
  98 .Sx Functions
  99 available to programmers.
 100 .Ss Types
 101 Functions (see
 102 .Sx Functions )
 103 may use the following types:
 104 .Bl -ohang
 105 .It Vt "enum rofferr"
 106 Instructions for further processing to the caller of
 107 .Fn roff_parseln .
 108 .It Vt struct roff
 109 An opaque type defined in
 110 .Pa roff.c .
 111 Its values are only used privately within the library.
 112 .It Vt mandocmsg
 113 A function callback type defined in
 114 .Pa mandoc.h .
 115 .El
 116 .Ss Functions
 117 Function descriptions follow:
 118 .Bl -ohang
 119 .It Fn roff_alloc
 120 Allocates a parsing structure.
 121 The
 122 .Fa data
 123 pointer is passed to
 124 .Fa msgs .
 125 The
 126 .Fa pflags
 127 arguments are defined in
 128 .Pa roff.h .
 129 Returns NULL on failure.
 130 If non-NULL, the pointer must be freed with
 131 .Fn roff_free .
 132 .It Fn roff_reset
 133 Reset the parser for another parse routine.
 134 After its use,
 135 .Fn roff_parseln
 136 behaves as if invoked for the first time.
 137 .It Fn roff_free
 138 Free all resources of a parser.
 139 The pointer is no longer valid after invocation.
 140 .It Fn roff_parseln
 141 Parse a nil-terminated line of input.
 142 The character array
 143 .Fa bufp
 144 may be modified or reallocated within this function.
 145 In the latter case,
 146 .Fa bufsz
 147 will be modified accordingly.
 148 The
 149 .Fa offs
 150 pointer will be modified if the line start during subsequent processing
 151 of the line is not at the zeroth index.
 152 This line should not contain the trailing newline.
 153 Returns 0 on failure, 1 on success.
 154 .It Fn roff_endparse
 155 Signals that the parse is complete.
 156 Returns 0 on failure, 1 on success.
 157 .El
 158 .Sh USER-DEFINED STRINGS
 159 Strings defined by the
 160 .Xr roff 7
 161 .Sx \&ds
 162 instruction are saved using the
 163 .Fn roff_setstr
 164 function and retrieved using the
 165 .Fn roff_getstr
 166 and
 167 .Fn roff_getstrn
 168 functions.
 169 .Pp
 170 These functions take the name of the string to be accessed
 171 as their first argument.
 172 While
 173 .Fn roff_getstr
 174 requires the name to be null-terminated,
 175 .Fn roff_getstrn
 176 accepts non-terminated strings, but requires the length of the name
 177 to be specified.
 178 .Pp
 179 The second argument to
 180 .Fn roff_setstr
 181 is the new value of the string.
 182 It will be copied to internal storage, so both pointers to constant
 183 strings and pointers to volatile storage are acceptable.
 184 .Pp
 185 All of these functions return a pointer to the new value of the string
 186 in internal storage, which should be considered read-only, so use
 187 .Xr strdup 3
 188 on it as appropriate.
 189 The read functions return NULL when a string of the specified name
 190 is not available or empty, and
 191 .Fn roff_setstr
 192 returns NULL when memory allocation fails.
 193 In the latter case, the string will remain unset.
 194 .Pp
 195 The function
 196 .Fn roff_freestr
 197 clears all user-defined strings.
 198 It always succeeds.
 199 Both
 200 .Fn roff_reset
 201 and
 202 .Fn roff_free
 203 call it.
 204 .Sh EXAMPLES
 205 See
 206 .Pa main.c
 207 in the source distribution for an example of usage.
 208 .Sh SEE ALSO
 209 .Xr mandoc 1 ,
 210 .Xr man 3 ,
 211 .Xr mdoc 3 ,
 212 .Xr roff 7
 213 .Sh AUTHORS
 214 The
 215 .Nm
 216 library was written by
 217 .An Kristaps Dzonsons Aq kristaps@bsd.lv .
 218 .Sh BUGS
 219 The implementation of user-defined strings needs improvement:
 220 .Bl -dash
 221 .It
 222 String values are taken literally and are not interpreted.
 223 .It
 224 Parsing of quoted strings is incomplete.
 225 .It
 226 The stings are stored internally using a singly linked list,
 227 which is fine for small numbers of strings,
 228 but ineffient when handling many strings.
 229 .El