Return to roff.3 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/roff.3, Revision 1.2

1.2     ! kristaps    1: .\"    $Id: roff.3,v 1.1 2010/05/25 22:16:59 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.2     ! kristaps   17: .Dd $Mdocdate: May 25 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 *"
                     33: .Fn roff_alloc "mandocmsg msgs" "void *data"
                     34: .Ft int
                     35: .Fn roff_endparse "struct roff *roff"
                     36: .Ft void
                     37: .Fn roff_free "struct roff *roff"
                     38: .Ft "enum rofferr"
                     39: .Fo roff_parseln
                     40: .Fa "struct roff *roff"
                     41: .Fa "int line"
                     42: .Fa "char **bufp"
                     43: .Fa "size_t *bufsz"
                     44: .Fa "int pos"
                     45: .Fa "int *offs"
                     46: .Fc
                     47: .Ft void
                     48: .Fn roff_reset "struct roff *roff"
                     49: .Sh DESCRIPTION
                     50: The
                     51: .Nm
                     52: library processes lines of
                     53: .Xr roff 7
                     54: input.
                     55: .Pp
                     56: In general, applications initiate a parsing sequence with
                     57: .Fn roff_alloc ,
                     58: parse each line in a document with
                     59: .Fn roff_parseln ,
                     60: close the parsing session with
                     61: .Fn roff_endparse ,
                     62: and finally free all allocated memory with
                     63: .Fn roff_free .
                     64: The
                     65: .Fn roff_reset
                     66: function may be used in order to reset the parser for another input
                     67: sequence.
                     68: .Pp
                     69: The
                     70: .Fn roff_parseln
                     71: function should be invoked before passing a line into the
                     72: .Xr mdoc 3
                     73: or
                     74: .Xr man 3
                     75: libraries.
                     76: .Pp
                     77: See the
                     78: .Sx EXAMPLES
                     79: section for a full example.
                     80: .Sh REFERENCE
                     81: This section further defines the
                     82: .Sx Types
                     83: and
                     84: .Sx Functions
                     85: available to programmers.
                     86: .Ss Types
                     87: Functions (see
                     88: .Sx Functions )
                     89: may use the following types:
                     90: .Bl -ohang
                     91: .It Vt "enum rofferr"
                     92: Instructions for further processing to the caller of
                     93: .Fn roff_parseln .
                     94: .It Vt struct roff
                     95: An opaque type defined in
                     96: .Pa roff.c .
                     97: Its values are only used privately within the library.
                     98: .It Vt mandocmsg
                     99: A function callback type defined in
                    100: .Pa mandoc.h .
                    101: .El
                    102: .Ss Functions
                    103: Function descriptions follow:
                    104: .Bl -ohang
                    105: .It Fn roff_alloc
                    106: Allocates a parsing structure.
                    107: The
                    108: .Fa data
                    109: pointer is passed to
                    110: .Fa msgs .
                    111: The
                    112: .Fa pflags
                    113: arguments are defined in
                    114: .Pa roff.h .
                    115: Returns NULL on failure.
                    116: If non-NULL, the pointer must be freed with
                    117: .Fn roff_free .
                    118: .It Fn roff_reset
                    119: Reset the parser for another parse routine.
                    120: After its use,
                    121: .Fn roff_parseln
                    122: behaves as if invoked for the first time.
                    123: .It Fn roff_free
                    124: Free all resources of a parser.
                    125: The pointer is no longer valid after invocation.
                    126: .It Fn roff_parseln
                    127: Parse a nil-terminated line of input.
                    128: The character array
                    129: .Fa bufp
                    130: may be modified or reallocated within this function.
                    131: In the latter case,
                    132: .Fa bufsz
                    133: will be modified accordingly.
                    134: The
                    135: .Fa offs
                    136: pointer will be modified if the line start during subsequent processing
                    137: of the line is not at the zeroth index.
                    138: This line should not contain the trailing newline.
                    139: Returns 0 on failure, 1 on success.
                    140: .It Fn roff_endparse
                    141: Signals that the parse is complete.
                    142: Returns 0 on failure, 1 on success.
                    143: .El
                    144: .Sh EXAMPLES
                    145: See
                    146: .Pa main.c
                    147: in the source distribution for an example of usage.
                    148: .Sh SEE ALSO
                    149: .Xr mandoc 1 ,
                    150: .Xr man 3 ,
                    151: .Xr mdoc 3 ,
                    152: .Xr roff 7
                    153: .Sh AUTHORS
                    154: The
                    155: .Nm
                    156: library was written by
                    157: .An Kristaps Dzonsons Aq kristaps@bsd.lv .