=================================================================== RCS file: /cvs/mandoc/mandoc.3,v retrieving revision 1.1 retrieving revision 1.6 diff -u -p -r1.1 -r1.6 --- mandoc/mandoc.3 2011/03/22 10:02:50 1.1 +++ mandoc/mandoc.3 2011/05/01 10:40:52 1.6 @@ -1,4 +1,4 @@ -.\" $Id: mandoc.3,v 1.1 2011/03/22 10:02:50 kristaps Exp $ +.\" $Id: mandoc.3,v 1.6 2011/05/01 10:40:52 kristaps Exp $ .\" .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons .\" Copyright (c) 2010 Ingo Schwarze @@ -15,25 +15,41 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: March 22 2011 $ +.Dd $Mdocdate: May 1 2011 $ .Dt MANDOC 3 .Os .Sh NAME .Nm mandoc , +.Nm mandoc_escape , .Nm man_meta , .Nm man_node , +.Nm mchars_alloc , +.Nm mchars_free , +.Nm mchars_num2char , +.Nm mchars_res2cp , +.Nm mchars_res2str , +.Nm mchars_spec2cp , +.Nm mchars_spec2str , .Nm mdoc_meta , .Nm mdoc_node , .Nm mparse_alloc , .Nm mparse_free , .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 man.h .In mdoc.h .In mandoc.h +.Ft "enum mandoc_esc" +.Fo mandoc_escape +.Fa "const char **in" +.Fa "const char **seq" +.Fa "int *len" +.Fc .Ft "const struct man_meta *" .Fo man_meta .Fa "const struct man *man" @@ -42,6 +58,40 @@ .Fo man_node .Fa "const struct man *man" .Fc +.Ft "struct mchars *" +.Fn mchars_alloc +.Ft void +.Fn mchars_free "struct mchars *p" +.Ft char +.Fn mchars_num2char "const char *cp" "size_t sz" +.Ft "const char *" +.Fo mchars_res2str +.Fa "struct mchars *p" +.Fa "const char *cp" +.Fa "size_t sz" +.Fa "size_t *rsz" +.Fc +.Ft int +.Fo mchars_res2cp +.Fa "struct mchars *p" +.Fa "const char *cp" +.Fa "size_t sz" +.Ft "const char *" +.Fc +.Ft "const char *" +.Fo mchars_spec2str +.Fa "struct mchars *p" +.Fa "const char *cp" +.Fa "size_t sz" +.Fa "size_t *rsz" +.Fc +.Ft int +.Fo mchars_spec2cp +.Fa "struct mchars *p" +.Fa "const char *cp" +.Fa "size_t sz" +.Ft "const char *" +.Fc .Ft "const struct mdoc_meta *" .Fo mdoc_meta .Fa "const struct mdoc *mdoc" @@ -77,9 +127,19 @@ .Fa "struct mdoc **mdoc" .Fa "struct man **man" .Fc +.Ft "const char *" +.Fo mparse_strerror +.Fa "enum mandocerr" +.Fc +.Ft "const char *" +.Fo mparse_strlevel +.Fa "enum mandoclevel" +.Fc .Vt extern const char * const * man_macronames; .Vt extern const char * const * mdoc_argnames; .Vt extern const char * const * mdoc_macronames; +.Fd "#define ASCII_NBRSP" +.Fd "#define ASCII_HYPH" .Sh DESCRIPTION The .Nm mandoc @@ -121,6 +181,154 @@ or invoke .Fn mparse_reset and parse new files. .El +.Pp +The +.Nm +library also contains routines for translating character strings into glyphs +.Pq see Fn mchars_alloc +and parsing escape sequences from strings +.Pq see Fn mandoc_escape . +.Sh REFERENCE +This section documents the functions, types, and variables available +via +.In mandoc.h . +.Ss Types +.Bl -ohang +.It Vt "enum mandoc_esc" +.It Vt "enum mandocerr" +.It Vt "enum mandoclevel" +.It Vt "struct mchars" +An opaque pointer to an object allowing for translation between +character strings and glyphs. +See +.Fn mchars_alloc . +.It Vt "enum mparset" +.It Vt "struct mparse" +.It Vt "mandocmsg" +.El +.Ss Functions +.Bl -ohang +.It Fn mandoc_escape +Scan an escape sequence, i.e., a character string beginning with +.Sq \e . +Pass a pointer to this string as +.Va end ; +it will be set to the supremum of the parsed escape sequence unless +returning ESCAPE_ERROR, in which case the string is bogus and should be +thrown away. +If not ESCAPE_ERROR or ESCAPE_IGNORE, +.Va start +is set to the first relevant character of the substring (font, glyph, +whatever) of length +.Va sz . +Both +.Va start +and +.Va sz +may be NULL. +.It Fn man_meta +Obtain the meta-data of a successful parse. +This may only be used on a pointer returned by +.Fn mparse_result . +.It Fn man_node +Obtain the root node of a successful parse. +This may only be used on a pointer returned by +.Fn mparse_result . +.It Fn mchars_alloc +Allocate an +.Vt "struct mchars *" +object for translating special characters into glyphs. +See +.Xr mandoc_char 7 +for an overview of special characters. +The object must be freed with +.Fn mchars_free . +.It Fn mchars_free +Free an object created with +.Fn mchars_alloc . +.It Fn mchars_num2char +Convert a character index as found in \eN\(aq\(aq into a printable +character. +Returns \e0 (the nil character) if the input sequence is malformed. +.It Fn mchars_res2cp +Convert a predefined character into a valid Unicode codepoint. +Returns \-1 on failure and 0 if no code-point exists (if this occurs, +the caller should fall back to +.Fn mchars_res2str ) . +.It Fn mchars_res2str +Convert a predefined character into an ASCII string. +Returns NULL on failure. +.It Fn mchars_spec2cp +Convert a special character into a valid Unicode codepoint. +Returns \-1 on failure and 0 if no code-point exists (if this occurs, +the caller should fall back to +.Fn mchars_spec2str ) . +.It Fn mchars_spec2str +Convert a special character into an ASCII string. +Returns NULL on failure. +.It Fn mdoc_meta +Obtain the meta-data of a successful parse. +This may only be used on a pointer returned by +.Fn mparse_result . +.It Fn mdoc_node +Obtain the root node of a successful parse. +This may only be used on a pointer returned by +.Fn mparse_result . +.It Fn mparse_alloc +Allocate a parser. +The same parser may be used for multiple files so long as +.Fn mparse_reset +is called between parses. +.Fn mparse_free +must be called to free the memory allocated by this function. +.It Fn mparse_free +Free all memory allocated by +.Fn mparse_alloc . +.It Fn mparse_readfd +Parse a file or file descriptor. +If +.Va fd +is -1, +.Va fname +is opened for reading. +Otherwise, +.Va fname +is assumed to be the name associated with +.Va fd . +This may be called multiple times with different parameters; however, +.Fn mparse_reset +should be invoked between parses. +.It Fn mparse_reset +Reset a parser so that +.Fn mparse_readfd +may be used again. +.It Fn mparse_result +Obtain the result of a parse. +Only successful parses +.Po +i.e., those where +.Fn mparse_readfd +returned less than MANDOCLEVEL_FATAL +.Pc +should invoke this function, in which case one of the two pointers will +be filled in. +.It Fn mparse_strerror +Return a statically-allocated string representation of an error code. +.It Fn mparse_strlevel +Return a statically-allocated string representation of a level code. +.El +.Ss Variables +.Bl -ohang +.It Va man_macronames +The string representation of a man macro as indexed by +.Vt "enum mant" . +.It Va mdoc_argnames +The string representation of a mdoc macro argument as indexed by +.Vt "enum mdocargt" . +.It Va mdoc_macronames +The string representation of a mdoc macro as indexed by +.Vt "enum mdoct" . +.El .Sh IMPLEMENTATION NOTES This section consists of structural documentation for .Xr mdoc 7 @@ -241,7 +449,7 @@ where a new body introduces a new phrase. .Pp The .Xr mdoc 7 -syntax tree accomodates for broken block structures as well. +syntax tree accommodates for broken block structures as well. The ENDBODY node is available to end the formatting associated with a given block before the physical end of that block. It has a non-null @@ -313,6 +521,7 @@ levels of badly-nested blocks. .Xr mandoc 1 , .Xr eqn 7 , .Xr man 7 , +.Xr mandoc_char 7 , .Xr mdoc 7 , .Xr roff 7 , .Xr tbl 7