ref: 102d4a76edbf450a4a59e413a5896343f74c349d
parent: 2af25ac0f9d5f298204422a2321895ce7c709f97
author: Werner Lemberg <[email protected]>
date: Tue Dec 2 05:27:40 EST 2014
[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/'.
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,20 @@
2014-12-02 Werner Lemberg <[email protected]>
+ [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 <[email protected]>
+
[docmaker] Ensure Python 3 compatibility.
* src/tools/docmaker/content.py (ContentProcessor::set_section,
--- a/src/tools/docmaker/content.py
+++ b/src/tools/docmaker/content.py
@@ -610,9 +610,15 @@
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 []
--- a/src/tools/docmaker/formatter.py
+++ b/src/tools/docmaker/formatter.py
@@ -183,13 +183,17 @@
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;
--- a/src/tools/docmaker/tohtml.py
+++ b/src/tools/docmaker/tohtml.py
@@ -582,6 +582,9 @@
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 @@
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>"