typo; noticed by jmc@ some time ago

[mandoc.git] / mandoc.3

diff --git a/mandoc.3 b/mandoc.3
index db7637491491057123e9b52905392f1e00dccace..8f76ad21fff4e65201c512e1fb8e52ea70b02841 100644 (file)
--- a/mandoc.3
+++ b/mandoc.3
@@ -1,4 +1,4 @@
-.\"    $Id: mandoc.3,v 1.23 2014/01/05 20:26:36 schwarze Exp $
+.\"    $Id: mandoc.3,v 1.25 2014/08/05 05:48:56 schwarze Exp $

 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>


@@ -15,21 +15,16 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"

-.Dd $Mdocdate: January 5 2014 $
+.Dd $Mdocdate: August 5 2014 $

 .Dt MANDOC 3
 .Os
 .Sh NAME
 .Nm mandoc ,
 .Dt MANDOC 3
 .Os
 .Sh NAME
 .Nm mandoc ,

-.Nm mandoc_escape ,
+.Nm man_deroff ,

 .Nm man_meta ,
 .Nm man_mparse ,
 .Nm man_node ,
 .Nm man_meta ,
 .Nm man_mparse ,
 .Nm man_node ,

-.Nm mchars_alloc ,
-.Nm mchars_free ,
-.Nm mchars_num2char ,
-.Nm mchars_num2uc ,
-.Nm mchars_spec2cp ,
-.Nm mchars_spec2str ,
+.Nm mdoc_deroff ,

 .Nm mdoc_meta ,
 .Nm mdoc_node ,
 .Nm mparse_alloc ,
 .Nm mdoc_meta ,
 .Nm mdoc_node ,
 .Nm mparse_alloc ,


@@ -45,63 +40,26 @@
 .Sh LIBRARY
 .Lb libmandoc
 .Sh SYNOPSIS
 .Sh LIBRARY
 .Lb libmandoc
 .Sh SYNOPSIS

-.In man.h
-.In mdoc.h
+.In sys/types.h

 .In mandoc.h
 .In mandoc.h

-.Ft "enum mandoc_esc"
-.Fo mandoc_escape
-.Fa "const char **end"
-.Fa "const char **start"
-.Fa "int *sz"
-.Fc
-.Ft "const struct man_meta *"
-.Fo man_meta
-.Fa "const struct man *man"
-.Fc
-.Ft "const struct mparse *"
-.Fo man_mparse
-.Fa "const struct man *man"
-.Fc
-.Ft "const struct man_node *"
-.Fo man_node
-.Fa "const struct man *man"
-.Fc
-.Ft "struct mchars *"
-.Fn mchars_alloc "void"
-.Ft void
-.Fn mchars_free "struct mchars *p"
-.Ft char
-.Fn mchars_num2char "const char *cp" "size_t sz"
-.Ft int
-.Fn mchars_num2uc "const char *cp" "size_t sz"
-.Ft "const char *"
-.Fo mchars_spec2str
-.Fa "const struct mchars *p"
-.Fa "const char *cp"
-.Fa "size_t sz"
-.Fa "size_t *rsz"
-.Fc
-.Ft int
-.Fo mchars_spec2cp
-.Fa "const struct mchars *p"
-.Fa "const char *cp"
-.Fa "size_t sz"
-.Fc
-.Ft "const struct mdoc_meta *"
-.Fo mdoc_meta
-.Fa "const struct mdoc *mdoc"
-.Fc
-.Ft "const struct mdoc_node *"
-.Fo mdoc_node
-.Fa "const struct mdoc *mdoc"
-.Fc
-.Ft void
+.Fd "#define ASCII_NBRSP"
+.Fd "#define ASCII_HYPH"
+.Fd "#define ASCII_BREAK"
+.Ft struct mparse *

 .Fo mparse_alloc
 .Fo mparse_alloc

-.Fa "enum mparset inttype"
+.Fa "int options"

 .Fa "enum mandoclevel wlevel"
 .Fa "mandocmsg mmsg"
 .Fa "char *defos"
 .Fa "enum mandoclevel wlevel"
 .Fa "mandocmsg mmsg"
 .Fa "char *defos"

-.Fa "int quick"
+.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
 .Fc
 .Ft void
 .Fo mparse_free


@@ -130,6 +88,7 @@
 .Fa "struct mparse *parse"
 .Fa "struct mdoc **mdoc"
 .Fa "struct man **man"
 .Fa "struct mparse *parse"
 .Fa "struct mdoc **mdoc"
 .Fa "struct man **man"

+.Fa "char **sodest"

 .Fc
 .Ft "const char *"
 .Fo mparse_strerror
 .Fc
 .Ft "const char *"
 .Fo mparse_strerror


@@ -139,11 +98,45 @@
 .Fo mparse_strlevel
 .Fa "enum mandoclevel"
 .Fc
 .Fo mparse_strlevel
 .Fa "enum mandoclevel"
 .Fc

-.Vt extern const char * const * man_macronames;
+.In sys/types.h
+.In mandoc.h
+.In mdoc.h
+.Ft void
+.Fo mdoc_deroff
+.Fa "char **dest"
+.Fa "const struct mdoc_node *node"
+.Fc
+.Ft "const struct mdoc_meta *"
+.Fo mdoc_meta
+.Fa "const struct mdoc *mdoc"
+.Fc
+.Ft "const struct mdoc_node *"
+.Fo mdoc_node
+.Fa "const struct mdoc *mdoc"
+.Fc

 .Vt extern const char * const * mdoc_argnames;
 .Vt extern const char * const * mdoc_macronames;
 .Vt extern const char * const * mdoc_argnames;
 .Vt extern const char * const * mdoc_macronames;

-.Fd "#define ASCII_NBRSP"
-.Fd "#define ASCII_HYPH"
+.In sys/types.h
+.In mandoc.h
+.In man.h
+.Ft void
+.Fo man_deroff
+.Fa "char **dest"
+.Fa "const struct man_node *node"
+.Fc
+.Ft "const struct man_meta *"
+.Fo man_meta
+.Fa "const struct man *man"
+.Fc
+.Ft "const struct mparse *"
+.Fo man_mparse
+.Fa "const struct man *man"
+.Fc
+.Ft "const struct man_node *"
+.Fo man_node
+.Fa "const struct man *man"
+.Fc
+.Vt extern const char * const * man_macronames;

 .Sh DESCRIPTION
 The
 .Nm mandoc
 .Sh DESCRIPTION
 The
 .Nm mandoc


@@ -185,37 +178,22 @@ or invoke
 .Fn mparse_reset
 and parse new files.
 .El
 .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
 .Sh REFERENCE
 This section documents the functions, types, and variables available
 via

-.In mandoc.h .
+.In mandoc.h ,
+with the exception of those documented in
+.Xr mandoc_escape 3
+and
+.Xr mchars_alloc 3 .

 .Ss Types
 .Bl -ohang
 .Ss Types
 .Bl -ohang

-.It Vt "enum mandoc_esc"
-An escape sequence classification.

 .It Vt "enum mandocerr"
 A fatal error, error, or warning message during parsing.
 .It Vt "enum mandoclevel"
 A classification of an
 .Vt "enum mandocerr"
 as regards system operation.
 .It Vt "enum mandocerr"
 A fatal error, error, or warning message during parsing.
 .It Vt "enum mandoclevel"
 A classification of an
 .Vt "enum mandocerr"
 as regards system operation.

-.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"
-The type of parser when reading input.
-This should usually be
-.Dv MPARSE_AUTO
-for auto-detection.

 .It Vt "struct mparse"
 An opaque pointer to a running parse sequence.
 Created with
 .It Vt "struct mparse"
 An opaque pointer to a running parse sequence.
 Created with


@@ -231,38 +209,20 @@ messages emitted by the parser.
 .El
 .Ss Functions
 .Bl -ohang
 .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 the character after the
-.Sq \e
-as
-.Va end ;
-it will be set to the supremum of the parsed escape sequence unless
-returning
-.Dv ESCAPE_ERROR ,
-in which case the string is bogus and should be
-thrown away.
-If not
-.Dv ESCAPE_ERROR
-or
-.Dv 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
-.Dv NULL .
-Declared in
-.In mandoc.h ,
-implemented in
-.Pa mandoc.c .
+.It Fn man_deroff
+Obtain a text-only representation of a
+.Vt struct man_node ,
+including text contained in its child nodes.
+To be used on children of the pointer returned from
+.Fn man_node .
+When it is no longer needed, the pointer returned from
+.Fn man_deroff
+can be passed to
+.Xr free 3 .

 .It Fn man_meta
 .It Fn man_meta

-Obtain the meta-data of a successful parse.
+Obtain the meta-data of a successful
+.Xr man 7
+parse.

 This may only be used on a pointer returned by
 .Fn mparse_result .
 Declared in
 This may only be used on a pointer returned by
 .Fn mparse_result .
 Declared in


@@ -276,67 +236,29 @@ Declared in
 implemented in
 .Pa man.c .
 .It Fn man_node
 implemented in
 .Pa man.c .
 .It Fn man_node

-Obtain the root node of a successful parse.
+Obtain the root node of a successful
+.Xr man 7
+parse.

 This may only be used on a pointer returned by
 .Fn mparse_result .
 Declared in
 .In man.h ,
 implemented in
 .Pa man.c .
 This may only be used on a pointer returned by
 .Fn mparse_result .
 Declared in
 .In man.h ,
 implemented in
 .Pa man.c .

-.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 .
-Declared in
-.In mandoc.h ,
-implemented in
-.Pa chars.c .
-.It Fn mchars_free
-Free an object created with
-.Fn mchars_alloc .
-Declared in
-.In mandoc.h ,
-implemented in
-.Pa chars.c .
-.It Fn mchars_num2char
-Convert a character index (e.g., the \eN\(aq\(aq escape) into a
-printable ASCII character.
-Returns \e0 (the nil character) if the input sequence is malformed.
-Declared in
-.In mandoc.h ,
-implemented in
-.Pa chars.c .
-.It Fn mchars_num2uc
-Convert a hexadecimal character index (e.g., the \e[uNNNN] escape) into
-a Unicode codepoint.
-Returns \e0 (the nil character) if the input sequence is malformed.
-Declared in
-.In mandoc.h ,
-implemented in
-.Pa chars.c .
-.It Fn mchars_spec2cp
-Convert a special character into a valid Unicode codepoint.
-Returns \-1 on failure or a non-zero Unicode codepoint on success.
-Declared in
-.In mandoc.h ,
-implemented in
-.Pa chars.c .
-.It Fn mchars_spec2str
-Convert a special character into an ASCII string.
-Returns
-.Dv NULL
-on failure.
-Declared in
-.In mandoc.h ,
-implemented in
-.Pa chars.c .
+.It Fn mdoc_deroff
+Obtain a text-only representation of a
+.Vt struct mdoc_node ,
+including text contained in its child nodes.
+To be used on children of the pointer returned from
+.Fn mdoc_node .
+When it is no longer needed, the pointer returned from
+.Fn mdoc_deroff
+can be passed to
+.Xr free 3 .

 .It Fn mdoc_meta
 .It Fn mdoc_meta

-Obtain the meta-data of a successful parse.
+Obtain the meta-data of a successful
+.Xr mdoc
+parse.

 This may only be used on a pointer returned by
 .Fn mparse_result .
 Declared in
 This may only be used on a pointer returned by
 .Fn mparse_result .
 Declared in


@@ -344,7 +266,9 @@ Declared in
 implemented in
 .Pa mdoc.c .
 .It Fn mdoc_node
 implemented in
 .Pa mdoc.c .
 .It Fn mdoc_node

-Obtain the root node of a successful parse.
+Obtain the root node of a successful
+.Xr mdoc
+parse.

 This may only be used on a pointer returned by
 .Fn mparse_result .
 Declared in
 This may only be used on a pointer returned by
 .Fn mparse_result .
 Declared in


@@ -355,15 +279,33 @@ implemented in
 Allocate a parser.
 The arguments have the following effect:
 .Bl -tag -offset 5n -width inttype
 Allocate a parser.
 The arguments have the following effect:
 .Bl -tag -offset 5n -width inttype

-.It Ar inttype
-When set to
+.It Ar options
+When the

 .Dv MPARSE_MDOC
 or
 .Dv MPARSE_MDOC
 or

-.Dv MPARSE_MAN ,
-only that parser will be used.
-With
-.Dv MPARSE_AUTO ,
-the document type will be automatically detected.
+.Dv MPARSE_MAN
+bit is set, only that parser is used.
+Otherwise, the document type is automatically detected.
+.Pp
+When the
+.Dv MPARSE_SO
+bit is set,
+.Xr roff 7
+.Ic \&so
+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
+.Fn mparse_result .
+.Pp
+When the
+.Dv MPARSE_QUICK
+bit is set, parsing is aborted after the NAME section.
+This is for example useful in
+.Xr makewhatis 8
+.Fl Q
+to quickly build minimal databases.

 .It Ar wlevel
 Can be set to
 .Dv MANDOCLEVEL_FATAL ,
 .It Ar wlevel
 Can be set to
 .Dv MANDOCLEVEL_FATAL ,


@@ -384,9 +326,6 @@ macro, overriding the
 .Dv OSNAME
 preprocessor definition and the results of
 .Xr uname 3 .
 .Dv OSNAME
 preprocessor definition and the results of
 .Xr uname 3 .

-.It Ar quick
-When set, parsing is aborted after the NAME section.
-This is for example useful to quickly build minimal databases.

 .El
 .Pp
 The same parser may be used for multiple files so long as
 .El
 .Pp
 The same parser may be used for multiple files so long as


@@ -456,7 +395,7 @@ i.e., those where
 .Fn mparse_readfd
 returned less than MANDOCLEVEL_FATAL
 .Pc
 .Fn mparse_readfd
 returned less than MANDOCLEVEL_FATAL
 .Pc

-should invoke this function, in which case one of the two pointers will
+should invoke this function, in which case one of the three pointers will

 be filled in.
 Declared in
 .In mandoc.h ,
 be filled in.
 Declared in
 .In mandoc.h ,


@@ -510,6 +449,8 @@ The following non-printing characters may be embedded in text strings:
 A non-breaking space character.
 .It Dv ASCII_HYPH
 A soft hyphen.
 A non-breaking space character.
 .It Dv ASCII_HYPH
 A soft hyphen.

+.It Dv ASCII_BREAK
+A breakable zero-width space.

 .El
 .Pp
 Escape characters are also passed verbatim into text strings.
 .El
 .Pp
 Escape characters are also passed verbatim into text strings.


@@ -517,11 +458,9 @@ An escape character is a sequence of characters beginning with the
 backslash
 .Pq Sq \e .
 To construct human-readable text, these should be intercepted with
 backslash
 .Pq Sq \e .
 To construct human-readable text, these should be intercepted with

-.Fn mandoc_escape
-and converted with one of
-.Fn mchars_num2char ,
-.Fn mchars_spec2str ,
-and so on.
+.Xr mandoc_escape 3
+and converted with one the functions described in
+.Xr mchars_alloc 3 .

 .Ss Man Abstract Syntax Tree
 This AST is governed by the ontological rules dictated in
 .Xr man 7
 .Ss Man Abstract Syntax Tree
 This AST is governed by the ontological rules dictated in
 .Xr man 7


@@ -566,7 +505,7 @@ where capitalised non-terminals represent nodes.
 .El
 .Pp
 The only elements capable of nesting other elements are those with
 .El
 .Pp
 The only elements capable of nesting other elements are those with

-next-lint scope as documented in
+next-line scope as documented in

 .Xr man 7 .
 .Ss Mdoc Abstract Syntax Tree
 This AST is governed by the ontological
 .Xr man 7 .
 .Ss Mdoc Abstract Syntax Tree
 This AST is governed by the ontological


@@ -702,10 +641,13 @@ front-ends to
 .Xr mandoc 1
 are unable to render them in any meaningful way.
 Furthermore, behaviour when encountering badly-nested blocks is not
 .Xr mandoc 1
 are 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
+consistent across troff implementations, especially when using multiple

 levels of badly-nested blocks.
 .Sh SEE ALSO
 .Xr mandoc 1 ,
 levels of badly-nested blocks.
 .Sh SEE ALSO
 .Xr mandoc 1 ,

+.Xr mandoc_escape 3 ,
+.Xr mandoc_malloc 3 ,
+.Xr mchars_alloc 3 ,

 .Xr eqn 7 ,
 .Xr man 7 ,
 .Xr mandoc_char 7 ,
 .Xr eqn 7 ,
 .Xr man 7 ,
 .Xr mandoc_char 7 ,