[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

@@ -1,3 +1,17 @@
+2015-11-26  Werner Lemberg  <wl@gnu.org>
+
+	[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  <wl@gnu.org>
 
 	* src/bdf/bdflib.c (bdf_load_font): Fix small memory leak (#46480).

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 )
 
 
 #

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.

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: