![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to man.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc|
Return to man.3 CVS log | Up to [cvsweb.bsd.lv] / mandoc |
| version 1.20, 2010/06/27 15:52:41 | version 1.27, 2010/12/17 11:41:45 | ||
|---|---|---|---|
|
|
||
| .Nd man macro compiler library | .Nd man macro compiler library | ||
| .Sh SYNOPSIS | .Sh SYNOPSIS | ||
| .In mandoc.h | .In mandoc.h | ||
| .In regs.h | |||
| .In man.h | .In man.h | ||
| .Vt extern const char * const * man_macronames; | .Vt extern const char * const * man_macronames; | ||
| .Ft "struct man *" | .Ft "struct man *" | ||
| .Fo man_alloc | .Fo man_alloc | ||
| .Fa "const struct regset *regs" | .Fa "struct regset *regs" | ||
| .Fa "void *data" | .Fa "void *data" | ||
| .Fa "int pflags" | |||
| .Fa "mandocmsg msgs" | .Fa "mandocmsg msgs" | ||
| .Fc | .Fc | ||
| .Ft int | .Ft int | ||
|
|
||
| .Fn man_reset | .Fn man_reset | ||
| function may be used in order to reset the parser for another input | function may be used in order to reset the parser for another input | ||
| sequence. | sequence. | ||
| See the | |||
| .Sx EXAMPLES | |||
| section for a full example. | |||
| .Pp | .Pp | ||
| Beyond the full set of macros defined in | Beyond the full set of macros defined in | ||
| .Xr man 7 , | .Xr man 7 , | ||
| the | the | ||
| .Nm | .Nm | ||
| library also accepts the following macros: | library also accepts the following macro: | ||
| .Pp | .Pp | ||
| .Bl -tag -width Ds -compact | .Bl -tag -width Ds -compact | ||
| .It PD | .It PD | ||
| Has no effect. Handled as a current-scope line macro. | Has no effect. | ||
| .It Sp | |||
| A synonym for | |||
| .Sq sp 0.5v | |||
| .Pq part of the standard preamble for Perl documentation . | |||
| Handled as a line macro. | |||
| .It Vb | |||
| A synonym for | |||
| .Sq nf | |||
| .Pq part of the standard preamble for Perl documentation . | |||
| Handled as a current-scope line macro. | Handled as a current-scope line macro. | ||
| .It Ve | |||
| A synonym for | |||
| .Sq fi , | |||
| closing | |||
| .Sq Vb | |||
| .Pq part of the standard preamble for Perl documentation . | |||
| Handled as a current-scope line macro. | |||
| .El | .El | ||
| .Pp | |||
| Furthermore, the following escapes are accepted to allow | |||
| .Xr pod2man 1 | |||
| documents to be correctly formatted: | |||
| \e*(-- (dash), | |||
| \e*(PI (pi), | |||
| \e*(L" (left double-quote), | |||
| \e*(R" (right double-quote), | |||
| \e*(C+ (C++), | |||
| \e*(C` (left single-quote), | |||
| \e*(C' (right single-quote), | |||
| \e*(Aq (apostrophe), | |||
| \e*^ (hat), | |||
| \e*, (comma), | |||
| \e*~ (tilde), | |||
| \e*/ (forward slash), | |||
| \e*: (umlaut), | |||
| \e*8 (beta), | |||
| \e*o (degree), | |||
| \e*(D- (Eth), | |||
| \e*(d- (eth), | |||
| \e*(Th (Thorn), | |||
| and | |||
| \e*(th (thorn). | |||
| .Sh REFERENCE | |||
| This section further defines the | |||
| .Sx Types , | |||
| .Sx Functions | |||
| and | |||
| .Sx Variables | |||
| available to programmers. | |||
| Following that, the | |||
| .Sx Abstract Syntax Tree | |||
| section documents the output tree. | |||
| .Ss Types | .Ss Types | ||
| Both functions (see | |||
| .Sx Functions ) | |||
| and variables (see | |||
| .Sx Variables ) | |||
| may use the following types: | |||
| .Bl -ohang | .Bl -ohang | ||
| .It Vt struct man | .It Vt struct man | ||
| An opaque type defined in | An opaque type. | ||
| .Pa man.c . | |||
| Its values are only used privately within the library. | Its values are only used privately within the library. | ||
| .It Vt mandocmsg | |||
| A function callback type defined in | |||
| .Pa mandoc.h . | |||
| .It Vt struct man_node | .It Vt struct man_node | ||
| A parsed node. | A parsed node. | ||
| Defined in | |||
| .Pa man.h . | |||
| See | See | ||
| .Sx Abstract Syntax Tree | .Sx Abstract Syntax Tree | ||
| for details. | for details. | ||
| .El | .El | ||
| .Ss Functions | .Ss Functions | ||
| Function descriptions follow: | |||
| .Bl -ohang | .Bl -ohang | ||
| .It Fn man_alloc | .It Fn man_alloc | ||
| Allocates a parsing structure. | Allocates a parsing structure. | ||
|
|
||
| .Fa data | .Fa data | ||
| pointer is passed to | pointer is passed to | ||
| .Fa msgs . | .Fa msgs . | ||
| The | |||
| .Fa pflags | |||
| arguments are defined in | |||
| .Pa man.h . | |||
| Returns NULL on failure. | Returns NULL on failure. | ||
| If non-NULL, the pointer must be freed with | If non-NULL, the pointer must be freed with | ||
| .Fn man_free . | .Fn man_free . | ||
|
|
||
| .Fn parsed . | .Fn parsed . | ||
| This example does not error-check nor free memory upon failure. | This example does not error-check nor free memory upon failure. | ||
| .Bd -literal -offset indent | .Bd -literal -offset indent | ||
| struct regset regs; | |||
| struct man *man; | struct man *man; | ||
| struct man_node *node; | struct man_node *node; | ||
| char *buf; | char *buf; | ||
| size_t len; | size_t len; | ||
| int line; | int line; | ||
| bzero(®s, sizeof(struct regset)); | |||
| line = 1; | line = 1; | ||
| man = man_alloc(NULL, 0, NULL); | man = man_alloc(®s, NULL, NULL); | ||
| buf = NULL; | buf = NULL; | ||
| alloc_len = 0; | alloc_len = 0; | ||
|
|
||
| man_free(man); | man_free(man); | ||
| .Ed | .Ed | ||
| .Pp | .Pp | ||
| Please see | To compile this, execute | ||
| .Pp | |||
| .Dl % cc main.c libman.a libmandoc.a | |||
| .Pp | |||
| where | |||
| .Pa main.c | .Pa main.c | ||
| in the source archive for a rigorous reference. | is the example file. | ||
| .Sh SEE ALSO | .Sh SEE ALSO | ||
| .Xr mandoc 1 , | .Xr mandoc 1 , | ||
| .Xr man 7 | .Xr man 7 |