===================================================================
RCS file: /cvs/mandoc/mandoc.h,v
retrieving revision 1.18
retrieving revision 1.24
diff -u -p -r1.18 -r1.24
--- mandoc/mandoc.h	2010/08/20 01:02:07	1.18
+++ mandoc/mandoc.h	2010/11/29 15:45:15	1.24
@@ -1,4 +1,4 @@
-/*	$Id: mandoc.h,v 1.18 2010/08/20 01:02:07 schwarze Exp $ */
+/*	$Id: mandoc.h,v 1.24 2010/11/29 15:45:15 kristaps Exp $ */
 /*
  * Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
  *
@@ -17,63 +17,63 @@
 #ifndef MANDOC_H
 #define MANDOC_H
 
-/*
- * This contains declarations that are available system-wide.
- */
-
 #define ASCII_NBRSP	 31  /* non-breaking space */
 #define	ASCII_HYPH	 30  /* breakable hyphen */
 
-__BEGIN_DECLS
-
+/*
+ * Status level.  This refers to both internal status (i.e., whilst
+ * running, when warnings/errors are reported) and an indicator of a
+ * threshold of when to halt (when said internal state exceeds the
+ * threshold).
+ */
 enum	mandoclevel {
 	MANDOCLEVEL_OK = 0,
 	MANDOCLEVEL_RESERVED,
-	MANDOCLEVEL_WARNING,
-	MANDOCLEVEL_ERROR,
-	MANDOCLEVEL_FATAL,
-	MANDOCLEVEL_BADARG,
-	MANDOCLEVEL_SYSERR,
+	MANDOCLEVEL_WARNING, /* warnings: syntax, whitespace, etc. */
+	MANDOCLEVEL_ERROR, /* input has been thrown away */
+	MANDOCLEVEL_FATAL, /* input is borked */
+	MANDOCLEVEL_BADARG, /* bad argument in invocation */
+	MANDOCLEVEL_SYSERR, /* system error */
 	MANDOCLEVEL_MAX
 };
 
+/*
+ * All possible things that can go wrong within a parse, be it libroff,
+ * libmdoc, or libman.
+ */
 enum	mandocerr {
 	MANDOCERR_OK,
 
-	MANDOCERR_WARNING, /* ===== end of warnings ===== */
-
+	MANDOCERR_WARNING, /* ===== start of warnings ===== */
 	MANDOCERR_UPPERCASE, /* text should be uppercase */
 	MANDOCERR_SECOOO, /* sections out of conventional order */
 	MANDOCERR_SECREP, /* section name repeats */
 	MANDOCERR_PROLOGOOO, /* out of order prologue */
 	MANDOCERR_PROLOGREP, /* repeated prologue entry */
 	MANDOCERR_LISTFIRST, /* list type must come first */
-	MANDOCERR_BADSTANDARD, /* bad standard */
-	MANDOCERR_BADLIB, /* bad library */
 	MANDOCERR_BADTAB, /* tab in non-literal context */
 	MANDOCERR_BADESCAPE, /* bad escape sequence */
 	MANDOCERR_BADQUOTE, /* unterminated quoted string */
 	MANDOCERR_NOWIDTHARG, /* argument requires the width argument */
 	/* FIXME: merge with MANDOCERR_IGNARGV. */
 	MANDOCERR_WIDTHARG, /* superfluous width argument */
-	MANDOCERR_IGNARGV, /* ignoring argument */
 	MANDOCERR_BADDATE, /* bad date argument */
 	MANDOCERR_BADWIDTH, /* bad width argument */
 	MANDOCERR_BADMSEC, /* unknown manual section */
 	MANDOCERR_SECMSEC, /* section not in conventional manual section */
 	MANDOCERR_EOLNSPACE, /* end of line whitespace */
 	MANDOCERR_SCOPENEST, /* blocks badly nested */
-	MANDOCERR_SCOPEEXIT, /* scope open on exit */
 
-	MANDOCERR_ERROR, /* ===== end of errors ===== */
-
+	MANDOCERR_ERROR, /* ===== start of errors ===== */
 	MANDOCERR_NAMESECFIRST, /* NAME section must come first */
 	MANDOCERR_BADBOOL, /* bad Boolean value */
 	MANDOCERR_CHILD, /* child violates parent syntax */
 	MANDOCERR_BADATT, /* bad AT&T symbol */
+	MANDOCERR_BADSTANDARD, /* bad standard */
 	MANDOCERR_LISTREP, /* list type repeated */
 	MANDOCERR_DISPREP, /* display type repeated */
 	MANDOCERR_ARGVREP, /* argument repeated */
+	MANDOCERR_IGNARGV, /* ignoring argument */
 	MANDOCERR_NONAME, /* manual name not yet set */
 	MANDOCERR_MACROOBS, /* obsolete macro ignored */
 	MANDOCERR_MACROEMPTY, /* empty macro ignored */
@@ -89,6 +89,7 @@ enum	mandocerr {
 	MANDOCERR_ARGCOUNT, /* argument count wrong */
 	MANDOCERR_NOSCOPE, /* no such block is open */
 	MANDOCERR_SCOPEREP, /* scope already open */
+	MANDOCERR_SCOPEEXIT, /* scope open on exit */
 	/* FIXME: merge following with MANDOCERR_ARGCOUNT */
 	MANDOCERR_NOARGS, /* macro requires line argument(s) */
 	MANDOCERR_NOBODY, /* macro requires body argument(s) */
@@ -99,16 +100,15 @@ enum	mandocerr {
 	MANDOCERR_FONTTYPE, /* missing font type */
 	MANDOCERR_ARGSLOST, /* line argument(s) will be lost */
 	MANDOCERR_BODYLOST, /* body argument(s) will be lost */
+	MANDOCERR_IGNPAR, /* paragraph macro ignored */
 
-	MANDOCERR_FATAL, /* ===== end of fatal errors ===== */
-
+	MANDOCERR_FATAL, /* ===== start of fatal errors ===== */
 	MANDOCERR_COLUMNS, /* column syntax is inconsistent */
 	/* FIXME: this should be a MANDOCERR_ERROR */
 	MANDOCERR_NESTEDDISP, /* displays may not be nested */
 	MANDOCERR_BADDISP, /* unsupported display type */
 	MANDOCERR_SCOPEFATAL, /* blocks badly nested */
 	MANDOCERR_SYNTNOSCOPE, /* no scope to rewind: syntax violated */
-	MANDOCERR_SYNTSCOPE, /* scope broken, syntax violated */
 	MANDOCERR_SYNTLINESCOPE, /* line scope broken, syntax violated */
 	MANDOCERR_SYNTARGVCOUNT, /* argument count wrong, violates syntax */
 	MANDOCERR_SYNTCHILD, /* child violates parent syntax */
@@ -117,16 +117,26 @@ enum	mandocerr {
 	MANDOCERR_NODOCPROLOG, /* no document prologue */
 	MANDOCERR_UTSNAME, /* utsname system call failed */
 	MANDOCERR_MEM, /* static buffer exhausted */
-
 	MANDOCERR_MAX
 };
 
+/*
+ * Available registers (set in libroff, accessed elsewhere).
+ */
 enum	regs {
-	REG_nS = 0,	/* register: nS */
+	REG_nS = 0,
 	REG__MAX
 };
 
 /*
+ * A register (struct reg) can consist of many types: this consists of
+ * normalised types from the original string form.
+ */
+union	regval {
+	unsigned  u; /* unsigned integer */
+};
+
+/*
  * A single register entity.  If "set" is zero, the value of the
  * register should be the default one, which is per-register.  It's
  * assumed that callers know which type in "v" corresponds to which
@@ -134,9 +144,7 @@ enum	regs {
  */
 struct	reg {
 	int		  set; /* whether set or not */
-	union {
-		unsigned  u; /* unsigned integer */
-	} v;
+	union regval	  v; /* parsed data */
 };
 
 /*
@@ -147,6 +155,8 @@ struct	reg {
 struct	regset {
 	struct reg	  regs[REG__MAX];
 };
+
+__BEGIN_DECLS
 
 /*
  * Callback function for warnings, errors, and fatal errors as they