[freetype2] master 98afe3f 1/2: [docmaker] Allow references to section names.

[Werner LEMBERG]

branch: master
commit 98afe3f5c8490837adc2fc60ae483ad57a76f76e
Author: Werner Lemberg <address@hidden>
Commit: Werner Lemberg <address@hidden>

    [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.
---
 ChangeLog                       |   17 ++++++++++++
 src/tools/docmaker/formatter.py |    5 +++
 src/tools/docmaker/tohtml.py    |   53 +++++++++++++++++++++++++++++---------
 3 files changed, 62 insertions(+), 13 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 85e00c1..e188de7 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,20 @@
+2015-11-28  Werner Lemberg  <address@hidden>
+
+       [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  <address@hidden>
 
        [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 = ( '&lsquo;<a href="' + url + '">'
+                            + block.title + '</a>&rsquo;'
+                            + 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():