version 1.37, 2016/07/07 19:19:01 |
version 1.43, 2018/12/14 01:18:25 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2010-2016 Ingo Schwarze <schwarze@openbsd.org> |
.\" Copyright (c) 2010-2017 Ingo Schwarze <schwarze@openbsd.org> |
.\" |
.\" |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" purpose with or without fee is hereby granted, provided that the above |
.\" purpose with or without fee is hereby granted, provided that the above |
|
|
.Sh NAME |
.Sh NAME |
.Nm mandoc , |
.Nm mandoc , |
.Nm deroff , |
.Nm deroff , |
.Nm mandocmsg , |
|
.Nm man_mparse , |
|
.Nm man_validate , |
.Nm man_validate , |
.Nm mdoc_validate , |
.Nm mdoc_validate , |
.Nm mparse_alloc , |
.Nm mparse_alloc , |
|
.Nm mparse_copy , |
.Nm mparse_free , |
.Nm mparse_free , |
.Nm mparse_getkeep , |
|
.Nm mparse_keep , |
|
.Nm mparse_open , |
.Nm mparse_open , |
.Nm mparse_readfd , |
.Nm mparse_readfd , |
.Nm mparse_reset , |
.Nm mparse_reset , |
.Nm mparse_result , |
.Nm mparse_result |
.Nm mparse_strerror , |
|
.Nm mparse_strlevel |
|
.Nd mandoc macro compiler library |
.Nd mandoc macro compiler library |
.Sh SYNOPSIS |
.Sh SYNOPSIS |
.In sys/types.h |
.In sys/types.h |
|
.In stdio.h |
.In mandoc.h |
.In mandoc.h |
.Pp |
.Pp |
.Fd "#define ASCII_NBRSP" |
.Fd "#define ASCII_NBRSP" |
|
|
.Ft struct mparse * |
.Ft struct mparse * |
.Fo mparse_alloc |
.Fo mparse_alloc |
.Fa "int options" |
.Fa "int options" |
.Fa "enum mandoclevel wlevel" |
.Fa "enum mandoc_os oe_e" |
.Fa "mandocmsg mmsg" |
.Fa "char *os_s" |
.Fa "char *defos" |
|
.Fc |
.Fc |
.Ft void |
.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 |
.Fo mparse_free |
.Fa "struct mparse *parse" |
.Fa "struct mparse *parse" |
.Fc |
.Fc |
.Ft const char * |
.Ft void |
.Fo mparse_getkeep |
.Fo mparse_copy |
.Fa "const struct mparse *parse" |
.Fa "const struct mparse *parse" |
.Fc |
.Fc |
.Ft void |
|
.Fo mparse_keep |
|
.Fa "struct mparse *parse" |
|
.Fc |
|
.Ft int |
.Ft int |
.Fo mparse_open |
.Fo mparse_open |
.Fa "struct mparse *parse" |
.Fa "struct mparse *parse" |
.Fa "const char *fname" |
.Fa "const char *fname" |
.Fc |
.Fc |
.Ft "enum mandoclevel" |
.Ft void |
.Fo mparse_readfd |
.Fo mparse_readfd |
.Fa "struct mparse *parse" |
.Fa "struct mparse *parse" |
.Fa "int fd" |
.Fa "int fd" |
|
|
.Fa "struct roff_man **man" |
.Fa "struct roff_man **man" |
.Fa "char **sodest" |
.Fa "char **sodest" |
.Fc |
.Fc |
.Ft "const char *" |
|
.Fo mparse_strerror |
|
.Fa "enum mandocerr" |
|
.Fc |
|
.Ft "const char *" |
|
.Fo mparse_strlevel |
|
.Fa "enum mandoclevel" |
|
.Fc |
|
.In roff.h |
.In roff.h |
.Ft void |
.Ft void |
.Fo deroff |
.Fo deroff |
|
|
.In mandoc.h |
.In mandoc.h |
.In man.h |
.In man.h |
.Vt extern const char * const * man_macronames; |
.Vt extern const char * const * man_macronames; |
.Ft "const struct mparse *" |
|
.Fo man_mparse |
|
.Fa "const struct roff_man *man" |
|
.Fc |
|
.Ft void |
.Ft void |
.Fo man_validate |
.Fo man_validate |
.Fa "struct roff_man *man" |
.Fa "struct roff_man *man" |
|
|
.Fn man_validate , |
.Fn man_validate , |
respectively; |
respectively; |
.It |
.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 |
iterate over parse nodes with starting from the |
.Fa first |
.Fa first |
member of the returned |
member of the returned |
|
|
This may be used across parsed input if |
This may be used across parsed input if |
.Fn mparse_reset |
.Fn mparse_reset |
is called between parses. |
is called between parses. |
.It Vt "mandocmsg" |
|
A prototype for a function to handle error and warning |
|
messages emitted by the parser. |
|
.El |
.El |
.Ss Functions |
.Ss Functions |
.Bl -ohang |
.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 |
.Fn deroff |
can be passed to |
can be passed to |
.Xr free 3 . |
.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 |
.It Fn man_validate |
Validate the |
Validate the |
.Dv MACROSET_MAN |
.Dv MACROSET_MAN |
Line 295 This is for example useful in |
|
Line 259 This is for example useful in |
|
.Xr makewhatis 8 |
.Xr makewhatis 8 |
.Fl Q |
.Fl Q |
to quickly build minimal databases. |
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 , |
If |
.Dv MANDOCLEVEL_ERROR , |
.Dv MANDOC_OS_OTHER , |
|
the system is automatically detected from |
|
.Ic \&Os , |
|
.Fl Ios , |
or |
or |
.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 |
A default string for the |
.Xr mdoc 7 |
.Xr mdoc 7 |
.Sq \&Os |
.Ic \&Os |
macro, overriding the |
macro, overriding the |
.Dv OSNAME |
.Dv OSNAME |
preprocessor definition and the results of |
preprocessor definition and the results of |
|
|
.In mandoc.h , |
.In mandoc.h , |
implemented in |
implemented in |
.Pa read.c . |
.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 |
Declared in |
.In mandoc.h , |
.In mandoc.h , |
implemented in |
implemented in |
.Pa read.c . |
.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 |
.It Fn mparse_open |
Open the file for reading. |
Open the file for reading. |
If that fails and |
If that fails and |
|
|
.In mandoc.h , |
.In mandoc.h , |
implemented in |
implemented in |
.Pa read.c . |
.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 |
.El |
.Ss Variables |
.Ss Variables |
.Bl -ohang |
.Bl -ohang |
|
|
.Ed |
.Ed |
.Pp |
.Pp |
Here, the formatting of the |
Here, the formatting of the |
.Sq \&Ao |
.Ic \&Ao |
block extends from TEXT ao to TEXT ac, |
block extends from TEXT ao to TEXT ac, |
while the formatting of the |
while the formatting of the |
.Sq \&Bo |
.Ic \&Bo |
block extends from TEXT bo to TEXT bc. |
block extends from TEXT bo to TEXT bc. |
It renders as follows in |
It renders as follows in |
.Fl T Ns Cm ascii |
.Fl T Ns Cm ascii |
Line 644 Using badly-nested blocks is |
|
Line 580 Using badly-nested blocks is |
|
.Em strongly discouraged ; |
.Em strongly discouraged ; |
for example, the |
for example, the |
.Fl T Ns Cm html |
.Fl T Ns Cm html |
and |
front-end to |
.Fl T Ns Cm xhtml |
|
front-ends to |
|
.Xr mandoc 1 |
.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 |
Furthermore, behaviour when encountering badly-nested blocks is not |
consistent across troff implementations, especially when using multiple |
consistent across troff implementations, especially when using multiple |
levels of badly-nested blocks. |
levels of badly-nested blocks. |