===================================================================
RCS file: /cvs/mandoc/man.h,v
retrieving revision 1.42
retrieving revision 1.48
diff -u -p -r1.42 -r1.48
--- mandoc/man.h	2010/07/31 23:52:58	1.42
+++ mandoc/man.h	2010/12/08 10:58:22	1.48
@@ -1,4 +1,4 @@
-/*	$Id: man.h,v 1.42 2010/07/31 23:52:58 schwarze Exp $ */
+/*	$Id: man.h,v 1.48 2010/12/08 10:58:22 kristaps Exp $ */
 /*
  * Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
  *
@@ -17,8 +17,9 @@
 #ifndef MAN_H
 #define MAN_H
 
-#include <time.h>
-
+/* 
+ * What follows is a list of ALL possible macros. 
+ */
 enum	mant {
 	MAN_br = 0,
 	MAN_TH,
@@ -42,24 +43,23 @@ enum	mant {
 	MAN_IR,
 	MAN_RI,
 	MAN_na,
-	MAN_i,
 	MAN_sp,
 	MAN_nf,
 	MAN_fi,
-	MAN_r,
 	MAN_RE,
 	MAN_RS,
 	MAN_DT,
 	MAN_UC,
 	MAN_PD,
-	MAN_Sp,
-	MAN_Vb,
-	MAN_Ve,
 	MAN_AT,
 	MAN_in,
+	MAN_ft,
 	MAN_MAX
 };
 
+/* 
+ * Type of a syntax node. 
+ */
 enum	man_type {
 	MAN_TEXT,
 	MAN_ELEM,
@@ -69,37 +69,44 @@ enum	man_type {
 	MAN_BODY
 };
 
+/* 
+ * Information from prologue. 
+ */
 struct	man_meta {
-	char		*msec;
-	time_t		 date;
-	char		*rawdate;
-	char		*vol;
-	char		*title;
-	char		*source;
+	char		*msec; /* `TH' section (1, 3p, etc.) */
+	time_t		 date; /* `TH' normalised date */
+	char		*rawdate; /* raw `TH' date */
+	char		*vol; /* `TH' volume */
+	char		*title; /* `TH' title (e.g., FOO) */
+	char		*source; /* `TH' source (e.g., GNU) */
 };
 
+/* 
+ * Single node in tree-linked AST. 
+ */
 struct	man_node {
-	struct man_node	*parent;
-	struct man_node	*child;
-	struct man_node	*next;
-	struct man_node	*prev;
-	int		 nchild;
+	struct man_node	*parent; /* parent AST node */
+	struct man_node	*child; /* first child AST node */
+	struct man_node	*next; /* sibling AST node */
+	struct man_node	*prev; /* prior sibling AST node */
+	int		 nchild; /* number children */
 	int		 line;
 	int		 pos;
-	enum mant	 tok;
+	enum mant	 tok; /* tok or MAN__MAX if none */
 	int		 flags;
-#define	MAN_VALID	(1 << 0)
-#define	MAN_ACTED	(1 << 1)
-#define	MAN_EOS		(1 << 2)
-	enum man_type	 type;
-	char		*string;
-	struct man_node	*head;
-	struct man_node	*body;
+#define	MAN_VALID	(1 << 0) /* has been validated */
+#define	MAN_ACTED	(1 << 1) /* has been acted upon */
+#define	MAN_EOS		(1 << 2) /* at sentence boundary */
+	enum man_type	 type; /* AST node type */
+	char		*string; /* TEXT node argument */
+	struct man_node	*head; /* BLOCK node HEAD ptr */
+	struct man_node	*body; /* BLOCK node BODY ptr */
 };
 
-#define	MAN_IGN_MACRO	 (1 << 0)
-#define	MAN_IGN_ESCAPE	 (1 << 2)
-
+/*
+ * Names of macros.  Index is enum mant.  Indexing into this returns
+ * the normalised name, e.g., man_macronames[MAN_SH] -> "SH".
+ */
 extern	const char *const *man_macronames;
 
 __BEGIN_DECLS
@@ -107,7 +114,7 @@ __BEGIN_DECLS
 struct	man;
 
 void	 	  man_free(struct man *);
-struct	man	 *man_alloc(struct regset *, void *, int, mandocmsg);
+struct	man	 *man_alloc(struct regset *, void *, mandocmsg);
 void		  man_reset(struct man *);
 int	 	  man_parseln(struct man *, int, char *, int);
 int		  man_endparse(struct man *);