diff options
Diffstat (limited to 'freetype/src/tools')
| -rw-r--r-- | freetype/src/tools/afblue.pl | 7 | ||||
| -rw-r--r-- | freetype/src/tools/docmaker/content.py | 216 | ||||
| -rw-r--r-- | freetype/src/tools/docmaker/docmaker.py | 39 | ||||
| -rw-r--r-- | freetype/src/tools/docmaker/formatter.py | 73 | ||||
| -rw-r--r-- | freetype/src/tools/docmaker/sources.py | 200 | ||||
| -rw-r--r-- | freetype/src/tools/docmaker/tohtml.py | 445 | ||||
| -rw-r--r-- | freetype/src/tools/docmaker/utils.py | 81 | ||||
| -rw-r--r-- | freetype/src/tools/ftrandom/README | 2 | ||||
| -rw-r--r-- | freetype/src/tools/ftrandom/ftrandom.c | 4 | ||||
| -rw-r--r-- | freetype/src/tools/test_trig.c | 16 |
10 files changed, 659 insertions, 424 deletions
diff --git a/freetype/src/tools/afblue.pl b/freetype/src/tools/afblue.pl index 58aa2a055..60fe6966a 100644 --- a/freetype/src/tools/afblue.pl +++ b/freetype/src/tools/afblue.pl @@ -63,8 +63,8 @@ my $enum_element_re = qr/ ^ \s* ( [A-Za-z0-9_]+ ) \s* $ /x; # '#' <preprocessor directive> '\n' my $preprocessor_re = qr/ ^ \# /x; -# '/' '/' <comment> '\n' -my $comment_re = qr| ^ // |x; +# [<ws>] '/' '/' <comment> '\n' +my $comment_re = qr| ^ \s* // |x; # empty line my $whitespace_only_re = qr/ ^ \s* $ /x; @@ -159,6 +159,9 @@ sub convert_ascii_chars # A series of ASCII characters in the printable range. my $s = shift; + # We ignore spaces. + $s =~ s/ //g; + my $count = $s =~ s/\G(.)/'$1', /g; $curr_offset += $count; $curr_elem_size += $count; diff --git a/freetype/src/tools/docmaker/content.py b/freetype/src/tools/docmaker/content.py index 98025e67e..adea6f1d7 100644 --- a/freetype/src/tools/docmaker/content.py +++ b/freetype/src/tools/docmaker/content.py @@ -1,57 +1,81 @@ -# Content (c) 2002, 2004, 2006-2009, 2012, 2013 -# David Turner <david@freetype.org> # -# This file contains routines used to parse the content of documentation -# comment blocks and build more structured objects out of them. +# content.py +# +# Parse comment blocks to build content blocks (library file). +# +# Copyright 2002, 2004, 2006-2009, 2012-2014 by +# David Turner. +# +# This file is part of the FreeType project, and may only be used, +# modified, and distributed under the terms of the FreeType project +# license, LICENSE.TXT. By continuing to use, modify, or distribute +# this file you indicate that you have read the license and +# understand and accept it fully. + +# +# This file contains routines to parse documentation comment blocks, +# building more structured objects out of them. # + from sources import * -from utils import * +from utils import * + import string, re -# this regular expression is used to detect code sequences. these -# are simply code fragments embedded in '{' and '}' like in: # -# { -# x = y + z; -# if ( zookoo == 2 ) -# { -# foobar(); -# } -# } +# Regular expressions to detect code sequences. `Code sequences' are simply +# code fragments embedded in '{' and '}', as demonstrated in the following +# example. +# +# { +# x = y + z; +# if ( zookoo == 2 ) +# { +# foobar(); +# } +# } # -# note that indentation of the starting and ending accolades must be -# exactly the same. the code sequence can contain accolades at greater -# indentation +# Note that the indentation of the first opening brace and the last closing +# brace must be exactly the same. The code sequence itself should have a +# larger indentation than the surrounding braces. # re_code_start = re.compile( r"(\s*){\s*$" ) re_code_end = re.compile( r"(\s*)}\s*$" ) -# this regular expression is used to isolate identifiers from -# other text # -re_identifier = re.compile( r'((?:\w|-)*)' ) - - -# we collect macros ending in `_H'; while outputting the object data, we use -# this info together with the object's file location to emit the appropriate -# header file macro and name before the object itself +# A regular expression to isolate identifiers from other text. # -re_header_macro = re.compile( r'^#define\s{1,}(\w{1,}_H)\s{1,}<(.*)>' ) +re_identifier = re.compile( r'((?:\w|-)*)' ) -############################################################################# # -# The DocCode class is used to store source code lines. +# We collect macro names ending in `_H' (group 1), as defined in +# `config/ftheader.h'. While outputting the object data, we use this info +# together with the object's file location (group 2) to emit the appropriate +# header file macro and its associated file name before the object itself. # -# 'self.lines' contains a set of source code lines that will be dumped as -# HTML in a <PRE> tag. +# Example: # -# The object is filled line by line by the parser; it strips the leading -# "margin" space from each input line before storing it in 'self.lines'. +# #define FT_FREETYPE_H <freetype.h> # +re_header_macro = re.compile( r'^#define\s{1,}(\w{1,}_H)\s{1,}<(.*)>' ) + + +################################################################ +## +## DOC CODE CLASS +## +## The `DocCode' class is used to store source code lines. +## +## `self.lines' contains a set of source code lines that will be dumped as +## HTML in a <PRE> tag. +## +## The object is filled line by line by the parser; it strips the leading +## `margin' space from each input line before storing it in `self.lines'. +## class DocCode: def __init__( self, margin, lines ): @@ -77,12 +101,14 @@ class DocCode: -############################################################################# -# -# The DocPara class is used to store "normal" text paragraph. -# -# 'self.words' contains the list of words that make up the paragraph -# +################################################################ +## +## DOC PARA CLASS +## +## `Normal' text paragraphs are stored in the `DocPara' class. +## +## `self.words' contains the list of words that make up the paragraph. +## class DocPara: def __init__( self, lines ): @@ -123,17 +149,18 @@ class DocPara: return result - -############################################################################# -# -# The DocField class is used to store a list containing either DocPara or -# DocCode objects. Each DocField also has an optional "name" which is used -# when the object corresponds to a field or value definition -# +################################################################ +## +## DOC FIELD CLASS +## +## The `DocField' class stores a list containing either `DocPara' or +## `DocCode' objects. Each DocField object also has an optional `name' +## that is used when the object corresponds to a field or value definition. +## class DocField: def __init__( self, name, lines ): - self.name = name # can be None for normal paragraphs/sources + self.name = name # can be `None' for normal paragraphs/sources self.items = [] # list of items mode_none = 0 # start parsing mode @@ -143,14 +170,14 @@ class DocField: margin = -1 # current code sequence indentation cur_lines = [] - # now analyze the markup lines to see if they contain paragraphs, - # code sequences or fields definitions + # analyze the markup lines to check whether they contain paragraphs, + # code sequences, or fields definitions # start = 0 mode = mode_none for l in lines: - # are we parsing a code sequence ? + # are we parsing a code sequence? if mode == mode_code: m = re_code_end.match( l ) if m and len( m.group( 1 ) ) <= margin: @@ -161,10 +188,10 @@ class DocField: cur_lines = [] mode = mode_none else: - # nope, continue the code sequence + # otherwise continue the code sequence cur_lines.append( l[margin:] ) else: - # start of code sequence ? + # start of code sequence? m = re_code_start.match( l ) if m: # save current lines @@ -222,13 +249,29 @@ class DocField: return result - -# this regular expression is used to detect field definitions # -re_field = re.compile( r"\s*(\w*|\w(\w|\.)*\w)\s*::" ) - - - +# A regular expression to detect field definitions. +# +# Examples: +# +# foo :: +# foo.bar :: +# +re_field = re.compile( r""" + \s* + ( + \w* + | + \w (\w | \.)* \w + ) + \s* :: + """, re.VERBOSE ) + + +################################################################ +## +## DOC MARKUP CLASS +## class DocMarkup: def __init__( self, tag, lines ): @@ -242,7 +285,7 @@ class DocMarkup: for l in lines: m = re_field.match( l ) if m: - # we detected the start of a new field definition + # We detected the start of a new field definition. # first, save the current one if cur_lines: @@ -275,7 +318,10 @@ class DocMarkup: print " " * margin + "</" + self.tag + ">" - +################################################################ +## +## DOC CHAPTER CLASS +## class DocChapter: def __init__( self, block ): @@ -291,7 +337,10 @@ class DocChapter: self.order = [] - +################################################################ +## +## DOC SECTION CLASS +## class DocSection: def __init__( self, name = "Other" ): @@ -320,18 +369,21 @@ class DocSection: self.title = title self.abstract = block.get_markup_words( "abstract" ) self.description = block.get_markup_items( "description" ) - self.order = block.get_markup_words( "order" ) + self.order = block.get_markup_words_all( "order" ) return def reorder( self ): self.block_names = sort_order_list( self.block_names, self.order ) - +################################################################ +## +## CONTENT PROCESSOR CLASS +## class ContentProcessor: def __init__( self ): - """initialize a block content processor""" + """Initialize a block content processor.""" self.reset() self.sections = {} # dictionary of documentation sections @@ -342,8 +394,8 @@ class ContentProcessor: self.headers = {} # dictionary of header macros def set_section( self, section_name ): - """set current section during parsing""" - if not self.sections.has_key( section_name ): + """Set current section during parsing.""" + if not section_name in self.sections: section = DocSection( section_name ) self.sections[section_name] = section self.section = section @@ -354,15 +406,14 @@ class ContentProcessor: chapter = DocChapter( block ) self.chapters.append( chapter ) - def reset( self ): - """reset the content processor for a new block""" + """Reset the content processor for a new block.""" self.markups = [] self.markup = None self.markup_lines = [] def add_markup( self ): - """add a new markup section""" + """Add a new markup section.""" if self.markup and self.markup_lines: # get rid of last line of markup if it's empty @@ -378,8 +429,8 @@ class ContentProcessor: self.markup_lines = [] def process_content( self, content ): - """process a block content and return a list of DocMarkup objects - corresponding to it""" + """Process a block content and return a list of DocMarkup objects + corresponding to it.""" markup = None markup_lines = [] first = 1 @@ -437,7 +488,7 @@ class ContentProcessor: # listed there for chap in self.chapters: for sec in chap.order: - if self.sections.has_key( sec ): + if sec in self.sections: section = self.sections[sec] section.chapter = chap section.reorder() @@ -452,6 +503,7 @@ class ContentProcessor: others = [] for sec in self.sections.values(): if not sec.chapter: + sec.reorder() others.append( sec ) # create a new special chapter for all remaining sections @@ -463,7 +515,10 @@ class ContentProcessor: self.chapters.append( chap ) - +################################################################ +## +## DOC BLOCK CLASS +## class DocBlock: def __init__( self, source, follow, processor ): @@ -540,7 +595,7 @@ class DocBlock: return self.source.location() def get_markup( self, tag_name ): - """return the DocMarkup corresponding to a given tag in a block""" + """Return the DocMarkup corresponding to a given tag in a block.""" for m in self.markups: if m.tag == string.lower( tag_name ): return m @@ -553,6 +608,21 @@ class DocBlock: except: return [] + def get_markup_words_all( self, tag_name ): + try: + m = self.get_markup( tag_name ) + words = [] + for item in m.fields[0].items: + # We honour empty lines in an `<Order>' section element by + # adding the sentinel `/empty/'. The formatter should then + # convert it to an appropriate representation in the + # `section_enter' function. + words += item.words + words.append( "/empty/" ) + return words + except: + return [] + def get_markup_text( self, tag_name ): result = self.get_markup_words( tag_name ) return string.join( result ) diff --git a/freetype/src/tools/docmaker/docmaker.py b/freetype/src/tools/docmaker/docmaker.py index bf75c5d5f..4fb1abf23 100644 --- a/freetype/src/tools/docmaker/docmaker.py +++ b/freetype/src/tools/docmaker/docmaker.py @@ -1,16 +1,26 @@ #!/usr/bin/env python # -# DocMaker (c) 2002, 2004, 2008, 2013 David Turner <david@freetype.org> +# docmaker.py # -# This program is a re-write of the original DocMaker tool used -# to generate the API Reference of the FreeType font engine -# by converting in-source comments into structured HTML. +# Convert source code markup to HTML documentation. # -# This new version is capable of outputting XML data, as well -# as accepts more liberal formatting options. +# Copyright 2002, 2004, 2008, 2013, 2014 by +# David Turner. # -# It also uses regular expression matching and substitution -# to speed things significantly. +# This file is part of the FreeType project, and may only be used, +# modified, and distributed under the terms of the FreeType project +# license, LICENSE.TXT. By continuing to use, modify, or distribute +# this file you indicate that you have read the license and +# understand and accept it fully. + +# +# This program is a re-write of the original DocMaker tool used to generate +# the API Reference of the FreeType font rendering engine by converting +# in-source comments into structured HTML. +# +# This new version is capable of outputting XML data as well as accepting +# more liberal formatting options. It also uses regular expression matching +# and substitution to speed up operation significantly. # from sources import * @@ -39,13 +49,13 @@ def usage(): def main( argv ): - """main program loop""" + """Main program loop.""" global output_dir try: - opts, args = getopt.getopt( sys.argv[1:], \ - "ht:o:p:", \ + opts, args = getopt.getopt( sys.argv[1:], + "ht:o:p:", ["help", "title=", "output=", "prefix="] ) except getopt.GetoptError: usage() @@ -56,7 +66,6 @@ def main( argv ): sys.exit( 1 ) # process options - # project_title = "Project" project_prefix = None output_dir = None @@ -90,7 +99,9 @@ def main( argv ): # process sections content_processor.finish() - formatter = HtmlFormatter( content_processor, project_title, project_prefix ) + formatter = HtmlFormatter( content_processor, + project_title, + project_prefix ) formatter.toc_dump() formatter.index_dump() @@ -98,9 +109,7 @@ def main( argv ): # if called from the command line -# if __name__ == '__main__': main( sys.argv ) - # eof diff --git a/freetype/src/tools/docmaker/formatter.py b/freetype/src/tools/docmaker/formatter.py index f62ce676c..7152c019d 100644 --- a/freetype/src/tools/docmaker/formatter.py +++ b/freetype/src/tools/docmaker/formatter.py @@ -1,19 +1,37 @@ -# Formatter (c) 2002, 2004, 2007, 2008 David Turner <david@freetype.org> # +# formatter.py +# +# Convert parsed content blocks to a structured document (library file). +# +# Copyright 2002, 2004, 2007, 2008, 2014 by +# David Turner. +# +# This file is part of the FreeType project, and may only be used, +# modified, and distributed under the terms of the FreeType project +# license, LICENSE.TXT. By continuing to use, modify, or distribute +# this file you indicate that you have read the license and +# understand and accept it fully. + +# +# This is the base Formatter class. Its purpose is to convert a content +# processor's data into specific documents (i.e., table of contents, global +# index, and individual API reference indices). +# +# You need to sub-class it to output anything sensible. For example, the +# file `tohtml.py' contains the definition of the `HtmlFormatter' sub-class +# to output HTML. +# + from sources import * from content import * from utils import * -# This is the base Formatter class. Its purpose is to convert -# a content processor's data into specific documents (i.e., table of -# contents, global index, and individual API reference indices). -# -# You need to sub-class it to output anything sensible. For example, -# the file tohtml.py contains the definition of the HtmlFormatter sub-class -# used to output -- you guessed it -- HTML. -# +################################################################ +## +## FORMATTER CLASS +## class Formatter: def __init__( self, processor ): @@ -36,20 +54,22 @@ class Formatter: self.add_identifier( field.name, block ) self.block_index = self.identifiers.keys() - self.block_index.sort( index_sort ) + self.block_index.sort( key = index_key ) def add_identifier( self, name, block ): - if self.identifiers.has_key( name ): + if name in self.identifiers: # duplicate name! - sys.stderr.write( \ - "WARNING: duplicate definition for '" + name + "' in " + \ - block.location() + ", previous definition in " + \ - self.identifiers[name].location() + "\n" ) + sys.stderr.write( "WARNING: duplicate definition for" + + " '" + name + "' " + + "in " + block.location() + ", " + + "previous definition in " + + self.identifiers[name].location() + + "\n" ) else: self.identifiers[name] = block # - # Formatting the table of contents + # formatting the table of contents # def toc_enter( self ): pass @@ -97,7 +117,7 @@ class Formatter: close_output( output ) # - # Formatting the index + # formatting the index # def index_enter( self ): pass @@ -128,7 +148,7 @@ class Formatter: close_output( output ) # - # Formatting a section + # formatting a section # def section_enter( self, section ): pass @@ -162,7 +182,22 @@ class Formatter: self.section_enter( section ) for name in section.block_names: - block = self.identifiers[name] + skip_entry = 0 + try: + block = self.identifiers[name] + # `block_names' can contain field names also, + # which we filter out + for markup in block.markups: + if markup.tag == 'values': + for field in markup.fields: + if field.name == name: + skip_entry = 1 + except: + skip_entry = 1 # this happens e.g. for `/empty/' entries + + if skip_entry: + continue + self.block_enter( block ) for markup in block.markups[1:]: # always ignore first markup! diff --git a/freetype/src/tools/docmaker/sources.py b/freetype/src/tools/docmaker/sources.py index dab834978..61ecc22c4 100644 --- a/freetype/src/tools/docmaker/sources.py +++ b/freetype/src/tools/docmaker/sources.py @@ -1,62 +1,70 @@ -# Sources (c) 2002-2004, 2006-2009, 2012, 2013 -# David Turner <david@freetype.org> # +# sources.py # -# this file contains definitions of classes needed to decompose -# C sources files into a series of multi-line "blocks". There are -# two kinds of blocks: +# Convert source code comments to multi-line blocks (library file). # -# - normal blocks, which contain source code or ordinary comments +# Copyright 2002-2004, 2006-2009, 2012-2014 by +# David Turner. # -# - documentation blocks, which have restricted formatting, and -# whose text always start with a documentation markup tag like -# "<Function>", "<Type>", etc.. +# This file is part of the FreeType project, and may only be used, +# modified, and distributed under the terms of the FreeType project +# license, LICENSE.TXT. By continuing to use, modify, or distribute +# this file you indicate that you have read the license and +# understand and accept it fully. + +# +# This library file contains definitions of classes needed to decompose C +# source code files into a series of multi-line `blocks'. There are two +# kinds of blocks. +# +# - Normal blocks, which contain source code or ordinary comments. # -# the routines used to process the content of documentation blocks -# are not contained here, but in "content.py" +# - Documentation blocks, which have restricted formatting, and whose text +# always start with a documentation markup tag like `<Function>', +# `<Type>', etc. # -# the classes and methods found here only deal with text parsing -# and basic documentation block extraction +# The routines to process the content of documentation blocks are contained +# in file `content.py'; the classes and methods found here only deal with +# text parsing and basic documentation block extraction. # -import fileinput, re, sys, os, string +import fileinput, re, sys, os, string ################################################################ ## -## BLOCK FORMAT PATTERN +## SOURCE BLOCK FORMAT CLASS +## +## A simple class containing compiled regular expressions to detect +## potential documentation format block comments within C source code. ## -## A simple class containing compiled regular expressions used -## to detect potential documentation format block comments within -## C source code +## The `column' pattern must contain a group to `unbox' the content of +## documentation comment blocks. ## -## note that the 'column' pattern must contain a group that will -## be used to "unbox" the content of documentation comment blocks +## Later on, paragraphs are converted to long lines, which simplifies the +## regular expressions that act upon the text. ## class SourceBlockFormat: def __init__( self, id, start, column, end ): - """create a block pattern, used to recognize special documentation blocks""" + """Create a block pattern, used to recognize special documentation + blocks.""" self.id = id self.start = re.compile( start, re.VERBOSE ) self.column = re.compile( column, re.VERBOSE ) self.end = re.compile( end, re.VERBOSE ) - # -# format 1 documentation comment blocks look like the following: +# Format 1 documentation comment blocks. # -# /************************************/ +# /************************************/ (at least 2 asterisks) # /* */ # /* */ # /* */ -# /************************************/ -# -# we define a few regular expressions here to detect them +# /************************************/ (at least 2 asterisks) # - start = r''' \s* # any number of whitespace /\*{2,}/ # followed by '/' and at least two asterisks then '/' @@ -75,16 +83,13 @@ re_source_block_format1 = SourceBlockFormat( 1, start, column, start ) # -# format 2 documentation comment blocks look like the following: +# Format 2 documentation comment blocks. # # /************************************ (at least 2 asterisks) # * +# * (1 asterisk) # * -# * -# * -# **/ (1 or more asterisks at the end) -# -# we define a few regular expressions here to detect them +# */ (1 or more asterisks) # start = r''' \s* # any number of whitespace @@ -93,9 +98,9 @@ start = r''' ''' column = r''' - \s* # any number of whitespace - \*{1}(?!/) # followed by precisely one asterisk not followed by `/' - (.*) # then anything (group1) + \s* # any number of whitespace + \*{1}(?![*/]) # followed by precisely one asterisk not followed by `/' + (.*) # then anything (group1) ''' end = r''' @@ -107,47 +112,56 @@ re_source_block_format2 = SourceBlockFormat( 2, start, column, end ) # -# the list of supported documentation block formats, we could add new ones -# relatively easily +# The list of supported documentation block formats. We could add new ones +# quite easily. # re_source_block_formats = [re_source_block_format1, re_source_block_format2] # -# the following regular expressions corresponds to markup tags -# within the documentation comment blocks. they're equivalent -# despite their different syntax +# The following regular expressions correspond to markup tags within the +# documentation comment blocks. They are equivalent despite their different +# syntax. +# +# A markup tag consists of letters or character `-', to be found in group 1. # -# notice how each markup tag _must_ begin a new line +# Notice that a markup tag _must_ begin a new paragraph. # re_markup_tag1 = re.compile( r'''\s*<((?:\w|-)*)>''' ) # <xxxx> format re_markup_tag2 = re.compile( r'''\s*@((?:\w|-)*):''' ) # @xxxx: format # -# the list of supported markup tags, we could add new ones relatively -# easily +# The list of supported markup tags. We could add new ones quite easily. # re_markup_tags = [re_markup_tag1, re_markup_tag2] + # -# used to detect a cross-reference, after markup tags have been stripped +# 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. +# +# A cross reference consists of letters, digits, or characters `-' and `_'. # re_crossref = re.compile( r'@((?:\w|-)*)(.*)' ) # @foo # -# used to detect italic and bold styles in paragraph text +# Two regular expressions to detect italic and bold markup, respectively. +# Group 1 is the markup, group 2 the rest of the line. +# +# Note that the markup is limited to words consisting of letters, digits, +# the character `_', or an apostrophe (but not as the first character). # -re_italic = re.compile( r"_(\w(\w|')*)_(.*)" ) # _italic_ -re_bold = re.compile( r"\*(\w(\w|')*)\*(.*)" ) # *bold* +re_italic = re.compile( r"_(\w(?:\w|')*)_(.*)" ) # _italic_ +re_bold = re.compile( r"\*(\w(?:\w|')*)\*(.*)" ) # *bold* # -# this regular expression code to identify an URL has been taken from +# This regular expression code to identify an URL has been taken from # # http://mail.python.org/pipermail/tutor/2002-September/017228.html # -# (with slight modifications) +# (with slight modifications). # - urls = r'(?:https?|telnet|gopher|file|wais|ftp)' ltrs = r'\w' gunk = r'/#~:.?+=&%@!\-' @@ -177,17 +191,22 @@ url = r""" re_url = re.compile( url, re.VERBOSE | re.MULTILINE ) # -# used to detect the end of commented source lines +# A regular expression that stops collection of comments for the current +# block. # -re_source_sep = re.compile( r'\s*/\*\s*\*/' ) +re_source_sep = re.compile( r'\s*/\*\s*\*/' ) # /* */ # -# used to perform cross-reference within source output +# A regular expression to find possible C identifiers while outputting +# source code verbatim, covering things like `*foo' or `(bar'. Group 1 is +# the prefix, group 2 the identifier -- since we scan lines from left to +# right, sequentially splitting the source code into prefix and identifier +# is fully sufficient for our purposes. # re_source_crossref = re.compile( r'(\W*)(\w*)' ) # -# a list of reserved source keywords +# A regular expression that matches a list of reserved C source keywords. # re_source_keywords = re.compile( '''\\b ( typedef | struct | @@ -215,24 +234,16 @@ re_source_keywords = re.compile( '''\\b ( typedef | ## ## SOURCE BLOCK CLASS ## -## A SourceProcessor is in charge of reading a C source file -## and decomposing it into a series of different "SourceBlocks". -## each one of these blocks can be made of the following data: -## -## - A documentation comment block that starts with "/**" and -## whose exact format will be discussed later -## -## - normal sources lines, including comments +## There are two important fields in a `SourceBlock' object. ## -## the important fields in a text block are the following ones: +## self.lines +## A list of text lines for the corresponding block. ## -## self.lines : a list of text lines for the corresponding block -## -## self.content : for documentation comment blocks only, this is the -## block content that has been "unboxed" from its -## decoration. This is None for all other blocks -## (i.e. sources or ordinary comments with no starting -## markup tag) +## self.content +## For documentation comment blocks only, this is the block content +## that has been `unboxed' from its decoration. This is `None' for all +## other blocks (i.e., sources or ordinary comments with no starting +## markup tag) ## class SourceBlock: @@ -269,7 +280,7 @@ class SourceBlock: def location( self ): return "(" + self.filename + ":" + repr( self.lineno ) + ")" - # debugging only - not used in normal operations + # debugging only -- not used in normal operations def dump( self ): if self.content: print "{{{content start---" @@ -286,39 +297,38 @@ class SourceBlock: print line - ################################################################ ## ## SOURCE PROCESSOR CLASS ## -## The SourceProcessor is in charge of reading a C source file -## and decomposing it into a series of different "SourceBlock" -## objects. +## The `SourceProcessor' is in charge of reading a C source file and +## decomposing it into a series of different `SourceBlock' objects. ## -## each one of these blocks can be made of the following data: +## A SourceBlock object consists of the following data. ## -## - A documentation comment block that starts with "/**" and -## whose exact format will be discussed later +## - A documentation comment block using one of the layouts above. Its +## exact format will be discussed later. ## -## - normal sources lines, include comments +## - Normal sources lines, including comments. ## ## class SourceProcessor: def __init__( self ): - """initialize a source processor""" + """Initialize a source processor.""" self.blocks = [] self.filename = None self.format = None self.lines = [] def reset( self ): - """reset a block processor, clean all its blocks""" + """Reset a block processor and clean up all its blocks.""" self.blocks = [] self.format = None def parse_file( self, filename ): - """parse a C source file, and add its blocks to the processor's list""" + """Parse a C source file and add its blocks to the processor's + list.""" self.reset() self.filename = filename @@ -337,16 +347,16 @@ class SourceProcessor: self.process_normal_line( line ) else: if self.format.end.match( line ): - # that's a normal block end, add it to 'lines' and - # create a new block + # A normal block end. Add it to `lines' and create a + # new block self.lines.append( line ) self.add_block_lines() elif self.format.column.match( line ): - # that's a normal column line, add it to 'lines' + # A normal column line. Add it to `lines'. self.lines.append( line ) else: - # humm.. this is an unexpected block end, - # create a new block, but don't process the line + # An unexpected block end. Create a new block, but + # don't process the line. self.add_block_lines() # we need to process the line again @@ -356,7 +366,8 @@ class SourceProcessor: self.add_block_lines() def process_normal_line( self, line ): - """process a normal line and check whether it is the start of a new block""" + """Process a normal line and check whether it is the start of a new + block.""" for f in re_source_block_formats: if f.start.match( line ): self.add_block_lines() @@ -366,9 +377,12 @@ class SourceProcessor: self.lines.append( line ) def add_block_lines( self ): - """add the current accumulated lines and create a new block""" + """Add the current accumulated lines and create a new block.""" if self.lines != []: - block = SourceBlock( self, self.filename, self.lineno, self.lines ) + block = SourceBlock( self, + self.filename, + self.lineno, + self.lines ) self.blocks.append( block ) self.format = None @@ -376,7 +390,7 @@ class SourceProcessor: # debugging only, not used in normal operations def dump( self ): - """print all blocks in a processor""" + """Print all blocks in a processor.""" for b in self.blocks: b.dump() diff --git a/freetype/src/tools/docmaker/tohtml.py b/freetype/src/tools/docmaker/tohtml.py index 7944f1c99..05fc08a92 100644 --- a/freetype/src/tools/docmaker/tohtml.py +++ b/freetype/src/tools/docmaker/tohtml.py @@ -1,5 +1,19 @@ -# ToHTML (c) 2002, 2003, 2005-2008, 2013 -# David Turner <david@freetype.org> +# +# tohtml.py +# +# A sub-class container of the `Formatter' class to produce HTML. +# +# Copyright 2002, 2003, 2005-2008, 2013, 2014 by +# David Turner. +# +# This file is part of the FreeType project, and may only be used, +# modified, and distributed under the terms of the FreeType project +# license, LICENSE.TXT. By continuing to use, modify, or distribute +# this file you indicate that you have read the license and +# understand and accept it fully. + +# The parent class is contained in file `formatter.py'. + from sources import * from content import * @@ -8,7 +22,7 @@ from formatter import * import time -# The following defines the HTML header used by all generated pages. +# The following strings define the HTML header used by all generated pages. html_header_1 = """\ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> @@ -21,62 +35,125 @@ html_header_1 = """\ html_header_2 = """\ API Reference</title> <style type="text/css"> + a:link { color: #0000EF; } + a:visited { color: #51188E; } + a:hover { color: #FF0000; } + body { font-family: Verdana, Geneva, Arial, Helvetica, serif; color: #000000; - background: #FFFFFF; } + background: #FFFFFF; + width: 87%; + margin: auto; } + + div.section { width: 75%; + margin: auto; } + div.section hr { margin: 4ex 0 1ex 0; } + div.section h4 { background-color: #EEEEFF; + font-size: medium; + font-style: oblique; + font-weight: bold; + margin: 3ex 0 1.5ex 9%; + padding: 0.3ex 0 0.3ex 1%; } + div.section p { margin: 1.5ex 0 1.5ex 10%; } + div.section pre { margin: 3ex 0 3ex 9%; + background-color: #D6E8FF; + padding: 2ex 0 2ex 1%; } + div.section table.fields { width: 90%; + margin: 1.5ex 0 1.5ex 10%; } + div.section table.toc { width: 95%; + margin: 1.5ex 0 1.5ex 5%; } + div.timestamp { text-align: center; + font-size: 69%; + margin: 1.5ex 0 1.5ex 0; } - p { text-align: justify; } h1 { text-align: center; } - li { text-align: justify; } - td { padding: 0 0.5em 0 0.5em; } - td.left { padding: 0 0.5em 0 0.5em; - text-align: left; } + h3 { font-size: medium; + margin: 4ex 0 1.5ex 0; } - a:link { color: #0000EF; } - a:visited { color: #51188E; } - a:hover { color: #FF0000; } + p { text-align: justify; } + + pre.colored { color: blue; } span.keyword { font-family: monospace; text-align: left; white-space: pre; color: darkblue; } - pre.colored { color: blue; } + table.fields td.val { font-weight: bold; + text-align: right; + width: 30%; + vertical-align: baseline; + padding: 1ex 1em 1ex 0; } + table.fields td.desc { vertical-align: baseline; + padding: 1ex 0 1ex 1em; } + table.fields td.desc p:first-child { margin: 0; } + table.fields td.desc p { margin: 1.5ex 0 0 0; } + table.index { margin: 6ex auto 6ex auto; + border: 0; + border-collapse: separate; + border-spacing: 1em 0.3ex; } + table.index tr { padding: 0; } + table.index td { padding: 0; } + table.index-toc-link { width: 100%; + border: 0; + border-spacing: 0; + margin: 1ex 0 1ex 0; } + table.index-toc-link td.left { padding: 0 0.5em 0 0.5em; + font-size: 83%; + text-align: left; } + table.index-toc-link td.middle { padding: 0 0.5em 0 0.5em; + font-size: 83%; + text-align: center; } + table.index-toc-link td.right { padding: 0 0.5em 0 0.5em; + font-size: 83%; + text-align: right; } + table.synopsis { margin: 6ex auto 6ex auto; + border: 0; + border-collapse: separate; + border-spacing: 2em 0.6ex; } + table.synopsis tr { padding: 0; } + table.synopsis td { padding: 0; } + table.toc td.link { width: 30%; + text-align: right; + vertical-align: baseline; + padding: 1ex 1em 1ex 0; } + table.toc td.desc { vertical-align: baseline; + padding: 1ex 0 1ex 1em; + text-align: left; } + table.toc td.desc p:first-child { margin: 0; + text-align: left; } + table.toc td.desc p { margin: 1.5ex 0 0 0; + text-align: left; } - ul.empty { list-style-type: none; } </style> </head> <body> """ -html_header_3 = """ -<table align=center><tr><td><font size=-1>[<a href="\ +html_header_3l = """ +<table class="index-toc-link"><tr><td class="left">[<a href="\ """ -html_header_3i = """ -<table align=center><tr><td width="100%"></td> -<td><font size=-1>[<a href="\ +html_header_3r = """ +<table class="index-toc-link"><tr><td class="right">[<a href="\ """ html_header_4 = """\ -">Index</a>]</font></td> -<td width="100%"></td> -<td><font size=-1>[<a href="\ +">Index</a>]</td><td class="right">[<a href="\ """ -html_header_5 = """\ -">TOC</a>]</font></td></tr></table> -<center><h1>\ +html_header_5t = """\ +">TOC</a>]</td></tr></table> +<h1>\ """ -html_header_5t = """\ -">Index</a>]</font></td> -<td width="100%"></td></tr></table> -<center><h1>\ +html_header_5i = """\ +">Index</a>]</td></tr></table> +<h1>\ """ html_header_6 = """\ - API Reference</h1></center> + API Reference</h1> """ @@ -87,8 +164,8 @@ html_footer = """\ """ # The header and footer used for each section. -section_title_header = "<center><h1>" -section_title_footer = "</h1></center>" +section_title_header = "<h1>" +section_title_footer = "</h1>" # The header and footer used for code segments. code_header = '<pre class="colored">' @@ -99,66 +176,65 @@ para_header = "<p>" para_footer = "</p>" # Block header and footer. -block_header = '<table align=center width="75%"><tr><td>' +block_header = '<div class="section">' block_footer_start = """\ -</td></tr></table> -<hr width="75%"> -<table align=center width="75%"><tr><td><font size=-2>[<a href="\ +<hr> +<table class="index-toc-link"><tr><td class="left">[<a href="\ """ block_footer_middle = """\ -">Index</a>]</font></td> -<td width="100%"></td> -<td><font size=-2>[<a href="\ +">Index</a>]</td>\ +<td class="middle">[<a href="#">Top</a>]</td>\ +<td class="right">[<a href="\ """ block_footer_end = """\ -">TOC</a>]</font></td></tr></table> +">TOC</a>]</td></tr></table></div> """ # Description header/footer. -description_header = '<table align=center width="87%"><tr><td>' -description_footer = "</td></tr></table><br>" +description_header = "" +description_footer = "" # Marker header/inter/footer combination. -marker_header = '<table align=center width="87%" cellpadding=5><tr bgcolor="#EEEEFF"><td><em><b>' -marker_inter = "</b></em></td></tr><tr><td>" -marker_footer = "</td></tr></table>" +marker_header = "<h4>" +marker_inter = "</h4>" +marker_footer = "" # Header location header/footer. -header_location_header = '<table align=center width="87%"><tr><td>' -header_location_footer = "</td></tr></table><br>" +header_location_header = "<p>" +header_location_footer = "</p>" # Source code extracts header/footer. -source_header = '<table align=center width="87%"><tr bgcolor="#D6E8FF"><td><pre>\n' -source_footer = "\n</pre></table><br>" +source_header = "<pre>" +source_footer = "</pre>" # Chapter header/inter/footer. -chapter_header = '<br><table align=center width="75%"><tr><td><h2>' -chapter_inter = '</h2><ul class="empty"><li>' -chapter_footer = '</li></ul></td></tr></table>' +chapter_header = """\ +<div class="section"> +<h2>\ +""" +chapter_inter = '</h2>' +chapter_footer = '</div>' # Index footer. index_footer_start = """\ <hr> -<table><tr><td width="100%"></td> -<td><font size=-2>[<a href="\ +<table class="index-toc-link"><tr><td class="right">[<a href="\ """ index_footer_end = """\ -">TOC</a>]</font></td></tr></table> +">TOC</a>]</td></tr></table> """ # TOC footer. toc_footer_start = """\ <hr> -<table><tr><td><font size=-2>[<a href="\ +<table class="index-toc-link"><tr><td class="left">[<a href="\ """ toc_footer_end = """\ -">Index</a>]</font></td> -<td width="100%"></td> -</tr></table> +">Index</a>]</td></tr></table> """ -# source language keyword coloration/styling +# Source language keyword coloration and styling. keyword_prefix = '<span class="keyword">' keyword_suffix = '</span>' @@ -166,66 +242,78 @@ section_synopsis_header = '<h2>Synopsis</h2>' section_synopsis_footer = '' -# Translate a single line of source to HTML. This will convert -# a "<" into "<.", ">" into ">.", etc. +# Translate a single line of source to HTML. This converts `<', `>', and +# `&' into `<',`>', and `&'. +# def html_quote( line ): - result = string.replace( line, "&", "&" ) - result = string.replace( result, "<", "<" ) - result = string.replace( result, ">", ">" ) + result = string.replace( line, "&", "&" ) + result = string.replace( result, "<", "<" ) + result = string.replace( result, ">", ">" ) return result - +################################################################ +## +## HTML FORMATTER CLASS +## class HtmlFormatter( Formatter ): def __init__( self, processor, project_title, file_prefix ): Formatter.__init__( self, processor ) - global html_header_1, html_header_2, html_header_3 - global html_header_4, html_header_5, html_footer + global html_header_1 + global html_header_2 + global html_header_3l, html_header_3r + global html_header_4 + global html_header_5t, html_header_5i + global html_header_6 + global html_footer if file_prefix: file_prefix = file_prefix + "-" else: file_prefix = "" - self.headers = processor.headers - self.project_title = project_title - self.file_prefix = file_prefix - self.html_header = html_header_1 + project_title + \ - html_header_2 + \ - html_header_3 + file_prefix + "index.html" + \ - html_header_4 + file_prefix + "toc.html" + \ - html_header_5 + project_title + \ - html_header_6 - - self.html_index_header = html_header_1 + project_title + \ - html_header_2 + \ - html_header_3i + file_prefix + "toc.html" + \ - html_header_5 + project_title + \ - html_header_6 - - self.html_toc_header = html_header_1 + project_title + \ - html_header_2 + \ - html_header_3 + file_prefix + "index.html" + \ - html_header_5t + project_title + \ - html_header_6 - - self.html_footer = "<center><font size=""-2"">generated on " + \ - time.asctime( time.localtime( time.time() ) ) + \ - "</font></center>" + html_footer + self.headers = processor.headers + self.project_title = project_title + self.file_prefix = file_prefix + self.html_header = ( + html_header_1 + project_title + + html_header_2 + + html_header_3l + file_prefix + "index.html" + + html_header_4 + file_prefix + "toc.html" + + html_header_5t + project_title + + html_header_6 ) + self.html_index_header = ( + html_header_1 + project_title + + html_header_2 + + html_header_3r + file_prefix + "toc.html" + + html_header_5t + project_title + + html_header_6 ) + self.html_toc_header = ( + html_header_1 + project_title + + html_header_2 + + html_header_3l + file_prefix + "index.html" + + html_header_5i + project_title + + html_header_6 ) + self.html_footer = ( + '<div class="timestamp">generated on ' + + time.asctime( time.localtime( time.time() ) ) + + "</div>" + html_footer ) self.columns = 3 def make_section_url( self, section ): return self.file_prefix + section.name + ".html" - def make_block_url( self, block ): - return self.make_section_url( block.section ) + "#" + block.name + def make_block_url( self, block, name = None ): + if name == None: + name = block.name + return self.make_section_url( block.section ) + "#" + name def make_html_word( self, word ): - """analyze a simple word to detect cross-references and styling""" - # look for cross-references + """Analyze a simple word to detect cross-references and markup.""" + # handle cross-references m = re_crossref.match( word ) if m: try: @@ -236,27 +324,28 @@ class HtmlFormatter( Formatter ): return '<a href="' + url + '">' + name + '</a>' + rest except: # we detected a cross-reference to an unknown item - sys.stderr.write( \ - "WARNING: undefined cross reference '" + name + "'.\n" ) + sys.stderr.write( "WARNING: undefined cross reference" + + " '" + name + "'.\n" ) return '?' + name + '?' + rest - # look for italics and bolds + # handle markup for italic and bold m = re_italic.match( word ) if m: name = m.group( 1 ) - rest = m.group( 3 ) + rest = m.group( 2 ) return '<i>' + name + '</i>' + rest m = re_bold.match( word ) if m: name = m.group( 1 ) - rest = m.group( 3 ) + rest = m.group( 2 ) return '<b>' + name + '</b>' + rest return html_quote( word ) def make_html_para( self, words ): - """ convert words of a paragraph into tagged HTML text, handle xrefs """ + """Convert words of a paragraph into tagged HTML text. Also handle + cross references.""" line = "" if words: line = self.make_html_word( words[0] ) @@ -265,8 +354,8 @@ class HtmlFormatter( Formatter ): # handle hyperlinks line = re_url.sub( r'<a href="\1">\1</a>', line ) # convert `...' quotations into real left and right single quotes - line = re.sub( r"(^|\W)`(.*?)'(\W|$)", \ - r'\1‘\2’\3', \ + line = re.sub( r"(^|\W)`(.*?)'(\W|$)", + r'\1‘\2’\3', line ) # convert tilde into non-breakable space line = string.replace( line, "~", " " ) @@ -274,7 +363,7 @@ class HtmlFormatter( Formatter ): return para_header + line + para_footer def make_html_code( self, lines ): - """ convert a code sequence to HTML """ + """Convert a code sequence to HTML.""" line = code_header + '\n' for l in lines: line = line + html_quote( l ) + '\n' @@ -282,7 +371,7 @@ class HtmlFormatter( Formatter ): return line + code_footer def make_html_items( self, items ): - """ convert a field's content into some valid HTML """ + """Convert a field's content into HTML.""" lines = [] for item in items: if item.lines: @@ -297,7 +386,9 @@ class HtmlFormatter( Formatter ): def print_html_field( self, field ): if field.name: - print "<table><tr valign=top><td><b>" + field.name + "</b></td><td>" + print( '<table><tr valign="top"><td><b>' + + field.name + + "</b></td><td>" ) print self.make_html_items( field.items ) @@ -318,12 +409,24 @@ class HtmlFormatter( Formatter ): result = result + prefix + '<b>' + name + '</b>' elif re_source_keywords.match( name ): # this is a C keyword - result = result + prefix + keyword_prefix + name + keyword_suffix - elif self.identifiers.has_key( name ): + result = ( result + prefix + + keyword_prefix + name + keyword_suffix ) + elif name in self.identifiers: # this is a known identifier block = self.identifiers[name] - result = result + prefix + '<a href="' + \ - self.make_block_url( block ) + '">' + name + '</a>' + id = block.name + + # link to a field ID if possible + for markup in block.markups: + if markup.tag == 'values': + for field in markup.fields: + if field.name: + id = name + + result = ( result + prefix + + '<a href="' + + self.make_block_url( block, id ) + + '">' + name + '</a>' ) else: result = result + html_quote( line[:length] ) @@ -335,15 +438,11 @@ class HtmlFormatter( Formatter ): return result def print_html_field_list( self, fields ): - print "<p></p>" - print "<table cellpadding=3 border=0>" + print '<table class="fields">' for field in fields: - if len( field.name ) > 22: - print "<tr valign=top><td colspan=0><b>" + field.name + "</b></td></tr>" - print "<tr valign=top><td></td><td>" - else: - print "<tr valign=top><td><b>" + field.name + "</b></td><td>" - + print ( '<tr><td class="val" id="' + field.name + '">' + + field.name + + '</td><td class="desc">' ) self.print_html_items( field.items ) print "</td></tr>" print "</table>" @@ -352,10 +451,9 @@ class HtmlFormatter( Formatter ): table_fields = [] for field in markup.fields: if field.name: - # we begin a new series of field or value definitions, we - # will record them in the 'table_fields' list before outputting - # all of them as a single table - # + # We begin a new series of field or value definitions. We + # record them in the `table_fields' list before outputting + # all of them as a single table. table_fields.append( field ) else: if table_fields: @@ -368,7 +466,7 @@ class HtmlFormatter( Formatter ): self.print_html_field_list( table_fields ) # - # Formatting the index + # formatting the index # def index_enter( self ): print self.html_index_header @@ -380,11 +478,11 @@ class HtmlFormatter( Formatter ): self.index_items[name] = url def index_exit( self ): - # block_index already contains the sorted list of index names + # `block_index' already contains the sorted list of index names count = len( self.block_index ) - rows = ( count + self.columns - 1 ) / self.columns + rows = ( count + self.columns - 1 ) // self.columns - print "<table align=center border=0 cellpadding=0 cellspacing=0>" + print '<table class="index">' for r in range( rows ): line = "<tr>" for c in range( self.columns ): @@ -392,7 +490,8 @@ class HtmlFormatter( Formatter ): if i < count: bname = self.block_index[r + c * rows] url = self.index_items[bname] - line = line + '<td><a href="' + url + '">' + bname + '</a></td>' + line = ( line + '<td><a href="' + url + '">' + + bname + '</a></td>' ) else: line = line + '<td></td>' line = line + "</tr>" @@ -400,9 +499,9 @@ class HtmlFormatter( Formatter ): print "</table>" - print index_footer_start + \ - self.file_prefix + "toc.html" + \ - index_footer_end + print( index_footer_start + + self.file_prefix + "toc.html" + + index_footer_end ) print self.html_footer @@ -415,21 +514,20 @@ class HtmlFormatter( Formatter ): Formatter.index_dump( self, index_filename ) # - # Formatting the table of content + # formatting the table of contents # def toc_enter( self ): print self.html_toc_header - print "<center><h1>Table of Contents</h1></center>" + print "<h1>Table of Contents</h1>" def toc_chapter_enter( self, chapter ): - print chapter_header + string.join( chapter.title ) + chapter_inter - print "<table cellpadding=5>" + print chapter_header + string.join( chapter.title ) + chapter_inter + print '<table class="toc">' def toc_section_enter( self, section ): - print '<tr valign=top><td class="left">' - print '<a href="' + self.make_section_url( section ) + '">' + \ - section.title + '</a></td><td>' - + print ( '<tr><td class="link">' + + '<a href="' + self.make_section_url( section ) + '">' + + section.title + '</a></td><td class="desc">' ) print self.make_html_para( section.abstract ) def toc_section_exit( self, section ): @@ -440,14 +538,14 @@ class HtmlFormatter( Formatter ): print chapter_footer def toc_index( self, index_filename ): - print chapter_header + \ - '<a href="' + index_filename + '">Global Index</a>' + \ - chapter_inter + chapter_footer + print( chapter_header + + '<a href="' + index_filename + '">Global Index</a>' + + chapter_inter + chapter_footer ) def toc_exit( self ): - print toc_footer_start + \ - self.file_prefix + "index.html" + \ - toc_footer_end + print( toc_footer_start + + self.file_prefix + "index.html" + + toc_footer_end ) print self.html_footer @@ -461,14 +559,12 @@ class HtmlFormatter( Formatter ): Formatter.toc_dump( self, toc_filename, index_filename ) # - # Formatting sections + # formatting sections # def section_enter( self, section ): print self.html_header - print section_title_header - print section.title - print section_title_footer + print section_title_header + section.title + section_title_footer maxwidth = 0 for b in section.blocks.values(): @@ -476,32 +572,43 @@ class HtmlFormatter( Formatter ): maxwidth = len( b.name ) width = 70 # XXX magic number - if maxwidth <> 0: + if maxwidth > 0: # print section synopsis print section_synopsis_header - print "<table align=center cellspacing=5 cellpadding=0 border=0>" + print '<table class="synopsis">' - columns = width / maxwidth + columns = width // maxwidth if columns < 1: columns = 1 count = len( section.block_names ) - rows = ( count + columns - 1 ) / columns + # don't handle last entry if it is empty + if section.block_names[-1] == "/empty/": + count -= 1 + rows = ( count + columns - 1 ) // columns for r in range( rows ): line = "<tr>" for c in range( columns ): i = r + c * rows - line = line + '<td></td><td>' + line = line + '<td>' if i < count: name = section.block_names[i] - line = line + '<a href="#' + name + '">' + name + '</a>' + if name == "/empty/": + # it can happen that a complete row is empty, and + # without a proper `filler' the browser might + # collapse the row to a much smaller height (or + # even omit it completely) + line = line + " " + else: + line = ( line + '<a href="#' + name + '">' + + name + '</a>' ) line = line + '</td>' line = line + "</tr>" print line - print "</table><br><br>" + print "</table>" print section_synopsis_footer print description_header @@ -513,7 +620,7 @@ class HtmlFormatter( Formatter ): # place html anchor if needed if block.name: - print '<h4><a name="' + block.name + '">' + block.name + '</a></h4>' + print( '<h3 id="' + block.name + '">' + block.name + '</h3>' ) # dump the block C source lines now if block.code: @@ -521,16 +628,17 @@ class HtmlFormatter( Formatter ): for f in self.headers.keys(): if block.source.filename.find( f ) >= 0: header = self.headers[f] + ' (' + f + ')' - break; + break # if not header: -# sys.stderr.write( \ -# 'WARNING: No header macro for ' + block.source.filename + '.\n' ) +# sys.stderr.write( +# "WARNING: No header macro for" +# + " '" + block.source.filename + "'.\n" ) if header: - print header_location_header - print 'Defined in ' + header + '.' - print header_location_footer + print ( header_location_header + + 'Defined in ' + header + '.' + + header_location_footer ) print source_header for l in block.code: @@ -552,15 +660,16 @@ class HtmlFormatter( Formatter ): print marker_footer def block_exit( self, block ): - print block_footer_start + self.file_prefix + "index.html" + \ - block_footer_middle + self.file_prefix + "toc.html" + \ - block_footer_end + print( block_footer_start + self.file_prefix + "index.html" + + block_footer_middle + self.file_prefix + "toc.html" + + block_footer_end ) def section_exit( self, section ): print html_footer def section_dump_all( self ): for section in self.sections: - self.section_dump( section, self.file_prefix + section.name + '.html' ) + self.section_dump( section, + self.file_prefix + section.name + '.html' ) # eof diff --git a/freetype/src/tools/docmaker/utils.py b/freetype/src/tools/docmaker/utils.py index 1d96658c7..b35823ab7 100644 --- a/freetype/src/tools/docmaker/utils.py +++ b/freetype/src/tools/docmaker/utils.py @@ -1,48 +1,42 @@ -# Utils (c) 2002, 2004, 2007, 2008 David Turner <david@freetype.org> # - -import string, sys, os, glob - -# current output directory +# utils.py # -output_dir = None - - -# This function is used to sort the index. It is a simple lexicographical -# sort, except that it places capital letters before lowercase ones. +# Auxiliary functions for the `docmaker' tool (library file). # -def index_sort( s1, s2 ): - if not s1: - return -1 - - if not s2: - return 1 - - l1 = len( s1 ) - l2 = len( s2 ) - m1 = string.lower( s1 ) - m2 = string.lower( s2 ) +# Copyright 2002, 2004, 2007, 2008, 2014 by +# David Turner. +# +# This file is part of the FreeType project, and may only be used, +# modified, and distributed under the terms of the FreeType project +# license, LICENSE.TXT. By continuing to use, modify, or distribute +# this file you indicate that you have read the license and +# understand and accept it fully. - for i in range( l1 ): - if i >= l2 or m1[i] > m2[i]: - return 1 - if m1[i] < m2[i]: - return -1 +import string, sys, os, glob, itertools - if s1[i] < s2[i]: - return -1 - if s1[i] > s2[i]: - return 1 +# current output directory +# +output_dir = None - if l2 > l1: - return -1 - return 0 +# A function that generates a sorting key. We want lexicographical order +# (primary key) except that capital letters are sorted before lowercase +# ones (secondary key). +# +# The primary key is implemented by lowercasing the input. The secondary +# key is simply the original data appended, character by character. For +# example, the sort key for `FT_x' is `fFtT__xx', while the sort key for +# `ft_X' is `fftt__xX'. Since ASCII codes of uppercase letters are +# numerically smaller than the codes of lowercase letters, `fFtT__xx' gets +# sorted before `fftt__xX'. +# +def index_key( s ): + return string.join( itertools.chain( *zip( s.lower(), s ) ) ) -# Sort input_list, placing the elements of order_list in front. +# Sort `input_list', placing the elements of `order_list' in front. # def sort_order_list( input_list, order_list ): new_list = order_list[:] @@ -52,9 +46,9 @@ def sort_order_list( input_list, order_list ): return new_list -# Open the standard output to a given project documentation file. Use -# "output_dir" to determine the filename location if necessary and save the -# old stdout in a tuple that is returned by this function. +# Divert standard output to a given project documentation file. Use +# `output_dir' to determine the filename location if necessary and save the +# old stdout handle in a tuple that is returned by this function. # def open_output( filename ): global output_dir @@ -69,7 +63,7 @@ def open_output( filename ): return ( new_file, old_stdout ) -# Close the output that was returned by "close_output". +# Close the output that was returned by `open_output'. # def close_output( output ): output[0].close() @@ -83,15 +77,16 @@ def check_output(): if output_dir: if output_dir != "": if not os.path.isdir( output_dir ): - sys.stderr.write( "argument" + " '" + output_dir + "' " + \ - "is not a valid directory" ) + sys.stderr.write( "argument" + + " '" + output_dir + "' " + + "is not a valid directory" ) sys.exit( 2 ) else: output_dir = None def file_exists( pathname ): - """checks that a given file exists""" + """Check that a given file exists.""" result = 1 try: file = open( pathname, "r" ) @@ -104,12 +99,12 @@ def file_exists( pathname ): def make_file_list( args = None ): - """builds a list of input files from command-line arguments""" + """Build a list of input files from command-line arguments.""" file_list = [] # sys.stderr.write( repr( sys.argv[1 :] ) + '\n' ) if not args: - args = sys.argv[1 :] + args = sys.argv[1:] for pathname in args: if string.find( pathname, '*' ) >= 0: diff --git a/freetype/src/tools/ftrandom/README b/freetype/src/tools/ftrandom/README index c093f15e8..71bf05323 100644 --- a/freetype/src/tools/ftrandom/README +++ b/freetype/src/tools/ftrandom/README @@ -43,6 +43,6 @@ Arguments are: --rasterize Call FT_Render_Glyph as well as loading it. --result <dir> This is the directory in which test files are placed. - --test <file> Run a single test on a pre-generated testcase. + --test <file> Run a single test on a pre-generated testcase. Done in the current process so it can be debugged more easily. diff --git a/freetype/src/tools/ftrandom/ftrandom.c b/freetype/src/tools/ftrandom/ftrandom.c index 7c9795711..9a5b63267 100644 --- a/freetype/src/tools/ftrandom/ftrandom.c +++ b/freetype/src/tools/ftrandom/ftrandom.c @@ -449,9 +449,9 @@ fseek( new, getRandom( 0, item->len - 1 ), SEEK_SET ); if ( item->isbinary ) - putc( getRandom( 0, 0xff ), new ); + putc( getRandom( 0, 0xFF ), new ); else if ( item->isascii ) - putc( getRandom( 0x20, 0x7e ), new ); + putc( getRandom( 0x20, 0x7E ), new ); else { int hex = getRandom( 0, 15 ); diff --git a/freetype/src/tools/test_trig.c b/freetype/src/tools/test_trig.c index 49d927e36..99ac1cf17 100644 --- a/freetype/src/tools/test_trig.c +++ b/freetype/src/tools/test_trig.c @@ -20,7 +20,7 @@ int i; - for ( i = 0; i < FT_ANGLE_2PI; i += 0x10000 ) + for ( i = 0; i < FT_ANGLE_2PI; i += 0x10000L ) { FT_Fixed f1, f2; double d2; @@ -46,7 +46,7 @@ int i; - for ( i = 0; i < FT_ANGLE_2PI; i += 0x10000 ) + for ( i = 0; i < FT_ANGLE_2PI; i += 0x10000L ) { FT_Fixed f1, f2; double d2; @@ -72,7 +72,7 @@ int i; - for ( i = 0; i < FT_ANGLE_PI2-0x2000000; i += 0x10000 ) + for ( i = 0; i < FT_ANGLE_PI2 - 0x2000000L; i += 0x10000L ) { FT_Fixed f1, f2; double d2; @@ -98,7 +98,7 @@ int i; - for ( i = 0; i < FT_ANGLE_2PI; i += 0x10000 ) + for ( i = 0; i < FT_ANGLE_2PI; i += 0x10000L ) { FT_Fixed c2, s2; double l, a, c1, s1; @@ -133,7 +133,7 @@ int i; - for ( i = 0; i < FT_ANGLE_2PI; i += 0x10000 ) + for ( i = 0; i < FT_ANGLE_2PI; i += 0x10000L ) { FT_Vector v; double a, c1, s1; @@ -166,7 +166,7 @@ int i; - for ( i = 0; i < FT_ANGLE_2PI; i += 0x10000 ) + for ( i = 0; i < FT_ANGLE_2PI; i += 0x10000L ) { FT_Vector v; FT_Fixed l, l2; @@ -193,7 +193,7 @@ int rotate; - for ( rotate = 0; rotate < FT_ANGLE_2PI; rotate += 0x10000 ) + for ( rotate = 0; rotate < FT_ANGLE_2PI; rotate += 0x10000L ) { double ra, cra, sra; int i; @@ -203,7 +203,7 @@ cra = cos( ra ); sra = sin( ra ); - for ( i = 0; i < FT_ANGLE_2PI; i += 0x10000 ) + for ( i = 0; i < FT_ANGLE_2PI; i += 0x10000L ) { FT_Fixed c2, s2, c4, s4; FT_Vector v; |