Annotation of mandoc/roff.3, Revision 1.1
1.1 ! kristaps 1: .\" $Id: man.3,v 1.17 2010/05/25 21:46:48 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$
! 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 .
CVSweb