[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]'.
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 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153
diff --git a/ChangeLog b/ChangeLog
index 42451d3..a1f2128 100644
--- a/ChangeLog
+++ b/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).
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 + " "
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: