Commit 102d4a76edbf450a4a59e413a5896343f74c349d
2014-12-02T10:27:40
[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/'.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
diff --git a/ChangeLog b/ChangeLog
index 7142efd..9721bda 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,20 @@
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 (ContentProcessor::set_section,
diff --git a/src/tools/docmaker/content.py b/src/tools/docmaker/content.py
index 76a06a7..728b592 100644
--- a/src/tools/docmaker/content.py
+++ b/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 []
diff --git a/src/tools/docmaker/formatter.py b/src/tools/docmaker/formatter.py
index e8fda83..b1c88be 100644
--- a/src/tools/docmaker/formatter.py
+++ b/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;
diff --git a/src/tools/docmaker/tohtml.py b/src/tools/docmaker/tohtml.py
index 34379a1..e05512a 100644
--- a/src/tools/docmaker/tohtml.py
+++ b/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>"