[docmaker] Honour empty lines in `<Order>' section element.

This greatly improves the readability of the `Synopsis' links.

* src/tools/docmaker/content.py (DocBlock::get_markup_words_all):
Insert string `/empty/' between items.

* src/tools/docmaker/formatter.py (Formatter::section_dump): Make it
robust against nonexistent keys.

* src/tools/docmaker/tohtml.py (HtmlFormatter::section_enter): Emit
empty <td> elements for `/empty/'.

ChangeLog

@@ -1,3 +1,18 @@
+2014-12-02  Werner Lemberg  <wl@gnu.org>
+
+	[docmaker] Honour empty lines in `<Order>' section element.
+
+	This greatly improves the readability of the `Synopsis' links.
+
+	* src/tools/docmaker/content.py (DocBlock::get_markup_words_all):
+	Insert string `/empty/' between items.
+
+	* src/tools/docmaker/formatter.py (Formatter::section_dump): Make it
+	robust against nonexistent keys.
+
+	* src/tools/docmaker/tohtml.py (HtmlFormatter::section_enter): Emit
+	empty <td> elements for `/empty/'.
+
 2014-12-02  Werner Lemberg  <wl@gnu.org>
 
 	[docmaker] Ensure Python 3 compatibility.

src/tools/docmaker/content.py

@@ -610,9 +610,15 @@ class  DocBlock:
     def  get_markup_words_all( self, tag_name ):
         try:
             m = self.get_markup( tag_name )
-            return [word
-                      for items in m.fields[0].items
-                        for word in items.words]
+            words = m.fields[0].items[0].words
+            for item in m.fields[0].items[1:]:
+                # We honour empty lines in an `<Order>' section element by
+                # adding the sentinel `/empty/'.  The formatter should then
+                # convert it to an appropriate representation in the
+                # `section_enter' function.
+                words.append( "/empty/" )
+                words += item.words
+            return words
         except:
             return []
 

src/tools/docmaker/formatter.py

@@ -183,13 +183,17 @@ class  Formatter:
 
         for name in section.block_names:
             skip_entry = 0
-            block = self.identifiers[name]
-            # `block_names' can contain field names also, which we filter out
-            for markup in block.markups:
-                if markup.tag == 'values':
-                    for field in markup.fields:
-                        if field.name == name:
-                            skip_entry = 1
+            try:
+                block = self.identifiers[name]
+                # `block_names' can contain field names also,
+                # which we filter out
+                for markup in block.markups:
+                    if markup.tag == 'values':
+                        for field in markup.fields:
+                            if field.name == name:
+                                skip_entry = 1
+            except:
+                skip_entry = 1   # this happens e.g. for `/empty/' entries
 
             if skip_entry:
               continue;

src/tools/docmaker/tohtml.py

@@ -582,6 +582,9 @@ class  HtmlFormatter( Formatter ):
                 columns = 1
 
             count = len( section.block_names )
+            # don't handle last entry if it is empty
+            if section.block_names[-1] == "/empty/":
+                count -= 1
             rows  = ( count + columns - 1 ) // columns
 
             for r in range( rows ):
@@ -591,8 +594,9 @@ class  HtmlFormatter( Formatter ):
                     line = line + '<td>'
                     if i < count:
                         name = section.block_names[i]
-                        line = ( line + '<a href="#' + name + '">'
-                                 + name + '</a>' )
+                        if name != "/empty/":
+                            line = ( line + '<a href="#' + name + '">'
+                                     + name + '</a>' )
 
                     line = line + '</td>'
                 line = line + "</tr>"