From a723526ae75fbdbe26f59940c2de994c6c3fb0bb Mon Sep 17 00:00:00 2001 From: Werner Lemberg Date: Tue, 30 Aug 2005 00:22:46 +0000 Subject: [PATCH] * 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. --- ChangeLog | 14 ++++++++ docs/CUSTOMIZE | 61 +++++++++++++++++---------------- docs/DEBUG | 59 +++++++++++++++++--------------- docs/INSTALL | 52 +++++++++++++++++------------ docs/INSTALL.ANY | 41 ++++++++++++----------- docs/INSTALL.GNU | 48 ++++++++++++++------------ docs/INSTALL.UNX | 25 ++++++++------ docs/TRUETYPE | 23 +++++++------ docs/UPGRADE.UNX | 57 ++++++++++++++++--------------- docs/VERSION.DLL | 37 ++++++++++---------- docs/formats.txt | 63 ++++++++++++++++++----------------- include/freetype/freetype.h | 20 +++++++++++ include/freetype/ftchapters.h | 15 +++++++++ src/tools/docmaker/tohtml.py | 50 ++++++++++++++------------- 14 files changed, 324 insertions(+), 241 deletions(-) diff --git a/ChangeLog b/ChangeLog index f1321a62c..f3d4c91a5 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,17 @@ +2005-08-29 Werner Lemberg + + * 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. + 2005-08-28 George Williams * src/truetype/ttgload.c [TT_MAX_COMPOSITE_RECURSE]: Removed. diff --git a/docs/CUSTOMIZE b/docs/CUSTOMIZE index e2beb6891..e1b3c065e 100644 --- a/docs/CUSTOMIZE +++ b/docs/CUSTOMIZE @@ -1,5 +1,5 @@ -How to customize the compilation of the library: -================================================ +How to customize the compilation of the library +=============================================== FreeType is highly customizable to fit various needs, and this document describes how it is possible to select options and components @@ -8,7 +8,7 @@ How to customize the compilation of the library: I. Configuration macros - The file found in "include/freetype/config/ftoption.h" contains a list + The file found in `include/freetype/config/ftoption.h' contains a list of commented configuration macros that can be toggled by developers to indicate which features should be active while building the library. @@ -22,23 +22,28 @@ I. Configuration macros II. Modules list - The file found in "include/freetype/config/ftmodule.h" contains a list + The file found in `include/freetype/config/ftmodule.h' contains a list of names corresponding to the modules and font drivers to be statically compiled in the FreeType library during the build. You can change it to suit your own preferences. Be aware that certain - modules depend on others, as described by the file "modules.txt" in + modules depend on others, as described by the file `modules.txt' in this directory. You can modify the file's content to suit your needs, or override it at compile time with one of the methods described below. + Note that you also have to rename the various `*.mk' files in the + module directories which you want to exclude so that the extension + isn't `.mk' -- GNU make uses a simple globbing mechanism to include + all those files. + III. System interface FreeType's default interface to the system (i.e., the parts that deal with memory management and i/o streams) is located in - "src/base/ftsystem.c". + `src/base/ftsystem.c'. The current implementation uses standard C library calls to manage memory and to read font files. It is however possible to write custom @@ -74,32 +79,32 @@ IV. Overriding default configuration and module headers Use the C include path to ensure that your own versions of the files are used at compile time when the lines - #include FT_CONFIG_OPTIONS_H - #include FT_CONFIG_MODULES_H + #include FT_CONFIG_OPTIONS_H + #include FT_CONFIG_MODULES_H are compiled. Their default values being and , you can do something like: - custom/ - freetype/ - config/ - ftoption.h => custom options header - ftmodule.h => custom modules list + custom/ + freetype/ + config/ + ftoption.h => custom options header + ftmodule.h => custom modules list - include/ => normal FreeType 2 include - freetype/ - ... + include/ => normal FreeType 2 include + freetype/ + ... - then change the C include path to always give the path to "custom" - before the FreeType 2 "include". + then change the C include path to always give the path to `custom' + before the FreeType 2 `include'. - 2. Re-defining FT_CONFIG_OPTIONS_H and FT_CONFIG_MODULES_H + 2. Redefining FT_CONFIG_OPTIONS_H and FT_CONFIG_MODULES_H Another way to do the same thing is to redefine the macros used to name the configuration headers. To do so, you need a custom - "ft2build.h" whose content can be as simple as: + `ft2build.h' whose content can be as simple as: #ifndef __FT2_BUILD_MY_PLATFORM_H__ #define __FT2_BUILD_MY_PLATFORM_H__ @@ -111,25 +116,25 @@ IV. Overriding default configuration and module headers #endif /* __FT2_BUILD_MY_PLATFORM_H__ */ - Place those files in a separate directory, e.g.: + Place those files in a separate directory, e.g., custom/ ft2build.h => custom version described above my-ftoption.h => custom options header my-ftmodule.h => custom modules list header - and change the C include path to ensure that "custom" is always - placed before the FT2 "include" during compilation. + and change the C include path to ensure that `custom' is always + placed before the FT2 `include' during compilation. ------------------------------------------------------------------------ -Copyright 2003 by +Copyright 2003, 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. diff --git a/docs/DEBUG b/docs/DEBUG index 4e1323391..4b0501aff 100644 --- a/docs/DEBUG +++ b/docs/DEBUG @@ -6,7 +6,7 @@ I. Configuration macros 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 @@ located in the file "ftoptions.h". The macros are: 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 @@ II. Debugging macros 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 @@ its code: 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 . + 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 @@ its code: 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 @@ III. Environment variables -------------------------- The following environment variables control debugging output and -behaviour of FreeType at runtime: +behaviour of FreeType at runtime. + FT2_DEBUG @@ -131,19 +133,20 @@ behaviour of FreeType at runtime: 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 @@ behaviour of FreeType at runtime: 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 @@ behaviour of FreeType at runtime: 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 @@ behaviour of FreeType at runtime: 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. diff --git a/docs/INSTALL b/docs/INSTALL index b342d96de..d53cafafc 100644 --- a/docs/INSTALL +++ b/docs/INSTALL @@ -10,41 +10,46 @@ I. Normal installation and upgrades 1. Native TrueType Hinting Native TrueType hinting is disabled by default[1]. If you really - need it, read the file "TRUETYPE" for information. + need it, read the file `TRUETYPE' for information. + 2. Unix Systems (as well as Cygwin or MSys on Windows) - Please read *both* UPGRADE.UNX and INSTALL.UNX to install or upgrade - FreeType 2 on a Unix system. Note that you *will* need GNU Make, + Please read *both* `UPGRADE.UNX' and `INSTALL.UNX' to install or + upgrade FreeType 2 on a Unix system. Note that you *need* GNU Make, since other make tools won't work (this includes BSD Make). - 3. On VMS with the "mms" build tool + + 3. On VMS with the `mms' build tool - See INSTALL.VMS for installation instructions on this platform. + See `INSTALL.VMS' for installation instructions on this platform. + 4. Other systems using GNU Make On non-Unix platforms, it is possible to build the library using GNU - Make utility. Note that *NO OTHER MAKE TOOL WILL WORK*[2]! This + Make utility. Note that *NO OTHER MAKE TOOL WILL WORK*[2]! This methods supports several compilers on Windows, OS/2, and BeOS, - including Mingw, Visual C++, Borland C++, and more. + including MinGW, Visual C++, Borland C++, and more. - Instructions are provided in the file "INSTALL.GNU". + Instructions are provided in the file `INSTALL.GNU'. - 5. With an IDE Project File (e.g. for Visual Studio or CodeWarrior) + + 5. With an IDE Project File (e.g., for Visual Studio or CodeWarrior) - We provide a small number of "project files" for various IDEs to + We provide a small number of `project files' for various IDEs to automatically build the library as well. Note that these files are - not supported and sporadically maintained by FreeType developers, so - don't expect them to work in each release. + not supported and only sporadically maintained by FreeType + developers, so don't expect them to work in each release. - To find them, have a look at the content of the "builds/" + To find them, have a look at the content of the `builds/' directory, where stands for your OS or environment. + 6. From you own IDE, or own Makefiles If you want to create your own project file, follow the instructions - given in the "INSTALL.ANY" document of this directory. + given in the `INSTALL.ANY' document of this directory. II. Custom builds of the library @@ -52,7 +57,7 @@ II. Custom builds of the library Customizing the compilation of FreeType is easy, and allows you to select only the components of the font engine that you really need. - For more details read the file "CUSTOMIZE". + For more details read the file `CUSTOMIZE'. ------------------------------------------------------------------------ @@ -60,19 +65,22 @@ II. Custom builds of the library [1] More details on: http://www.freetype.org/patents.html [2] make++, a make tool written in Perl, has sufficient support of GNU - make extensions to build FreeType. See - http://makepp.sourceforge.net for more information; you need version - 1.19 or newer, and you must pass option `--norc-substitution'. + make extensions to build FreeType. See + + http://makepp.sourceforge.net + + for more information; you need version 1.19 or newer, and you must + pass option `--norc-substitution'. ------------------------------------------------------------------------ Copyright 2000, 2001, 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. diff --git a/docs/INSTALL.ANY b/docs/INSTALL.ANY index 4045b2fa9..75e701a0c 100644 --- a/docs/INSTALL.ANY +++ b/docs/INSTALL.ANY @@ -1,26 +1,26 @@ Instructions on how to build FreeType with your own build tool ============================================================== -See the file `CUSTOMIZE' to learn how to customize FreeType to -specific environments. +See the file `CUSTOMIZE' to learn how to customize FreeType to specific +environments. I. Standard procedure --------------------- - * DISABLE PRE-COMPILED HEADERS! This is very important for Visual + * DISABLE PRE-COMPILED HEADERS! This is very important for Visual C++, because FreeType uses lines like: #include FT_FREETYPE_H - which are not correctly supported by this compiler while being ISO - C compliant! + which are not correctly supported by this compiler while being ISO C + compliant! - * You need to add the directories `freetype2/include' to your - include path when compiling the library. + * You need to add the directories `freetype2/include' to your include + path when compiling the library. - * FreeType 2 is made of several components; each of them is located - in a subdirectory of `freetype2/src'. For example, + * FreeType 2 is made of several components; each of them is located in + a subdirectory of `freetype2/src'. For example, `freetype2/src/truetype/' contains the TrueType font driver. * DO NOT COMPILE ALL C FILES! Rather, compile the following ones: @@ -85,14 +85,17 @@ I. Standard procedure `type42.c' needs `truetype.c' - You are done. In case of problems, see the archives of the FreeType + Read the file `CUSTOMIZE' in case you want to compile only a subset of + the drivers, renderers, and optional modules. + + You are done. In case of problems, see the archives of the FreeType development mailing list. II. Support for flat-directory compilation ------------------------------------------ - It is possible to put all FreeType 2 source files into a single + It is possible to put all FreeType 2 source files into a single directory, with the *exception* of the `include' hierarchy. 1. Copy all files in current directory @@ -110,19 +113,19 @@ II. Support for flat-directory compilation cc -c -Ifreetype2/include ftbase.c etc. - You don't need to define the FT_FLAT_COMPILATION macro (as this - was required in previous releases of FreeType 2). + You don't need to define the FT_FLAT_COMPILATION macro (as this was + required in previous releases of FreeType 2). ----------------------------------------------------------------------- +------------------------------------------------------------------------ Copyright 2003, 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 accept it fully. +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. --- end of INSTALL.ANY --- diff --git a/docs/INSTALL.GNU b/docs/INSTALL.GNU index cd2208ec5..096b4b5f6 100644 --- a/docs/INSTALL.GNU +++ b/docs/INSTALL.GNU @@ -11,20 +11,22 @@ the file INSTALL.UNX instead. 1. Install GNU Make ------------------- - Because GNU Make is the only Make tool supported to compile - FreeType 2, you should install it on your machine. + Because GNU Make is the only Make tool supported to compile FreeType + 2, you should install it on your machine. The FreeType 2 build system relies on many features special to GNU - Make -- trying to build the library with any other Make tool will - *fail*. + Make. - NEARLY ALL OTHER MAKE TOOLS WILL FAIL, INCLUDING "BSD MAKE", SO - REALLY INSTALL A RECENT VERSION OF GNU MAKE ON YOUR SYSTEM! + NEARLY ALL OTHER MAKE TOOLS FAIL, INCLUDING `BSD MAKE', SO REALLY + INSTALL A RECENT VERSION OF GNU MAKE ON YOUR SYSTEM! Note that make++, a make tool written in Perl, supports enough - features of GNU make to compile FreeType. See - http://makepp.sourceforge.net for more information; you need version - 1.19 or newer, and you must pass option `--norc-substitution'. + features of GNU make to compile FreeType. See + + http://makepp.sourceforge.net + + for more information; you need version 1.19 or newer, and you must + pass option `--norc-substitution'. Make sure that you are invoking GNU Make from the command line, by typing something like: @@ -36,7 +38,7 @@ the file INSTALL.UNX instead. VERSION 3.78.1 OR NEWER IS NEEDED! - 2. Invoke 'make' + 2. Invoke `make' ---------------- Go to the root directory of FreeType 2, then simply invoke GNU Make @@ -59,13 +61,15 @@ the file INSTALL.UNX instead. remove the file 'config.mk' from this directory then read the INSTALL file for help. - Otherwise, simply type 'make' again to build the library. + Otherwise, simply type 'make' again to build the library + or 'make refdoc' to build the API reference (the latter needs + python). ============================================================= If the detected settings correspond to your platform and compiler, skip to step 5. Note that if your platform is completely alien to - the build system, the detected platform will be 'ansi'. + the build system, the detected platform will be `ansi'. 3. Configure the build system for a different compiler @@ -90,9 +94,9 @@ the file INSTALL.UNX instead. The name to use is platform-dependent. The list of available compilers for your system is available in the file - `builds//detect.mk' + `builds//detect.mk'. - If you are satisfied by the new configuration summary, skip to + If you are satisfied by the new configuration summary, skip to step 5. @@ -131,20 +135,20 @@ the file INSTALL.UNX instead. Final note The build system builds a statically linked library of the font - engine in the "objs" directory. It does _not_ support the build of + engine in the `objs' directory. It does _not_ support the build of DLLs on Windows and OS/2. If you need these, you have to either use - a IDE-specific project file, or follow the instructions in - "INSTALL.ANY" to create your own Makefiles. + an IDE-specific project file, or follow the instructions in + `INSTALL.ANY' to create your own Makefiles. ------------------------------------------------------------------------ -Copyright 2003, 2004 by +Copyright 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. diff --git a/docs/INSTALL.UNX b/docs/INSTALL.UNX index 52f282025..f6deea8c7 100644 --- a/docs/INSTALL.UNX +++ b/docs/INSTALL.UNX @@ -1,5 +1,5 @@ This document contains instructions on how to build the FreeType library -on Unix systems. This also works for emulations like Cygwin or MSys on +on Unix systems. This also works for emulations like Cygwin or MSys on Win32: @@ -12,8 +12,11 @@ Win32: [Well, this is not really correct. Recently, a perl implementation of make called `makepp' has appeared which can also build FreeType 2 - successfully on Unix platforms. See http://makepp.sourceforge.net - for more details; you need version 1.19 or newer, and you must pass + successfully on Unix platforms. See + + http://makepp.sourceforge.net + + for more details; you need version 1.19 or newer, and you must pass option `--norc-substitution'.] Trying to compile the library with a different Make tool will print @@ -36,7 +39,7 @@ Win32: make make install (as root) - The default installation path is "/usr/local". It can be changed + The default installation path is `/usr/local'. It can be changed with the `--prefix=' option. Example: ./configure --prefix=/usr @@ -49,8 +52,8 @@ Win32: gmake gmake install (as root) - If this still doesn't work, something's rotten on your system - (e.g. you are using a very old version of GNU Make). + If this still doesn't work, there must be a problem with your system + (e.g., you are using a very old version of GNU Make). It is possible to compile FreeType in a different directory. Assuming the FreeType source files in directory `/src/freetype' a @@ -63,13 +66,13 @@ Win32: ------------------------------------------------------------------------ -Copyright 2003, 2004 by +Copyright 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. diff --git a/docs/TRUETYPE b/docs/TRUETYPE index 30029f4d2..27bfd443c 100644 --- a/docs/TRUETYPE +++ b/docs/TRUETYPE @@ -1,20 +1,23 @@ How to enable the TrueType native hinter if you need it --------------------------------------------------------- +------------------------------------------------------- The TrueType bytecode interpreter is disabled in all public releases - of the FreeType packages for patents reasons (see - http://www.freetype.org/patents.html for more details). + of the FreeType packages for patents reasons; see + + http://www.freetype.org/patents.html + + for more details. However, many Linux distributions do enable the interpreter in the FreeType packages (DEB/RPM/etc.) they produce for their platforms. If you are using TrueType fonts on your system, you most probably want to enable it manually by doing the following: - - open the file "include/freetype/config/ftoption.h" + - open the file `include/freetype/config/ftoption.h' - locate a line that says: - #undef TT_CONFIG_OPTION_BYTECODE_INTERPRETER + #undef TT_CONFIG_OPTION_BYTECODE_INTERPRETER - change it to: @@ -24,13 +27,13 @@ How to enable the TrueType native hinter if you need it ------------------------------------------------------------------------ -Copyright 2003 by +Copyright 2003, 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. diff --git a/docs/UPGRADE.UNX b/docs/UPGRADE.UNX index 6c273d4ef..de1b35b32 100644 --- a/docs/UPGRADE.UNX +++ b/docs/UPGRADE.UNX @@ -10,7 +10,7 @@ SPECIAL NOTE FOR UNIX USERS 1. Enable the TrueType bytecode hinter if you need it ----------------------------------------------------- - See the instructions in the file "TRUETYPE" of this directory. + See the instructions in the file `TRUETYPE' of this directory. Note that FreeType supports TrueType fonts without the bytecode interpreter through its auto-hinter, which now generates relatively @@ -20,9 +20,9 @@ SPECIAL NOTE FOR UNIX USERS 2. Determine the correct installation path ------------------------------------------ - By default, the configure script will install the library in - "/usr/local". However, many Unix distributions now install the - library in "/usr", since FreeType is becoming a critical system + By default, the configure script installs the library in + `/usr/local'. However, many Unix distributions now install the + library in `/usr', since FreeType is becoming a critical system component. If FreeType is already installed on your system, type @@ -30,11 +30,11 @@ SPECIAL NOTE FOR UNIX USERS freetype-config --prefix on the command line. This should return the installation path - (e.g., "/usr" or "/usr/local"). To avoid problems of parallel + (e.g., `/usr' or `/usr/local'). To avoid problems of parallel FreeType versions, use this path for the --prefix option of the configure script. - Otherwise, simply use "/usr" (or whatever you think is adequate for + Otherwise, simply use `/usr' (or whatever you think is adequate for your installation). @@ -47,14 +47,13 @@ SPECIAL NOTE FOR UNIX USERS the library with the instructions below using any other alternative (including BSD Make). - Trying to compile the library with a different Make tool will print - a message like: + Trying to compile the library with a different Make tool prints a + message like: Sorry, GNU make is required to build FreeType2. - and the build process will be aborted. If this happens, install GNU - Make on your system, and use the GNUMAKE environment variable to - name it. + and the build process is aborted. If this happens, install GNU Make + on your system, and use the GNUMAKE environment variable to name it. 4. Build and install the library @@ -67,24 +66,24 @@ SPECIAL NOTE FOR UNIX USERS make make install (as root) - where "" must be replaced by the prefix returned by the - "freetype-config" command. + where `' must be replaced by the prefix returned by the + `freetype-config' command. When using a different command to invoke GNU Make, use the GNUMAKE variable. For example, if `gmake' is the command to use on your system, do something like: - GNUMAKE=gmake ./configure --prefix= - gmake - gmake install (as root) + GNUMAKE=gmake ./configure --prefix= + gmake + gmake install (as root) 5. Take care of XFree86 version 4 --------------------------------- - Certain recent Linux distributions will install _several_ versions - of FreeType on your system. For example, on a fresh Mandrake 8.1 - system, you can find the following files: + Certain Linux distributions install _several_ versions of FreeType + on your system. For example, on a fresh Mandrake 8.1 system, you + can find the following files: /usr/lib/libfreetype.so which links to /usr/lib/libfreetype.6.1.0.so @@ -97,16 +96,16 @@ SPECIAL NOTE FOR UNIX USERS Note that these files correspond to two distinct versions of the library! It seems that this surprising issue is due to the install scripts of recent XFree86 servers (from 4.1.0) which install their - own (dated) version of the library in "/usr/X11R6/lib". + own (dated) version of the library in `/usr/X11R6/lib'. In certain _rare_ cases you may experience minor problems if you - install this release of the library in "/usr" only, namely, that - certain applications will not benefit from the bug fixes and - rendering improvements you would expect. + install this release of the library in `/usr' only, namely, that + certain applications do not benefit from the bug fixes and rendering + improvements you would expect. There are two good ways to deal with this situation: - - Install the library _twice_, in "/usr" and in "/usr/X11R6" (you + - Install the library _twice_, in `/usr' and in `/usr/X11R6' (you have to do that each time you install a new FreeType release though). @@ -125,13 +124,13 @@ SPECIAL NOTE FOR UNIX USERS ------------------------------------------------------------------------ -Copyright 2003 by +Copyright 2003, 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. diff --git a/docs/VERSION.DLL b/docs/VERSION.DLL index f7cf88c02..b880ffc6b 100644 --- a/docs/VERSION.DLL +++ b/docs/VERSION.DLL @@ -1,4 +1,4 @@ -Due to our use of "libtool" to generate and install the FreeType 2 +Due to our use of `libtool' to generate and install the FreeType 2 libraries on Unix systems, as well as other historical events, it is generally very difficult to know precisely which release of the font engine is installed on a given system. @@ -7,19 +7,19 @@ This file tries to explain why and to document ways to properly detect FreeType on Unix. -1. Version & Release numbers ----------------------------- +1. Version and Release numbers +------------------------------ For each new public release of FreeType 2, there are generally *three* -distinct "version" numbers to consider: +distinct `version' numbers to consider: * The official FT2 release number, like 2.0.9, or 2.1.3. - * The libtool (and Unix) specific version number, like "9.2.3". This - is what "freetype-config --version" will return. + * The libtool (and Unix) specific version number, like 9.2.3. This is + what `freetype-config --version' returns. * The platform-specific shared object number, used for example when - the library is installed as "/usr/lib/libfreetype.so.6.3.2". + the library is installed as `/usr/lib/libfreetype.so.6.3.2'. The platform-specific number is, unsurprisingly, platform-specific and varies with the operating system you are using (several variants of @@ -32,14 +32,14 @@ tied to it. The release number is available at *compile* time through the following macros defined in FT_FREETYPE_H: - - FREETYPE_MAJOR : major release number - - FREETYPE_MINOR : minor release number - - FREETYPE_PATCH : patch release number + - FREETYPE_MAJOR: major release number + - FREETYPE_MINOR: minor release number + - FREETYPE_PATCH: patch release number See below for a small autoconf fragment. The release number is also available at *runtime* through the -"FT_Library_Version" API. Unfortunately, this one wasn't available or +`FT_Library_Version' API. Unfortunately, this one wasn't available or working correctly before the 2.1.3 official release. @@ -50,6 +50,7 @@ The following table gives, for each official release, the corresponding libtool number, as well as the shared object number found on _most_ systems, but not all of them: + release libtool so ------------------------------- 2.2.0 9.9.3 6.3.9 @@ -74,10 +75,10 @@ The libtool numbers are a bit inconsistent due to the library's history: - 2.1.0 was created as a development branch from 2.0.8 (hence the same libtool numbers). - - 2.0.9 was a bug-fix release of the "stable" branch, and we + - 2.0.9 was a bug-fix release of the `stable' branch, and we incorrectly increased its libtool number. - - 2.1.4 is still in the "development" branch, however it is stable + - 2.1.4 is still in the `development' branch, however it is stable enough to be the basis of an upcoming 2.2.0 release. @@ -86,7 +87,7 @@ The libtool numbers are a bit inconsistent due to the library's history: Lars Clausen contributed the following autoconf fragment to detect which version of FreeType is installed on a system. This one tests for a -version that is at least 2.0.9; you should change it to check against +version that is at least 2.0.9; you should change it to check against other release numbers. @@ -113,10 +114,10 @@ other release numbers. 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. diff --git a/docs/formats.txt b/docs/formats.txt index 332af0a89..2f7c3d94e 100644 --- a/docs/formats.txt +++ b/docs/formats.txt @@ -1,46 +1,46 @@ -This file contains a list of various font formats. It gives the +This file contains a list of various font formats. It gives the reference document and whether it is supported in FreeType 2. file type: - The only special case is `MAC'; on older Mac OS versions, a `file' - is stored as a data and a resource fork, this is, within two - separate data chunks. In all other cases, the font data is stored + The only special case is `MAC'; on older Mac OS versions, a `file' + is stored as a data and a resource fork, this is, within two + separate data chunks. In all other cases, the font data is stored in a single file. wrapper format: - The format used to represent the font data. In the table below it - is used only if the font format differs. Possible values are - `SFNT' (binary), `PS' (a text header, followed by binary or text - data), and `LZW' (compressed with either `gzip' or `compress'). + The format used to represent the font data. In the table below it + is used only if the font format differs. Possible values are `SFNT' + (binary), `PS' (a text header, followed by binary or text data), and + `LZW' (compressed with either `gzip' or `compress'). font format: - How the font is to be accessed, possibly after converting the file - type and wrapper format into a generic form. Bitmap formats are - `BDF', `PCF', and one form of `WINFNT'; all others are vector + How the font is to be accessed, possibly after converting the file + type and wrapper format into a generic form. Bitmap formats are + `BDF', `PCF', and one form of `WINFNT'; all others are vector formats. font type: - Sub-formats of the font format. `SBIT' and `MACSBIT' are bitmap + Sub-formats of the font format. `SBIT' and `MACSBIT' are bitmap formats, `MM' and `VAR' support optical axes. glyph access: - If not specified, the glyph access is `standard' to the font - format. Values are `CID' for CID-keyed fonts, `SYNTHETIC' for - fonts which are modified versions of other fonts by means of a - transformation matrix, `COLLECTION' for collecting multiple fonts - (sharing most of the data) into a single file, and `TYPE_0' for PS - fonts which are to be accessed in a tree-like structure. + If not specified, the glyph access is `standard' to the font format. + Values are `CID' for CID-keyed fonts, `SYNTHETIC' for fonts which + are modified versions of other fonts by means of a transformation + matrix, `COLLECTION' for collecting multiple fonts (sharing most of + the data) into a single file, and `TYPE_0' for PS fonts which are to + be accessed in a tree-like structure. FreeType driver: - The module in the FreeType library which handles the specific font - format. A missing entry means that FreeType doesn't support the + The module in the FreeType library which handles the specific font + format. A missing entry means that FreeType doesn't support the font format (yet). -Please send additions and/or corrections to wl@gnu.org or to the -FreeType developer's list at freetype-devel@nongnu.org (for subscribers -only). If you can provide a font example for a format which isn't +Please send additions and/or corrections to wl@gnu.org or to the +FreeType developer's list at freetype-devel@nongnu.org (for subscribers +only). If you can provide a font example for a format which isn't supported yet please send a mail too. @@ -122,16 +122,17 @@ MAC --- PS TYPE_1 --- type1 T1_SPEC.pdf --- --- WINFNT VECTOR --- --- MS Windows 3 Developer's Notes -[1] Support should be rather simple since this is identical to `CFF' - but in a PS wrapper. +[1] Support should be rather simple since this is identical to `CFF' but + in a PS wrapper. [2] Official PFR specification: http://www.bitstream.com/categories/developer/truedoc/pfrspec.html http://www.bitstream.com/categories/developer/truedoc/pfrspec1.2.pdf - The syntax of the auxiliary data is not defined there, but is partially - defined in MHP 1.0.3 (also called ETSI TS 101812 V1.3.1) section 7.4. + The syntax of the auxiliary data is not defined there, but is + partially defined in MHP 1.0.3 (also called ETSI TS 101812 V1.3.1) + section 7.4. http://www.etsi.org/ http://webapp.etsi.org/workprogram/Report_WorkItem.asp?WKI_ID=18799 @@ -143,10 +144,10 @@ MAC --- PS TYPE_1 --- type1 T1_SPEC.pdf Copyright 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. diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h index 345d4fb81..7976b4fb2 100644 --- a/include/freetype/freetype.h +++ b/include/freetype/freetype.h @@ -56,6 +56,26 @@ FT_BEGIN_HEADER + /*************************************************************************/ + /* */ + /*
*/ + /* user_allocation */ + /* */ + /* */ + /* User allocation */ + /* */ + /* <Abstract> */ + /* How client applications should allocate FreeType data structures. */ + /* */ + /* <Description> */ + /* FreeType assumes that structures allocated by the user and passed */ + /* as arguments are zeroed out except for the actual data. With */ + /* other words, it is recommended to use `calloc' (or variants of it) */ + /* instead of `malloc' for allocation. */ + /* */ + /*************************************************************************/ + + /*************************************************************************/ /*************************************************************************/ /* */ diff --git a/include/freetype/ftchapters.h b/include/freetype/ftchapters.h index 0d2f87bf3..9fd25a376 100644 --- a/include/freetype/ftchapters.h +++ b/include/freetype/ftchapters.h @@ -6,6 +6,20 @@ /***************************************************************************/ +/***************************************************************************/ +/* */ +/* <Chapter> */ +/* general_remarks */ +/* */ +/* <Title> */ +/* General Remarks */ +/* */ +/* <Sections> */ +/* user_allocation */ +/* */ +/***************************************************************************/ + + /***************************************************************************/ /* */ /* <Chapter> */ @@ -24,6 +38,7 @@ /* */ /***************************************************************************/ + /***************************************************************************/ /* */ /* <Chapter> */ diff --git a/src/tools/docmaker/tohtml.py b/src/tools/docmaker/tohtml.py index 2a3cf239b..2b9c547d9 100644 --- a/src/tools/docmaker/tohtml.py +++ b/src/tools/docmaker/tohtml.py @@ -410,37 +410,39 @@ class HtmlFormatter(Formatter): print section.title print section_title_footer - # print section synopsys - print section_synopsis_header - print "<table align=center cellspacing=5 cellpadding=0 border=0>" - maxwidth = 0 for b in section.blocks.values(): - if len(b.name) > maxwidth: - maxwidth = len(b.name) + if len( b.name ) > maxwidth: + maxwidth = len( b.name ) width = 70 # XXX magic number - columns = width / maxwidth - if columns < 1: - columns = 1 + if maxwidth <> 0: + # print section synopsis + print section_synopsis_header + print "<table align=center cellspacing=5 cellpadding=0 border=0>" - count = len(section.block_names) - 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>' - if i < count: - name = section.block_names[i] - line = line + '<a href="#' + name + '">' + name + '</a>' + columns = width / maxwidth + if columns < 1: + columns = 1 - line = line + '</td>' - line = line + "</tr>" - print line + count = len( section.block_names ) + rows = ( count + columns - 1 ) / columns - print "</table><br><br>" - print section_synopsis_footer + for r in range( rows ): + line = "<tr>" + for c in range( columns ): + i = r + c * rows + line = line + '<td></td><td>' + if i < count: + name = section.block_names[i] + line = line + '<a href="#' + name + '">' + name + '</a>' + + line = line + '</td>' + line = line + "</tr>" + print line + + print "</table><br><br>" + print section_synopsis_footer print description_header print self.make_html_items( section.description )