Re-merged old port-building routines.

11 files changed, 135 insertions, 48 deletions

diff --git a/DESCR b/DESCR
index 4d25d8df..fe90abf6 100644
--- a/DESCR
+++ b/DESCR
@@ -1 +1,2 @@
-Compile mdoc macros into mark-up languages such as HTML and XML.
+The mdocml utility interfaces with the mdoc library to compile
+mdoc-roff documents into a variety of output formats.
diff --git a/Makefile b/Makefile
index 1d14a893..92637c33 100644
--- a/Makefile
+++ b/Makefile
@@ -2,57 +2,63 @@ VERSION	= 1.1.0
 
 CFLAGS += -W -Wall -Wno-unused-parameter -g 
 
-LNS	= macro.ln mdoc.ln mdocml.ln hash.ln strings.ln xstd.ln argv.ln validate.ln action.ln tree.ln
+LIBLNS	= macro.ln mdoc.ln hash.ln strings.ln xstd.ln argv.ln \
+	  validate.ln action.ln
+
+BINLNS	= tree.ln mdocml.ln
+
+LNS	= $(LIBLNS) $(BINLNS)
 
 LLNS	= llib-llibmdoc.ln llib-lmdocml.ln
 
 LIBS	= libmdoc.a
 
-OBJS	= macro.o mdoc.o mdocml.o hash.o strings.o xstd.o argv.o validate.o action.o tree.o
+LIBOBJS	= macro.o mdoc.o hash.o strings.o xstd.o argv.o \
+	  validate.o action.o
+
+BINOBJS	= tree.o mdocml.o
+
+OBJS	= $(LIBOBJS) $(BINOBJS)
 
-SRCS	= macro.c mdoc.c mdocml.c hash.c strings.c xstd.c argv.c validate.c action.c tree.c
+SRCS	= macro.c mdoc.c mdocml.c hash.c strings.c xstd.c argv.c \
+	  validate.c action.c tree.c
 
-HEADS	= mdoc.h
+HEADS	= mdoc.h private.h
 
 BINS	= mdocml
 
 CLEAN	= $(BINS) $(LNS) $(LLNS) $(LIBS) $(OBJS)
 
-SUCCESS	= test.1 test.7 test.8 test.9 test.11 test.11 test.12 test.16 \
-	  test.17 test.19 test.20 test.21 test.23 test.25 test.27     \
-	  test.28 test.29 test.31 test.32 test.33 test.34 test.35     \
-	  test.38 test.39 test.40 test.41 test.42 test.43 test.44     \
-	  test.45 test.46 test.47 test.49 test.51 test.52 test.53     \
-	  test.54 test.55 test.56 test.57 test.58 test.59 test.60     \
-	  test.62 test.67 test.68 test.71 test.72 test.73 test.74     \
-	  test.75
-
-FAIL	= test.0 test.2 test.3 test.4 test.5 test.6 test.13 test.14   \
-	  test.15 test.18 test.22 test.24 test.26 test.30 test.36     \
-	  test.37 test.48 test.50 test.61 test.63 test.64 test.65     \
-	  test.66 test.69 test.70
+INSTALL	= $(SRCS) $(HEADS) Makefile Makefile.port DESCR
 
 all:	$(BINS)
 
 lint:	$(LLNS)
 
-mdocml:	mdocml.o tree.o libmdoc.a
-	$(CC) $(CFLAGS) -o $@ mdocml.o tree.o libmdoc.a
-
 clean:
 	rm -f $(CLEAN)
 
-regress: mdocml $(SUCCESS) $(FAIL)
-	@for f in $(SUCCESS) ; do \
-		echo "./mdocml $$f" ; \
-		./mdocml $$f || exit 1 ; \
-	done
+dist:	mdocml-$(VERSION).tar.gz
+
+port:	mdocml-oport-$(VERSION).tar.gz
 
-llib-llibmdoc.ln: macro.ln mdoc.ln hash.ln strings.ln xstd.ln argv.ln validate.ln action.ln
-	$(LINT) $(LINTFLAGS) -Clibmdoc mdoc.ln macro.ln hash.ln strings.ln xstd.ln argv.ln validate.ln action.ln
+install:
+	mkdir -p $(PREFIX)/bin/
+	mkdir -p $(PREFIX)/include/mdoc/
+	mkdir -p $(PREFIX)/lib/
+	mkdir -p $(PREFIX)/man/man1/
+	install -m 0755 mdocml $(PREFIX)/bin/
+	install -m 0444 mdocml.1 $(PREFIX)/man/man1/
+	install -m 0444 mdoc.3 $(PREFIX)/man/man3/
+	install -m 0644 libmdoc.a $(PREFIX)/lib/
+	install -m 0444 mdoc.h $(PREFIX)/include/
 
-llib-lmdocml.ln: mdocml.ln tree.ln llib-llibmdoc.ln
-	$(LINT) $(LINTFLAGS) -Cmdocml mdocml.ln tree.ln llib-llibmdoc.ln
+uninstall:
+	rm -f $(PREFIX)/bin/mdocml
+	rm -f $(PREFIX)/man/man1/mdocml.1
+	rm -f $(PREFIX)/man/man3/mdoc.3
+	rm -f $(PREFIX)/lib/libmdoc.a
+	rm -f $(PREFIX)/include/mdoc.h
 
 macro.ln: macro.c private.h
 
@@ -96,6 +102,37 @@ action.o: action.c private.h
 
 private.h: mdoc.h
 
-libmdoc.a: macro.o mdoc.o hash.o strings.o xstd.o argv.o validate.o action.o
-	$(AR) rs $@ macro.o mdoc.o hash.o strings.o xstd.o argv.o validate.o action.o
+mdocml-oport-$(VERSION).tar.gz: Makefile.port DESCR
+	mkdir -p .dist/mdocml/pkg
+	sed -e "s!@VERSION@!$(VERSION)!" Makefile.port > .dist/mdocml/Makefile
+	md5 mdocml-$(VERSION).tar.gz > .dist/mdocml/distinfo
+	rmd160 mdocml-$(VERSION).tar.gz >> .dist/mdocml/distinfo
+	sha1 mdocml-$(VERSION).tar.gz >> .dist/mdocml/distinfo
+	install -m 0644 DESCR .dist/mdocml/pkg/DESCR
+	echo @comment $$OpenBSD$$ > .dist/mdocml/pkg/PLIST
+	echo bin/mdocml >> .dist/mdocml/pkg/PLIST
+	echo lib/libmdoc.a >> .dist/mdocml/pkg/PLIST
+	echo include/mdoc.h >> .dist/mdocml/pkg/PLIST
+	echo @man man/man1/mdocml.1 >> .dist/mdocml/pkg/PLIST
+	echo @man man/man3/mdoc.3 >> .dist/mdocml/pkg/PLIST
+	( cd .dist/ && tar zcf ../$@ mdocml/ )
+	rm -rf .dist/
+
+mdocml-$(VERSION).tar.gz: $(INSTALL)
+	mkdir -p .dist/mdocml/mdocml-$(VERSION)/
+	install -m 0644 $(INSTALL) .dist/mdocml/mdocml-$(VERSION)/
+	( cd .dist/mdocml/ && tar zcf ../../$@ mdocml-$(VERSION)/ )
+	rm -rf .dist/
+
+llib-llibmdoc.ln: $(LIBLNS)
+	$(LINT) $(LINTFLAGS) -Clibmdoc $(LIBLNS)
+
+llib-lmdocml.ln: $(BINLNS) llib-llibmdoc.ln
+	$(LINT) $(LINTFLAGS) -Cmdocml $(BINLNS) llib-llibmdoc.ln
+
+libmdoc.a: $(LIBOBJS)
+	$(AR) rs $@ $(LIBOBJS)
+
+mdocml:	$(BINOBJS) libmdoc.a
+	$(CC) $(CFLAGS) -o $@ $(BINOBJS) libmdoc.a
 
diff --git a/Makefile.port b/Makefile.port
index 8e002b5d..deda68ae 100644
--- a/Makefile.port
+++ b/Makefile.port
@@ -1,6 +1,6 @@
 # $OpenBSD$
 
-COMMENT=		compile mdoc macros into mark-up languages
+COMMENT=		mdoc macro compiler
 
 DISTNAME=		mdocml-@VERSION@
 CATEGORIES=		devel
diff --git a/action.c b/action.c
index abe3b901..98d2b042 100644
--- a/action.c
+++ b/action.c
@@ -22,6 +22,11 @@
 
 #include "private.h"
 
+/*
+ * Actions are executed on macros after they've been post-validated: in
+ * other words, a macro will not be "acted upon" until all of its
+ * children have been filled in (post-fix order).
+ */
 
 struct	actions {
 	int	(*post)(struct mdoc *);
@@ -149,6 +154,11 @@ const	struct actions mdoc_actions[MDOC_MAX] = {
 };
 
 
+/*
+ * The `Nm' macro sets the document's name when used the first time with
+ * an argument.  Subsequent calls without a value will result in the
+ * name value being used.
+ */
 static int
 post_nm(struct mdoc *mdoc)
 {
@@ -169,6 +179,10 @@ post_nm(struct mdoc *mdoc)
 }
 
 
+/*
+ * We keep track of the current section in order to provide warnings on
+ * section ordering, per-section macros, and so on.
+ */
 static int
 post_sh(struct mdoc *mdoc)
 {
@@ -188,6 +202,9 @@ post_sh(struct mdoc *mdoc)
 }
 
 
+/* 
+ * Prologue title must be parsed into document meta-data.
+ */
 static int
 post_dt(struct mdoc *mdoc)
 {
@@ -233,6 +250,9 @@ post_dt(struct mdoc *mdoc)
 }
 
 
+/* 
+ * Prologue operating system must be parsed into document meta-data.
+ */
 static int
 post_os(struct mdoc *mdoc)
 {
@@ -253,6 +273,9 @@ post_os(struct mdoc *mdoc)
 }
 
 
+/* 
+ * Prologue date must be parsed into document meta-data.
+ */
 static int
 post_dd(struct mdoc *mdoc)
 {
@@ -299,6 +322,10 @@ post_dd(struct mdoc *mdoc)
 }
 
 
+/*
+ * The end document shouldn't have the prologue macros as part of the
+ * syntax tree (they encompass only meta-data). 
+ */
 static int
 post_prologue(struct mdoc *mdoc)
 {
diff --git a/argv.c b/argv.c
index bd050efb..b9fbb11d 100644
--- a/argv.c
+++ b/argv.c
@@ -25,9 +25,14 @@
 
 #include "private.h"
 
+/*
+ * Parse arguments and parameters of macros.  Arguments follow the
+ * syntax of `-arg [val [valN...]]', while parameters are free-form text
+ * following arguments (if any).  This file must correctly handle the
+ * strange punctuation rules dictated by groff.
+ */
+
 /* FIXME: .It called with -column and quoted arguments. */
-/* FIXME: if arguments are quoted, they should not be later parsed for
- * macros. */
 
 static	int		 lookup(int, const char *);
 static	int		 parse(struct mdoc *, int,
diff --git a/hash.c b/hash.c
index 9e32aa05..95a1cce7 100644
--- a/hash.c
+++ b/hash.c
@@ -25,6 +25,12 @@
 
 #include "private.h"
 
+/*
+ * Routines for the perfect-hash hashtable used by the parser to look up
+ * tokens by their string-ified names (`.Fl' -> MDOC_Fl).  The
+ * allocation penalty for this is 27 * 26 * sizeof(ptr).
+ */
+
 
 void
 mdoc_tokhash_free(void *htab)
diff --git a/mdoc.c b/mdoc.c
index ca45b4ae..eab289de 100644
--- a/mdoc.c
+++ b/mdoc.c
@@ -26,6 +26,12 @@
 
 #include "private.h"
 
+/*
+ * Main caller in the libmdoc library.  This begins the parsing routine,
+ * handles allocation of data, and so forth.  Most of the "work" is done
+ * in macro.c, but this orchestrates who does what, when.
+ */
+
 const	char *const __mdoc_macronames[MDOC_MAX] = {		 
 	"\\\"",		"Dd",		"Dt",		"Os",
 	"Sh",		"Ss",		"Pp",		"D1",
@@ -83,6 +89,8 @@ const	char *const __mdoc_argnames[MDOC_ARG_MAX] = {
 	"emphasis",		"symbolic",
 	};
 
+/* Central table of library: who gets parsed how. */
+
 const	struct mdoc_macro __mdoc_macros[MDOC_MAX] = {
 	{ NULL, 0 }, /* \" */
 	{ macro_constant, MDOC_PROLOGUE }, /* Dd */
@@ -199,7 +207,6 @@ const	char * const *mdoc_macronames = __mdoc_macronames;
 const	char * const *mdoc_argnames = __mdoc_argnames;
 const	struct mdoc_macro * const mdoc_macros = __mdoc_macros;
 
-
 static	struct mdoc_arg	 *argdup(size_t, const struct mdoc_arg *);
 static	void		  argfree(size_t, struct mdoc_arg *);
 static	void	  	  argcpy(struct mdoc_arg *, 
diff --git a/mdoc.h b/mdoc.h
index ef2b5d3a..a232128b 100644
--- a/mdoc.h
+++ b/mdoc.h
@@ -390,6 +390,7 @@ struct	mdoc_node {
 #define	MDOC_ACTED	 (1 << 1)
 	enum mdoc_type	  type;
 	union mdoc_data	  data;
+	/* FIXME: have an enum mdoc_sec. */
 };
 
 /* Call-backs for parse messages. */
diff --git a/mdocml.1 b/mdocml.1
index ef1db230..8d73924c 100644
--- a/mdocml.1
+++ b/mdocml.1
@@ -18,7 +18,8 @@ The
 .Nm
 utility interfaces the
 .Xr mdoc 3
-library to validate and parse mdoc-macro documents.  Arguments follow:
+library to scan, parse and validate mdoc-macro documents.  Arguments
+follow:
 .Bl -tag -width "\-Werr... "
 .It Fl W Ns Ar err...
 Print warning messages.  May be set to 
diff --git a/validate.c b/validate.c
index 7a1151db..a3f69ecd 100644
--- a/validate.c
+++ b/validate.c
@@ -21,6 +21,14 @@
 
 #include "private.h"
 
+/*
+ * Pre- and post-validate macros as they're parsed.  Pre-validation
+ * occurs when the macro has been detected and its arguments parsed.
+ * Post-validation occurs when all child macros have also been parsed.
+ * In the ELEMENT case, this is simply the parameters of the macro; in
+ * the BLOCK case, this is the HEAD, BODY, TAIL and so on.
+ */
+
 typedef	int	(*v_pre)(struct mdoc *, struct mdoc_node *);
 typedef	int	(*v_post)(struct mdoc *);
 
diff --git a/xstd.c b/xstd.c
index dee1ff35..b5820d70 100644
--- a/xstd.c
+++ b/xstd.c
@@ -23,12 +23,16 @@
 
 #include "private.h"
 
+/*
+ * Contains wrappers for common functions to simplify their general
+ * usage throughout this codebase.
+ */
+
 #ifdef __linux__
 extern	size_t		 strlcat(char *, const char *, size_t);
 extern	size_t		 strlcpy(char *, const char *, size_t);
 #endif
 
-
 int
 xstrcmp(const char *p1, const char *p2)
 {
@@ -36,7 +40,6 @@ xstrcmp(const char *p1, const char *p2)
 	return(0 == strcmp(p1, p2));
 }
 
-
 int
 xstrlcat(char *dst, const char *src, size_t sz)
 {
@@ -44,7 +47,6 @@ xstrlcat(char *dst, const char *src, size_t sz)
 	return(strlcat(dst, src, sz) < sz);
 }
 
-
 int
 xstrlcpy(char *dst, const char *src, size_t sz)
 {
@@ -52,8 +54,6 @@ xstrlcpy(char *dst, const char *src, size_t sz)
 	return(strlcpy(dst, src, sz) < sz);
 }
 
-
-
 void *
 xcalloc(size_t num, size_t sz)
 {
@@ -64,7 +64,6 @@ xcalloc(size_t num, size_t sz)
 	return(p);
 }
 
-
 char *
 xstrdup(const char *p)
 {
@@ -75,7 +74,6 @@ xstrdup(const char *p)
 	return(pp);
 }
 
-
 int
 xstrlcats(char *buf, const struct mdoc_node *n, size_t sz)
 {
@@ -97,9 +95,6 @@ xstrlcats(char *buf, const struct mdoc_node *n, size_t sz)
 	return(1);
 }
 
-
-
-
 #ifdef __linux__
 /*	$OpenBSD: strlcat.c,v 1.13 2005/08/08 08:05:37 espie Exp $	*/
 
@@ -151,7 +146,6 @@ strlcat(char *dst, const char *src, size_t siz)
 	return(dlen + (s - src));	/* count does not include NUL */
 }
 
-
 size_t
 strlcpy(char *dst, const char *src, size_t siz)
 {