ref: 97b808fdade2a617eb474c867d1c21557f8b7d9e
parent: 4a15013a2988206cb126d6bc550e06f975439a13
author: Werner Lemberg <[email protected]>
date: Thu Nov 26 09:29:17 EST 2015
[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]'.
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,17 @@
+2015-11-26 Werner Lemberg <[email protected]>
+
+ [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 <[email protected]>
* src/bdf/bdflib.c (bdf_load_font): Fix small memory leak (#46480).
--- a/src/tools/docmaker/content.py
+++ b/src/tools/docmaker/content.py
@@ -46,9 +46,26 @@
#
-# 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 )
#
--- a/src/tools/docmaker/sources.py
+++ b/src/tools/docmaker/sources.py
@@ -138,12 +138,24 @@
#
# 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.
--- a/src/tools/docmaker/tohtml.py
+++ b/src/tools/docmaker/tohtml.py
@@ -317,10 +317,15 @@
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 @@
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 @@
# 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 @@
# 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: