Annotation of mandoc/man.3, Revision 1.1
1.1 ! kristaps 1: .\" $Id: mdoc.3,v 1.24 2009/03/26 16:23:22 kristaps Exp $
! 2: .\"
! 3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
! 4: .\"
! 5: .\" Permission to use, copy, modify, and distribute this software for any
! 6: .\" purpose with or without fee is hereby granted, provided that the
! 7: .\" above copyright notice and this permission notice appear in all
! 8: .\" copies.
! 9: .\"
! 10: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
! 11: .\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
! 12: .\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
! 13: .\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
! 14: .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
! 15: .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
! 16: .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
! 17: .\" PERFORMANCE OF THIS SOFTWARE.
! 18: .\"
! 19: .Dd $Mdocdate$
! 20: .Dt man 3
! 21: .Os
! 22: .\" SECTION
! 23: .Sh NAME
! 24: .Nm man_alloc ,
! 25: .Nm man_parseln ,
! 26: .Nm man_endparse ,
! 27: .Nm man_node ,
! 28: .Nm man_meta ,
! 29: .Nm man_free ,
! 30: .Nm man_reset
! 31: .Nd man macro compiler library
! 32: .\" SECTION
! 33: .Sh SYNOPSIS
! 34: .Fd #include <man.h>
! 35: .Vt extern const char * const * man_macronames;
! 36: .Ft "struct man *"
! 37: .Fn man_alloc "void *data" "int pflags" "const struct man_cb *cb"
! 38: .Ft void
! 39: .Fn man_reset "struct man *man"
! 40: .Ft void
! 41: .Fn man_free "struct man *man"
! 42: .Ft int
! 43: .Fn man_parseln "struct man *man" "int line" "char *buf"
! 44: .Ft "const struct man_node *"
! 45: .Fn man_node "struct man *man"
! 46: .Ft "const struct man_meta *"
! 47: .Fn man_meta "struct man *man"
! 48: .Ft int
! 49: .Fn man_endparse "struct man *man"
! 50: .\" SECTION
! 51: .Sh DESCRIPTION
! 52: The
! 53: .Nm man
! 54: library parses lines of
! 55: .Xr man 7
! 56: input (and
! 57: .Em only
! 58: man) into an abstract syntax tree (AST).
! 59: .\" PARAGRAPH
! 60: .Pp
! 61: In general, applications initiate a parsing sequence with
! 62: .Fn man_alloc ,
! 63: parse each line in a document with
! 64: .Fn man_parseln ,
! 65: close the parsing session with
! 66: .Fn man_endparse ,
! 67: operate over the syntax tree returned by
! 68: .Fn man_node
! 69: and
! 70: .Fn man_meta ,
! 71: then free all allocated memory with
! 72: .Fn man_free .
! 73: The
! 74: .Fn man_reset
! 75: function may be used in order to reset the parser for another input
! 76: sequence. See the
! 77: .Sx EXAMPLES
! 78: section for a full example.
! 79: .\" PARAGRAPH
! 80: .Pp
! 81: This section further defines the
! 82: .Sx Types ,
! 83: .Sx Functions
! 84: and
! 85: .Sx Variables
! 86: available to programmers. Following that, the
! 87: .Sx Abstract Syntax Tree
! 88: section documents the output tree.
! 89: .\" SUBSECTION
! 90: .Ss Types
! 91: Both functions (see
! 92: .Sx Functions )
! 93: and variables (see
! 94: .Sx Variables )
! 95: may use the following types:
! 96: .Bl -ohang -offset "XXXX"
! 97: .\" LIST-ITEM
! 98: .It Vt struct man
! 99: An opaque type defined in
! 100: .Pa man.c .
! 101: Its values are only used privately within the library.
! 102: .\" LIST-ITEM
! 103: .It Vt struct man_cb
! 104: A set of message callbacks defined in
! 105: .Pa man.h .
! 106: .\" LIST-ITEM
! 107: .It Vt struct man_node
! 108: A parsed node. Defined in
! 109: .Pa man.h .
! 110: See
! 111: .Sx Abstract Syntax Tree
! 112: for details.
! 113: .El
! 114: .\" SUBSECTION
! 115: .Ss Functions
! 116: Function descriptions follow:
! 117: .Bl -ohang -offset "XXXX"
! 118: .\" LIST-ITEM
! 119: .It Fn man_alloc
! 120: Allocates a parsing structure. The
! 121: .Fa data
! 122: pointer is passed to callbacks in
! 123: .Fa cb ,
! 124: which are documented further in the header file.
! 125: The
! 126: .Fa pflags
! 127: arguments are defined in
! 128: .Pa man.h .
! 129: Returns NULL on failure. If non-NULL, the pointer must be freed with
! 130: .Fn man_free .
! 131: .\" LIST-ITEM
! 132: .It Fn man_reset
! 133: Reset the parser for another parse routine. After its use,
! 134: .Fn man_parseln
! 135: behaves as if invoked for the first time.
! 136: .\" LIST-ITEM
! 137: .It Fn man_free
! 138: Free all resources of a parser. The pointer is no longer valid after
! 139: invocation.
! 140: .\" LIST-ITEM
! 141: .It Fn man_parseln
! 142: Parse a nil-terminated line of input. This line should not contain the
! 143: trailing newline. Returns 0 on failure, 1 on success. The input buffer
! 144: .Fa buf
! 145: is modified by this function.
! 146: .\" LIST-ITEM
! 147: .It Fn man_endparse
! 148: Signals that the parse is complete. Note that if
! 149: .Fn man_endparse
! 150: is called subsequent to
! 151: .Fn man_node ,
! 152: the resulting tree is incomplete. Returns 0 on failure, 1 on success.
! 153: .\" LIST-ITEM
! 154: .It Fn man_node
! 155: Returns the first node of the parse. Note that if
! 156: .Fn man_parseln
! 157: or
! 158: .Fn man_endparse
! 159: return 0, the tree will be incomplete.
! 160: .It Fn man_meta
! 161: Returns the document's parsed meta-data. If this information has not
! 162: yet been supplied or
! 163: .Fn man_parseln
! 164: or
! 165: .Fn man_endparse
! 166: return 0, the data will be incomplete.
! 167: .El
! 168: .\" SUBSECTION
! 169: .Ss Variables
! 170: The following variables are also defined:
! 171: .Bl -ohang -offset "XXXX"
! 172: .\" LIST-ITEM
! 173: .It Va man_macronames
! 174: An array of string-ified token names.
! 175: .El
! 176: .\" SUBSECTION
! 177: .Ss Abstract Syntax Tree
! 178: The
! 179: .Nm
! 180: functions produce an abstract syntax tree (AST) describing input in a
! 181: regular form. It may be reviewed at any time with
! 182: .Fn man_nodes ;
! 183: however, if called before
! 184: .Fn man_endparse ,
! 185: or after
! 186: .Fn man_endparse
! 187: or
! 188: .Fn man_parseln
! 189: fail, it may be incomplete.
! 190: .\" PARAGRAPH
! 191: .Pp
! 192: This AST is governed by the ontological
! 193: rules dictated in
! 194: .Xr man 7
! 195: and derives its terminology accordingly.
! 196: .\" PARAGRAPH
! 197: .Pp
! 198: The AST is composed of
! 199: .Vt struct man_node
! 200: nodes with element, root and text types as declared
! 201: by the
! 202: .Va type
! 203: field. Each node also provides its parse point (the
! 204: .Va line ,
! 205: .Va sec ,
! 206: and
! 207: .Va pos
! 208: fields), its position in the tree (the
! 209: .Va parent ,
! 210: .Va child ,
! 211: .Va next
! 212: and
! 213: .Va prev
! 214: fields) and some type-specific data.
! 215: .\" PARAGRAPH
! 216: .Pp
! 217: The tree itself is arranged according to the following normal form,
! 218: where capitalised non-terminals represent nodes.
! 219: .Pp
! 220: .Bl -tag -width "ELEMENTXX" -compact -offset "XXXX"
! 221: .\" LIST-ITEM
! 222: .It ROOT
! 223: \(<- mnode+
! 224: .It mnode
! 225: \(<- ELEMENT | TEXT
! 226: .It ELEMENT
! 227: \(<- ELEMENT | TEXT*
! 228: .It TEXT
! 229: \(<- [[:alpha:]]*
! 230: .El
! 231: .\" PARAGRAPH
! 232: .Pp
! 233: The only elements capable of nesting other elements are those with
! 234: next-lint scope as documented in
! 235: .Xr man 7 .
! 236: .\" SECTION
! 237: .Sh EXAMPLES
! 238: The following example reads lines from stdin and parses them, operating
! 239: on the finished parse tree with
! 240: .Fn parsed .
! 241: Note that, if the last line of the file isn't newline-terminated, this
! 242: will truncate the file's last character (see
! 243: .Xr fgetln 3 ) .
! 244: Further, this example does not error-check nor free memory upon failure.
! 245: .Bd -literal -offset "XXXX"
! 246: struct man *man;
! 247: struct man_node *node;
! 248: char *buf;
! 249: size_t len;
! 250: int line;
! 251:
! 252: line = 1;
! 253: man = man_alloc(NULL, 0, NULL);
! 254:
! 255: while ((buf = fgetln(fp, &len))) {
! 256: buf[len - 1] = '\\0';
! 257: if ( ! man_parseln(man, line, buf))
! 258: errx(1, "man_parseln");
! 259: line++;
! 260: }
! 261:
! 262: if ( ! man_endparse(man))
! 263: errx(1, "man_endparse");
! 264: if (NULL == (node = man_node(man)))
! 265: errx(1, "man_node");
! 266:
! 267: parsed(man, node);
! 268: man_free(man);
! 269: .Ed
! 270: .\" SECTION
! 271: .Sh SEE ALSO
! 272: .Xr mandoc 1 ,
! 273: .Xr man 7
! 274: .\" SECTION
! 275: .Sh AUTHORS
! 276: The
! 277: .Nm
! 278: utility was written by
! 279: .An Kristaps Dzonsons Aq kristaps@openbsd.org .
CVSweb
![[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