Write documentation for general doxygen hackery and customizations.

.gitattributes

@@ -2124,6 +2124,7 @@ Developers_manual/doc_tex/Developers_manual/fig/reference_counting.gif -text svn
 Developers_manual/doc_tex/Developers_manual/fig/reference_counting.pdf -text svneol=unset#application/pdf
 Developers_manual/doc_tex/Developers_manual/fig/use_real.gif -text svneol=unset#image/gif
 Developers_manual/doc_tex/Developers_manual/fig/use_real.pdf -text svneol=unset#application/pdf
+Documentation/Customizations.txt -text
 Documentation/Doxyfile -text
 Documentation/DoxygenLayout.xml -text
 Documentation/DoxygenLayoutPackage.xml -text

Documentation/Customizations.txt

@@ -0,0 +1,70 @@
+# Doxygen for CGAL #
+
+This is the documentation of doxygen hacks that are applied to make
+the output of Doxygen more suitable to CGAL. It explains the general
+structure of the build system, the ordinary customizations and the
+hacks that create what you see.
+
+## Overall structure ##
+
+## Ordinary Customization ##
+
+## Hacks ##
+
+### Package Overview ###
+
+The package overview is build by having a special command that is
+filtered by the shell script pkglist_filter.sh.
+
+A command has to be of the form \package_listing{PKG_NAME}, where
+PKG_NAME cannot contain a closing }. 
+
+The command is replaced by the text between the two delimiters
+PkgDescBegin and PkgDescEnd in the file ../PKG_NAME/doc/PKG_NAME/PackageDescription.txt
+
+If PKG_NAME is of the form A/B the selected file is
+../A/doc/B/PackageDescription.txt. This is to support packages like
+Sweep_line_2 and TDS_2 which don't reside in their own SVN packages.
+
+### Footnotes ###
+
+A JQuery footnotes plug-in jquery.footnotes is used to handle
+footnotes. The special doxygen command \footnote expands to the
+appropriate html marker. Some JavaScript in `header.html` is used to
+append the `<ol div="autoFootnotes0">` to the current doc-content div. It is not added to the footer because this would break when tree views are enabled.
+
+### autotoc ###
+
+TOCs in HTML are generated by the some JavaScript. This is necessary
+to work around the fact that doxygen does not supported sections that
+have no label in a TOC. This command simply becomes a normal toc in
+LaTex.
+
+### resize ###
+
+Resizing breaks when stuff is added to headers and footers. We
+overwrite the resize functions used by Doxygen with our own
+JavaScript. Also see `header.html`. See the associated Doxygen bug
+report: https://bugzilla.gnome.org/show_bug.cgi?id=683734
+
+### Top Nav-Bar ###
+
+A simple customization in `header.html` with impact on resizing
+functionality.
+
+### Reference Manual link in the tree view  ###
+
+This hack fiddles with the internal structures and functions of the
+treeview to remove the unnecessary intermediate top-level module part.
+
+It assigns the first element of the module array (found in module.js)
+to the Reference Manual entry. This makes the tree view link go to
+that group directly instead of the intermediate link. It also removes
+one level of nesting.
+
+Unfortunately this changes the overall tree structure. To adjust for
+that we hijack the gotoNode function of navtree.js and *augment* it
+with an additional check for the specific tree level we borked and
+redirect it.
+
+All of it is in `header.html`.