external/bsd/mdocml/dist/roff.3

   1 .\"     $Vendor-Id: roff.3,v 1.10 2011/01/01 16:18:39 kristaps 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 January 1, 2011
  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 .Nm roff_span
  28 .Nd roff macro compiler library
  29 .Sh SYNOPSIS
  30 .In mandoc.h
  31 .In roff.h
  32 .Ft "struct roff *"
  33 .Fo roff_alloc
  34 .Fa "struct regset *regs"
  35 .Fa "void *data"
  36 .Fa "mandocmsg msgs"
  37 .Fc
  38 .Ft void
  39 .Fn roff_endparse "struct roff *roff"
  40 .Ft void
  41 .Fn roff_free "struct roff *roff"
  42 .Ft "enum rofferr"
  43 .Fo roff_parseln
  44 .Fa "struct roff *roff"
  45 .Fa "int line"
  46 .Fa "char **bufp"
  47 .Fa "size_t *bufsz"
  48 .Fa "int pos"
  49 .Fa "int *offs"
  50 .Fc
  51 .Ft void
  52 .Fn roff_reset "struct roff *roff"
  53 .Ft "const struct tbl_span *"
  54 .Fn roff_span "const struct roff *roff"
  55 .Sh DESCRIPTION
  56 The
  57 .Nm
  58 library processes lines of
  59 .Xr roff 7
  60 input.
  61 .Pp
  62 In general, applications initiate a parsing sequence with
  63 .Fn roff_alloc ,
  64 parse each line in a document with
  65 .Fn roff_parseln ,
  66 close the parsing session with
  67 .Fn roff_endparse ,
  68 and finally free all allocated memory with
  69 .Fn roff_free .
  70 The
  71 .Fn roff_reset
  72 function may be used in order to reset the parser for another input
  73 sequence.
  74 .Pp
  75 The
  76 .Fn roff_parseln
  77 function should be invoked before passing a line into the
  78 .Xr mdoc 3
  79 or
  80 .Xr man 3
  81 libraries.
  82 .Pp
  83 See the
  84 .Sx EXAMPLES
  85 section for a full example.
  86 .Sh REFERENCE
  87 This section further defines the
  88 .Sx Types
  89 and
  90 .Sx Functions
  91 available to programmers.
  92 .Ss Types
  93 Functions (see
  94 .Sx Functions )
  95 may use the following types:
  96 .Bl -ohang
  97 .It Vt "enum rofferr"
  98 Instructions for further processing to the caller of
  99 .Fn roff_parseln .
 100 .It Vt struct roff
 101 An opaque type defined in
 102 .Pa roff.c .
 103 Its values are only used privately within the library.
 104 .It Vt mandocmsg
 105 A function callback type defined in
 106 .Pa mandoc.h .
 107 .El
 108 .Ss Functions
 109 Function descriptions follow:
 110 .Bl -ohang
 111 .It Fn roff_alloc
 112 Allocates a parsing structure.
 113 The
 114 .Fa data
 115 pointer is passed to
 116 .Fa msgs .
 117 Returns NULL on failure.
 118 If non-NULL, the pointer must be freed with
 119 .Fn roff_free .
 120 .It Fn roff_reset
 121 Reset the parser for another parse routine.
 122 After its use,
 123 .Fn roff_parseln
 124 behaves as if invoked for the first time.
 125 .It Fn roff_free
 126 Free all resources of a parser.
 127 The pointer is no longer valid after invocation.
 128 .It Fn roff_parseln
 129 Parse a nil-terminated line of input.
 130 The character array
 131 .Fa bufp
 132 may be modified or reallocated within this function.
 133 In the latter case,
 134 .Fa bufsz
 135 will be modified accordingly.
 136 The
 137 .Fa offs
 138 pointer will be modified if the line start during subsequent processing
 139 of the line is not at the zeroth index.
 140 This line should not contain the trailing newline.
 141 Returns 0 on failure, 1 on success.
 142 .It Fn roff_endparse
 143 Signals that the parse is complete.
 144 .It Fn roff_span
 145 If
 146 .Fn roff_parseln
 147 returned
 148 .Va ROFF_TBL ,
 149 return the last parsed table row.
 150 Returns NULL otherwise.
 151 .El
 152 .Sh EXAMPLES
 153 See
 154 .Pa main.c
 155 in the source distribution for an example of usage.
 156 .Sh SEE ALSO
 157 .Xr mandoc 1 ,
 158 .Xr man 3 ,
 159 .Xr mdoc 3 ,
 160 .Xr roff 7
 161 .Sh AUTHORS
 162 The
 163 .Nm
 164 library was written by
 165 .An Kristaps Dzonsons Aq kristaps@bsd.lv .
 166 .Sh BUGS
 167 The implementation of user-defined strings needs improvement:
 168 .Bl -dash
 169 .It
 170 String values are taken literally and are not interpreted.
 171 .It
 172 Parsing of quoted strings is incomplete.
 173 .It
 174 The stings are stored internally using a singly linked list,
 175 which is fine for small numbers of strings,
 176 but ineffient when handling many strings.
 177 .El