ref: 6fbb95beb102edb94b730acb309a95530a0f0fd9
parent: 3c7c5da3bb3b4ac18e6af261c1712fb0f6d62799
author: David Turner <[email protected]>
date: Mon Oct 23 14:32:55 EDT 2000
- added first draft of "Modules in FreeType 2" - minor formatting / testing in docmaker.py
binary files /dev/null b/docs/design/basic-design.png differ
binary files /dev/null b/docs/design/detailed-design.png differ
--- /dev/null
+++ b/docs/design/modules.html
@@ -1,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><freetype/ftmodule.h></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><freetype/ftrender.h></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->glyph->format</tt>. It is a 32-byte integer that
+ can take any value. However, the file <tt><freetype/ftimage.h></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->glyph->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->glyph->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->glyph->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->glyph->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><freetype/ftimage.h></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><freetype/ftimage.h></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><freetype/config/ftmodule.h></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><freetype/freetype.h></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><freetype/config/ftconfig.h></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><freetype/config/ftconfig.h></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>
--- a/docs/docmaker.py
+++ b/docs/docmaker.py
@@ -101,12 +101,15 @@
# 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 @@
#
# 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 ):
@@ -359,6 +362,30 @@
###########################################################################
#
# 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: