mandoc/mandoc.3 - diff

Return to mandoc.3 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mandoc.3 between version 1.42 and 1.44

version 1.42, 2018/08/23 19:33:27

version 1.44, 2018/12/30 00:49:55

Line 21

.Sh NAME

.Nm mandoc ,

.Nm deroff ,

.Nm mandocmsg ,

.Nm man_validate ,

.Nm mdoc_validate ,

.Nm mparse_alloc ,

.Nm mparse_copy ,

.Nm mparse_free ,

.Nm mparse_open ,

.Nm mparse_readfd ,

.Nm mparse_reset ,

.Nm mparse_result ,

.Nm mparse_result

.Nm mparse_strerror ,

.Nm mparse_strlevel ,

.Nm mparse_updaterc

.Nd mandoc macro compiler library

.Sh SYNOPSIS

.In sys/types.h

.In stdio.h

.In mandoc.h

.Pp

.Fd "#define ASCII_NBRSP"

Line 45

Line 40

.Ft struct mparse *

.Fo mparse_alloc

.Fa "int options"

.Fa "enum mandocerr mmin"

.Fa "mandocmsg mmsg"

.Fa "enum mandoc_os oe_e"

.Fa "char *os_s"

.Fc

.Ft void

.Fo (*mandocmsg)

.Fa "enum mandocerr errtype"

.Fa "enum mandoclevel level"

.Fa "const char *file"

.Fa "int line"

.Fa "int col"

.Fa "const char *msg"

.Fc

.Ft void

.Fo mparse_free

.Fa "struct mparse *parse"

.Fc

Line 72

Line 56

.Fa "struct mparse *parse"

.Fa "const char *fname"

.Fc

.Ft "enum mandoclevel"

.Ft void

.Fo mparse_readfd

.Fa "struct mparse *parse"

.Fa "int fd"

Line 82

Line 66

.Fo mparse_reset

.Fa "struct mparse *parse"

.Fc

.Ft void

.Ft struct roff_meta *

.Fo mparse_result

.Fa "struct mparse *parse"

.Fa "struct roff_man **man"

.Fa "char **sodest"

.Fc

.Ft "const char *"

.Fo mparse_strerror

.Fa "enum mandocerr"

.Fc

.Ft "const char *"

.Fo mparse_strlevel

.Fa "enum mandoclevel"

.Fc

.Ft void

.Fo mparse_updaterc

.Fa "struct mparse *parse"

.Fa "enum mandoclevel *rc"

.Fc

.In roff.h

.Ft void

.Fo deroff

Line 112

Line 81

.In mdoc.h

.Vt extern const char * const * mdoc_argnames;

.Vt extern const char * const * mdoc_macronames;

.Ft void

.Fo mdoc_validate

.Fa "struct roff_man *mdoc"

.Fc

.In sys/types.h

.In mandoc.h

.In man.h

.Vt extern const char * const * man_macronames;

.Ft void

.Fo man_validate

.Fa "struct roff_man *man"

.Fc

.Sh DESCRIPTION

The

.Nm mandoc

Line 164 close it with

Line 125 close it with

retrieve the syntax tree with

.Fn mparse_result ;

.It

depending on whether the

.Fa macroset

member of the returned

.Vt struct roff_man

.Dv MACROSET_MDOC

.Dv MACROSET_MAN ,

validate it with

.Fn mdoc_validate

.Fn man_validate ,

respectively;

.It

if information about the validity of the input is needed, fetch it with

.Fn mparse_updaterc ;

.It

iterate over parse nodes with starting from the

.Fa first

member of the returned

.Vt struct roff_man ;

.Vt struct roff_meta ;

.It

free all allocated memory with

.Fn mparse_free

Line 222 and freed with

Line 169 and freed with

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 error and warning

messages emitted by the parser.

.El

.Ss Functions

.Bl -ohang

Line 235 including text contained in its child nodes.

Line 179 including text contained in its child nodes.

To be used on children of the

.Fa first

member of

.Vt struct roff_man .

.Vt struct roff_meta .

When it is no longer needed, the pointer returned from

.Fn deroff

can be passed to

.Xr free 3 .

.It Fn man_validate

Validate the

.Dv MACROSET_MAN

parse tree obtained with

.Fn mparse_result .

Declared in

.In man.h ,

implemented in

.Pa man.c .

.It Fn mdoc_validate

Validate the

.Dv MACROSET_MDOC

parse tree obtained with

.Fn mparse_result .

Declared in

.In mdoc.h ,

implemented in

.Pa mdoc.c .

.It Fn mparse_alloc

Allocate a parser.

The arguments have the following effect:

Line 279 file inclusion requests are always honoured.

Line 205 file inclusion requests are always honoured.

Otherwise, if the request is the only content in an input file,

only the file name is remembered, to be returned in the

.Fa sodest

argument of

field of

.Fn mparse_result .

.Vt struct roff_meta .

.Pp

When the

.Dv MPARSE_QUICK

Line 289 This is for example useful in

Line 215 This is for example useful in

.Xr makewhatis 8

.Fl Q

to quickly build minimal databases.

.It Ar mmin

.Pp

Can be set to

When the

.Dv MANDOCERR_BASE ,

.Dv MARSE_VALIDATE

.Dv MANDOCERR_STYLE ,

bit is set,

.Dv MANDOCERR_WARNING ,

.Fn mparse_result

.Dv MANDOCERR_ERROR ,

runs the validation functions before returning the syntax tree.

.Dv MANDOCERR_UNSUPP ,

This is almost always required, except in certain debugging scenarios,

for example to dump unvalidated syntax trees.

.Dv MANDOCERR_MAX .

Messages below the selected level will be suppressed.

.It Ar mmsg

A callback function to handle errors and warnings.

See

.Pa main.c

for an example.

If printing of error messages is not desired,

.Dv NULL

may be passed.

.It Ar os_e

Operating system to check base system conventions for.

Line 395 implemented in

Line 311 implemented in

.Pa read.c .

.It Fn mparse_result

Obtain the result of a parse.

One of the two pointers will be filled in.

Declared in

.In mandoc.h ,

implemented in

.Pa read.c .

.It Fn mparse_strerror

Return a statically-allocated string representation of an error code.

Declared in

.In mandoc.h ,

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_updaterc

If the highest warning or error level that occurred during the current

.Fa parse

is higher than

.Pf * Fa rc ,

update

.Pf * Fa rc

accordingly.

This is useful after calling

.Fn mdoc_validate

.Fn man_validate .

Declared in

.In mandoc.h ,

implemented in

CVSweb