library: libHtml #include "THtml.h"

# THtml

class description - source file - inheritance tree (.pdf)

## class THtml : public TObject

| Inheritance Chart:
`TObject`
| <- | `THtml` |

        protected:

          THtml::TDocElement* AddDocElement(TDictionary* dict, TString& strDoc, const char* filename)
                         void Class2Html(TClass* classPtr, Bool_t force = kFALSE)
                         void ClassDescription(ofstream& out, TClass* classPtr, Bool_t& flag)
                         void ClassHtmlTree(ofstream& out, TClass* classPtr, THtml::ETraverse dir = kBoth, int depth = 1)
                         void ClassTree(TVirtualPad* canvas, TClass* classPtr, Bool_t force = kFALSE)
                       Bool_t CopyHtmlFile(const char* sourceName, const char* destName = "")
                         void CreateHierarchy(const char** classNames, Int_t numberOfClasses)
                         void CreateIndex(const char** classNames, Int_t numberOfClasses)
                         void CreateIndexByTopic(char** filenames, Int_t numberOfNames, Int_t maxLen)
                         void CreateListOfTypes()
                         void DescendHierarchy(ofstream& out, TClass* basePtr, const char** classNames, Int_t numberOfClasses, Int_t maxLines = 0, Int_t depth = 1)
                         void ExpandKeywords(ofstream& out, char* text, TClass* ptr2class, Bool_t& flag, const char* dir = "")
                         void ExpandPpLine(ofstream& out, char* line)
                       Bool_t FindMethodImpl(TString strMethFullName, TList& listMethodSameName, TList& listArgs, THtml::TParseStack& parseStack, Bool_t done = kFALSE) const
                      TClass* GetClass(const char* name, Bool_t load = kTRUE)
          THtml::TDocElement* GetDocElement(TDictionary* dict) const
                  const char* GetFileName(const char* filename) const
                        char* GetHtmlFileName(TClass* classPtr)
                        char* GetSourceFileName(const char* filename)
                       Bool_t IsModified(TClass* classPtr, const Int_t type)
                static Bool_t IsName(Int_t c)
                static Bool_t IsWord(Int_t c)
                         void NameSpace2FileName(char* name)
                      TClass* ParseClassDecl(char*& cfirstLinePos, const THtml::TParseStack& parseStack, TString& strClassName)
                         void ReplaceSpecialChars(ofstream& out, const char c)
                         void ReplaceSpecialChars(ofstream& out, const char* string)
                         void SortNames(const char** strings, Int_t num, Bool_t type = 0)
                        char* StrDup(const char* s1, Int_t n = 1)

        public:

                              THtml()
                      virtual ~THtml()
               static TClass* Class()
                         void Convert(const char* filename, const char* title, const char* dirname = "")
                         void ExtractClassDocumentation(const TClass* classPtr)
                         void ExtractDocumentation(const char* cFileName, TList* listClassesFound)
                  const char* GetDoc(TDictionary* dict) const
                   TPaveText* GetDocPave(TDictionary* dict)
                  const char* GetOutputDir() const
                  const char* GetSourceDir() const
          static TDictionary* GetType(const char* type)
                  const char* GetXwho() const
              virtual TClass* IsA() const
                         void MakeAll(Bool_t force = kFALSE, const char* filter = "*")
                         void MakeClass(const char* className, Bool_t force = kFALSE)
                        TMap* MakeHelp(TClass* cl)
                         void MakeIndex(const char* filter = "*")
                         void MakeTree(const char* className, Bool_t force = kFALSE)
                static Bool_t ParseWord(const char* begin, Int_t& step, const char* allowedChars = "0")
                static Bool_t ParseWord(const char* begin, Int_t& step, TString& strWord, const char* allowedChars = "0")
                         void SetEscape(char esc = \\)
                         void SetOutputDir(const char* dir)
                         void SetSourceDir(const char* dir)
                         void SetSourcePrefix(const char* prefix)
                         void SetXwho(const char* xwho)
                 virtual void ShowMembers(TMemberInspector& insp, char* parent)
                 virtual void Streamer(TBuffer& b)
                         void StreamerNVirtual(TBuffer& b)
                 virtual void WriteHtmlFooter(ofstream& out, const char* dir = "", const char* lastUpdate = "", const char* author = "", const char* copyright = "")
                 virtual void WriteHtmlHeader(ofstream& out, const char* title, TClass* cls = 0)

### Data Members

        protected:

                   TString fXwho            by default http://xwho.cern.ch/WHO/people?
               const char* fSourcePrefix    prefix to relative source path
               const char* fSourceDir       source path
               const char* fOutputDir       output directory
                     char* fLine            current line
                     Int_t fLen             maximum line length
                     char* fCounter         counter string
                    Bool_t fEscFlag         Flag to mark the symbol must be written "as is"
                      char fEsc             The special symbol ("backslash" by default) to mark "the next symbol should not be converted
                     TMap* fMapDocElements  map of <TDictionary*, TDocElement*> for all objects for which doc was parsed
          static THashList fgLocalTypes     list of types that are not in TROOT::GetClass
                     TList fFilesParsed     list of files on which ExtractDocumentatoin was run
                     Int_t fHierarchyLines  counter for no. lines in hierarchy

        public:

          static const THtml::ETraverse kUp
          static const THtml::ETraverse kDown
          static const THtml::ETraverse kBoth

## 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::GetDeclFiuleName()).
     If the header is not generated for a class, they will be relpaced 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) and Root.Html.SearchEngine (search engine for the class
     documentation). Both default to "".

     Examples:
           Root.Html.Homepage:     http://www.enricos-home.it
           Root.Html.SearchEngine: http://root.cern.ch/root/Search.phtml

     (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(): fMapDocElements(0)

     Create a THtml object.
     In case output directory does not exist an error
     will be printed and gHtml stays 0 also zombie bit will be set.

~THtml()

     Default destructor

void Class2Html(TClass * classPtr, Bool_t force)

     It creates HTML file for a single class

     Input: classPtr - pointer to the class

void ClassDescription(ofstream & out, TClass * classPtr, Bool_t & flag)

     This function builds the description of the class

     Input: out      - output file stream
            classPtr - pointer to the class
            flag     - this is a 'begin _html/end _html' flag

void ClassHtmlTree(ofstream & out, TClass * classPtr, ETraverse dir, int depth)

     This function builds the class tree for one class in HTML
     (inherited and succeeding classes, called recursively)

     Input: out      - output file stream
            classPtr - pointer to the class
            dir      - direction to traverse tree: up, down or both

void ClassTree(TVirtualPad * psCanvas, TClass * classPtr, Bool_t force)

     It makes a graphical class tree

     Input: psCanvas - pointer to the current canvas
            classPtr - pointer to the class

void Convert(const char *filename, const char *title, const char *dirname)

     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 html/examples directory.

      NOTE: Output file name is the same as filename, but with extension .html

Bool_t CopyHtmlFile(const char *sourceName, const char *destName)

     Copy file to HTML directory

      Input: sourceName - source file name
             destName   - optional destination name, if not
                          specified it would be the same
                          as the source file name

     Output: TRUE if file is successfully copied, or
             FALSE if it's not

       NOTE: The destination directory is always fOutputDir

void CreateIndex(const char **classNames, Int_t numberOfClasses)

     Create an index

     Input: classNames      - pointer to an array of class names
            numberOfClasses - number of elements

void CreateIndexByTopic(char **fileNames, Int_t numberOfNames, Int_t maxLen)

     It creates several index files

     Input: fileNames     - pointer to an array of file names
            numberOfNames - number of elements in the fileNames array
            maxLen        - maximum length of a single name

void CreateHierarchy(const char **classNames, Int_t numberOfClasses)

     Create a hierarchical class list
     The algorithm descends from the base classes and branches into
     all derived classes. Mixing classes are displayed several times.

     Input: classNames      - pointer to an array of class names
            numberOfClasses - number of elements

void DescendHierarchy(ofstream & out, TClass* basePtr, const char **classNames, Int_t numberOfClasses, Int_t maxLines, Int_t depth)

     Descend hierarchy recursively
     loop over all classes and look for classes with base class basePtr

void CreateListOfTypes()

     Create list of all data types

void ExpandKeywords(ofstream & out, char *text, TClass * ptr2class, Bool_t & flag, const char *dir)

     Find keywords in text & create URLs

     Input: out       - output file stream
            text      - pointer to the array of the characters to process
            ptr2class - pointer to the class
            flag      - this is a 'begin _html/end _html' flag
            dir       - usually "" or "../", depends of current file
                        directory position

void ExpandPpLine(ofstream & out, char *line)

     Expand preprocessor statements

     Input: out  - output file stream
            line - pointer to the array of characters,
                   usually one line from the source file

      NOTE: Looks for the #include statements and
            creates link to the corresponding file
            if such file exists

const char* GetFileName(const char *filename)

     It discards any directory information inside filename

      Input: filename - pointer to the file name

     Output: pointer to the string containing just a file name
             without any other directory information, i.e.
             '/usr/root/test.dat' will return 'test.dat'

char* GetSourceFileName(const char *filename)

     Find the source file. If filename contains a path it will be used
     together with the possible source prefix. If not found we try
     old algorithm, by stripping off the path and trying to find it in the
     specified source search path. Returned string must be deleted by the
     user. In case filename is not found 0 is returned.

char* GetHtmlFileName(TClass * classPtr)

     Return real HTML filename

      Input: classPtr - pointer to a class

     Output: pointer to the string containing a full name
             of the corresponding HTML file. The string must be deleted by the user.

TClass* GetClass(const char *name1, Bool_t load)

    *-*-*-*-*Return pointer to class with name*-*-*-*-*-*-*-*-*-*-*-*-*
    *-*      =================================

Bool_t IsModified(TClass * classPtr, const Int_t type)

     Check if file is modified

      Input: classPtr - pointer to the class
             type     - file type to compare with
                        values: kSource, kInclude, kTree

     Output: TRUE     - if file is modified since last time
             FALSE    - if file is up to date

Bool_t IsName(Int_t c)

     Check if c is a valid C++ name character

      Input: c - a single character

     Output: TRUE if c is a valid C++ name character
             and FALSE if it's not.

       NOTE: Valid name characters are [a..zA..Z0..9_],

Bool_t IsWord(Int_t c)

     Check if c is a valid first character for C++ name

      Input: c - a single character

     Output: TRUE if c is a valid first character for C++ name,
             and FALSE if it's not.

       NOTE: Valid first characters are [a..zA..Z_]

void MakeAll(Bool_t force, const char *filter)

     It makes 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.

void MakeClass(const char *className, Bool_t force)

     Make HTML files for a single class

     Input: className - name of the class to process

void MakeIndex(const char *filter)

     It makes an index files
     by default makes an index of all classes (if filter="*")
     To generate an index for all classes starting with "XX", do
        html.MakeIndex("XX*");

void MakeTree(const char *className, Bool_t force)

     Make an inheritance tree

     Input: className - name of the class to process

void ReplaceSpecialChars(ofstream & out, const char c)

     Replace ampersand, less-than and greater-than character

     Input: out - output file stream
            c   - single character

void ReplaceSpecialChars(ofstream & out, const char *string)

     Replace ampersand, less-than and greater-than characters

     Input: out    - output file stream
            string - pointer to an array of characters

void SortNames(const char **strings, Int_t num, Bool_t type)

     Sort strings

     Input: strings - pointer to an array of strings
            type    - sort type
                      values : kCaseInsensitive, kCaseSensitive
                      default: kCaseInsensitive

char* StrDup(const char *s1, Int_t n)

     Returns a pointer to a new string which is a duplicate
     of the string to which 's1' points.  The space for the
     new string is obtained using the 'new' operator. The new
     string has the length of 'strlen(s1) + n'.

void WriteHtmlHeader(ofstream & out, const char *title, TClass *cls/*=0*/)

     Write HTML header

     Input: out   - output file stream
            title - title for the HTML page

     evaluates the Root.Html.Header setting:
     * if not set, the standard header is written. (ROOT)
     * if set, and ends with a "+", the standard header is written and this file included afterwards. (ROOT, USER)
     * if set but doesn't end on "+" the file specified will be written instead of the standard header (USER)

     Any occurrence of "%TITLE%" (without the quotation marks) in the user provided header file
     will be replaced by the value of this method's parameter "title" before written to the output file.
     %CLASS% is replaced by the class name ("" if not a class), %INCFILE% by the header file name as
     given by TClass::GetDeclFileName() and %SRCFILE% by the source file name as given by
     TClass::GetImplFileName() (both "" if not a class).

void WriteHtmlFooter(ofstream & out, const char *dir, const char *lastUpdate, const char *author, const char *copyright)

     Write HTML footer

     Input: out        - output file stream
            dir        - usually equal to "" or "../", depends of
                         current file directory position, i.e. if
                         file is in the fOutputDir, then dir will be ""
            lastUpdate - last update string
            author     - author's name
            copyright  - copyright note

     Allows optional user provided footer to be written. Root.Html.Footer holds the file name for this footer.
     For details see THtml::WriteHtmlHeader (here, the "+" means the user's footer is written in front of Root's!)
     Occurences of %AUTHOR%, %UPDATE% and %COPYRIGHT% in the user's file are replaced by their corresponding
     values (author, lastUpdate and copyright) before written to out.

void NameSpace2FileName(char *name)

     Replace "::" in name by "__"
     Replace "<", ">", " ","," in name by "_"

void ExtractClassDocumentation(const TClass* classPtr)

void ExtractDocumentation(const char* cFileName, TList* listClassesFound)

     parse this source or header, collect classes and methods, and add their doc to
     fMapDocElemets
     return the list of class definitions found in listClassesFound
     search only for methods of classes that are in listClassesFound

TClass* ParseClassDecl(char* &cfirstLinePos, const TParseStack& parseStack, TString& strClassName)

Bool_t ParseWord(const char* begin, Int_t &step, TString& strWord, const char* allowedChars /*=0*/)

Bool_t ParseWord(const char* begin, Int_t &step, const char* allowedChars /*=0*/)

Bool_t FindMethodImpl(TString strMethFullName, TList& listMethSameName, TList& listArgs, TParseStack& parseStack, Bool_t done) const

     find strArgs in all methods in listMethSameName
     remove those from the list that don't fit
     Return kFALSE if error

TPaveText* GetDocPave(TDictionary* dict)

TMap* MakeHelp(TClass* cl)

### Inline Functions

            THtml::TDocElement* AddDocElement(TDictionary* dict, TString& strDoc, const char* filename)
            THtml::TDocElement* GetDocElement(TDictionary* dict) const
                    const char* GetSourceDir() const
                    const char* GetOutputDir() const
                    const char* GetXwho() const
                           void SetEscape(char esc = \\)
                           void SetSourcePrefix(const char* prefix)
                           void SetSourceDir(const char* dir)
                           void SetOutputDir(const char* dir)
                           void SetXwho(const char* xwho)
                   TDictionary* GetType(const char* type)
                    const char* GetDoc(TDictionary* dict) const
                        TClass* Class()
                        TClass* IsA() const
                           void ShowMembers(TMemberInspector& insp, char* parent)
                           void Streamer(TBuffer& b)
                           void StreamerNVirtual(TBuffer& b)

Author: Nenad Buncic (18/10/95), Axel Naumann (09/28/01)
Last update: root/html:$Name: $:$Id: THtml.cxx,v 1.76 2005/05/30 13:47:13 rdm Exp $
Copyright (C) 1995-2000, Rene Brun and Fons Rademakers. *