Annotation of src/usr.bin/mandoc/mdoc.3, Revision 1.1
1.1 ! kristaps 1: .\" $Id: mdoc.3,v 1.26 2009/03/31 13:50:19 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 mdoc 3
! 21: .Os
! 22: .\" SECTION
! 23: .Sh NAME
! 24: .Nm mdoc_alloc ,
! 25: .Nm mdoc_parseln ,
! 26: .Nm mdoc_endparse ,
! 27: .Nm mdoc_node ,
! 28: .Nm mdoc_meta ,
! 29: .Nm mdoc_free ,
! 30: .Nm mdoc_reset
! 31: .Nd mdoc macro compiler library
! 32: .\" SECTION
! 33: .Sh SYNOPSIS
! 34: .Fd #include <mdoc.h>
! 35: .Vt extern const char * const * mdoc_macronames;
! 36: .Vt extern const char * const * mdoc_argnames;
! 37: .Ft "struct mdoc *"
! 38: .Fn mdoc_alloc "void *data" "int pflags" "const struct mdoc_cb *cb"
! 39: .Ft int
! 40: .Fn mdoc_reset "struct mdoc *mdoc"
! 41: .Ft void
! 42: .Fn mdoc_free "struct mdoc *mdoc"
! 43: .Ft int
! 44: .Fn mdoc_parseln "struct mdoc *mdoc" "int line" "char *buf"
! 45: .Ft "const struct mdoc_node *"
! 46: .Fn mdoc_node "struct mdoc *mdoc"
! 47: .Ft "const struct mdoc_meta *"
! 48: .Fn mdoc_meta "struct mdoc *mdoc"
! 49: .Ft int
! 50: .Fn mdoc_endparse "struct mdoc *mdoc"
! 51: .\" SECTION
! 52: .Sh DESCRIPTION
! 53: The
! 54: .Nm mdoc
! 55: library parses lines of
! 56: .Xr mdoc 7
! 57: input (and
! 58: .Em only
! 59: mdoc) into an abstract syntax tree (AST).
! 60: .\" PARAGRAPH
! 61: .Pp
! 62: In general, applications initiate a parsing sequence with
! 63: .Fn mdoc_alloc ,
! 64: parse each line in a document with
! 65: .Fn mdoc_parseln ,
! 66: close the parsing session with
! 67: .Fn mdoc_endparse ,
! 68: operate over the syntax tree returned by
! 69: .Fn mdoc_node
! 70: and
! 71: .Fn mdoc_meta ,
! 72: then free all allocated memory with
! 73: .Fn mdoc_free .
! 74: The
! 75: .Fn mdoc_reset
! 76: function may be used in order to reset the parser for another input
! 77: sequence. See the
! 78: .Sx EXAMPLES
! 79: section for a full example.
! 80: .\" PARAGRAPH
! 81: .Pp
! 82: This section further defines the
! 83: .Sx Types ,
! 84: .Sx Functions
! 85: and
! 86: .Sx Variables
! 87: available to programmers. Following that, the
! 88: .Sx Abstract Syntax Tree
! 89: section documents the output tree.
! 90: .\" SUBSECTION
! 91: .Ss Types
! 92: Both functions (see
! 93: .Sx Functions )
! 94: and variables (see
! 95: .Sx Variables )
! 96: may use the following types:
! 97: .Bl -ohang -offset "XXXX"
! 98: .\" LIST-ITEM
! 99: .It Vt struct mdoc
! 100: An opaque type defined in
! 101: .Pa mdoc.c .
! 102: Its values are only used privately within the library.
! 103: .\" LIST-ITEM
! 104: .It Vt struct mdoc_cb
! 105: A set of message callbacks defined in
! 106: .Pa mdoc.h .
! 107: .\" LIST-ITEM
! 108: .It Vt struct mdoc_node
! 109: A parsed node. Defined in
! 110: .Pa mdoc.h .
! 111: See
! 112: .Sx Abstract Syntax Tree
! 113: for details.
! 114: .El
! 115: .\" SUBSECTION
! 116: .Ss Functions
! 117: Function descriptions follow:
! 118: .Bl -ohang -offset "XXXX"
! 119: .\" LIST-ITEM
! 120: .It Fn mdoc_alloc
! 121: Allocates a parsing structure. The
! 122: .Fa data
! 123: pointer is passed to callbacks in
! 124: .Fa cb ,
! 125: which are documented further in the header file.
! 126: The
! 127: .Fa pflags
! 128: arguments are defined in
! 129: .Pa mdoc.h .
! 130: Returns NULL on failure. If non-NULL, the pointer must be freed with
! 131: .Fn mdoc_free .
! 132: .\" LIST-ITEM
! 133: .It Fn mdoc_reset
! 134: Reset the parser for another parse routine. After its use,
! 135: .Fn mdoc_parseln
! 136: behaves as if invoked for the first time. If it returns 0, memory could
! 137: not be allocated.
! 138: .\" LIST-ITEM
! 139: .It Fn mdoc_free
! 140: Free all resources of a parser. The pointer is no longer valid after
! 141: invocation.
! 142: .\" LIST-ITEM
! 143: .It Fn mdoc_parseln
! 144: Parse a nil-terminated line of input. This line should not contain the
! 145: trailing newline. Returns 0 on failure, 1 on success. The input buffer
! 146: .Fa buf
! 147: is modified by this function.
! 148: .\" LIST-ITEM
! 149: .It Fn mdoc_endparse
! 150: Signals that the parse is complete. Note that if
! 151: .Fn mdoc_endparse
! 152: is called subsequent to
! 153: .Fn mdoc_node ,
! 154: the resulting tree is incomplete. Returns 0 on failure, 1 on success.
! 155: .\" LIST-ITEM
! 156: .It Fn mdoc_node
! 157: Returns the first node of the parse. Note that if
! 158: .Fn mdoc_parseln
! 159: or
! 160: .Fn mdoc_endparse
! 161: return 0, the tree will be incomplete.
! 162: .It Fn mdoc_meta
! 163: Returns the document's parsed meta-data. If this information has not
! 164: yet been supplied or
! 165: .Fn mdoc_parseln
! 166: or
! 167: .Fn mdoc_endparse
! 168: return 0, the data will be incomplete.
! 169: .El
! 170: .\" SUBSECTION
! 171: .Ss Variables
! 172: The following variables are also defined:
! 173: .Bl -ohang -offset "XXXX"
! 174: .\" LIST-ITEM
! 175: .It Va mdoc_macronames
! 176: An array of string-ified token names.
! 177: .\" LIST-ITEM
! 178: .It Va mdoc_argnames
! 179: An array of string-ified token argument names.
! 180: .El
! 181: .\" SUBSECTION
! 182: .Ss Abstract Syntax Tree
! 183: The
! 184: .Nm
! 185: functions produce an abstract syntax tree (AST) describing input in a
! 186: regular form. It may be reviewed at any time with
! 187: .Fn mdoc_nodes ;
! 188: however, if called before
! 189: .Fn mdoc_endparse ,
! 190: or after
! 191: .Fn mdoc_endparse
! 192: or
! 193: .Fn mdoc_parseln
! 194: fail, it may be incomplete.
! 195: .\" PARAGRAPH
! 196: .Pp
! 197: This AST is governed by the ontological
! 198: rules dictated in
! 199: .Xr mdoc 7
! 200: and derives its terminology accordingly.
! 201: .Qq In-line
! 202: elements described in
! 203: .Xr mdoc 7
! 204: are described simply as
! 205: .Qq elements .
! 206: .\" PARAGRAPH
! 207: .Pp
! 208: The AST is composed of
! 209: .Vt struct mdoc_node
! 210: nodes with block, head, body, element, root and text types as declared
! 211: by the
! 212: .Va type
! 213: field. Each node also provides its parse point (the
! 214: .Va line ,
! 215: .Va sec ,
! 216: and
! 217: .Va pos
! 218: fields), its position in the tree (the
! 219: .Va parent ,
! 220: .Va child ,
! 221: .Va next
! 222: and
! 223: .Va prev
! 224: fields) and some type-specific data.
! 225: .\" PARAGRAPH
! 226: .Pp
! 227: The tree itself is arranged according to the following normal form,
! 228: where capitalised non-terminals represent nodes.
! 229: .Pp
! 230: .Bl -tag -width "ELEMENTXX" -compact -offset "XXXX"
! 231: .\" LIST-ITEM
! 232: .It ROOT
! 233: \(<- mnode+
! 234: .It mnode
! 235: \(<- BLOCK | ELEMENT | TEXT
! 236: .It BLOCK
! 237: \(<- (HEAD [TEXT])+ [BODY [TEXT]] [TAIL [TEXT]]
! 238: .It BLOCK
! 239: \(<- BODY [TEXT] [TAIL [TEXT]]
! 240: .It ELEMENT
! 241: \(<- TEXT*
! 242: .It HEAD
! 243: \(<- mnode+
! 244: .It BODY
! 245: \(<- mnode+
! 246: .It TAIL
! 247: \(<- mnode+
! 248: .It TEXT
! 249: \(<- [[:alpha:]]*
! 250: .El
! 251: .\" PARAGRAPH
! 252: .Pp
! 253: Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
! 254: the BLOCK production. These refer to punctuation marks. Furthermore,
! 255: although a TEXT node will generally have a non-zero-length string, in
! 256: the specific case of
! 257: .Sq \&.Bd \-literal ,
! 258: an empty line will produce a zero-length string.
! 259: .\" SECTION
! 260: .Sh EXAMPLES
! 261: The following example reads lines from stdin and parses them, operating
! 262: on the finished parse tree with
! 263: .Fn parsed .
! 264: Note that, if the last line of the file isn't newline-terminated, this
! 265: will truncate the file's last character (see
! 266: .Xr fgetln 3 ) .
! 267: Further, this example does not error-check nor free memory upon failure.
! 268: .Bd -literal -offset "XXXX"
! 269: struct mdoc *mdoc;
! 270: struct mdoc_node *node;
! 271: char *buf;
! 272: size_t len;
! 273: int line;
! 274:
! 275: line = 1;
! 276: mdoc = mdoc_alloc(NULL, 0, NULL);
! 277:
! 278: while ((buf = fgetln(fp, &len))) {
! 279: buf[len - 1] = '\\0';
! 280: if ( ! mdoc_parseln(mdoc, line, buf))
! 281: errx(1, "mdoc_parseln");
! 282: line++;
! 283: }
! 284:
! 285: if ( ! mdoc_endparse(mdoc))
! 286: errx(1, "mdoc_endparse");
! 287: if (NULL == (node = mdoc_node(mdoc)))
! 288: errx(1, "mdoc_node");
! 289:
! 290: parsed(mdoc, node);
! 291: mdoc_free(mdoc);
! 292: .Ed
! 293: .\" SECTION
! 294: .Sh SEE ALSO
! 295: .Xr mandoc 1 ,
! 296: .Xr mdoc 7
! 297: .\" SECTION
! 298: .Sh AUTHORS
! 299: The
! 300: .Nm
! 301: utility was written by
! 302: .An Kristaps Dzonsons Aq kristaps@openbsd.org .
! 303: .\" SECTION
! 304: .Sh CAVEATS
! 305: .Bl -dash -compact
! 306: .\" LIST-ITEM
! 307: .It
! 308: The
! 309: .Sq \&.Xc
! 310: and
! 311: .Sq \&.Xo
! 312: macros aren't handled when used to span lines for the
! 313: .Sq \&.It
! 314: macro.
! 315: .\" LIST-ITEM
! 316: .It
! 317: The
! 318: .Sq \&.Bsx
! 319: macro family doesn't yet understand version arguments.
! 320: .\" LIST-ITEM
! 321: .It
! 322: If not given a value, the \-offset argument to
! 323: .Sq \&.Bd
! 324: and
! 325: .Sq \&.Bl
! 326: should be the width of
! 327: .Qq <string> ;
! 328: instead, a value of
! 329: .Li 10n
! 330: is provided.
! 331: .\" LIST-ITEM
! 332: .It
! 333: Columns widths in
! 334: .Sq \&.Bl \-column
! 335: should default to width
! 336: .Qq <stringx>
! 337: if not included.
! 338: .\" LIST-ITEM
! 339: .It
! 340: List-width suffix
! 341: .Qq m
! 342: isn't handled.
! 343: .\" LIST-ITEM
! 344: .It
! 345: Contents of the SYNOPSIS section aren't checked.
! 346: .El
![[BACK]](/icons/back.gif){kind=icon}
Return to mdoc.3 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / mandoc