kmx git

Commit 6fbb95beb102edb94b730acb309a95530a0f0fd9

2000-10-23T18:32:55
- added first draft of "Modules in FreeType 2" - minor formatting / testing in docmaker.py
diff --git a/docs/design/basic-design.png b/docs/design/basic-design.png
new file mode 100644
index 0000000..881e1a8
Binary files /dev/null and b/docs/design/basic-design.png differ
diff --git a/docs/design/detailed-design.png b/docs/design/detailed-design.png
new file mode 100644
index 0000000..174c1a9
Binary files /dev/null and b/docs/design/detailed-design.png differ
diff --git a/docs/design/modules.html b/docs/design/modules.html
new file mode 100644
index 0000000..118ddd4
--- /dev/null
+++ b/docs/design/modules.html
@@ -0,0 +1,639 @@
+<html>
+<head><title>FreeType 2 - Modules</title>
+<basefont face="Georgia, Arial, Helvetica, Geneva">
+<style content="text/css">
+  P { text-align=justify }
+  H1 { text-align=center }
+  H2 { text-align=center }
+  LI { text-align=justify }
+</style>
+</head>
+<body text=#000000 bgcolor=#ffffff>
+
+<center><table width="500"><tr><td>
+
+<center><h1>FreeType 2 Modules</h1></center>
+
+<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
+<h1>Introduction</h1>
+</td></tr></table>
+
+<p>
+The purpose of this document is to present in great details the way
+FreeType 2 uses and manages modules. Among other things, it answers
+the following questions:</p>
+
+<ul>
+  <li><p>
+  what is a module, and what kind of modules are recognized
+  by the library?
+  </p></li>
+
+  <li><p>
+  how are modules registered and managed by the library?
+  </p></li>
+
+  <li><p>
+  how to write a new module, especially new font drivers?
+  </p></li>
+
+  <li><p>
+  how to select specific modules for a given build of the
+  library ?
+  </p></li>
+
+  <li><p>
+  how to compile modules as stand-alone DLLs / shared objects?
+  </p></li>
+
+</ul>
+
+<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
+<h1>Overview</h1>
+</td></tr></table>
+
+
+<h3>1. Library design:</h3>
+
+<p>The design of the library is pretty basic:</p>
+<ul>
+  <li><p>
+    client applications typically call the FreeType 2 high-level
+    API, whose functions are implemented in a single component
+    called the <em>Base Layer</em>.
+  </p></li>
+
+  <li><p>
+    depending on the context or the task, the base
+    layer then calls one or more modules to perform the
+    work. In most cases, the client application doesn't
+    need to know what module was called.
+  </p></li>
+
+  <li><p>
+    the base layer also contains a set of routines that are
+    used for generic things like memory allocation, list
+    processing, i/o stream parsing, fixed point computation,
+    etc.. these functions can also be called by a module
+    at any, and they form what is called the "low-level
+    base API".
+  </p></li>
+</ul>
+
+<p>This is illustrated by the following graphics:</p>
+
+<center><img src="basic-design.png" width="312" height="312"></center>
+
+<p>Note that, however, FT2 comes with a set of <em>optional</em>
+components that can be ommited from certain builds, and whose
+purpose vary between two situations:</p>
+
+<ul>
+  <li><p>
+     some are located on top of the high-level API and provide
+     convenience functions that make certain things easier
+     for typical applications. They typically do not call
+     modules directly, though they can use the low level
+     base API for certain tasks.</p>
+
+  <p>As an example, see the the <tt>ftglyph</tt> component
+     that is used to manipulate glyph images more conveniently
+     than the default API.</p>
+  </p></li>
+
+  <li><p>
+     some other components complement the base layer, by providing
+     additional routines. Most of them allow client applications
+     to access format-specific data.</p>
+
+  <p>For example, the <tt>ftmm</tt> component provides high-level
+     functions to specify Multiple Master coordinates for MM Type 1
+     fonts.</p>
+  </p></li>
+</ul>
+
+<p>This is illustrated by the following graphics:</p>
+
+<center><img src="detailed-design.png" width="365" height="392"></center>
+
+<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
+<h1>Module Classes</h1>
+</td></tr></table>
+
+<p>
+The library is capable of managing and using several kinds of
+modules:</p>
+
+<ul>
+  <li><p>
+  <b>renderer</b> modules are used to convert scalable glyph images
+  to bitmaps. FreeType 2 comes by default with two of them:</p>
+
+  <center><table cellpadding=5><tr valign=top><td>
+  <p><b><tt>raster1</tt></b></p>
+  </td><td>
+  <p>supports the conversion of vectorial outlines (described by a
+  <tt>FT_Outline</tt> object) to <em>monochrome</em> bitmaps.
+  </td></tr><tr valign=top><td></p>
+
+  <p><b><tt>smooth</tt></b></p>
+  </td><td>
+  <p>supports the conversion of the same outlines to high-quality
+  <em>anti-aliased</em> pixmaps.</p>
+  </td></tr></table></center>
+
+
+  <p>The specification and interface of renderers is described in
+     details within this document.</p>
+
+  <p>Note that most font formats use <tt>FT_Outline</tt> objects
+     to describe scalable glyph images. However, FT2 is flexible
+     and allows specific modules to register and support other
+     formats. As an example, it's (at least theorically :-) perfectly
+     possible to write a renderer module that is capable of directly
+     converting MetaFont glyph definitions to bitmaps or pixmaps !
+     (of course, this assumes that you also write a MetaFont font
+     driver to load the definitions :-).
+  </p></li>
+
+  <li><p>
+  <b>font driver</b> modules are used to support one or more specific
+  font format. By default, FT2 comes with the following modules:</p>
+
+  <center><table cellpadding=5><tr valign=top><td>
+  <p><tt><b>truetype</b></tt></p>
+  </td><td>
+  <p>supports TrueType font files</p>
+  </td></tr><tr valign=top><td>
+
+  <p><tt><b>type1</b></tt></p>
+  </td><td>
+  <p>supports Postscript Type 1 fonts, both in binary (.pfb) or ASCII
+  (.pfa) formats, including Multiple Master fonts.</p>
+  </td></tr><tr valign=top><td>
+
+  <p><tt><b>cid</b></tt></p>
+  </td><td>
+  <p>supports Postscript CID-keyed fonts</p>
+  </td></tr><tr valign=top><td>
+
+  <p><tt><b>cff</b></tt></p>
+  </td><td>
+  <p>supports OpenType, CFF as well as CEF fonts (CEF is a derivative
+  of CFF used by Adobe in its SVG viewer).</p>
+  </td></tr><tr valign=top><td>
+
+  <p><tt><b>winfonts</b></tt></p>
+  </td><td>
+  <p>supports Windows bitmap fonts (i.e. ".FON" and ".FNT").</p>
+  </td></tr>
+
+  </td></tr></table></center>
+
+  <p>Note that font drivers can support bitmapped or scalable glyph
+     images. A given font driver that supports bezier outlines through
+     the <tt>FT_Outline</tt> can also provide its own hinter, or rely
+     on FreeType's <b>autohinter</b> module.
+  </p></li>
+
+  <li><p>
+  <b>helper</b> modules are used to hold shared code that is
+  often used by several font drivers, or even other modules.
+  Here are a few examples of helper modules that come with
+  FreeType 2:</p>
+
+  <table cellpadding=5><tr valign=top><td>
+  <b><tt>sfnt</tt></b>
+  </td><td>
+  used to support font formats based on the "<tt>SFNT</tt>"
+  storage scheme. This means TrueType & OpenType fonts as
+  well as other variants (like TrueType fonts that only
+  contain embedded bitmaps).
+  </td></tr><tr valign=top><td>
+  
+  <b><tt>psnames</tt></b>
+  </td><td>
+  used to provide various useful function related to glyph
+  names ordering and Postscript encodings/charsets. For example,
+  this module is capable of automatically synthetizing a Unicode
+  charmap from a Type 1 glyph name dictionary.
+  </td></tr></table></center>
+  </p></li>
+
+
+  <li><p>
+  finally, the <b>autohinter</b> module has a specific role in
+  FreeType 2, as it can be used automatically during glyph loading
+  to process individual glyph outlines when a font driver doesn't
+  provide it's own hinting engine.
+  </p></li>
+</ul>
+
+<p>We will now study how modules are described, then managed by
+   the library.</p>
+
+<h3>1. The <tt>FT_Module_Class</tt> structure:</h3>
+
+<p>As described later in this document, library initialisation is
+   performed by calling the <tt>FT_Init_FreeType</tt> function. The
+   latter is in charge of creating a new "empty" <tt>FT_Library</tt>
+   object, then register each "default" module by repeatedly calling
+   the <tt>FT_Add_Module</tt> function.</p>
+
+<p>Similarly, client applications can call <tt>FT_Add_Module</tt>
+   any time they wish in order to register a new module in the library.
+   Let's take a look at this function's declaration:</p>
+
+<pre><font color="blue">
+    extern FT_Error  FT_Add_Module( FT_Library              library,
+                                    const FT_Module_Class*  clazz );
+</font></pre>
+
+<p>As one can see, this function expects a handle to a library object,
+   as well as a pointer to a <tt>FT_Module_Class</tt> structure. It
+   returns an error code. In case of success, a new module object is
+   created and added to the library. Note by the way that the module
+   isn't returned directly by the call !.</p>
+
+<p>Let's study the definition of <tt>FT_Module_Class</tt>, and explain it
+   a bit. The following code is taken from
+   <tt>&lt;freetype/ftmodule.h&gt;</tt>:</p>
+
+<pre><font color="blue">
+  typedef struct  FT_Module_Class_
+  {
+    FT_ULong               module_flags;
+    FT_Int                 module_size;
+    const FT_String*       module_name;
+    FT_Fixed               module_version;
+    FT_Fixed               module_requires;
+
+    const void*            module_interface;
+
+    FT_Module_Constructor  module_init;
+    FT_Module_Destructor   module_done;
+    FT_Module_Requester    get_interface;
+
+  } FT_Module_Class;
+</font></pre>
+
+<p>here's a description of its fields:</p>
+
+<center><table cellpadding=5><tr valign=top><td>
+<p><b>module_flags</b></p>
+</td><td>
+<p>this is a set of bit flags used to describe the module's
+category. Valid values are:</p>
+  <ul>
+    <li><p>
+    <b>ft_module_font_driver</b> if the module is a font driver
+    </p></li>
+
+    <li><p>
+    <b>ft_module_renderer</b> if the module is a renderer
+    </p></li>
+
+    <li><p>
+    <b>ft_module_hinter</b> if the module is an auto-hinter
+    </p></li>
+
+    <li><p>
+    <b>ft_module_driver_scalable</b> if the module is a font
+    driver supporting scalable glyph formats.
+    </p></li>
+
+    <li><p>
+    <b>ft_module_driver_no_outlines</b> if the module is a
+    font driver supporting scalable glyph formats that <em>cannot</em>
+    be described by a <tt>FT_Outline</tt> object
+    </p></li>
+
+    <li><p>
+    <b>ft_module_driver_has_hinter</b> if the module is a font
+    driver that provides its own hinting scheme/algorithm
+    </p></li>
+  </ul>
+</td></tr><tr valign=top><td>
+
+<p><b>module_size</b></p>
+</td><td>
+<p>an integer that gives the size in <em>bytes</em> of a given module
+object. This should <em>never</em> be less than
+<tt>sizeof(FT_ModuleRec)</tt>, but can be more when the module
+needs to sub-class the base <tt>FT_ModuleRec</tt> class.</p>
+</td></tr><tr valign=top><td>
+
+<p><b>module_name</b></p>
+</td><td>
+<p>this is the module's internal name, coded as a simple ASCII C
+string. There can't be two modules with the same name registered
+in a given <tt>FT_Library</tt> object. However, <tt>FT_Add_Module</tt>
+uses the <b>module_version</b> field to detect module upgrades
+and perform them cleanly, even at run-time.</p>
+</td></tr><tr valign=top><td>
+
+<p><b>module_version</b></p>
+</td><td>
+<p>a 16.16 fixed float number giving the module's major and minor
+   version numbers. It is used to determine wether a module needs
+   to be upgraded when calling <tt>FT_Add_Module</tt>.</p>
+</td></tr><tr valign=top><td>
+
+<p><b>module_requires</b></p>
+</td><td>
+<p>a 16.16 fixed float number giving the version of FreeType 2 that
+   is required to install this module. By default, should be 0x20000
+   for FreeType 2.0</p>
+</td></tr><tr valign=top><td>
+
+<p><b>module_requires</b></p>
+</td><td>
+<p>most modules support one or more "interfaces", i.e. tables of function
+pointers. This field is used to point to the module's main interface,
+where there is one. It's a short-cut that prevents users of the module
+to call "get_interface" each time they need to access one of the object's
+common entry points.</p>
+
+<p>Note that is is optional, and can be set to NULL. Other interfaces
+can also be accessed through the <b>get_interface</b> field.</p>
+</td></tr><tr valign=top><td>
+
+<p><b>module_init</b></p>
+</td><td>
+<p>this is a pointer to a function used to initialise the fields of
+a fresh new <tt>FT_Module</tt> object. It is called <em>after</em> the module's
+base fields have been set by the library, and is generally used to
+initialise the fields of <tt>FT_ModuleRec</tt> subclasses.</p>
+
+<p>Most module classes set it to NULL to indicate that no extra
+initialisation is necessary</p>
+</td></tr><tr valign=top><td>
+
+<p><b>module_done</b></p>
+</td><td>
+<p>this is a pointer to a function used to finalise the fields of
+a given <tt>FT_Module</tt> object. Note that it is called <em>before</em> the
+library unsets the module's base fields, and is generally used to
+finalize the fields of <tt>FT_ModuleRec</tt> subclasses.</p>
+
+<p>Most module classes set it to NULL to indicate that no extra
+finalisation is necessary</p>
+</td></tr><tr valign=top><td>
+
+<p><b>get_interface</b></p>
+</td><td>
+<p>this is a pointer to a function used to request the address of
+a given module interface. Set it to NULL if you don't need to support
+additional interfaces but the main one.</p>
+</td></tr><tr valign=top><td>
+
+</td></tr></table></center>
+
+
+<h3>2. The <tt>FT_Module</tt> type:</h3>
+
+<p>the <tt>FT_Module</tt> type is a handle (i.e. a pointer) to a given
+   module object / instance, whose base structure is given by the
+   internal <tt>FT_ModuleRec</tt> type (we will not detail its
+   structure here).</p>
+
+<p>When <tt>FT_Add_Module</tt> is called, it first allocate a new
+   module instance, using the <tt><b>module_size</b></tt> class
+   field to determine its byte size. The function initializes
+   a the root <tt>FT_ModuleRec</tt> fields, then calls
+   the class-specific initializer <tt><b>module_init</b></tt>
+   when this field is not set to NULL.</p>
+
+
+
+
+<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
+<h1>Renderer Modules</h1>
+</td></tr></table>
+
+<p>As said previously, <b>renderers</b> are used to convert scalable
+   glyph images to bitmaps or pixmaps. Each renderer module is defined
+   through a <b>renderer class</b>, whose definition is found in the
+   file <tt>&lt;freetype/ftrender.h&gt;</tt>. However, a few concepts
+   need to be explained before having a detailed look at this structure.
+   </p>
+
+<h3>1. Glyph formats:</h3>
+
+<p>Each glyph image that is loaded by FreeType (either through
+   <tt>FT_Load_Glyph</tt> or <tt>FT_Load_Char</tt>), has a given
+   <em>image format</em>, described by the field
+   <tt>face-&gt;glyph-&gt;format</tt>. It is a 32-byte integer that
+   can take any value. However, the file <tt>&lt;freetype/ftimage.h&gt;</tt>
+   defines at least the following values:</p>
+
+<center><table cellpadding=5>
+<tr valign=top><td>
+<tt><b>ft_glyph_format_bitmap</b></tt>
+</td><td>
+this value is used to indicate that the glyph image is a bitmap or pixmap.
+Its content can then be accessed directly from
+<tt>face-&gt;glyph-&gt;bitmap</tt> after the glyph was loaded.
+</td></tr>
+
+<tr valign=top><td>
+<tt><b>ft_glyph_format_outline</b></tt>
+</td><td>
+this value is used to indicate that the glyph image is a scalable vectorial
+outline, that can be described by a <tt>FT_Outline</tt> object. Its content
+can be accessed directly from
+<tt>face-&gt;glyph-&gt;outline</tt> after the glyph was loaded.
+this is the format that is commonly returned by TrueType, Type1 and
+OpenType / CFF fonts.
+</td></tr>
+
+<tr valign=top><td>
+<tt><b>ft_glyph_format_plotter</b></tt>
+</td><td>
+this value is equivalent to <tt><b>ft_glyph_format_outline</b></tt> except
+that the outline stored corresponds to path strokes, instead of filled
+outlines. It can be returned from certain Type 1 fonts (notably the Hershey
+collection of free fonts).
+</td></tr>
+
+<tr valign=top><td>
+<tt><b>ft_glyph_format_composite</b></tt>
+</td><td>
+this value is used to indicate that the glyph image is really a "compound"
+of several other "sub-glyphs". This value is only returned when a glyph
+is loaded with the <tt><b>FT_LOAD_NO_RECURSE</b></tt> flag. The list of
+subglyphs that make up the composite can be accessed directly as
+<tt>face-&gt;glyph-&gt;subglyphs</tt> after the glyph was loaded.
+</td></tr>
+
+</table></center>
+
+<p>Note that this is only a list of pre-defined formats supported by
+   FreeType. Nothing prevents an application to install a new font
+   driver that creates other kinds of glyph images. For example, one
+   could imagine a MetaFont font driver, that would be capable to
+   parse font definition files and create in-memory "glyph programs",
+   that could be returned in <tt>face-&gt;glyph-&gt;other</tt>.</p>
+
+<h3>2. The <tt>FT_Outline</tt> type:</h3>
+
+<p>This structure, which is also defined, and heavily commented, in
+   the file <tt>&lt;freetype/ftimage.h&gt;</tt>, is used to hold
+   a scalable glyph image that is made of one or more contours, each
+   contour being described by line segments or bezier arcs (either
+   quadratic or cubic). The outline itself is stored in a compact
+   way that makes processing it easy.</p>
+
+<p>Points are placed in a 2D plane that uses the y-upwards convention,
+   and their coordinates are stored in 1/64th of pixels (also known
+   as the 26.6 fixed point format). Pixels correspond to single squares
+   whose borders are on integer coordinates (i.e. mutiples of 64).
+   In other words, pixel centers are located on half pixel coordinates.</p>
+
+<p>Outlines can be very easily transformed (translated, rotated, etc..)
+   before being converted to bitmap, which allows for sophisticated
+   use of text. FreeType 2 comes by default with two "outline renderer"
+   modules:</p>
+
+<p><ul>
+  <li><b>raster1</b>, used to convert them to monochrome bitmaps</li>
+  <li><b>smooth</b>, used to convert them to high-quality anti-aliased
+         pixmaps</li>
+</ul></p>
+
+<h3>3. Bitmaps and scan-conversion:</h3>
+
+<p>Bitmaps and pixmaps are described through a <tt>FT_Bitmap</tt>
+   structure, which is defined and heavily commented in
+   <tt>&lt;freetype/ftimage.h&gt;</tt>
+
+
+<pre><font color="blue">
+  typedef struct  FT_Renderer_Class_
+  {
+    FT_Module_Class       root;
+
+    FT_Glyph_Format       glyph_format;
+
+    FTRenderer_render     render_glyph;
+    FTRenderer_transform  transform_glyph;
+    FTRenderer_getCBox    get_glyph_cbox;
+    FTRenderer_setMode    set_mode;
+
+    FT_Raster_Funcs*      raster_class;
+
+  } FT_Renderer_Class;
+</font></pre>
+
+<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
+<h1>Font Driver Modules</h1>
+</td></tr></table>
+
+<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
+<h1>Library Initialisation & Dynamic Builds</h1>
+</td></tr></table>
+
+<p>By default, all components of FreeType 2 are compiled independently,
+   then grouped into a single static library file that can be installed
+   or used directly to compile client applications</p>
+
+<p>Such applications must normally call the <tt>FT_Init_FreeType</tt>
+   function before using the library. This function is in charge of
+   two things:</p>
+
+<ul>
+  <li><p>
+     First, it creates a <tt>FT_Library</tt> object (by calling
+     the public function <tt>FT_New_Library</tt>). This new
+     object is "empty" and has no module registered in it.
+  </p></li>
+
+  <li><p>
+     Then, it registers all "default modules" by repeatedly calling
+     <tt>FT_Add_Module</tt>.
+  </p></li>
+</ul>
+
+<p>It is important to notice that the default implementation of
+   <tt>FT_Init_FreeType</tt>, which is located in the source
+   file <tt>"src/base/ftinit.c"</tt> always uses a <em>static</em>
+   list of modules that is generated at compile time from the
+   configuration file <tt>&lt;freetype/config/ftmodule.h&gt;</tt>.
+</p>
+
+<p>There are cases where this may be inadequate. For example, one
+   might want to compile modules as independent DLLs in a specific
+   location (like <tt>"/usr/lib/freetype/module/"</tt>), and have
+   the library initialisation function load the modules dynamically
+   by parsing the directory's content</p>
+
+<p>This is possible, and we're going to explain how to do it.</p>
+
+
+<h4>a. Building the library as a DLL (i.e. "shared object" on Unix)</h4>
+
+<p>But first of all, let's explain how to build FreeType 2 as a single
+   DLL or shared object, i.e. one that includes the base layer, all
+   default modules and optional components into a single file.</p>
+
+<p>When building dynamic libraries, certain compilers require specific
+   directives to <em>declare</em> exported DLL entry points. For example, the
+   "<tt>__cdecl</tt>" directive is required by Win32 compilers, as it forces
+   the use of the "C" parameter passing convention (instead of "smarter"
+   schemes, which usually use registers and the stack to pass parameters).</p>
+
+<p>To make matter worse, some of these compilers require the directive
+   before the function's return type, while some others want it between
+   the return type and the function's identifier.</p>
+
+<p>To allow such compilations, the <tt>FT_EXPORT_DEF()</tt> macro is
+   used in all public header files in order to declare each high-level
+   API function of FreeType 2, as in the following example, taken from
+   <tt>&lt;freetype/freetype.h&gt;</tt>:</p>
+
+<pre><font color="blue">
+   FT_EXPORT_DEF(FT_Error)  FT_Init_FreeType( void );
+</font></pre>
+
+<p>the definition of <tt>FT_EXPORT_DEF(x)</tt> defaults to <tt>"extern x"</tt>,
+   except when a specific definition is given in the library's system-specific
+   configuration file <tt>&lt;freetype/config/ftconfig.h&gt;</tt>. This
+   allows project builders to specify the exact compilation directive
+   they need.</p>
+
+<p>Similarly, the <tt>FT_EXPORT_FUNC(x)</tt> macro is defined and used to
+   <em>define</em> exported functions within the FreeType 2 source code.
+   However, it is only used at compilation time.</p>
+
+
+<p>Note that on Unix, there is no need for specific exportation directives.
+   However, the code must be compiled in a special way, named Position
+   Independent Code ("PIC"), which is normally selected through specific
+   compiler flags (like "-PIC" with gcc).</p>
+
+
+<h4>b. Building modules as DLLs</h4>
+
+<p>In order to build modules as dynamic libraries, we first need to compile
+   the base layer (and optional components) as a single DLL. This is very
+   similar to the case we just described, except that we also need to
+   export all functions that are part of the "low level base API",
+   as these will get called by the modules in various cases.</p>
+
+<p>Similarly to the high-level API, all functions of the low-level base
+   API are declared in the internal header files of FreeType 2 with the
+   <tt>BASE_DEF(x)</tt> macro. The latter is similar to
+   <tt>FT_EXPORT_DEF</tt> and defaults to <tt>"extern x"</tt> unless
+   you specify a specific definition in
+   <tt>&lt;freetype/config/ftconfig.h&gt;</tt>.</p>
+<p>
+
+<hr>
+
+<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
+<h1>Conclusion</h1>
+</td></tr></table>
+
+</td></tr></table></center>
+</body>
+</html>
diff --git a/docs/docmaker.py b/docs/docmaker.py
index 812b599..b71d81f 100644
--- a/docs/docmaker.py
+++ b/docs/docmaker.py
@@ -101,12 +101,15 @@ source_footer = """</pre></table>
 # The first two markers contain arbitrary text, while the last one contains
 # a list of field
 #
-#
 # each field is simple of the format:  WORD :: TEXT....
 #
 # Note that typically, each comment block is followed by some source
 # code declaration that may need to be kept in the reference..
 #
+# Note that markers can alternatively be written as "@MARKER:"
+# instead of "<MAKRER>". All marker identifiers are converted to
+# lower case during parsing, in order to simply sorting..
+#
 
 
 def make_block_list():
@@ -323,8 +326,8 @@ class DocParagraph:
         #
         # but older Python versions don't have the `extend' attribute
         #
-        self.words[len( self.words ) : len( self.words )] = \
-          string.split( line )
+        last = len(self.words)
+        self.words[last:last] = string.split( line )
         
     
     def dump( self ):
@@ -360,6 +363,30 @@ class DocParagraph:
 #
 # DocContent is used to store the content of a given marker.
 #
+# the "self.items" list contains (field,elements) record, where
+# "field" corresponds to a given structure fields or function
+# parameter (indicated by a "::"), or NULL for a normal section
+# of text/code
+#
+# hence, the following example:
+#
+#   <MyMarker>
+#      this is an example of what can be put in a content section,
+#
+#      a second line of example text
+#
+#      x :: a simple test field, with some content
+#      y :: even before, this field has some code content
+#           {
+#             y = x+2;
+#           }
+#
+# should be stored as
+#     [ ( None, [ DocParagraph, DocParagraph] ),
+#       ( "x",  [ DocParagraph ] ),
+#       ( "y",  [ DocParagraph, DocCode ] ) ]
+# 
+#
 class DocContent:
 
     def __init__( self, lines_list ):
kc3-lang/freetype

Commit 6fbb95beb102edb94b730acb309a95530a0f0fd9
