Author: greg.ercolano
Date: 2012-03-05 12:59:51 -0800 (Mon, 05 Mar 2012)
New Revision: 663
Log:
Updated CMP index.
Modified:
trunk/cmp.php
Modified: trunk/cmp.php
===================================================================
--- trunk/cmp.php 2012-03-05 07:45:23 UTC (rev 662)
+++ trunk/cmp.php 2012-03-05 20:59:51 UTC (rev 663)
@@ -28,19 +28,106 @@
<li><a href="#SPECIFIC_GOALS">Specific Goals</a></li>
<li><a href="#SOFTWARE_DEVELOPMENT_PRACTICES">Software Development
Practices</a>
- <ul>
- <li><a href="#RELEASE">FLTK Release Process</a></li>
- </ul></li>
+ <ul><small>
+ <li><a href="#DOCUMENTATION">Documentation</a></li>
+ <li><a href="#BUILD_SYSTEM">Build System</a></li>
+ <li><a href="#PACKAGING">Packaging</a></li>
+ <li><a href="#RELEASE">FLTK Release Process</a>
+ <ul>
+ <li><a href="#FRP_CREATING_ARCHIVES">Creating the Release
Archives</a></li>
+ <li><a href="#FRP_TESTING_ARCHIVES_LINUX">Testing the Archives on
Linux</a></li>
+ <li><a href="#FRP_TESTING_ARCHIVES_MAC">Testing the Archives on Mac
OS X</a></li>
+ <li><a href="#FRP_TESTING_ARCHIVES_WIN">Testing the Archives on
Windows</a></li>
+ <li><a href="#FRP_UPLOADING_TO_WEB">Uploading the Files to the Web
Server</a></li>
+ </ul>
+ </li>
+ </small></ul></li>
<li><a href="#TROUBLE_REPORT_PROCESSING">Trouble Report Processing</a></li>
- <li><a href="#SOFTWARE_RELEASES">Software Releases</a></li>
+ <li><a href="#SOFTWARE_RELEASES">Software Releases</a>
+ <ul><small>
+ <li><a href="#SR_VERSION_NUMBERING">Version Numbering</a></li>
+ <li><a href="#SR_GENERATION">Generation</a></li>
+ <li><a href="#SR_TESTING">Testing</a></li>
+ <li><a href="#SR_RELEASES">Releases</a>
+ <ul>
+ <li><a href="#SR_BETA_RELEASES">Beta Releases</a>
+ <li><a href="#SR_RELEASE_CANDIDATES">Release Candidates</a>
+ <li><a href="#SR_PRODUCTION_RELEASES">Production Releases</a>
+ <li><a href="#SR_MAJOR_RELEASES">Major Releases</a>
+ <li><a href="#SR_MINOR_RELEASES">Minor Releases</a>
+ <li><a href="#SR_PATCH_RELEASES">Patch Releases</a>
+ </small></ul>
+ </li>
+ </ul></li>
- <li><a href="#FILE_MANAGEMENT">File Management</a></li>
+ <li><a href="#FILE_MANAGEMENT">File Management</a>
+ <ul><small>
+ <li><a href="#FM_CONFIGURATION_MANAGEMENT">Configuration
Management</a></li>
+ <li><a href="#FM_DIRECTORY_STRUCTURE">Directory Structure</a></li>
+ <li><a href="#FM_SOURCE_FILES">Source Files</a></li>
+ <li><a href="#FM_HEADER_FILES">Header Files</a></li>
+ <li><a href="#FM_MAKEFILES">Makefiles</a></li>
+ </small></ul>
+ </li>
- <li><a href="#CODING_STANDARDS">Coding Standards</a></li>
+ <li><a href="#CODING_STANDARDS">Coding Standards</a>
+ <ul><small>
+ <li><a href="#CS_GENERAL_CODING_STYLE">General Coding Style</a></li>
+ <li><a href="#CS_SOURCE_FILE_DOCUMENTATION">Source File
Documentation</a></li>
+ <li><a href="#CS_DOCUMENATION_COMMENTS">Documenation
(Comments)</a></li>
+ <li><a href="#CS_GENERAL_DEV_RECOMMENDATIONS">General Developer
Recommendations</a></li>
+ <li><a href="#CS_METHODOLOGY_ALGORITHMS">Methodology, Algorithms,
Etc.</a></li>
+ <li><a href="#CS_CPP_PORTABILITY">C++ Portability</a>
+ <ul>
+ <li><a href="#CS_FLTK_1_1_X_RESTRICTIONS">FLTK 1.1.x
Restrictions</a></li>
+ <li><a href="#CS_FLTK_2_0_X_RESTRICTIONS">FLTK 2.0.x
Restrictions</a></li>
+ </ul>
+ </li>
+ <li><a href="#CS_SOURCE_FILE_NAMING">Source File Naming</a></li>
+ <li><a href="#CS_FUNC_METHOD_VAR_NAMING">Function/Method/Variable
Naming</a></li>
+ <li><a href="#CS_STRUCT_CLASS_NAMING">Structure/Class Naming</a></li>
+ <li><a href="#CS_CONST_ENUM_NAMING">Constant/Enumeration
Naming</a></li>
+ <li><a href="#CS_PREPROCESSOR_VARS">Preprocessor Variables</a>
+ <ul>
+ <li><a href="#WIN32">WIN32</a></li>
+ <li><a href="#__CYGWIN__">__CYGWIN__</a></li>
+ <li><a href="#__APPLE__">__APPLE__</a></li>
+ <li><a href="#__APPLE_QUARTZ__">__APPLE_QUARTZ__</a></li>
+ <li><a href="#USE_X11">USE_X11</a></li>
+ <li><a href="#USE_XFT">USE_XFT</a></li>
+ <li><a href="#FL_LIBRARY">FL_LIBRARY</a></li>
+ <li><a href="#FL_INTERNALS">FL_INTERNALS</a></li>
+ <li><a href="#FL_DOXYGEN">FL_DOXYGEN</a></li>
+ <li><a href="#FLTK_ABI_VERSION">FLTK_ABI_VERSION</a></li>
+ </ul>
+ </li>
+ <li><a href="#CS_MISCELLANEOUS">Miscellaneous</a></li>
+ </small></ul>
+ </li>
- <li><a href="#MAKEFILES">Makefile Standards</a></li>
+ <li><a href="#MAKEFILES">Makefile Standards</a>
+ <ul><small>
+ <li><a href="#MK_GENERAL_ORGANIZATION">General Organization</a></li>
+ <li><a href="#MK_MAKEFILE_DOCUMENTATION">Makefile
Documentation</a></li>
+ <li><a href="#MK_PORTABLE_MAKEFILE_CONSTRUCTION">Portable Makefile
Construction</a></li>
+ <li><a href="#MK_STANDARD_VARS">Standard Variables</a></li>
+ <li><a href="#MK_STANDARD_TARGETS">Standard Targets</a></li>
+ <li><a href="#MK_OBJECT_FILES">Object Files</a></li>
+ <li><a href="#MK_PROGRAMS">Programs</a></li>
+ <li><a href="#MK_STATIC_LIBS">Static Libraries</a></li>
+ <li><a href="#MK_SHARED_LIBS">Shared Libraries</a></li>
+ <li><a href="#MK_DEPENDENCIES">Dependencies</a></li>
+ <li><a href="#MK_INSTALL_UNINSTALL_SUPPORT">Install/Uninstall
Support</a></li>
+ </ul></small>
+ </li>
+ <li><a href="#DEVELOPER_REFERENCE">Developer Reference</a>
+ <ul><small>
+ <li><a href="#DR_COMMENT_STYLE">Comment Style</a></li>
+ <li><a href="#DR_GENERAL_DEV_RECO">General Developer
Recommendations</a></li>
+ </small></ul>
+ </li>
</ul>
@@ -127,10 +214,9 @@
to prevent full compatibility.</p>
-<h1><a name="SOFTWARE_DEVELOPMENT_PRACTICES">Software
-Development Practices</a></h1>
+<h1><a name="SOFTWARE_DEVELOPMENT_PRACTICES">Software Development
Practices</a></h1>
-<h2>Documentation</h2>
+<h2><a name="DOCUMENTATION">Documentation</a></h2>
<p>All widgets are documented using the <a
href='http://www.stack.nl/~dimitri/doxygen/'>Doxygen</a>
@@ -150,7 +236,7 @@
<p>The final manuals are formatted using the <a
href='http://www.easysw.com/htmldoc/'>HTMLDOC</a> software.</p>
-<h2>Build System</h2>
+<h2><a name="BUILD_SYSTEM">Build System</a></h2>
<p>The FLTK build system uses <a
href='http://www.gnu.org/software/autoconf/'>GNU autoconf</a> to
@@ -170,7 +256,7 @@
which depend on GNU-specific extensions, and GNU libtool is not
portable or reliable enough for FLTK.</p>
-<h2>Packaging</h2>
+<h2><a name="PACKAGING">Packaging</a></h2>
<p>Source packages are created using the <tt>makesrcdist</tt>
script in the Subversion repository. The script accepts one or
@@ -249,7 +335,7 @@
</ul>
-<h3>Creating the Release Archives</h3>
+<h3><a name="FRP_CREATING_ARCHIVES">Creating the Release Archives</a></h3>
<p>Each software release provides three archives:</p>
@@ -289,7 +375,7 @@
</ol>
-<h3>Testing the Archives on Linux</h3>
+<h3><a name="FRP_TESTING_ARCHIVES_LINUX">Testing the Archives on Linux</a></h3>
<p>Run the following commands to test the release:</p>
@@ -303,7 +389,7 @@
./demo
</pre>
-<h3>Testing the Archives on Mac OS X</h3>
+<h3><a name="FRP_TESTING_ARCHIVES_MAC">Testing the Archives on Mac OS
X</a></h3>
<p>Run the following commands to test the release:</p>
@@ -316,7 +402,7 @@
./demo
</pre>
-<h3>Testing the Archives on Microsoft Windows</h3>
+<h3><a name="FRP_TESTING_ARCHIVES_WIN">Testing the Archives on Microsoft
Windows</a></h3>
<p>Extract the files from the .tar.gz archive and then open the
<var>ide/VisualC2010/fltk.sln</var> file in Visual C. Build the
@@ -325,7 +411,7 @@
target to test that each of the demo programs is functioning
properly.</p>
-<h3>Uploading the Files to the Web Server</h3>
+<h3><a name="FRP_UPLOADING_TO_WEB">Uploading the Files to the Web
Server</a></h3>
<p>Go to the following URL to upload the release archives:</p>
@@ -430,7 +516,7 @@
<h1><a name="SOFTWARE_RELEASES">Software Releases</a></h1>
-<h2>Version Numbering</h2>
+<h2><a name="SR_VERSION_NUMBERING">Version Numbering</a></h2>
<p>FLTK uses a three-part version number separated by periods to
represent the major, minor, and patch release numbers:
@@ -511,21 +597,21 @@
3.0.1 First patch release of 3.0
</pre>
-<h2>Generation</h2>
+<h2><a name="SR_GENERATION">Generation</a></h2>
<p>Software releases shall be generated for each successfully
completed software trouble report. All object and executable
files shall be deleted prior to performing a full build to
ensure that source files are recompiled.</p>
-<h2>Testing</h2>
+<h2><a name="SR_TESTING">Testing</a></h2>
<p>Software testing shall be conducted according to the FLTK
Software Test Plan (<i>Editor's note: to be written, along with
an automated/semi-automated test framework</i>). Failed tests
cause STRs to be generated to correct the problems found.</p>
-<h2>Releases</h2>
+<h2><a name="SR_RELEASES">Releases</a></h2>
<p>When testing has been completed successfully a new
distribution image is created by copying the current
@@ -588,7 +674,7 @@
version releases. At least one release candidate is generated
prior to each production release.</p>
-<h3>Beta Releases</h3>
+<h3><a name="SR_BETA_RELEASES">Beta Releases</a></h3>
<p>Beta releases are generated when substantial changes have
been made that may affect the reliability of the software. Beta
@@ -600,7 +686,7 @@
Functional changes may be included in subsequent beta releases
until the first release candidate.</p>
-<h3>Release Candidates</h3>
+<h3><a name="SR_RELEASE_CANDIDATES">Release Candidates</a></h3>
<p>Release candidates are generated at least two weeks prior to
a production release. Release candidates are targeted for
@@ -615,21 +701,21 @@
are generated at weekly intervals until all level 4/5 trouble
reports are resolved.
-<h3><a name="PRODUCTION_RELEASES">Production Releases</a></h3>
+<h3><a name="SR_PRODUCTION_RELEASES">Production Releases</a></h3>
<p>Production releases are generated after a successful release
candidate and represent a stable release of the software
suitable for all users.
-<ul class='new'>
+<div class='new'>
- <h3><a name="MAJOR_RELEASES">Major Releases (Version #.x.x)</h3>
+ <h3><a name="SR_MAJOR_RELEASES">Major Releases (Version #.x.x)</a></h3>
<p>
Major Releases occur when there's a major rewrite of the code, or a
significant
redefinition of the API.
</p>
- <h3><a name="MINOR_RELEASES">Minor Releases (Version x.#.x)</a></h3>
+ <h3><a name="SR_MINOR_RELEASES">Minor Releases (Version x.#.x)</a></h3>
Minor Releases add ABI breaking features/fixes. Rarely breaks the API in
any
significant way.
<p>
@@ -647,7 +733,7 @@
so that only the <tt>'new ABI breaking code'</tt> is left in its
place for default builds.
<p>
- <h3><a name="PATCH_RELEASES">Patch Releases (Version x.x.#)</a></h3>
+ <h3><a name="SR_PATCH_RELEASES">Patch Releases (Version x.x.#)</a></h3>
<p>Patch releases are generated to fix priority 2-5 STRs. Patch
releases may not add additional functionality from priority 1 STRs.
@@ -663,14 +749,14 @@
ABI version number in FL/Enumerations.H, and re-building
FLTK and their apps.
</p>
-</ul>
+</div>
<h1><a name="FILE_MANAGEMENT">File Management</a></h1>
<p>This section describes how project files and directories are
named and managed.
-<h2>Configuration Management</h2>
+<h2><a name="FM_CONFIGURATION_MANAGEMENT">Configuration Management</a></h2>
<p>Source files shall be placed under the control of the
Subversion ("SVN") software. Source
@@ -694,7 +780,7 @@
<p>Documentation on the Subversion software is <a
href="svn.php">available on-line</a>.</p>
-<h2>Directory Structure</h2>
+<h2><a name="FM_DIRECTORY_STRUCTURE">Directory Structure</a></h2>
<p>Each source file shall be placed a sub-directory
corresponding to the software sub-system it belongs to
@@ -702,7 +788,7 @@
compatible with case-insensitive filesystems, no two directory
names shall differ only by the case of the letters in the name.
-<h2>Source Files</h2>
+<h2><a name="FM_SOURCE_FILES">Source Files</a></h2>
<p>Source files shall be documented and formatted as described
in the <a href="#CODING_STANDARDS">Coding Standards</a> section.
@@ -736,7 +822,7 @@
makefiles, etc.) shall have extensions as required by the
IDE/compiler tool.
-<h2>Header Files</h2>
+<h2><a name="FM_HEADER_FILES">Header Files</a></h2>
<p>In addition to the source file requirements, all header files
must utilitize so-called "guard" definitions to prevent multiple
@@ -758,7 +844,7 @@
trailing underscores are added to limit global namespace
pollution.</p>
-<h2>Makefiles</h2>
+<h2><a name="FM_MAKEFILES">Makefiles</a></h2>
<p>Makefiles shall be documented and formatted as described
in the <a href="#MAKEFILES">Makefile Standards</a> section.
@@ -775,7 +861,7 @@
be obvious from looking at the code, but here it all is in one
spot.
-<h2>General Coding Style</h2>
+<h2><a name="CS_GENERAL_CODING_STYLE">General Coding Style</a></h2>
<p>The FLTK code basically follows the K&R coding style. While many
of the developers are not entirely satisfied with this coding style, no
@@ -831,7 +917,7 @@
different than the Microsoft standard of 4, but you can change
that to match UNIX. A space also follows all reserved words.
-<h2>Source File Documentation</h2>
+<h2><a name="CS_SOURCE_FILE_DOCUMENTATION">Source File Documentation</a></h2>
<p>Each source file must start with the standard FLTK header
containing the Subversion "$Id$" keyword, description of the
@@ -886,7 +972,7 @@
<p>The purpose of the trailer is to indicate the end of the
source file so that truncations are immediately obvious.
-<h2>Documentation (Comments) <a
href="#DEVELOPER_REFERENCE_COMMENT_STYLE">*</a></h2>
+<h2><a name="CS_DOCUMENATION_COMMENTS">Documentation (Comments)</a> <a
href="#DR_COMMENT_STYLE">*</a></h2>
<p>FLTK 2.0 <a class=new>and FLTK 1.3 and up</a> uses Doxygen with the JavaDoc
comment style to
document all classes, structures, enumerations, methods, and
@@ -947,7 +1033,7 @@
comments in those.
</a>
-<h2>General Developer Recommendations <a
href="#DEVELOPER_REFERENCE_GENERAL">*</a></h2>
+<h2><a name="CS_GENERAL_DEV_RECOMMENDATIONS">General Developer
Recommendations</a> <a href="#DR_GENERAL_DEV_RECO">*</a></h2>
<ul class=new>
Most important rule: <b>Put Doxygen comments where the code's
implementation is.</b>
This means don't put the docs with the prototypes in the .H file, unless
that's where
@@ -957,14 +1043,15 @@
<li> Most other docs go in the source files</li>
<li> For doxygen syntax in C++ files, use:
<pre class='command'>
- /** for standard dox comments */
- ///< for single line post-declaration short dox comments
+ /** for standard doxygen comments */
+ ///< for short single line post-declaration doxygen comments
</pre>
</li>
<li> For doxygen syntax in C files, use:
<pre class='command'>
- /** for standard dox comments */
- /**< for single line post-declaration short dox comments */</pre>
+ /** for standard doxygen comments */
+ /**< for short single line post-declaration doxygen comments */
+ </pre>
</li>
<li> Use <tt>\p</tt> for parameters citation in the description</li>
<li> Use <tt>\param[in] xxx</tt> and <tt>\param[out] xxx</tt> for
input/output parameters.</li>
@@ -977,15 +1064,16 @@
/*@ beware */
//! beware
//@ beware</pre>
- There may be others. For this reason, <i>follow all non-doxygen comments
leaders with a space</i>
- to avoid doxygen parsing:
- <pre class='command'>
+ There may be others. For this reason, <i>follow all non-doxygen comment
leaders with a space</i>
+ to avoid accidental doxygen parsing:
+ <p><table><tr><td><pre class='command'>
/* safe from doxygen */
// safe from doxygen
^
/|\
|
<i>Space immediately after comment characters</i></pre></li>
+ </td></tr></table><p>
<li> Note: Several characters are 'special' within doxygen commments, and
must be escaped
with a backslash to appear in the docs correctly. Some of these are:
<pre class='command'>
@@ -1195,7 +1283,7 @@
int my_variable2_; /**< C file's brief doxygen description of the
member/variable */
</pre>
-<h2>Methodology, Algorithms, Etc.</h2>
+<h2><a name="CS_METHODOLOGY_ALGORITHMS">Methodology, Algorithms, Etc.</a></h2>
<p>The goal of FLTK is to provide a robust GUI toolkit that is
small, fast, and reliable. <b>All</b> public API functions and
@@ -1235,14 +1323,14 @@
</ol>
-<h2>C++ Portability</h2>
+<h2><a name="CS_CPP_PORTABILITY">C++ Portability</a></h2>
<p>Since FLTK is targeted at platforms which often lack complete
ISO C++ support or have limited memory, all C++ code in FLTK
must use a subset of ISO C++. FLTK These restrictions shall be
reviewed prior to each major release of FLTK.</p>
-<h3>FLTK 1.1.x Restrictions</h3>
+<h3><a name="CS_FLTK_1_1_X_RESTRICTIONS">FLTK 1.1.x Restrictions</a></h3>
<p>The following C++ features may be not used in FLTK 1.1.x
code:</p>
@@ -1262,7 +1350,7 @@
</ul>
-<h3>FLTK 2.0.x Restrictions</h3>
+<h3><a name="CS_FLTK_2_0_X_RESTRICTIONS">FLTK 2.0.x Restrictions</a></h3>
<p>The following C++ features may be not used in FLTK 2.0.x
code:</p>
@@ -1283,14 +1371,14 @@
types. The <tt>dynamic_cast</tt> keyword must not be used since
run-time typing features are not be available at all times.</p>
-<h2>Source File Naming</h2>
+<h2><a name="CS_SOURCE_FILE_NAMING">Source File Naming</a></h2>
<p>The current practice is to use an extension of ".c" for C
source files, ".h" for C header files, ".cxx" for C++ source
files, and ".H" for C++ header files in the "FL" directory (".h"
otherwise.)
-<h2>Function/Method/Variable Naming</h2>
+<h2><a name="CS_FUNC_METHOD_VAR_NAMING">Function/Method/Variable
Naming</a></h2>
<p>All public (exported) functions and variables must be placed
in the "fltk" namespace. Except for constructor and destructor
@@ -1299,7 +1387,7 @@
Private member variables of classes end with an extra
underscore, e.g. "text_size_".
-<h2>Structure/Class Naming</h2>
+<h2><a name="CS_STRUCT_CLASS_NAMING">Structure/Class Naming</a></h2>
<p>All public (exported) structures and classes must be placed
in the "fltk" namespace and consist of capitalized words without
@@ -1310,7 +1398,7 @@
without the underscore as applicable, e.g. "text_size_" and
"text_size()".
-<h2>Constant/Enumeration Naming</h2>
+<h2><a name="CS_CONST_ENUM_NAMING">Constant/Enumeration Naming</a></h2>
<p>Public enumerations and constant variables must be placed
inside the "fltk" namespace and consist of UPPERCASE WORDS
@@ -1321,7 +1409,7 @@
definitions.
-<h2>Preprocessor Variables</h2>
+<h2><a name="CS_PREPROCESSOR_VARS">Preprocessor Variables</a></h2>
File config.h and the C++ compilers define a few preprocessor variables
that help organizing platform-specific code
@@ -1331,20 +1419,20 @@
must not, directly or indirectly, include config.h.
<ul>
-<li>WIN32 identifies the MS-Windows platform (both
+<li><a name="WIN32"></a>WIN32 identifies the MS-Windows platform (both
for the 32- and 64-bit versions). Don't use _WIN32.
-<li>__CYGWIN__ is defined when FLTK runs on the MS-Windows OS but uses
+<li><a name="__CYGWIN__"></a>__CYGWIN__ is defined when FLTK runs on the
MS-Windows OS but uses
Cygwin's POSIX emulation features (cygwin1.dll). [more to come...]
-<li>__APPLE__ identifies the Mac OS X platform.
+<li><a name="__APPLE__"></a>__APPLE__ identifies the Mac OS X platform.
-<li>__APPLE_QUARTZ__ is defined by config.h for the Mac OS X
+<li><a name="__APPLE_QUARTZ__"></a>__APPLE_QUARTZ__ is defined by config.h for
the Mac OS X
platform. At present, use of __APPLE_QUARTZ__ is equivalent to
using __APPLE__. This may change in the future if other graphics
systems than Quartz are supported on the Mac OS platform.
-<li>USE_X11 is defined by config.h when Xlib is the
+<li><a name="USE_X11"></a>USE_X11 is defined by config.h when Xlib is the
graphics system used. Thus, USE_X11 is defined on all Unix and Linux
platforms, and on Windows, if configure used <tt>--enable-cygwin</tt>
<b>and</b> <tt>--enable-x11</tt>. Xlib-specific code is also often
@@ -1357,25 +1445,25 @@
#endif
</tt></pre>
-<li>USE_XFT is defined by config.h when USE_X11 is defined.
+<li><a name="USE_XFT"></a>USE_XFT is defined by config.h when USE_X11 is
defined.
It is set to 1 when the Xft library of scalable, anti-aliased
fonts is used, and to 0 otherwise.
-<li>FL_LIBRARY is defined by all FLTK library build tools
+<li><a name="FL_LIBRARY"></a>FL_LIBRARY is defined by all FLTK library build
tools
when the FLTK library itself is compiled.
Application program developers should not define it when compiling
their programs.
-<li>FL_INTERNALS. Application program developers can define
+<li><a name="FL_INTERNALS"></a>FL_INTERNALS. Application program developers
can define
this variable to get access to some internal classes (e.g., the
Fl_X class) if they need it. APIs to these internal classes are
highly subject to changes, though.
-<li>FL_DOXYGEN is defined when the Doxygen program that builds
+<li><a name="FL_DOXYGEN"></a>FL_DOXYGEN is defined when the Doxygen program
that builds
the FLTK documentation processes the source code. This variable
has two major uses.
<ol>
-<li> <tt>#ifndef FL_DOXYGEN / #endif</tt> allows to hide code from Doxygen.
+<li><a name="XXX"></a> <tt>#ifndef FL_DOXYGEN / #endif</tt> allows to hide
code from Doxygen.
<li>The Doxygen program does not define the platform-specific
variables __APPLE__ or WIN32 (even if it's run on Mac OS or MSWindows).
Thus, platform-specific (say, Mac-specific) code must be bracketted as
@@ -1386,7 +1474,7 @@
</tt></pre>
</ol>
<li class='new'><a name="FLTK_ABI_VERSION">FLTK_ABI_VERSION</a> is used to
allow developers
- to implement ABI breaking code in <a href="#PATCH_RELEASES">Patch
Releases</a>.
+ to implement ABI breaking code in <a href="#SR_PATCH_RELEASES">Patch
Releases</a>.
Normally unset, can be set by users or devs in FL/Enumerations.H to enable
ABI breaking features for testing or use by end users in static builds of
FLTK.
<p>
@@ -1401,17 +1489,18 @@
</pre>
ABI breaking features are by default '#ifdef'ed out with this variable
during patch releases, and are merged in by developers during the next
- <a href="#MINOR_RELEASES">Minor Release</a>.
+ <a href="#SR_MINOR_RELEASES">Minor Release</a>.
<p>
- Example: if the current patch release is 1.3.1, and the developer adds an
- ABI-breaking fix to what will be the next 1.3.2 release, then the addition
- would be implemented as:
- <pre class='command'>
+ Example: If the current patch release is 1.3.1, and the developer adds an
+ ABI-breaking fix to what will be the next 1.3.2 release, then the new
+ code would be implemented as:
+ <p><ul><table><tr><td><pre class='command'>
#if FLTK_ABI_VERSION >= 10302 // FLTK 1.3.2, the <u>next</u> patch
release #
... new ABI breaking code ...
#else
... old non-ABI breaking (default builds) ...
#endif</pre>
+ </td></tr></table></ul>
This variable solves several issues:
<ul type=disc>
<li> Allows ABI breaking code to be implemented at any time by
developers.</li>
@@ -1422,7 +1511,7 @@
</li>
</ul>
-<h2>Miscellaneous</h2>
+<h2><a name="CS_MISCELLANEOUS">Miscellaneous</a></h2>
When using <tt>switch</tt> - <tt>case</tt> statements, and your
<tt>case</tt> statement does not end in <tt>break</tt> in order to
@@ -1437,7 +1526,7 @@
to allow FLTK to be built on as many systems and environments as
possible.</p>
-<h2>General Organization</h2>
+<h2><a name="MK_GENERAL_ORGANIZATION">General Organization</a></h2>
<p>The FLTK source code is organized functionally into a
top-level makefile, include file, and subdirectories each with
@@ -1482,7 +1571,7 @@
software and are used to generate a static version of the
corresponding file.</p>
-<h2>Makefile Documentation</h2>
+<h2><a name="MK_MAKEFILE_DOCUMENTATION">Makefile Documentation</a></h2>
<p>Each make file must start with the standard FLTK header
containing the Subversion "$Id$" keyword, description of the
@@ -1528,7 +1617,7 @@
<p>The purpose of the trailer is to indicate the end of the
makefile so that truncations are immediately obvious.
-<h2>Portable Makefile Construction</h2>
+<h2><a name="MK_PORTABLE_MAKEFILE_CONSTRUCTION">Portable Makefile
Construction</a></h2>
<p>FLTK uses a common subset of make program syntax to ensure
that the software can be compiled "out of the box" on as many
@@ -1610,7 +1699,7 @@
</ul>
-<h2>Standard Variables</h2>
+<h2><a name="MK_STANDARD_VARS">Standard Variables</a></h2>
<p>The following variables are defined in the "makeinclude" file
generated by the <tt>autoconf</tt> software:
@@ -1713,7 +1802,7 @@
</ul>
-<h2>Standard Targets</h2>
+<h2><a name="MK_STANDARD_TARGETS">Standard Targets</a></h2>
<p>The following standard targets must be defined in each makefile:
@@ -1746,12 +1835,12 @@
</ul>
-<h2>Object Files</h2>
+<h2><a name="MK_OBJECT_FILES">Object Files</a></h2>
<p>Object files (the result of compiling a C or C++ source file)
have the extension ".o".
-<h2>Programs</h2>
+<h2><a name="MK_PROGRAMS">Programs</a></h2>
<p>Program files (the result of linking object files and
libraries together to form an executable file) have the
@@ -1764,7 +1853,7 @@
<img src='images/tab.gif' alt='Tab' width='32' height='12'
align='middle'/> $(CXX) $(LDFLAGS) -o $@ $(OBJECTS) $(LIBS)
</pre>
-<h2>Static Libraries</h2>
+<h2><a name="MK_STATIC_LIBS">Static Libraries</a></h2>
<p>Static libraries have a prefix of "lib" and the extension
".a". A typical static library target looks like:
@@ -1777,7 +1866,7 @@
<img src='images/tab.gif' alt='Tab' width='32' height='12'
align='middle'/> $(RANLIB) $@
</pre>
-<h2>Shared Libraries</h2>
+<h2><a name="MK_SHARED_LIBS">Shared Libraries</a></h2>
<p>Shared libraries have a prefix of "lib" and the extension
".dylib", ".sl", ".so", or "_s.a" depending on the operating
@@ -1821,7 +1910,8 @@
</pre>
-<h2><a name='TARGET_DEPEND'>Dependencies</a></h2>
+<a name='TARGET_DEPEND'></a>
+<h2><a name='MK_DEPENDENCIES'>Dependencies</a></h2>
<p>Static dependencies are expressed in each makefile following the
target, for example:</p>
@@ -1845,7 +1935,8 @@
system and express any non-Linux dependencies statically in the
makefile.
-<h2><a name='TARGET_INSTALL'>Install/Uninstall Support</a></h2>
+<a name='TARGET_INSTALL'></a>
+<h2><a name='MK_INSTALL_UNINSTALL_SUPPORT'>Install/Uninstall Support</a></h2>
<p>All makefiles must contain install and uninstall rules which
install or remove the corresponding software. These rules must
@@ -1866,11 +1957,11 @@
<hr>
-<h2><a name="DEVELOPER_REFERENCE">Developer References</a></h2>
+<h1><a name="DEVELOPER_REFERENCE">Developer Reference</a></h1>
<ul class='new'>
- <h3><a name='DEVELOPER_REFERENCE_COMMENT_STYLE'>Comment Style</a></h3>
+ <h2><a name='DR_COMMENT_STYLE'>Comment Style</a></h2>
Developers for 1.3 settled on the /** .. */ format for these reasons:
<pre>
erco 3/13/09:
@@ -1890,7 +1981,7 @@
We seem to be going with /** style comments, no (*)s running down left
margin (as per Duncan's sugg).
</pre>
- <h3><a name='DEVELOPER_REFERENCE_GENERAL'>General Developer
Recommendations</a></h3>
+ <h2><a name='DR_GENERAL_DEV_RECO'>General Developer Recommendations</a></h2>
Many of the notes in this section are from Fabien's TODO.doc, and seem
consistent with the
actual fltk docs during the 1.1.x-to-1.3.x doxygenification transition.
_______________________________________________
fltk-commit mailing list
[email protected]
http://lists.easysw.com/mailman/listinfo/fltk-commit
