Commit 98afe3f5c8490837adc2fc60ae483ad57a76f76e
2015-11-28T11:58:49
[docmaker] Allow references to section names. In the reference, we show the section's title enclosed in single quotes. * src/tools/docmaker/formatter.py (Formatter::__init__): Collect section names as identifiers. * src/tools/docmaker/tohtml.py (section_title_header): Split into... (section_title_header1, section_title_header2): ... these two strings. (HtmlFormatter::make_block_url, make_html_word, html_source_quote): Handle sections. (HtmlFormatter::section_enter): Updated to add `id' HTML attribute.
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 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134
diff --git a/ChangeLog b/ChangeLog
index 85e00c1..e188de7 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,20 @@
+2015-11-28 Werner Lemberg <wl@gnu.org>
+
+ [docmaker] Allow references to section names.
+
+ In the reference, we show the section's title enclosed in single
+ quotes.
+
+ * src/tools/docmaker/formatter.py (Formatter::__init__): Collect
+ section names as identifiers.
+
+ * src/tools/docmaker/tohtml.py (section_title_header): Split into...
+ (section_title_header1, section_title_header2): ... these two
+ strings.
+ (HtmlFormatter::make_block_url, make_html_word, html_source_quote):
+ Handle sections.
+ (HtmlFormatter::section_enter): Updated to add `id' HTML attribute.
+
2015-11-27 Tamas Kenez <tamas.kenez@adasworks.com>
[cmake] Add script to test the config module.
diff --git a/src/tools/docmaker/formatter.py b/src/tools/docmaker/formatter.py
index f0a8808..8669739 100644
--- a/src/tools/docmaker/formatter.py
+++ b/src/tools/docmaker/formatter.py
@@ -56,6 +56,11 @@ class Formatter:
self.block_index = self.identifiers.keys()
self.block_index.sort( key = index_key )
+ # also add section names to dictionary (without making them appear
+ # in the index)
+ for section in self.sections:
+ self.add_identifier( section.name, section )
+
def add_identifier( self, name, block ):
if name in self.identifiers:
# duplicate name!
diff --git a/src/tools/docmaker/tohtml.py b/src/tools/docmaker/tohtml.py
index 7b5c6c4..a7206f5 100644
--- a/src/tools/docmaker/tohtml.py
+++ b/src/tools/docmaker/tohtml.py
@@ -164,7 +164,8 @@ html_footer = """\
"""
# The header and footer used for each section.
-section_title_header = "<h1>"
+section_title_header1 = '<h1 id="'
+section_title_header2 = '">'
section_title_footer = "</h1>"
# The header and footer used for code segments.
@@ -309,7 +310,14 @@ class HtmlFormatter( Formatter ):
def make_block_url( self, block, name = None ):
if name == None:
name = block.name
- return self.make_section_url( block.section ) + "#" + name
+
+ try:
+ section_url = self.make_section_url( block.section )
+ except:
+ # we already have a section
+ section_url = self.make_section_url( block )
+
+ return section_url + "#" + name
def make_html_word( self, word ):
"""Analyze a simple word to detect cross-references and markup."""
@@ -326,7 +334,18 @@ class HtmlFormatter( Formatter ):
# normalize url, following RFC 3986
url = string.replace( url, "[", "(" )
url = string.replace( url, "]", ")" )
- return '<a href="' + url + '">' + name + '</a>' + rest
+
+ try:
+ # for sections, display title
+ url = ( '‘<a href="' + url + '">'
+ + block.title + '</a>’'
+ + rest )
+ except:
+ url = ( '<a href="' + url + '">'
+ + name + '</a>'
+ + rest )
+
+ return url
except:
# we detected a cross-reference to an unknown item
sys.stderr.write( "WARNING: undefined cross reference"
@@ -422,16 +441,22 @@ class HtmlFormatter( Formatter ):
id = block.name
# link to a field ID if possible
- for markup in block.markups:
- if markup.tag == 'values':
- for field in markup.fields:
- if field.name:
- id = name
+ try:
+ for markup in block.markups:
+ if markup.tag == 'values':
+ for field in markup.fields:
+ if field.name:
+ id = name
+
+ result = ( result + prefix
+ + '<a href="'
+ + self.make_block_url( block, id )
+ + '">' + name + '</a>' )
+ except:
+ # sections don't have `markups'; however, we don't
+ # want references to sections here anyway
+ result = result + html_quote( line[:length] )
- result = ( result + prefix
- + '<a href="'
- + self.make_block_url( block, id )
- + '">' + name + '</a>' )
else:
result = result + html_quote( line[:length] )
@@ -575,7 +600,9 @@ class HtmlFormatter( Formatter ):
def section_enter( self, section ):
print self.html_header
- print section_title_header + section.title + section_title_footer
+ print ( section_title_header1 + section.name + section_title_header2
+ + section.title
+ + section_title_footer )
maxwidth = 0
for b in section.blocks.values():