mandoc/mandoc.3 - diff

Return to mandoc.3 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mandoc.3 between version 1.37 and 1.43

version 1.37, 2016/07/07 19:19:01

version 1.43, 2018/12/14 01:18:25

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 21

.Sh NAME

.Nm mandoc ,

.Nm deroff ,

.Nm mandocmsg ,

.Nm man_mparse ,

.Nm man_validate ,

.Nm mdoc_validate ,

.Nm mparse_alloc ,

.Nm mparse_copy ,

.Nm mparse_free ,

.Nm mparse_getkeep ,

.Nm mparse_keep ,

.Nm mparse_open ,

.Nm mparse_readfd ,

.Nm mparse_reset ,

.Nm mparse_result ,

.Nm mparse_result

.Nm mparse_strerror ,

.Nm mparse_strlevel

.Nd mandoc macro compiler library

.Sh SYNOPSIS

.In sys/types.h

.In stdio.h

.In mandoc.h

.Pp

.Fd "#define ASCII_NBRSP"

Line 46

Line 42

.Ft struct mparse *

.Fo mparse_alloc

.Fa "int options"

.Fa "enum mandoclevel wlevel"

.Fa "enum mandoc_os oe_e"

.Fa "mandocmsg mmsg"

.Fa "char *os_s"

.Fa "char *defos"

.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

.Ft const char *

.Ft void

.Fo mparse_getkeep

.Fo mparse_copy

.Fa "const struct mparse *parse"

.Fc

.Ft void

.Fo mparse_keep

.Fa "struct mparse *parse"

.Fc

.Ft int

.Fo mparse_open

.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 92

Line 74

.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

.In roff.h

.Ft void

.Fo deroff

Line 119

Line 93

.In mandoc.h

.In man.h

.Vt extern const char * const * man_macronames;

.Ft "const struct mparse *"

.Fo man_mparse

.Fa "const struct roff_man *man"

.Fc

.Ft void

.Fo man_validate

.Fa "struct roff_man *man"

Line 181 or

Line 151 or

.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

Line 222 and freed with

Line 195 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 240 When it is no longer needed, the pointer returned from

Line 210 When it is no longer needed, the pointer returned from

.Fn deroff

can be passed to

.Xr free 3 .

.It Fn man_mparse

Get the parser used for the current output.

Declared in

.In man.h ,

implemented in

.Pa man.c .

.It Fn man_validate

Validate the

.Dv MACROSET_MAN

Line 295 This is for example useful in

Line 259 This is for example useful in

.Xr makewhatis 8

.Fl Q

to quickly build minimal databases.

.It Ar wlevel

.It Ar os_e

Can be set to

Operating system to check base system conventions for.

.Dv MANDOCLEVEL_BADARG ,

.Dv MANDOCLEVEL_ERROR ,

.Dv MANDOC_OS_OTHER ,

the system is automatically detected from

.Ic \&Os ,

.Fl Ios ,

.Dv MANDOCLEVEL_WARNING .

.Xr uname 3 .

Messages below the selected level will be suppressed.

.It Ar os_s

.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 defos

A default string for the

.Xr mdoc 7

.Sq \&Os

.Ic \&Os

macro, overriding the

.Dv OSNAME

preprocessor definition and the results of

Line 339 Declared in

Line 297 Declared in

.In mandoc.h ,

implemented in

.Pa read.c .

.It Fn mparse_getkeep

.It Fn mparse_copy

Acquire the keep buffer.

Dump a copy of the input to the standard output; used for

Must follow a call of

.Fl man T Ns Cm man .

.Fn mparse_keep .

Declared in

.In mandoc.h ,

implemented in

.Pa read.c .

.It Fn mparse_keep

Instruct the parser to retain a copy of its parsed input.

This can be acquired with subsequent

.Fn mparse_getkeep

calls.

Declared in

.In mandoc.h ,

implemented in

.Pa read.c .

.It Fn mparse_open

Open the file for reading.

If that fails and

Line 404 Declared in

Line 352 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 .

.El

.Ss Variables

.Bl -ohang

Line 625 TEXT end

Line 561 TEXT end

.Ed

.Pp

Here, the formatting of the

.Sq \&Ao

.Ic \&Ao

block extends from TEXT ao to TEXT ac,

while the formatting of the

.Sq \&Bo

.Ic \&Bo

block extends from TEXT bo to TEXT bc.

It renders as follows in

.Fl T Ns Cm ascii

Line 644 Using badly-nested blocks is

Line 580 Using badly-nested blocks is

.Em strongly discouraged ;

for example, the

.Fl T Ns Cm html

and

front-end to

.Fl T Ns Cm xhtml

front-ends to

.Xr mandoc 1

are unable to render them in any meaningful way.

is unable to render them in any meaningful way.

Furthermore, behaviour when encountering badly-nested blocks is not

consistent across troff implementations, especially when using multiple

levels of badly-nested blocks.

CVSweb