[freetype2] master 97b808f: [docmaker] Allow `foo[bar]' as identifier.

[Werner LEMBERG]

branch: master
commit 97b808fdade2a617eb474c867d1c21557f8b7d9e
Author: Werner Lemberg <address@hidden>
Commit: Werner Lemberg <address@hidden>

    [docmaker] Allow `foo[bar]' as identifier.
    
    We need this to handle equally named properties in different
    modules.
    
    * src/tools/docmaker/content.py (re_identifier),
    src/tools/docmaker/sources.py (re_crossref): Allow `foo[bar]'.
    
    * src/tools/docmaker/tohtml.py (HtmlFormatter::make_html_word,
    HtmlFormatter::index_exit, HtmlFormatter::section_enter,
    HtmlFormatter::block_enter): Handle `foo[bar]'.
---
 ChangeLog                     |   14 ++++++++++++++
 src/tools/docmaker/content.py |   21 +++++++++++++++++++--
 src/tools/docmaker/sources.py |   20 ++++++++++++++++----
 src/tools/docmaker/tohtml.py  |   31 +++++++++++++++++++++++++++----
 4 files changed, 76 insertions(+), 10 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 42451d3..a1f2128 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,17 @@
+2015-11-26  Werner Lemberg  <address@hidden>
+
+       [docmaker] Allow `foo[bar]' as identifier.
+
+       We need this to handle equally named properties in different
+       modules.
+
+       * src/tools/docmaker/content.py (re_identifier),
+       src/tools/docmaker/sources.py (re_crossref): Allow `foo[bar]'.
+
+       * src/tools/docmaker/tohtml.py (HtmlFormatter::make_html_word,
+       HtmlFormatter::index_exit, HtmlFormatter::section_enter,
+       HtmlFormatter::block_enter): Handle `foo[bar]'.
+
 2015-11-25  Werner Lemberg  <address@hidden>
 
        * src/bdf/bdflib.c (bdf_load_font): Fix small memory leak (#46480).
diff --git a/src/tools/docmaker/content.py b/src/tools/docmaker/content.py
index 1961878..2f60ce6 100644
--- a/src/tools/docmaker/content.py
+++ b/src/tools/docmaker/content.py
@@ -46,9 +46,26 @@ re_code_end   = re.compile( r"(\s*)}\s*$" )
 
 
 #
-# A regular expression to isolate identifiers from other text.
+# A regular expression to isolate identifiers from other text.  Two syntax
+# forms are supported:
 #
-re_identifier = re.compile( r'((?:\w|-)*)' )
+#   <name>
+#   <name>[<id>]
+#
+# where both `<name>' and `<id>' consist of alphanumeric characters, `_',
+# and `-'.  Use `<id>' if there are multiple, valid `<name>' entries; in the
+# index, `<id>' will be appended in parentheses.
+#
+# For example,
+#
+#   stem_darkening[autofit]
+#
+# becomes `stem_darkening (autofit)' in the index.
+#
+re_identifier = re.compile( r"""
+                              ((?:\w|-)+
+                               (?:\[(?:\w|-)+\])?)
+                            """, re.VERBOSE )
 
 
 #
diff --git a/src/tools/docmaker/sources.py b/src/tools/docmaker/sources.py
index be38132..9a4777d 100644
--- a/src/tools/docmaker/sources.py
+++ b/src/tools/docmaker/sources.py
@@ -138,12 +138,24 @@ re_markup_tags = [re_markup_tag1, re_markup_tag2]
 
 #
 # A regular expression to detect a cross reference, after markup tags have
-# been stripped off.  Group 1 is the reference, group 2 the rest of the
-# line.
+# been stripped off.
 #
-# A cross reference consists of letters, digits, or characters `-' and `_'.
+# Two syntax forms are supported:
 #
-re_crossref = re.compile( r'@((?:\w|-)*)(.*)' )    #  @foo
+#   @<name>
+#   @<name>[<id>]
+#
+# where both `<name>' and `<id>' consist of alphanumeric characters, `_',
+# and `-'.  Use `<id>' if there are multiple, valid `<name>' entries.
+#
+# Example: @foo[bar]
+#
+re_crossref = re.compile( r"""
+                            @
+                            (?P<name>(?:\w|-)+
+                                     (?:\[(?:\w|-)+\])?)
+                            (?P<rest>.*)
+                          """, re.VERBOSE )
 
 #
 # Two regular expressions to detect italic and bold markup, respectively.
diff --git a/src/tools/docmaker/tohtml.py b/src/tools/docmaker/tohtml.py
index bc6bcf0..7b5c6c4 100644
--- a/src/tools/docmaker/tohtml.py
+++ b/src/tools/docmaker/tohtml.py
@@ -317,10 +317,15 @@ class  HtmlFormatter( Formatter ):
         m = re_crossref.match( word )
         if m:
             try:
-                name = m.group( 1 )
-                rest = m.group( 2 )
+                name = m.group( 'name' )
+                rest = m.group( 'rest' )
                 block = self.identifiers[name]
                 url   = self.make_block_url( block )
+                # display `foo[bar]' as `foo'
+                name = re.sub( r'\[.*\]', '', name )
+                # normalize url, following RFC 3986
+                url = string.replace( url, "[", "(" )
+                url = string.replace( url, "]", ")" )
                 return '<a href="' + url + '">' + name + '</a>' + rest
             except:
                 # we detected a cross-reference to an unknown item
@@ -490,6 +495,12 @@ class  HtmlFormatter( Formatter ):
                 if i < count:
                     bname = self.block_index[r + c * rows]
                     url   = self.index_items[bname]
+                    # display `foo[bar]' as `foo (bar)'
+                    bname = string.replace( bname, "[", " (" )
+                    bname = string.replace( bname, "]", ")"  )
+                    # normalize url, following RFC 3986
+                    url = string.replace( url, "[", "(" )
+                    url = string.replace( url, "]", ")" )
                     line  = ( line + '<td><a href="' + url + '">'
                               + bname + '</a></td>' )
                 else:
@@ -601,7 +612,13 @@ class  HtmlFormatter( Formatter ):
                             # even omit it completely)
                             line = line + "&nbsp;"
                         else:
-                            line = ( line + '<a href="#' + name + '">'
+                            url = name
+                            # display `foo[bar]' as `foo'
+                            name = re.sub( r'\[.*\]', '', name )
+                            # normalize url, following RFC 3986
+                            url = string.replace( url, "[", "(" )
+                            url = string.replace( url, "]", ")" )
+                            line = ( line + '<a href="#' + url + '">'
                                      + name + '</a>' )
 
                     line = line + '</td>'
@@ -620,7 +637,13 @@ class  HtmlFormatter( Formatter ):
 
         # place html anchor if needed
         if block.name:
-            print( '<h3 id="' + block.name + '">' + block.name + '</h3>' )
+            url = block.name
+            # display `foo[bar]' as `foo'
+            name = re.sub( r'\[.*\]', '', block.name )
+            # normalize url, following RFC 3986
+            url = string.replace( url, "[", "(" )
+            url = string.replace( url, "]", ")" )
+            print( '<h3 id="' + url + '">' + name + '</h3>' )
 
         # dump the block C source lines now
         if block.code: