Return to roff.3 CVS log

Up to [cvsweb.bsd.lv] / mandoc

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 .