The THtml class is designed to easily document
classes, code, and code related text files (like change logs). It generates HTML
pages conforming to the XHTML 1.0 transitional specifications; an example of
these pages is ROOT's own
reference guide. This page was verified to be valid XHTML 1.0 transitional,
which proves that all pages generated by THtml can be valid, as long as the user
provided XHTML (documentation, header, etc) is valid. You can check the current
THtml by clicking this icon:

When trying to document a class, THtml searches for a source file in
the directories set via SetInputDir(). If it cannot find it, it assumes
that this class must have been documented before. Based on the library
this class is defined in, it checks the configuration variable
Root.Html.LibName, and creates a link using its value.
Alternatively, you can set these URLs via THtml::SetLibURL().

Example:
If a class MyClass is defined in class mylibs/libMyLib.so, and .rootrc
contains

Root.Html.MyLib: ../mylib/

THtml will create a link to "../mylib/MyClass.html".

The library name association can be set up using the rootmap facility.
For the library in the example above, which contains a dictionary
generated from the linkdef MyLinkdef.h, the command to generate the
rootmap file is

Here, -r specifies that the entries for libMyLib should be updated,
-l specifies the library we're dealing with, -d its
dependencies, and -c its linkdef. The rootmap file must be within
one of the LD_LIBRARY_PATH (or PATH for Windows) directories
when ROOT is started, otherwise ROOT will not use it.

The class documentation has to appear in the header file containing the
class, right in front of its declaration. It is introduced by a string
defined by Root.Html.Description or SetClassDocTag(). See the section on
documentation syntax for further details.

Example:

Root.Html.Description: //____________________

The class documentation will show which include statement is to be used
and which library needs to be linked to access it.
The include file name is determined via
TClass::GetDeclFileName();
leading parts are removed if they match any of the ':' separated entries in
THtml::GetIncludePath().

During the conversion,
THtml will look for
some strings ("tags") in the source file, which have to appear right in
front of e.g. the author's name, copyright notice, etc. These tags can be
defined with the following environment variables: Root.Html.Author,
Root.Html.LastUpdate and Root.Html.Copyright, or with
SetAuthorTag(), SetLastUpdateTag(), SetCopyrightTag().

If the LastUpdate tag is not found, the current date and time are used.
This is useful when using
THtml::MakeAll()'s
default option force=kFALSE, in which case
THtml generates
documentation only for changed classes.

Authors can be a comma separated list of author entries. Each entry has
one of the following two formats

Name (non-alpha).

THtml will generate an
HTML link for Name, taking the Root.Html.XWho configuration
variable (defaults to "http://consult.cern.ch/xwho/people?") and adding
all parts of the name with spaces replaces by '+'. Non-alphanumerical
characters are printed out behind Name.

Example:

// Author: Enrico Fermi appears in the source file.
THtml will generate the link
http://consult.cern.ch/xwho/people?Enrico+Fermi. This works well for
people at CERN.

Name <link> Info.

THtml will generate
an HTML link for Name as specified by link and print
Info behind Name.

THtml generates
a default header and footer for all pages. You can
specify your own versions with the configuration variables Root.Html.Header
and Root.Html.Footer, or by calling SetHeader(), SetFooter().
Both variables default to "", using the standard Root
versions. If it has a "+" appended, THtml will
write both versions (user and root) to a file, for the header in the order
1st root, 2nd user, and for the footer 1st user, 2nd root (the root
versions containing "<html>" and </html> tags, resp).

If you want to replace root's header you have to write a file containing
all HTML elements necessary starting with the <doctype> tag and ending with
(and including) the <body> tag. If you add your header it will be added
directly after Root's <body> tag. Any occurrence of the string %TITLE%
in the user's header file will be replaced by
a sensible, automatically generated title. If the header is generated for a
class, occurrences of %CLASS% will be replaced by the current class's name,
%SRCFILE% and %INCFILE% by the name of the source and header file, resp.
(as given by TClass::GetImplFileName(),
TClass::GetDeclFileName()).
If the header is not generated for a class, they will be replaced by "".

Root's footer starts with the tag <!--SIGNATURE-->. It includes the
author(s), last update, copyright, the links to the Root home page, to the
user home page, to the index file (ClassIndex.html), to the top of the page
and this page is automatically generated infomation. It ends with the
tags </body></html>. If you want to replace it,
THtml will search for some
tags in your footer: Occurrences of the strings %AUTHOR%, %UPDATE%, and
%COPYRIGHT% are replaced by their
corresponding values before writing the html file. The %AUTHOR% tag will be
replaced by the exact string that follows Root.Html.Author, no link
generation will occur.

Additional parameters can be set by Root.Html.Homepage (address of the
user's home page), Root.Html.SearchEngine (search engine for the class
documentation), Root.Html.Search (search URL, where %u is replaced by the
referer and %s by the escaped search expression), and a ViewVC base URL
Root.Html.ViewCVS. For the latter, the file name is appended or, if
the URL contains %f, %f is replaced by the file name.
All values default to "".

XHTML 1.0 transitional recommends the specification of the charset in the
content type meta tag, see e.g. http://www.w3.org/TR/2002/REC-xhtml1-20020801/THtml generates it for the HTML output files. It defaults to ISO-8859-1, and
can be changed using Root.Html.Charset.

All classes to be documented will have an entry in the ClassIndex.html,
showing their name with a link to their documentation page and a miniature
description. This discription for e.g. the class MyClass has to be given
in MyClass's header as a comment right after ClassDef(MyClass, n).

A member function description block starts immediately after '{'
and looks like this:

void TWorld::HelloWorldFunc(string *text)
{
// This is an example of description for the
// TWorld member function
helloWorld.Print( text );
}

Like in a class description block, everything until the first
non-commented line is considered as a valid member function
description block.
If the rootrc variable Root.Html.DescriptionStyle is set to
Doc++ THtml will also look for method documentation in front of
the function implementation. This feature is not recommended; source code
making use of this does not comply to the ROOT documentation standards, which
means future versions of THtml might not support it anymore.

You can insert pure html code into your documentation comments. During the
generation of the documentation, this code will be inserted as is
into the html file.

Pure html code must be surrounded by the keywords
BEGIN_HTML and END_HTML, where the
case is ignored.
An example of pure html code is this class description you are reading right now.
THtml uses a
TDocHtmlDirective
object to process this directive.

THtml can create images from scripts. You can either call an external
script by surrounding it by "begin_macro"/"end_macro", or include an unnamed
macro within these keywords. The macro should return a pointer to an object;
this object will then be saved as a GIF file.

Objects deriving from
TGObject (GUI elements)
will need to run in graphics mode (non-batch). You must specify this as a parameter:
"Begin_macro(GUI)...".
To create a second tab that displays the source of the macro you can specify
the argument "Begin_macro(source)...".
Of course you can combine them,
e.g. as "Begin_macro(source,gui)...".
THtml uses a
TDocMacroDirective
object to process this directive.

You can specify TLatex
style text and let THtml convert it into an image by surrounding it by "Begin_Latex", "End_Latex".
You can have multiple lines, and e.g. align each line at the '=' sign by passing
the argument separator='='. You can also specify how to align these parts;
if you want the part left of the separator to be right aligned, and the right part
to be left aligned, you could specify align='rl'.
THtml uses a TDocLatexDirective
object to process the directive.
This is an example output with arguments separator='=', align='rl':

THtml::MakeIndex() will generate index files for classes
and types, all modules, and the product which you can set by
THtml::SetProductName().
THtml will make use of external documentation in the module and product index,
either by linking it or by including it.
The files for modules are searched based on the source file directory of the
module's classes.

A filename starting with "index." will be included in the index page;
all other files will be linked.
Only files ending on .html or .txt will be taken into account;
the text files will first be run through
THtml::Convert().
You can see an example here;
the part between "Index of HIST classes" and "Jump to" is created by parsing
the module's doc directory.

THtml can generate a number of graphical representations for a class, which
are displayed as a tabbed set of imaged ontop of the class description.
It can show the inheritance, inherited and hidden members, directly and
indirectly included files, and library dependencies.
These graphs are generated using the Graphviz
package. You can install it from http://www.graphviz.org.
You can either put it into your $PATH, or tell THtml where to find it by calling
SetDotDir().

Internally, THtml is just an API class that sets up the list of known
classes, and forwards API invocations to the "work horses".
TDocOutput
generates the output by letting a
TDocParser
object parse the sources, which in turn invokes objects deriving from
TDocDirective
to process directives.

It converts a single text file to HTML
Input: filename - name of the file to convert
title - title which will be placed at the top of the HTML file
dirname - optional parameter, if it's not specified, output will
be placed in htmldoc/examples directory.
relpath - optional parameter pointing to the THtml generated doc
on the server, relative to the current page.
includeOutput - if != kNoOutput, run the script passed as filename and
store all created canvases in PNG files that are
shown next to the converted source. Bitwise-ORing with
kForceOutput re-runs the script even if output PNGs exist
that are newer than the script. If kCompiledOutput is
passed, the script is run through ACLiC (.x filename+)
context - line shown verbatim at the top of the page; e.g. for links.
If context is non-empty it is expected to also print the
title.
NOTE: Output file name is the same as filename, but with extension .html

Produce documentation for all the classes specified in the filter (by default "*")
To process all classes having a name starting with XX, do:
html.MakeAll(kFALSE,"XX*");
If force=kFALSE (default), only the classes that have been modified since
the previous call to this function will be generated.
If force=kTRUE, all classes passing the filter will be processed.
If numthreads is != -1, use numthreads threads, else decide automatically
based on the number of CPUs.

Entry point of worker threads for multi-threaded MakeAll().
info points to an (internal) THtmlThreadInfo object containing the current
THtml object, and whether "force" was passed to MakeAll().
The thread will poll GetNextClass() until no further class is available.

Set the directory containing the source files.
The source file for a class MyClass will be searched
by prepending dir to the value of
MyClass::Class()->GetImplFileName() - which can contain
directory information!
Also resets the class structure, in case new files can
be found after this call.