* include/freetype/freetype.h, include/freetype/ftchapters.h: Add
a preliminary section with some explanations about user allocation.
* src/tools/docmaker/tohtml.py (HtmlFormatter.section_enter):
Don't abort if there are no data types, functions, etc., in a
section.
Print synopsis only if we have a data type, function, etc.
* docs/INSTALL.ANY, docs/INSTALL, docs/INSTALL.UNX, docs/CUSTOMIZE,
docs/INSTALL.GNU, docs/TRUETYPE, docs/DEBUG, docs/UPGRADE.UNX,
docs/VERSION.DLL, docs/formats.txt: Revised, formatted.
diff --git a/docs/DEBUG b/docs/DEBUG
index 4e13233..4b0501a 100644
--- a/docs/DEBUG
+++ b/docs/DEBUG
@@ -6,7 +6,7 @@
There are several ways to enable debugging features in a FreeType 2
builds. This is controlled through the definition of special macros
-located in the file "ftoptions.h". The macros are:
+located in the file `ftoptions.h'. The macros are:
FT_DEBUG_LEVEL_ERROR
@@ -23,7 +23,7 @@
FT_TRACE2, ..., FT_TRACE7.
The trace macros are used to send debugging messages when an
- appropriate "debug level" is configured at runtime through the
+ appropriate `debug level' is configured at runtime through the
FT2_DEBUG environment variable (more on this later).
FT_DEBUG_MEMORY
@@ -51,16 +51,17 @@
Several macros can be used within the FreeType sources to help debugging
its code:
+
1. FT_ERROR(( ... ))
This macro is used to send debug messages that indicate relatively
serious errors (like broken font files), but will not stop the
execution of the running program. Its code is compiled only when
either FT_DEBUG_LEVEL_ERROR or FT_DEBUG_LEVEL_TRACE are defined in
- "ftoption.h".
+ `ftoption.h'.
Note that you have to use a printf-like signature, but with double
- parentheses, like in:
+ parentheses, like in
FT_ERROR(( "your %s is not %s\n", "foo", "bar" ));
@@ -70,31 +71,31 @@
This macro is used to check strong assertions at runtime. If its
condition isn't TRUE, the program will abort with a panic message.
Its code is compiled when either FT_DEBUG_LEVEL_ERROR or
- FT_DEBUG_LEVEL_TRACE are defined. You don't need double-parentheses
- here. For example:
+ FT_DEBUG_LEVEL_TRACE are defined. You don't need double parentheses
+ here. For example
FT_ASSERT( ptr != NULL );
3. FT_TRACE( level, (message...) )
-
+
The FT_TRACE macro is used to send general-purpose debugging
messages during program execution. This macro uses an *implicit*
macro named FT_COMPONENT used to name the current FreeType component
being run.
The developer should always define FT_COMPONENT as appropriate, for
- example as in:
+ example as in
#undef FT_COMPONENT
#define FT_COMPONENT trace_io
The value of the FT_COMPONENT macro is an enumeration named
trace_XXXX where XXXX is one of the component names defined in the
- internal file <freetype/internal/fttrace.h>.
+ internal file `freetype/internal/fttrace.h'.
- Each such component is assigned a "debug level", ranging from 0
- to 7, through the use of the FT2_DEBUG environment variable
+ Each such component is assigned a `debug level', ranging from 0
+ to 7, through the use of the FT2_DEBUG environment variable
(described below) when a program linked with FreeType starts.
When FT_TRACE is called, its level is compared to the one of the
@@ -106,11 +107,11 @@
least* 2.
The second parameter to FT_TRACE must contain parentheses and
- correspond to a printf-like call, as in:
+ correspond to a printf-like call, as in
FT_TRACE( 2, ( "your %s is not %s\n", "foo", "bar" ) )
- The shortcut macros FT_TRACE0, FT_TRACE1, FT_TRACE2_, ... FT_TRACE7
+ The shortcut macros FT_TRACE0, FT_TRACE1, FT_TRACE2, ..., FT_TRACE7
can be used with constant level indices, and are much cleaner to
use, as in
@@ -121,7 +122,8 @@
--------------------------
The following environment variables control debugging output and
-behaviour of FreeType at runtime:
+behaviour of FreeType at runtime.
+
FT2_DEBUG
@@ -131,19 +133,20 @@
component1:level1 component2:level2 component3:level3 ...
- where "componentX" is the name of a tracing component, as defined in
- "fttrace.h", but without the "trace_" prefix. "levelX" is the
+ where `componentX' is the name of a tracing component, as defined in
+ `fttrace.h', but without the `trace_' prefix. `levelX' is the
corresponding level to use at runtime.
- "any" is a special component name that will be interpreted as
- "any/all components". For example, the following definitions
+ `any' is a special component name that will be interpreted as
+ `any/all components'. For example, the following definitions
set FT2_DEBUG=any:2 memory:5 io:4 (on Windows)
export FT2_DEBUG="any:2 memory:5 io:4" (on Linux with bash)
both stipulate that all components should have level 2, except for
- the memory and io components which will be set to trace levels 5
- and 4, respectively.
+ the memory and io components which will be set to trace levels 5 and
+ 4, respectively.
+
FT2_DEBUG_MEMORY
@@ -154,9 +157,10 @@
considerably saves time when debugging new additions to the library.
This code is only compiled when FreeType is built with the
- FT_DEBUG_MEMORY macro #defined in "ftoption.h" though, it will be
+ FT_DEBUG_MEMORY macro #defined in `ftoption.h' though, it will be
ignored in other builds.
+
FT2_ALLOC_TOTAL_MAX
This variable is ignored if FT2_DEBUG_MEMORY is not defined. It
@@ -168,6 +172,7 @@
If it is undefined, or if its value is not strictly positive, then
no allocation bounds are checked at runtime.
+
FT2_ALLOC_COUNT_MAX
This variable is ignored if FT2_DEBUG_MEMORY is not defined. It
@@ -177,17 +182,17 @@
engine's robustness.
If it is undefined, or if its value is not strictly positive, then
- no allocation bounsd are checked at runtime.
+ no allocation bounds are checked at runtime.
------------------------------------------------------------------------
-Copyright 2002, 2003, 2004 by
+Copyright 2002, 2003, 2004, 2005 by
David Turner, Robert Wilhelm, and Werner Lemberg.
-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
+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.