diff -r 000000000000 -r 42188c7ea2d9 Orb/Doxygen/doc/customize.doc --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Orb/Doxygen/doc/customize.doc Thu Jan 21 17:29:01 2010 +0000 @@ -0,0 +1,263 @@ +/****************************************************************************** + * + * + * + * Copyright (C) 1997-2008 by Dimitri van Heesch. + * + * Permission to use, copy, modify, and distribute this software and its + * documentation under the terms of the GNU General Public License is hereby + * granted. No representations are made about the suitability of this software + * for any purpose. It is provided "as is" without express or implied warranty. + * See the GNU General Public License for more details. + * + * Documents produced by Doxygen are derivative works derived from the + * input used in their production; they are not affected by this license. + * + */ +/*! \page customize Customizing the output + +Doxygen provides various levels of customization. +The \ref minor_tweaks "first section" discusses what to +do if you want to do minor tweaker to the look and feel of the output. +The \ref layout "next" section show how to reorder and hide certain +information on a page. +The \ref xmlgenerator "last" section show how to generate whatever output +you want based on the XML output produced by doxygen. + +\section minor_tweaks Minor Tweaks + +To simply tweak things like fonts or colors, margins, or other look \& feel +espects of the HTML output you can create a different +cascading style sheet. +You can also let doxygen use a custom header and footer for each HTML +page it generates, for instance to include a logo or to make the +doxygen output blend in with the rest of the web site. + +To do this first run doxygen as follows: +\verbatim +doxygen -w html header.html footer.html customdoxygen.css +\endverbatim + +This will create 3 files: +- header.html is a HTML fragment which doxygen normally uses to start + a HTML page. Note that the fragment ends with a body tag and that is + contains a couple of commands of the form \$word. These will be replaced + by doxygen on the fly. +- footer.html is a HTML fragment which doxygen normally uses to end + a HTML page. Also here special commands can be used. This file contain the + link to www.doxygen.org and the body and html end tags. +- customdoxygen.css is the default cascading style sheet + used by doxygen. + +You should edit these files and then reference them from the config file. +\verbatim +HTML_HEADER = header.html +HTML_FOOTER = footer.html +HTML_STYLESHEET = customdoxygen.css +\endverbatim + +See the documentation of the \ref cfg_html_header "HTML_HEADER" tag +for more information about the possible meta commands. + +\note You should not put the style sheet in the HTML output directory. Treat +it is a source file. Doxygen will copy it for you. + +\note If you use images or other external content in a custom header you +need to make sure these end up in the HTML output directory yourself, +for instance by writing a script that runs doxygen can then copies the +images to the output. + + +\section layout Changing the layout of pages + +In some cases you may want to change the way the output is structured. +A different style sheet or custom headers and footers do not help in such +case. + +The solution doxygen provides is a layout file, which you can +modify and doxygen will use to control what information is presented, +in which order, and to some extent also how information is presented. +The layout file is an XML file. + +The default layout can be generated +by doxygen using the following command: +\verbatim +doxygen -l +\endverbatim +optionally the name of the layout file can be specified, if omitted +\c DoxygenLayout.xml will be used. + +The next step is to mention the layout file in the config file +\verbatim +LAYOUT_FILE = DoxygenLayout.xml +\endverbatim +The change the layout all you need to do is edit the layout file. + +The toplevel structure of the file looks as follows: +\verbatim + + + ... + + + ... + + + ... + + + ... + + + ... + + + ... + + +\endverbatim + +The root tag of the XML is \c doxygenlayout, it has an attribute named +\c version, which will be used in the future to cope with changes that are +not backward compatible. + +The first section, enclosed by \c navindex tags represents the layout of +the navigation tabs displayed at the top of each HTML page. +Each tab is represented by a \c tab tag in the XML file. + +You can hide tabs by setting the \c visible attribute to \c no. +You can also override the default title of a tab by specifying it as +the value of the \c title attribute. If the title field is the empty string +(the default) then doxygen will fill in an appropriate title. +You can reorder the tabs by moving the tab tags in the XML file +within the \c navindex section and even change the tree structure. +Do not change the value of the \c type attribute however. +Only a fixed set of types are supported, each representing a link to a +specific index. + +The sections after \c navindex represent the layout of the different +pages generated by doxygen: +- The \c class section represents the layout of all pages generated for + documented classes, structs, unions, and interfaces. +- The \c namespace section represents the layout of all pages generated for + documented namespaces (and also Java packages). +- The \c file section represents the layout of all pages generated for + documented files. +- The \c group section represents the layout of all pages generated for + documented groups (or modules). +- The \c directory section represents the layout of all pages generated for + documented directories. + +Each XML tag within one of the above page sections represents a certain +piece of information. Some pieces can appear in each type of page, +others are specific for a certain type of page. +Doxygen will list the pieces in the order in which they appear +in the XML file. + +Some tags have a \c visible attribute which can be +used to hide the fragment from the generated output, by setting the attribute's +value to "no". You can also use the value of a configuration option to +determine the visibility, by using +its name prefixed with a dollar sign, e.g. +\verbatim + ... + + ... +\endverbatim +This was mainly added for backward compatibility. +Note that the \c visible attribute is just a hint for doxygen. +If no relevant information is available for a certain piece it is +omitted even if it is set to \c yes (i.e. no empty sections are generated). + +Some tags have a \c title attribute. This attribute can be used +to customize the title doxygen will use as a header for the piece. + +@warning at the moment you should not remove tags from the layout file +as a way to hide information. Doing so can cause broken links in the +generated output! + +At the moment the following generic tags are possible for each page: +
+
\c briefdescription +
Represents the brief description on a page. +
\c detaileddescription +
Represents the detailed description on a page. +
\c authorsection +
Represents the author section of a page (only used for man pages). +
\c memberdecl +
Represents the quick overview of members on a page (member declarations). + This tag has child tags each representing a list of + members of a certain type. + The possible child tags are not listed in detail in the document, + but the name of the tag should be a good indication of the type + of members that the tag represents. +
\c memberdef +
Represents the detailed member list on a page (member definition). + Like the \c memberdecl tag, also this tag has a number of + possible child tags. +
+ +The class page has the following specific tags: +
+
\c includes +
Represents the include file needed to obtain the definition for + this class. +
\c inheritancegraph +
Represents the inheritance relations for a class. + Note that the CLASS_DIAGRAM option determines + if the inheritance relation is a list of base and derived classes or + a graph. +
\c collaborationgraph +
Represents the collaboration graph for a class. +
\c allmemberslink +
Represents the link to the list of all members for a class. +
\c usedfiles +
Represents the list of files from which documentation for the class was + extracted. +
+ +The file page has the following specific tags: +
+
\c includes +
Represents the list of \#include statements contained in this file. +
\c includegraph +
Represents the include dependency graph for the file. +
\c includedbygraph +
Represents the included by dependency graph for the file. +
\c sourcelink +
Represents the link to the source code of this file. +
+ +The group page has a specific \c groupgraph tag which represents the +graph showing the dependencies between groups. + +Similarily, the directory page has a specific \c directorygraph tag +which represents the graph showing the dependencies between the directories +based on the \#include relations of the files inside the directories. + +\section xmlgenerator Using the XML output + +If the above two methods still do not provide enough flexibility, you +can also use the XML output produced by doxygen as a basis to +generate the output you like. To do this set GENERATE_XML to YES. + +The XML output consists of an index file named \c index.xml which +lists all items extracted by doxygen with references to the other XML files +for details. The structure of the index is described by a schema file +\c index.xsd. All other XML files are described by the schema file +named \c compound.xsd. If you prefer one big XML file +you can combine the index and the other files using the +XSLT file \c combine.xslt. + +You can use any XML parser to parse the file or use the one that can be found +in the \c addon/doxmlparser directory of doxygen source distribution. +Look at \c addon/doxmlparser/include/doxmlintf.h for the interface of the +parser and in \c addon/doxmlparser/example for examples. + +The advantage of using the doxmlparser is that it +will only read the index file into memory and then only those XML +files that you implicitly load via navigating through the index. As a +result this works even for very large projects where reading all XML +files as one big DOM tree would not fit into memory. + + */