ref: 98afe3f5c8490837adc2fc60ae483ad57a76f76e
parent: 30fdfe6c6624d0fa4d52d4291beb70c9e2a353b1
author: Werner Lemberg <[email protected]>
date: Sat Nov 28 06:58:49 EST 2015
[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.
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,20 @@
+2015-11-28 Werner Lemberg <[email protected]>
+
+ [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 <[email protected]>
[cmake] Add script to test the config module.
--- a/src/tools/docmaker/formatter.py
+++ b/src/tools/docmaker/formatter.py
@@ -56,6 +56,11 @@
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!
--- a/src/tools/docmaker/tohtml.py
+++ b/src/tools/docmaker/tohtml.py
@@ -164,7 +164,8 @@
"""
# 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,8 +310,15 @@
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."""
# handle cross-references
@@ -326,7 +334,18 @@
# 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 @@
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>' )
+ 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] )
+
else:
result = result + html_quote( line[:length] )
@@ -575,7 +600,9 @@
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():