From 51b80f5088ac30124cca09023af7fcccc4b63653 Mon Sep 17 00:00:00 2001 From: Kristaps Dzonsons Date: Tue, 22 Mar 2011 10:02:50 +0000 Subject: Step 3: consolidate manuals. The parse functions in mdoc.h, roff.h, and man.h are now part of libmandoc.h, so remove these from their respective manuals (they're no longer public-facing and we don't need a libmandoc.3 (yet?)). Before that, move the juicy data (parse tree syntax) into new-born mandoc.3. Peck around in Makefile and index.sgml to reflect reality. --- man.3 | 283 ------------------------------------------------------------------ 1 file changed, 283 deletions(-) delete mode 100644 man.3 (limited to 'man.3') diff --git a/man.3 b/man.3 deleted file mode 100644 index 2f1ae508..00000000 --- a/man.3 +++ /dev/null @@ -1,283 +0,0 @@ -.\" $Id: man.3,v 1.30 2011/02/09 09:18:15 kristaps Exp $ -.\" -.\" Copyright (c) 2009-2010 Kristaps Dzonsons -.\" -.\" Permission to use, copy, modify, and distribute this software for any -.\" purpose with or without fee is hereby granted, provided that the above -.\" copyright notice and this permission notice appear in all copies. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES -.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF -.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR -.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN -.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF -.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -.\" -.Dd $Mdocdate: February 9 2011 $ -.Dt MAN 3 -.Os -.Sh NAME -.Nm man , -.Nm man_addeqn , -.Nm man_addspan , -.Nm man_alloc , -.Nm man_endparse , -.Nm man_free , -.Nm man_meta , -.Nm man_node , -.Nm man_parseln , -.Nm man_reset -.Nd man macro compiler library -.Sh SYNOPSIS -.In mandoc.h -.In man.h -.Vt extern const char * const * man_macronames; -.Ft int -.Fo man_addeqn -.Fa "struct man *man" -.Fa "const struct eqn *eqn" -.Fc -.Ft int -.Fo man_addspan -.Fa "struct man *man" -.Fa "const struct tbl_span *span" -.Fc -.Ft "struct man *" -.Fo man_alloc -.Fa "struct regset *regs" -.Fa "void *data" -.Fa "mandocmsg msgs" -.Fc -.Ft int -.Fn man_endparse "struct man *man" -.Ft void -.Fn man_free "struct man *man" -.Ft "const struct man_meta *" -.Fn man_meta "const struct man *man" -.Ft "const struct man_node *" -.Fn man_node "const struct man *man" -.Ft int -.Fo man_parseln -.Fa "struct man *man" -.Fa "int line" -.Fa "char *buf" -.Fc -.Ft void -.Fn man_reset "struct man *man" -.Sh DESCRIPTION -The -.Nm -library parses lines of -.Xr man 7 -input into an abstract syntax tree (AST). -.Pp -In general, applications initiate a parsing sequence with -.Fn man_alloc , -parse each line in a document with -.Fn man_parseln , -close the parsing session with -.Fn man_endparse , -operate over the syntax tree returned by -.Fn man_node -and -.Fn man_meta , -then free all allocated memory with -.Fn man_free . -The -.Fn man_reset -function may be used in order to reset the parser for another input -sequence. -.Pp -Beyond the full set of macros defined in -.Xr man 7 , -the -.Nm -library also accepts the following macro: -.Pp -.Bl -tag -width Ds -compact -.It PD -Has no effect. -Handled as a current-scope line macro. -.El -.Ss Types -.Bl -ohang -.It Vt struct man -An opaque type. -Its values are only used privately within the library. -.It Vt struct man_node -A parsed node. -See -.Sx Abstract Syntax Tree -for details. -.El -.Ss Functions -If -.Fn man_addeqn , -.Fn man_addspan , -.Fn man_parseln , -or -.Fn man_endparse -return 0, calls to any function but -.Fn man_reset -or -.Fn man_free -will raise an assertion. -.Bl -ohang -.It Fn man_addeqn -Add an equation to the parsing stream. -Returns 0 on failure, 1 on success. -.It Fn man_addspan -Add a table span to the parsing stream. -Returns 0 on failure, 1 on success. -.It Fn man_alloc -Allocates a parsing structure. -The -.Fa data -pointer is passed to -.Fa msgs . -Always returns a valid pointer. -The pointer must be freed with -.Fn man_free . -.It Fn man_reset -Reset the parser for another parse routine. -After its use, -.Fn man_parseln -behaves as if invoked for the first time. -.It Fn man_free -Free all resources of a parser. -The pointer is no longer valid after invocation. -.It Fn man_parseln -Parse a nil-terminated line of input. -This line should not contain the trailing newline. -Returns 0 on failure, 1 on success. -The input buffer -.Fa buf -is modified by this function. -.It Fn man_endparse -Signals that the parse is complete. -Returns 0 on failure, 1 on success. -.It Fn man_node -Returns the first node of the parse. -.It Fn man_meta -Returns the document's parsed meta-data. -.El -.Ss Variables -The following variables are also defined: -.Bl -ohang -.It Va man_macronames -An array of string-ified token names. -.El -.Ss Abstract Syntax Tree -The -.Nm -functions produce an abstract syntax tree (AST) describing input in a -regular form. -It may be reviewed at any time with -.Fn man_nodes ; -however, if called before -.Fn man_endparse , -or after -.Fn man_endparse -or -.Fn man_parseln -fail, it may be incomplete. -.Pp -This AST is governed by the ontological rules dictated in -.Xr man 7 -and derives its terminology accordingly. -.Pp -The AST is composed of -.Vt struct man_node -nodes with element, root and text types as declared by the -.Va type -field. -Each node also provides its parse point (the -.Va line , -.Va sec , -and -.Va pos -fields), its position in the tree (the -.Va parent , -.Va child , -.Va next -and -.Va prev -fields) and some type-specific data. -.Pp -The tree itself is arranged according to the following normal form, -where capitalised non-terminals represent nodes. -.Pp -.Bl -tag -width "ELEMENTXX" -compact -.It ROOT -\(<- mnode+ -.It mnode -\(<- ELEMENT | TEXT | BLOCK -.It BLOCK -\(<- HEAD BODY -.It HEAD -\(<- mnode* -.It BODY -\(<- mnode* -.It ELEMENT -\(<- ELEMENT | TEXT* -.It TEXT -\(<- [[:alpha:]]* -.El -.Pp -The only elements capable of nesting other elements are those with -next-lint scope as documented in -.Xr man 7 . -.Sh EXAMPLES -The following example reads lines from stdin and parses them, operating -on the finished parse tree with -.Fn parsed . -This example does not error-check nor free memory upon failure. -.Bd -literal -offset indent -struct regset regs; -struct man *man; -struct man_node *node; -char *buf; -size_t len; -int line; - -bzero(®s, sizeof(struct regset)); -line = 1; -man = man_alloc(®s, NULL, NULL); -buf = NULL; -alloc_len = 0; - -while ((len = getline(&buf, &alloc_len, stdin)) >= 0) { - if (len && buflen[len - 1] = '\en') - buf[len - 1] = '\e0'; - if ( ! man_parseln(man, line, buf)) - errx(1, "man_parseln"); - line++; -} - -free(buf); - -if ( ! man_endparse(man)) - errx(1, "man_endparse"); -if (NULL == (node = man_node(man))) - errx(1, "man_node"); - -parsed(man, node); -man_free(man); -.Ed -.Pp -To compile this, execute -.Pp -.Dl % cc main.c libman.a libmandoc.a -.Pp -where -.Pa main.c -is the example file. -.Sh SEE ALSO -.Xr mandoc 1 , -.Xr man 7 -.Sh AUTHORS -The -.Nm -library was written by -.An Kristaps Dzonsons Aq kristaps@bsd.lv . -- cgit v1.2.3-56-ge451