Explicitly bless in the documentation, and fix in the man backend,

the practice of using \dt and \dd in anything other than the obvious
interleaving.

[originally from svn r4417]

3 files changed, 64 insertions, 5 deletions

diff --git a/bk_man.c b/bk_man.c
index d2607d9..1dcce64 100644
--- a/bk_man.c
+++ b/bk_man.c
@@ -124,6 +124,7 @@ void man_backend(paragraph *sourceform, keywordlist *keywords,
     paragraph *p;
     FILE *fp;
     manconfig conf;
+    int had_described_thing;
 
     IGNORE(unused);
     IGNORE(keywords);
@@ -165,6 +166,13 @@ void man_backend(paragraph *sourceform, keywordlist *keywords,
 
     fprintf(fp, ".UC\n");
 
+    had_described_thing = FALSE;
+#define cleanup_described_thing do { \
+    if (had_described_thing) \
+	fprintf(fp, "\n"); \
+    had_described_thing = FALSE; \
+} while (0)
+
     for (p = sourceform; p; p = p->next) switch (p->type) {
 	/*
 	 * Things we ignore because we've already processed them or
@@ -187,6 +195,7 @@ void man_backend(paragraph *sourceform, keywordlist *keywords,
       case para_Heading:
       case para_Subsect:
 
+	cleanup_described_thing;
 	{
 	    int depth;
 	    if (p->type == para_Subsect)
@@ -211,6 +220,7 @@ void man_backend(paragraph *sourceform, keywordlist *keywords,
 	 * Code paragraphs.
 	 */
       case para_Code:
+	cleanup_described_thing;
 	fprintf(fp, ".PP\n");
 	man_codepara(fp, p->words, conf.charset);
 	break;
@@ -220,6 +230,7 @@ void man_backend(paragraph *sourceform, keywordlist *keywords,
 	 */
       case para_Normal:
       case para_Copyright:
+	cleanup_described_thing;
 	fprintf(fp, ".PP\n");
 	man_text(fp, p->words, TRUE, 0, &conf);
 	break;
@@ -231,6 +242,9 @@ void man_backend(paragraph *sourceform, keywordlist *keywords,
       case para_BiblioCited:
       case para_Bullet:
       case para_NumberedList:
+	if (p->type != para_Description)
+	    cleanup_described_thing;
+
 	if (p->type == para_Bullet) {
 	    char *bullettext;
 	    man_convert(conf.bullet, -1, &bullettext, QUOTE_QUOTES,
@@ -242,22 +256,34 @@ void man_backend(paragraph *sourceform, keywordlist *keywords,
 	    man_text(fp, p->kwtext, FALSE, QUOTE_QUOTES, &conf);
 	    fprintf(fp, "\"\n");
 	} else if (p->type == para_Description) {
-	    /*
-	     * Do nothing; the .xP for this paragraph is the .IP
-	     * which has come before it in the DescribedThing.
-	     */
+	    if (had_described_thing) {
+		/*
+		 * Do nothing; the .xP for this paragraph is the
+		 * .IP which has come before it in the
+		 * DescribedThing.
+		 */
+	    } else {
+		/*
+		 * A \dd without a preceding \dt is given a blank
+		 * one.
+		 */
+		fprintf(fp, ".IP \"\"\n");
+	    }
 	} else if (p->type == para_BiblioCited) {
 	    fprintf(fp, ".IP \"");
 	    man_text(fp, p->kwtext, FALSE, QUOTE_QUOTES, &conf);
 	    fprintf(fp, "\"\n");
 	}
 	man_text(fp, p->words, TRUE, 0, &conf);
+	had_described_thing = FALSE;
 	break;
 
       case para_DescribedThing:
+	cleanup_described_thing;
 	fprintf(fp, ".IP \"");
 	man_text(fp, p->words, FALSE, QUOTE_QUOTES, &conf);
 	fprintf(fp, "\"\n");
+	had_described_thing = TRUE;
 	break;
 
       case para_Rule:
@@ -265,18 +291,22 @@ void man_backend(paragraph *sourceform, keywordlist *keywords,
 	 * This isn't terribly good. Anyone who wants to do better
 	 * should feel free!
 	 */
+	cleanup_described_thing;
 	fprintf(fp, ".PP\n----------------------------------------\n");
 	break;
 
       case para_LcontPush:
       case para_QuotePush:
+	cleanup_described_thing;
 	fprintf(fp, ".RS\n");
       	break;
       case para_LcontPop:
       case para_QuotePop:
+	cleanup_described_thing;
 	fprintf(fp, ".RE\n");
 	break;
     }
+    cleanup_described_thing;
 
     /*
      * Tidy up.
diff --git a/doc/input.but b/doc/input.but
index 4166ee7..f0097c5 100644
--- a/doc/input.but
+++ b/doc/input.but
@@ -672,6 +672,16 @@ This produces the following output:
 
 }
 
+If you really want to, you are allowed to use \c{\\dt} and \c{\\dd}
+without strictly interleaving them (multiple consecutive \c{\\dt}s
+or consecutive \c{\\dd}s, or a description list starting with
+\c{\\dd} or ending with \c{\\dt}). This is probably most useful if
+you are listing a sequence of things with \c{\\dt}, but only some of
+them actually need \c{\\dd} descriptions. You should \e{not} use
+multiple consecutive \c{\\dd}s to provide a multi-paragraph
+definition of something; that's what \c{\\lcont} is for, as
+explained in \k{input-list-continuation}.
+
 \S2{input-list-continuation} \ii{Continuing list items} into further
 paragraphs
 
diff --git a/inputs/test.but b/inputs/test.but
index 58d10ef..87bcaf7 100644
--- a/inputs/test.but
+++ b/inputs/test.but
@@ -32,7 +32,7 @@ a bit]
 
 \define{eur} \u20AC{EUR }
 
-\versionid $Id: test.but,v 1.34 2004/07/16 11:54:04 simon Exp $
+\versionid $Id: test.but,v 1.35 2004/08/06 12:17:56 simon Exp $
 
 \C{ch\\ap} First chapter title; for similar wrapping reasons this
 chapter title will be ludicrously long. I wonder how much more
@@ -157,6 +157,25 @@ to make up for it. I don't know. These mammals. Pa-thetic.
 \dd An exemplary contributor to the global economy. Unless he's CMOT
 Dibbler.
 
+This is a much more interesting description list, testing
+consecutive \c{\\dt}s and consecutive \c{\\dd}s:
+
+\dt One
+
+\dt Two
+
+\dt Three
+
+\dd Ay
+
+\dt Four
+
+\dd Bee
+
+\dd Cee
+
+\dd Dee
+
 A-paragraph-full-of-hyphens-to-test-the-idea-that-word-wrapping-can-happen-somewhere-in-all-this-hyphenatory-nonsense.
 
 A\-paragraph\-full\-of\-nonbreaking\-hyphens\-to\-test\-the\-idea\-that\-word\-wrapping\-misses\-them.