THtml

Class Description


 The HyperText Markup Language (HTML) is a simple data format used to
 create hypertext documents that are portable from one platform to another.
 HTML documents are SGML documents with generic semantics that are
 appropriate for representing information from a wide range of domains.

 The THtml class is designed to provide an easy way for converting ROOT
 classes, and files as well, into HTML documents. Here are the few rules and
 suggestions for a configuration, coding and usage.


 Configuration:
 -------------

 (i)   Input files

 Define Root.Html.SourceDir to point to directories containing .cxx and
 .h files ( see: TEnv ) of the classes you want to document. Better yet,
 specify separate Unix.*.Root.Html.SourceDir and WinNT.*.Root.Html.SourceDir.
 Root.Html.SourcePrefix can hold an additional (relative) path to help THtml
 find the source files. Its default value is "". Root's class documentation
 files can be linked in if Root.Html.Root is set to Root's class
 documentation root. It defaults to "".

 Examples:
   Unix.*.Root.Html.SourceDir:  .:src:include
   WinNT.*.Root.Html.SourceDir: .;src;include
   Root.Html.SourcePrefix:
   Root.Html.Root:              http://root.cern.ch/root/html


 (ii)  Output directory

 The output directory can be specified using the Root.Html.OutputDir
 environment variable ( default value: "htmldoc" ). If it doesn't exist, it
 will be created.

 Examples (with defaults given):
   Root.Html.OutputDir:         htmldoc


 (iii) Class documentation

 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. See below, section "Coding", for
 further details.

 Examples (with defaults given):
   Root.Html.Description:       //____________________


 (iv)  Source file information

 During the conversion, THtml will look for the certain number of user
 defined 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.

 If the LastUpdate tag is not found, the current date and time are given.
 This makes sense if one uses THtml'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 environment variable (defaults to
    "http://consult.cern.ch/xwho/people?") and adding all parts of the name
    with spaces replaces by '+'. Non-Alphas 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 a HTML link for Name as specified
    by "link" and print Info behind Name.

    Example: "// Author: Enrico Fermi <http://www.enricos-home.it>" or
    "// Author: Enrico Fermi <mailto:enrico@fnal.gov>" in the
    source file. That's world compatible.

 Examples (with defaults given):
       Root.Html.Author:     // Author:
       Root.Html.LastUpdate: // @(#)
       Root.Html.Copyright:  * Copyright
       Root.Html.XWho:       http://consult.cern.ch/xwho/people?


 (v)   Style

 THtml generates a default header and footer for all pages. You can
 specify your own versions with the environment variables Root.Html.Header
 and Root.Html.Footer. Both variables default to "", using the standard Root
 versions. If set the parameter to your file and append a "+", 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%"
 (without the quotation marks) 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%" (without the quotation marks) 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.


 (vi)  Miscellaneous

 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) and Root.Html.Search (search URL). All default to "".

 Examples:
       Root.Html.Homepage:     http://www.enricos-home.it
       Root.Html.SearchEngine: http://root.cern.ch/root/Search.phtml
       Root.Html.Search:       http://www.google.com/search?q=%s+site%3Aroot.cern.ch%2Froot%2Fhtml


 (vii) HTML Charset

 HTML 4.01 transitional recommends the specification of the charset in the
 content type meta tag, see e.g.

http://www.w3.org/TR/REC-html40/charset.html

 THtml generates it for the HTML output files. It defaults to ISO-8859-1, and
 can be changed using Root.Html.Charset.

 Example:
       Root.Html.Charset:      EUC-JP




 Coding rules:
 ------------

 A class description block, which must be placed before the first
 member function, has a following form:

       
       //                                                            
       // TMyClass                                                   
       //                                                            
       // This is the description block.                             
       //                                                            
       

 The environment variable Root.Html.Description ( see: TEnv ) contents
 the delimiter string ( default value: //_________________ ). It means
 that you can also write your class description block like this:

       //_____________________________________________________________
       // A description of the class starts with the line above, and
       // will take place here !
       

 Note that EVERYTHING until the first non-commented line is considered
 as a valid class description block.

 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.

   ==> The "Begin_Html" and "End_Html" special keywords <=========
       --------------------------------------------
 You can insert pure html code in your comment lines. During the
 generation of the documentation, this code will be inserted as is
 in the html file.
 Pure html code must be inserted between the keywords "Begin_Html"
 and "End_Html" starting/finishing anywhere in the comment lines.
 Examples of pure html code are given in many Root classes.
 See for example the classes TDataMember and TMinuit.

   ==> The escape character
       --------------------
 Outside blocks starting with "Begin_Html" and finishing with "End_Html"
 one can prevent the automatic translation of symbols like "<" and ">"
 to "&lt;" and "&gt;" by using the escape character in front.
 The default escape character is backslash and can be changed
 via the member function SetEscape.

   ==> The ClassIndex
       --------------
 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 ).



 Usage:
 -----

     Root> THtml html;                // create a THtml object
     Root> html.MakeAll()             // invoke a make for all classes
     Root> html.MakeClass("TMyClass") // create a HTML files for that class only
     Root> html.MakeIndex()           // creates an index files only
     Root> html.MakeTree("TMyClass")  // creates an inheritance tree for a class

     Root> html.Convert( hist1.mac, "Histogram example" )


 Environment variables:
 ---------------------

   Root.Html.OutputDir    (default: htmldoc)
   Root.Html.SourceDir    (default: .:src/:include/)
   Root.Html.Author       (default: // Author:) - start tag for authors
   Root.Html.LastUpdate   (default: // @(#)) - start tag for last update
   Root.Html.Copyright    (default:  * Copyright) - start tag for copyright notice
   Root.Html.Description  (default: //____________________ ) - start tag for class descr
   Root.Html.HomePage     (default: ) - URL to the user defined home page
   Root.Html.Header       (default: ) - location of user defined header
   Root.Html.Footer       (default: ) - location of user defined footer
   Root.Html.Root         (default: ) - URL of Root's class documentation
   Root.Html.SearchEngine (default: ) - link to the search engine
   Root.Html.XWho         (default: http://consult.cern.ch/xwho/people?) - URL stem of CERN's xWho system
   Root.Html.Charset      (default: ISO-8859-1) - HTML character set

THtml

class THtml : public TObject

Data Members

Class Description