From 97b808fdade2a617eb474c867d1c21557f8b7d9e Mon Sep 17 00:00:00 2001 From: Werner Lemberg Date: Thu, 26 Nov 2015 14:29:17 +0100 Subject: [PATCH] [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 42451d332..a1f212858 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,17 @@ +2015-11-26 Werner Lemberg + + [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 * 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 1961878a7..2f60ce6f4 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|-)*)' ) +# +# [] +# +# where both `' and `' consist of alphanumeric characters, `_', +# and `-'. Use `' if there are multiple, valid `' entries; in the +# index, `' 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 be38132d1..9a4777d3c 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 +# @ +# @[] +# +# where both `' and `' consist of alphanumeric characters, `_', +# and `-'. Use `' if there are multiple, valid `' entries. +# +# Example: @foo[bar] +# +re_crossref = re.compile( r""" + @ + (?P(?:\w|-)+ + (?:\[(?:\w|-)+\])?) + (?P.*) + """, 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 bc6bcf051..7b5c6c43c 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 '' + name + '' + 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 + '' + bname + '' ) else: @@ -601,7 +612,13 @@ class HtmlFormatter( Formatter ): # even omit it completely) line = line + " " else: - line = ( line + '' + 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 + '' + name + '' ) line = line + '' @@ -620,7 +637,13 @@ class HtmlFormatter( Formatter ): # place html anchor if needed if block.name: - print( '

' + block.name + '

' ) + 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( '

' + name + '

' ) # dump the block C source lines now if block.code: