===================================================================
RCS file: /cvs/mandoc/mdoc.h,v
retrieving revision 1.24
retrieving revision 1.29
diff -u -p -r1.24 -r1.29
--- mandoc/mdoc.h	2009/01/17 14:04:25	1.24
+++ mandoc/mdoc.h	2009/02/20 07:43:15	1.29
@@ -1,4 +1,4 @@
-/* $Id: mdoc.h,v 1.24 2009/01/17 14:04:25 kristaps Exp $ */
+/* $Id: mdoc.h,v 1.29 2009/02/20 07:43:15 kristaps Exp $ */
 /*
  * Copyright (c) 2008 Kristaps Dzonsons <kristaps@kth.se>
  *
@@ -195,9 +195,10 @@
 #define	MDOC_Symbolic	 61
 #define	MDOC_ARG_MAX	 62
 
+/* Warnings are either syntax or groff-compatibility. */
 enum	mdoc_warn {
-	WARN_SYNTAX,		/* Syntax warn (at line/col). */
-	WARN_COMPAT		/* Groff compat warn (at line/col). */
+	WARN_SYNTAX,
+	WARN_COMPAT
 };
 
 /* Possible values for the `At' macro. */
@@ -226,19 +227,6 @@ struct	mdoc_arg {
 	char		**value;
 };
 
-/*
- * Simplified grammar of syntax tree:
- *
- * MDOC_ROOT: root of tree
- * MDOC_TEXT: free-form text
- * MDOC_ELEM: elem [args] MDOC_TEXT...
- * MDOC_BLOCK, MDOC_HEAD, MDOC_BODY, MDOC_TAIL:
- *   MDOC_BLOCK:
- *     MDOC_HEAD [args] (MDOC_TEXT|MDOC_ELEM|MDOC_BLOCK)...
- *     MDOC_BODY (MDOC_TEXT|MDOC_ELEM|MDOC_BLOCK)...
- *     MDOC_TAIL (optional) (MDOC_TEXT|MDOC_ELEM|MDOC_BLOCK)...
- */
-
 /* Type of a syntax node. */
 enum	mdoc_type {
 	MDOC_TEXT,
@@ -340,22 +328,23 @@ enum	mdoc_arch {
 	ARCH_zaurus
 };
 
-/* Meta-information from prologue. */
+/* Information from prologue. */
 struct	mdoc_meta {
 	enum mdoc_msec	  msec;
 	enum mdoc_vol	  vol;
 	enum mdoc_arch	  arch;
 	time_t		  date;
-#define	META_TITLE_SZ	 (64)
-	char		  title[META_TITLE_SZ];
-#define	META_OS_SZ	 (64)
-	char		  os[META_OS_SZ];
+	char		 *title;
+	char		 *os;
+	char		 *name;
 };
 
+/* Text-only node. */
 struct	mdoc_text {
 	char		 *string;
 };
 
+/* Block (scoped) node. */
 struct	mdoc_block {
 	size_t		  argc;
 	struct mdoc_arg	 *argv;
@@ -364,6 +353,7 @@ struct	mdoc_block {
 	struct mdoc_node *tail;
 };
 
+/* In-line element node. */
 struct	mdoc_elem {
 	size_t		  sz;
 	char		**args;
@@ -371,13 +361,14 @@ struct	mdoc_elem {
 	struct mdoc_arg	 *argv;
 };
 
+/* Typed nodes of an AST node. */
 union	mdoc_data {
 	struct mdoc_text  text;
 	struct mdoc_elem  elem;
 	struct mdoc_block block;
 };
 
-/* Syntax node in parse tree. */
+/* Node in AST. */
 struct	mdoc_node {
 	struct mdoc_node *parent;
 	struct mdoc_node *child;
@@ -386,8 +377,12 @@ struct	mdoc_node {
 	int		  line;
 	int		  pos;
 	int		  tok;
+	int		  flags;
+#define	MDOC_VALID	 (1 << 0)
+#define	MDOC_ACTED	 (1 << 1)
 	enum mdoc_type	  type;
 	union mdoc_data	  data;
+	/* FIXME: have an enum mdoc_sec. */
 };
 
 /* Call-backs for parse messages. */
@@ -398,7 +393,10 @@ struct	mdoc_cb {
 			enum mdoc_warn, const char *);
 };
 
+/* Global table of macro names (`Bd', `Ed', etc.). */
 extern	const char *const *mdoc_macronames;
+
+/* Global table of argument names (`column', `tag', etc.). */
 extern	const char *const *mdoc_argnames;
 
 __BEGIN_DECLS
@@ -411,11 +409,14 @@ void	 	  mdoc_free(struct mdoc *);
 /* Allocate a new parser instance. */
 struct	mdoc	 *mdoc_alloc(void *data, const struct mdoc_cb *);
 
-/* Parse a single line (boolean retval). */
+/* Parse a single line in a stream (boolean retval). */
 int	 	  mdoc_parseln(struct mdoc *, int, char *buf);
 
-/* Get parse result or NULL. */
-const struct mdoc_node *mdoc_result(struct mdoc *);
+/* Get result first node (after mdoc_endparse!). */
+const struct mdoc_node *mdoc_node(struct mdoc *);
+
+/* Get result meta-information (after mdoc_endparse!). */
+const struct mdoc_meta *mdoc_meta(struct mdoc *);
 
 /* Signal end of parse sequence (boolean retval). */
 int		  mdoc_endparse(struct mdoc *);