docbook2mdoc: switch to mandoc(1)-style EXIT STATUS and DIAGNOSTICS

[schwarze@mandoc.bsd.lv]

Log Message:
-----------
switch to mandoc(1)-style EXIT STATUS and DIAGNOSTICS

Modified Files:
--------------
    docbook2mdoc:
        docbook2mdoc.1
        main.c
        node.h
        parse.c

Revision Data
-------------
Index: docbook2mdoc.1
===================================================================
RCS file: /home/cvs/mdocml/docbook2mdoc/docbook2mdoc.1,v
retrieving revision 1.9
retrieving revision 1.10
diff -Ldocbook2mdoc.1 -Ldocbook2mdoc.1 -u -p -r1.9 -r1.10
--- docbook2mdoc.1
+++ docbook2mdoc.1
@@ -42,7 +42,9 @@ is taken to be standard input.
 The arguments are as follows:
 .Bl -tag -width Ds
 .It Fl W
-Output non-fatal warning messages.
+Report warnings on standard error output, and if any occur, raise the
+.Sx EXIT STATUS
+to at least 2.
 .El
 .Pp
 .Nm
@@ -56,7 +58,27 @@ The only non-DocBook constructs recognis
 and <mml:*>, which is accepted and converted to
 .Xr eqn 7 .
 .Sh EXIT STATUS
-.Ex -std
+The
+.Nm
+utility exits with one of the following values:
+.Bl -tag -width 2n
+.It 0
+No error occurred, and if
+.Fl W
+was specified, no warning occurred either.
+.It 2
+At least one warning occurred, but no error, and
+.Fl W
+was specified.
+.It 3
+At least one parsing error occurred.
+.It 5
+Invalid command line arguments were specified.
+No input files have been read.
+.It 6
+Memory was exhausted.
+Parsing was aborted immediately.
+.El
 .Sh EXAMPLES
 To pipe a DocBook document
 .Pa foo.xml
@@ -65,6 +87,35 @@ through
 and a pager:
 .Pp
 .Dl $ docbook2mdoc foo.xml | mandoc -l
+.Sh DIAGNOSTICS
+Messages displayed by
+.Nm
+follow this format:
+.Pp
+.D1 Nm : Ar file : Ns Ar line : Ns Ar column : level : message
+.Pp
+The first three fields identify the
+.Ar file
+name,
+.Ar line
+number, and
+.Ar column
+number of the input file where the message was triggered.
+The line and column numbers start at 1.
+.Pp
+Message levels have the following meanings:
+.Bl -tag -width warning
+.It Sy fatal
+An operating system error occurred, typically memory exhaustion,
+and parsing was aborted immediately.
+.It Sy error
+Indicates a risk of information loss or severe misformatting,
+for example caused by unknown elements or missing include files.
+.It Sy warning
+Indicates a risk that the information shown or its formatting
+may mismatch the author's intent in minor ways.
+For example, mismatched or missing end tags are classified as warnings.
+.El
 .Sh SEE ALSO
 .Xr mandoc 1 ,
 .Xr eqn 7 ,
Index: node.h
===================================================================
RCS file: /home/cvs/mdocml/docbook2mdoc/node.h,v
retrieving revision 1.14
retrieving revision 1.15
diff -Lnode.h -Lnode.h -u -p -r1.14 -r1.15
--- node.h
+++ node.h
@@ -222,9 +222,10 @@ struct	pnode {
 struct	ptree {
 	struct pnode	*root;     /* The document element. */
 	int		 flags;
-#define	TREE_FAIL	 (1 << 0)  /* A fatal parse error occurred. */
-#define	TREE_EQN	 (1 << 1)  /* The document needs inline eqn(7). */
-#define	TREE_CLOSED	 (1 << 2)  /* The document element was closed. */
+#define	TREE_ERROR	 (1 << 0)  /* A parse error occurred. */
+#define	TREE_WARN	 (1 << 1)  /* A parser warning occurred. */
+#define	TREE_EQN	 (1 << 2)  /* The document needs inline eqn(7). */
+#define	TREE_CLOSED	 (1 << 3)  /* The document element was closed. */
 };
 
 
Index: parse.c
===================================================================
RCS file: /home/cvs/mdocml/docbook2mdoc/parse.c,v
retrieving revision 1.28
retrieving revision 1.29
diff -Lparse.c -Lparse.c -u -p -r1.28 -r1.29
--- parse.c
+++ parse.c
@@ -280,16 +280,24 @@ static void	 parse_fd(struct parse *, in
 
 
 static void
+fatal(struct parse *p)
+{
+	fprintf(stderr, "%s:%d:%d: FATAL: ", p->fname, p->line, p->col);
+	perror(NULL);
+	exit(6);
+}
+
+static void
 error_msg(struct parse *p, const char *fmt, ...)
 {
 	va_list		 ap;
 
-	fprintf(stderr, "%s:%d:%d: ", p->fname, p->line, p->col);
+	fprintf(stderr, "%s:%d:%d: ERROR: ", p->fname, p->line, p->col);
 	va_start(ap, fmt);
 	vfprintf(stderr, fmt, ap);
 	va_end(ap);
 	fputc('\n', stderr);
-	p->tree->flags |= TREE_FAIL;
+	p->tree->flags |= TREE_ERROR;
 }
 
 static void
@@ -300,11 +308,12 @@ warn_msg(struct parse *p, const char *fm
 	if ((p->flags & PFLAG_WARN) == 0)
 		return;
 
-	fprintf(stderr, "%s:%d:%d: warning: ", p->fname, p->line, p->col);
+	fprintf(stderr, "%s:%d:%d: WARNING: ", p->fname, p->line, p->col);
 	va_start(ap, fmt);
 	vfprintf(stderr, fmt, ap);
 	va_end(ap);
 	fputc('\n', stderr);
+	p->tree->flags |= TREE_WARN;
 }
 
 /*
@@ -327,10 +336,8 @@ xml_char(struct parse *ps, const char *p
 	}
 
 	if (ps->cur->node != NODE_TEXT) {
-		if ((dat = calloc(1, sizeof(*dat))) == NULL) {
-			perror(NULL);
-			exit(1);
-		}
+		if ((dat = calloc(1, sizeof(*dat))) == NULL)
+			fatal(ps);
 		dat->node = NODE_TEXT;
 		dat->spc = (ps->flags & PFLAG_SPC) != 0;
 		dat->parent = ps->cur;
@@ -348,11 +355,8 @@ xml_char(struct parse *ps, const char *p
 
 	assert(sz >= 0);
 	newsz = ps->cur->bsz + (ps->cur->bsz && (ps->flags & PFLAG_SPC)) + sz;
-	ps->cur->b = realloc(ps->cur->b, newsz + 1);
-	if (ps->cur->b == NULL) {
-		perror(NULL);
-		exit(1);
-	}
+	if ((ps->cur->b = realloc(ps->cur->b, newsz + 1)) == NULL)
+		fatal(ps);
 	if (ps->cur->bsz && (ps->flags & PFLAG_SPC))
 		ps->cur->b[ps->cur->bsz++] = ' ';
 	memcpy(ps->cur->b + ps->cur->bsz, p, sz);
@@ -420,10 +424,8 @@ xml_entity(struct parse *p, const char *
 				if ((ccp = pnode_getattr_raw(dat,
 				     ATTRKEY_DEFINITION, NULL)) == NULL)
 					continue;
-				if ((cp = strdup(ccp)) == NULL) {
-					perror(NULL);
-					exit(1);
-				}
+				if ((cp = strdup(ccp)) == NULL)
+					fatal(p);
 				pstate = PARSE_ELEM;
 				parse_string(p, cp, strlen(cp), &pstate, 0);
 				p->flags &= ~PFLAG_SPC;
@@ -437,10 +439,8 @@ xml_entity(struct parse *p, const char *
 
 	/* Create, append, and close out an entity node. */
 	if ((dat = calloc(1, sizeof(*dat))) == NULL ||
-	    (dat->b = dat->real = strdup(entity->roff)) == NULL) {
-		perror(NULL);
-		exit(1);
-	}
+	    (dat->b = dat->real = strdup(entity->roff)) == NULL)
+		fatal(p);
 	dat->node = NODE_ESCAPE;
 	dat->bsz = strlen(dat->b);
 	dat->spc = (p->flags & PFLAG_SPC) != 0;
@@ -503,10 +503,8 @@ xml_elem_start(struct parse *ps, const c
 	if (ps->tree->flags & TREE_CLOSED && ps->cur->parent == NULL)
 		warn_msg(ps, "element after end of document: <%s>", name);
 
-	if ((dat = calloc(1, sizeof(*dat))) == NULL) {
-		perror(NULL);
-		exit(1);
-	}
+	if ((dat = calloc(1, sizeof(*dat))) == NULL)
+		fatal(ps);
 
 	/*
 	 * Nodes that begin a new macro or request line or start by
@@ -595,20 +593,17 @@ xml_attrkey(struct parse *ps, const char
 		ps->flags &= ~PFLAG_ATTR;
 		return;
 	}
-	if ((attr = calloc(1, sizeof(*attr))) == NULL) {
-		perror(NULL);
-		exit(1);
-	}
+	if ((attr = calloc(1, sizeof(*attr))) == NULL)
+		fatal(ps);
+
 	attr->key = key;
 	attr->val = ATTRVAL__MAX;
 	if (value == NULL) {
 		attr->rawval = NULL;
 		ps->flags |= PFLAG_ATTR;
 	} else {
-		if ((attr->rawval = strdup(value)) == NULL) {
-			perror(NULL);
-			exit(1);
-		}
+		if ((attr->rawval = strdup(value)) == NULL)
+			fatal(ps);
 		ps->flags &= ~PFLAG_ATTR;
 	}
 	TAILQ_INSERT_TAIL(&ps->cur->attrq, attr, child);
@@ -627,10 +622,8 @@ xml_attrval(struct parse *ps, const char
 	if ((attr = TAILQ_LAST(&ps->cur->attrq, pattrq)) == NULL)
 		return;
 	if ((attr->val = attrval_parse(name)) == ATTRVAL__MAX &&
-	    (attr->rawval = strdup(name)) == NULL) {
-		perror(NULL);
-		exit(1);
-	}
+	    (attr->rawval = strdup(name)) == NULL)
+		fatal(ps);
 	ps->flags &= ~PFLAG_ATTR;
 }
 
Index: main.c
===================================================================
RCS file: /home/cvs/mdocml/docbook2mdoc/main.c,v
retrieving revision 1.4
retrieving revision 1.5
diff -Lmain.c -Lmain.c -u -p -r1.4 -r1.5
--- main.c
+++ main.c
@@ -75,18 +75,18 @@ main(int argc, char *argv[])
 
 	if ((parser = parse_alloc(warn)) == NULL) {
 		perror(NULL);
-		return 1;
+		return 6;
 	}
 	tree = parse_file(parser, fd, fname);
-	rc = tree->flags & TREE_FAIL ? 1 : 0;
+	rc = tree->flags & TREE_ERROR ? 3 : tree->flags & TREE_WARN ? 2 : 0;
 
 	/* Format. */
 
 	if (tree->root != NULL) {
-		if (rc)
+		if (rc > 2)
 			fputc('\n', stderr);
 		ptree_print(tree);
-		if (rc)
+		if (rc > 2)
 			fputs("\nThe output may be incomplete, see the "
 			    "parse error reported above.\n\n", stderr);
 	}
@@ -95,5 +95,5 @@ main(int argc, char *argv[])
 
 usage:
 	fprintf(stderr, "usage: %s [-W] [input_filename]\n", progname);
-	return 1;
+	return 5;
 }
--
 To unsubscribe send an email to source+unsubscribe@mandoc.bsd.lv