Annotation of mandoc/roff.3, Revision 1.4
1.4 ! schwarze 1: .\" $Id: roff.3,v 1.3 2010/06/27 15:52:41 kristaps Exp $
1.1 kristaps 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: .\"
1.4 ! schwarze 17: .Dd $Mdocdate: June 27 2010 $
1.1 kristaps 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
1.2 kristaps 30: .In regs.h
1.1 kristaps 31: .In roff.h
32: .Ft "struct roff *"
1.3 kristaps 33: .Fo roff_alloc
34: .Fa "struct regset *regs"
35: .Fa "mandocmsg msgs"
36: .Fa "void *data"
37: .Fc
1.1 kristaps 38: .Ft int
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"
1.4 ! schwarze 53: .In regs.h
! 54: .Ft "char *"
! 55: .Fn roff_setstr "const char *name" "const char *string"
! 56: .Ft "char *"
! 57: .Fn roff_getstr "const char *name"
! 58: .Ft "char *"
! 59: .Fn roff_getstrn "const char *name" "size_t len"
! 60: .Ft void
! 61: .Fn roff_freestr void
1.1 kristaps 62: .Sh DESCRIPTION
63: The
64: .Nm
65: library processes lines of
66: .Xr roff 7
67: input.
68: .Pp
69: In general, applications initiate a parsing sequence with
70: .Fn roff_alloc ,
71: parse each line in a document with
72: .Fn roff_parseln ,
73: close the parsing session with
74: .Fn roff_endparse ,
75: and finally free all allocated memory with
76: .Fn roff_free .
77: The
78: .Fn roff_reset
79: function may be used in order to reset the parser for another input
80: sequence.
81: .Pp
82: The
83: .Fn roff_parseln
84: function should be invoked before passing a line into the
85: .Xr mdoc 3
86: or
87: .Xr man 3
88: libraries.
89: .Pp
90: See the
91: .Sx EXAMPLES
92: section for a full example.
93: .Sh REFERENCE
94: This section further defines the
95: .Sx Types
96: and
97: .Sx Functions
98: available to programmers.
99: .Ss Types
100: Functions (see
101: .Sx Functions )
102: may use the following types:
103: .Bl -ohang
104: .It Vt "enum rofferr"
105: Instructions for further processing to the caller of
106: .Fn roff_parseln .
107: .It Vt struct roff
108: An opaque type defined in
109: .Pa roff.c .
110: Its values are only used privately within the library.
111: .It Vt mandocmsg
112: A function callback type defined in
113: .Pa mandoc.h .
114: .El
115: .Ss Functions
116: Function descriptions follow:
117: .Bl -ohang
118: .It Fn roff_alloc
119: Allocates a parsing structure.
120: The
121: .Fa data
122: pointer is passed to
123: .Fa msgs .
124: The
125: .Fa pflags
126: arguments are defined in
127: .Pa roff.h .
128: Returns NULL on failure.
129: If non-NULL, the pointer must be freed with
130: .Fn roff_free .
131: .It Fn roff_reset
132: Reset the parser for another parse routine.
133: After its use,
134: .Fn roff_parseln
135: behaves as if invoked for the first time.
136: .It Fn roff_free
137: Free all resources of a parser.
138: The pointer is no longer valid after invocation.
139: .It Fn roff_parseln
140: Parse a nil-terminated line of input.
141: The character array
142: .Fa bufp
143: may be modified or reallocated within this function.
144: In the latter case,
145: .Fa bufsz
146: will be modified accordingly.
147: The
148: .Fa offs
149: pointer will be modified if the line start during subsequent processing
150: of the line is not at the zeroth index.
151: This line should not contain the trailing newline.
152: Returns 0 on failure, 1 on success.
153: .It Fn roff_endparse
154: Signals that the parse is complete.
155: Returns 0 on failure, 1 on success.
156: .El
1.4 ! schwarze 157: .Sh USER-DEFINED STRINGS
! 158: Strings defined by the
! 159: .Xr roff 7
! 160: .Sx \&ds
! 161: instruction are saved using the
! 162: .Fn roff_setstr
! 163: function and retrieved using the
! 164: .Fn roff_getstr
! 165: and
! 166: .Fn roff_getstrn
! 167: functions.
! 168: .Pp
! 169: These functions take the name of the string to be accessed
! 170: as their first argument.
! 171: While
! 172: .Fn roff_getstr
! 173: requires the name to be null-terminated,
! 174: .Fn roff_getstrn
! 175: accepts non-terminated strings, but requires the length of the name
! 176: to be specified.
! 177: .Pp
! 178: The second argument to
! 179: .Fn roff_setstr
! 180: is the new value of the string.
! 181: It will be copied to internal storage, so both pointers to constant
! 182: strings and pointers to volatile storage are acceptable.
! 183: .Pp
! 184: All of these functions return a pointer to the new value of the string
! 185: in internal storage, which should be considered read-only, so use
! 186: .Xr strdup 3
! 187: on it as appropriate.
! 188: The read functions return NULL when a string of the specified name
! 189: is not available or empty, and
! 190: .Fn roff_setstr
! 191: returns NULL when memory allocation fails.
! 192: In the latter case, the string will remain unset.
! 193: .Pp
! 194: The function
! 195: .Fn roff_freestr
! 196: clears all user-defined strings.
! 197: It always succeeds.
! 198: Both
! 199: .Fn roff_reset
! 200: and
! 201: .Fn roff_free
! 202: call it.
1.1 kristaps 203: .Sh EXAMPLES
204: See
205: .Pa main.c
206: in the source distribution for an example of usage.
207: .Sh SEE ALSO
208: .Xr mandoc 1 ,
209: .Xr man 3 ,
210: .Xr mdoc 3 ,
211: .Xr roff 7
212: .Sh AUTHORS
213: The
214: .Nm
215: library was written by
216: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
1.4 ! schwarze 217: .Sh BUGS
! 218: The implementation of user-defined strings needs improvement:
! 219: .Bl -dash
! 220: .It
! 221: String values are taken literally and are not interpreted.
! 222: .It
! 223: Parsing of quoted strings is incomplete.
! 224: .It
! 225: The stings are stored internally using a singly linked list,
! 226: which is fine for small numbers of strings,
! 227: but ineffient when handling many strings.
! 228: .El
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to roff.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc