mandoc/mandoc.3 - diff

Return to mandoc.3 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mandoc.3 between version 1.25 and 1.31

version 1.25, 2014/08/05 05:48:56

version 1.31, 2015/01/15 04:26:40

Line 1

.\" $Id$

.\"

.\" Permission to use, copy, modify, and distribute this software for any

.\" purpose with or without fee is hereby granted, provided that the above

Line 31

.Nm mparse_free ,

.Nm mparse_getkeep ,

.Nm mparse_keep ,

.Nm mparse_open ,

.Nm mparse_readfd ,

.Nm mparse_reset ,

.Nm mparse_result ,

.Nm mparse_strerror ,

.Nm mparse_strlevel

.Nm mparse_wait ,

.Nd mandoc macro compiler library

.Sh LIBRARY

.Lb libmandoc

.Sh SYNOPSIS

.In sys/types.h

.In mandoc.h

.Pp

.Fd "#define ASCII_NBRSP"

.Fd "#define ASCII_HYPH"

.Fd "#define ASCII_BREAK"

Line 50

Line 51

.Fa "int options"

.Fa "enum mandoclevel wlevel"

.Fa "mandocmsg mmsg"

.Fa "const struct mchars *mchars"

.Fa "char *defos"

.Fc

.Ft void

Line 74

Line 76

.Fa "struct mparse *parse"

.Fc

.Ft "enum mandoclevel"

.Fo mparse_open

.Fa "struct mparse *parse"

.Fa "int *fd"

.Fa "const char *fname"

.Fc

.Ft "enum mandoclevel"

.Fo mparse_readfd

.Fa "struct mparse *parse"

.Fa "int fd"

Line 98

Line 106

.Fo mparse_strlevel

.Fa "enum mandoclevel"

.Fc

.Ft "enum mandoclevel"

.Fo mparse_wait

.Fa "struct mparse *parse"

.Fc

.In sys/types.h

.In mandoc.h

.In mdoc.h

Line 159 The following describes a general parse sequence:

Line 171 The following describes a general parse sequence:

.Bl -enum

.It

initiate a parsing sequence with

.Xr mchars_alloc 3

and

.Fn mparse_alloc ;

.It

parse files or file descriptors with

open a file with

.Xr open 2

.Fn mparse_open ;

.It

parse it with

.Fn mparse_readfd ;

.It

retrieve a parsed syntax tree, if the parse was successful, with

retrieve the syntax tree with

.Fn mparse_result ;

.It

iterate over parse nodes with

Line 173 or

Line 192 or

.Fn man_node ;

.It

free all allocated memory with

.Fn mparse_free ,

.Fn mparse_free

and

.Xr mchars_free 3 ,

or invoke

.Fn mparse_reset

and parse new files.

Line 189 and

Line 210 and

.Ss Types

.Bl -ohang

.It Vt "enum mandocerr"

A fatal error, error, or warning message during parsing.

An error or warning message during parsing.

.It Vt "enum mandoclevel"

A classification of an

.Vt "enum mandocerr"

as regards system operation.

.It Vt "struct mchars"

An opaque pointer to a a character table.

Created with

.Xr mchars_alloc 3

and freed with

.Xr mchars_free 3 .

.It Vt "struct mparse"

An opaque pointer to a running parse sequence.

Created with

Line 204 This may be used across parsed input if

Line 231 This may be used across parsed input if

.Fn mparse_reset

is called between parses.

.It Vt "mandocmsg"

A prototype for a function to handle fatal error, error, and warning

A prototype for a function to handle error and warning

messages emitted by the parser.

.El

.Ss Functions

Line 308 This is for example useful in

Line 335 This is for example useful in

to quickly build minimal databases.

.It Ar wlevel

Can be set to

.Dv MANDOCLEVEL_FATAL ,

.Dv MANDOCLEVEL_BADARG ,

.Dv MANDOCLEVEL_ERROR ,

.Dv MANDOCLEVEL_WARNING .

Line 318 A callback function to handle errors and warnings.

Line 345 A callback function to handle errors and warnings.

See

.Pa main.c

for an example.

.It Ar mchars

An opaque pointer to a a character table obtained from

.Xr mchars_alloc 3 .

.It Ar defos

A default string for the

.Xr mdoc 7

Line 361 Declared in

Line 391 Declared in

.In mandoc.h ,

implemented in

.Pa read.c .

.It Fn mparse_readfd

.It Fn mparse_open

Parse a file or file descriptor.

If the

.Fa fname

ends in

.Pa .gz ,

open with

.Xr gunzip 1 ;

otherwise, with

.Xr open 2 .

.Va fd

.Xr open 2

is -1,

fails, append

.Va fname

.Pa .gz

is opened for reading.

and try with

Otherwise,

.Xr gunzip 1 .

.Va fname

Return a file descriptor open for reading in

is assumed to be the name associated with

.Fa fd ,

.Va fd .

or -1 on failure.

This may be called multiple times with different parameters; however,

It can be passed to

.Fn mparse_readfd

or used directly.

Declared in

.In mandoc.h ,

implemented in

.Pa read.c .

.It Fn mparse_readfd

Parse a file descriptor opened with

.Xr open 2

.Fn mparse_open .

Pass the associated filename in

.Va fname .

Calls

.Fn mparse_wait

before returning.

This function may be called multiple times with different parameters; however,

.Fn mparse_reset

should be invoked between parses.

Declared in

Line 389 implemented in

Line 443 implemented in

.Pa read.c .

.It Fn mparse_result

Obtain the result of a parse.

Only successful parses

One of the three pointers will be filled in.

.Po

i.e., those where

.Fn mparse_readfd

returned less than MANDOCLEVEL_FATAL

.Pc

should invoke this function, in which case one of the three pointers will

be filled in.

Declared in

.In mandoc.h ,

implemented in

Line 409 implemented in

Line 456 implemented in

.Pa read.c .

.It Fn mparse_strlevel

Return a statically-allocated string representation of a level code.

Declared in

.In mandoc.h ,

implemented in

.Pa read.c .

.It Fn mparse_wait

Bury a

.Xr gunzip 1

child process that was spawned with

.Fn mparse_open .

To be called after the parse sequence is complete.

Not needed after

.Fn mparse_readfd ,

but does no harm in that case, either.

Returns

.Dv MANDOCLEVEL_OK

on success and

.Dv MANDOCLEVEL_SYSERR

on failure, that is, when

.Xr wait 2

fails, or when

.Xr gunzip 1

died from a signal or exited with non-zero status.

Declared in

.In mandoc.h ,

implemented in

CVSweb