roff.3

   1 .\"     $Id: roff.3,v 1.1 2010/05/25 22:16:59 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 $Mdocdate: May 25 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 .Fn roff_alloc "mandocmsg msgs" "void *data"
  33 .Ft int
  34 .Fn roff_endparse "struct roff *roff"
  35 .Ft void
  36 .Fn roff_free "struct roff *roff"
  37 .Ft "enum rofferr"
  38 .Fo roff_parseln
  39 .Fa "struct roff *roff"
  40 .Fa "int line"
  41 .Fa "char **bufp"
  42 .Fa "size_t *bufsz"
  43 .Fa "int pos"
  44 .Fa "int *offs"
  45 .Fc
  46 .Ft void
  47 .Fn roff_reset "struct roff *roff"
  48 .Sh DESCRIPTION
  49 The
  50 .Nm
  51 library processes lines of
  52 .Xr roff 7
  53 input.
  54 .Pp
  55 In general, applications initiate a parsing sequence with
  56 .Fn roff_alloc ,
  57 parse each line in a document with
  58 .Fn roff_parseln ,
  59 close the parsing session with
  60 .Fn roff_endparse ,
  61 and finally free all allocated memory with
  62 .Fn roff_free .
  63 The
  64 .Fn roff_reset
  65 function may be used in order to reset the parser for another input
  66 sequence.
  67 .Pp
  68 The
  69 .Fn roff_parseln
  70 function should be invoked before passing a line into the
  71 .Xr mdoc 3
  72 or
  73 .Xr man 3
  74 libraries.
  75 .Pp
  76 See the
  77 .Sx EXAMPLES
  78 section for a full example.
  79 .Sh REFERENCE
  80 This section further defines the
  81 .Sx Types
  82 and
  83 .Sx Functions
  84 available to programmers.
  85 .Ss Types
  86 Functions (see
  87 .Sx Functions )
  88 may use the following types:
  89 .Bl -ohang
  90 .It Vt "enum rofferr"
  91 Instructions for further processing to the caller of
  92 .Fn roff_parseln .
  93 .It Vt struct roff
  94 An opaque type defined in
  95 .Pa roff.c .
  96 Its values are only used privately within the library.
  97 .It Vt mandocmsg
  98 A function callback type defined in
  99 .Pa mandoc.h .
 100 .El
 101 .Ss Functions
 102 Function descriptions follow:
 103 .Bl -ohang
 104 .It Fn roff_alloc
 105 Allocates a parsing structure.
 106 The
 107 .Fa data
 108 pointer is passed to
 109 .Fa msgs .
 110 The
 111 .Fa pflags
 112 arguments are defined in
 113 .Pa roff.h .
 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 .