Return to roff.3 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/roff.3, Revision 1.3

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