THtml

class THtml : public TObject

    private:

             void Class2Html(TClass* classPtr, Bool_t force = kFALSE)
             void ClassDescription(ofstream& out, TClass* classPtr, Bool_t& flag)
             void ClassTree(TVirtualPad* canvas, TClass* classPtr, Bool_t force = kFALSE)
           Bool_t CopyHtmlFile(const char* sourceName, const char* destName)
             void CreateIndex(const char** classNames, Int_t numberOfClasses)
             void CreateIndexByTopic(char** filenames, Int_t numberOfNames, Int_t maxLen)
             void CreateListOfTypes()
             void DerivedClasses(ofstream& out, TClass* classPtr)
             void ExpandKeywords(ofstream& out, char* text, TClass* ptr2class, Bool_t& flag, const char* dir)
             void ExpandPpLine(ofstream& out, char* line)
          TClass* GetClass(const char* name, Bool_t load = kTRUE)
      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)
           Bool_t IsName(Int_t c)
           Bool_t IsWord(Int_t c)
             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 THtml()
                THtml THtml(THtml&)
         virtual void ~THtml()
       static TClass* Class()
                 void Convert(const char* filename, const char* title, const char* dirname)
          const char* GetOutputDir() const
          const char* GetSourceDir() const
          const char* GetXwho() const
      virtual TClass* IsA() const
                 void MakeAll(Bool_t force = kFALSE)
                 void MakeClass(const char* className, Bool_t force = kFALSE)
                 void MakeIndex()
                 void MakeTree(const char* className, Bool_t force = kFALSE)
                 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)
         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)

  Data Members
    private:

          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

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 is the few rules
 and suggestions for a configuration, coding and usage.


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

   The output directory could be specified using the Root.Html.OutputDir
 environment variable ( default value: "html/" ). Also it is necessary to
 define Root.Html.SourceDir to point to directories containing .cxx and .h
 files ( see: TEnv ).

       Examples:
                Root.Html.OutputDir: html
                Root.Html.SourceDir: src:include:.:/usr/user/source
                Root.Html.Root:      http://root.cern.ch/root/html


   During the conversion, THtml will look for the certain number of
 user defined strings, i.e. author's name, copyright note, etc.
 This could be defined with following environment variables:

       Root.Html.Author     ( default: // Author:)
       Root.Html.LastUpdate ( default: // @(#))
       Root.Html.Copyright  ( default:  * Copyright)



 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.

 Usage:
 -----

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

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


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

   Root.Html.OutputDir    ( default: htmldoc/)
   Root.Html.SourceDir    ( default: .:src/:include/)
   Root.Html.Author       ( default: // Author:)
   Root.Html.LastUpdate   ( default: // @(#))
   Root.Html.Copyright    ( default:  * Copyright)
   Root.Html.Description  ( default: //____________________ )
   Root.Html.HomePage     ( URL to the user defined home page )
   Root.Html.SearchEngine ( link to the search engine )

 Create a THtml object. Use object directly or via the global
 pointer gHtml. In case output directory does not exist an error
 will be printed and gHtml stays 0 also zombie bit will be set.

 Default destructor

 It creates HTML file for a single class


 Input: classPtr - pointer to the class

 This function builds the description of the class


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

 It makes a class tree


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

 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

 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

 Create an index


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

 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

 Create list of all data types

 It creates a list of derived classes


 Input: out      - output file stream
        classPtr - pointer to the class

 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 'html_begin/html_end' flag
        dir       - usually "" or "../", depends of current file
                    directory position

 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

 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'

 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.

 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.

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

 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

 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_],

 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_]

 It makes everything

 Make HTML files for a single class


 Input: className - name of the class to process

 It makes an index files

 Make an inheritance tree


 Input: className - name of the class to process

 Replace ampersand, less-than and greater-than character


 Input: out - output file stream
        c   - single character

 Replace ampersand, less-than and greater-than characters


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

 Sort strings


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

 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'.

 Write HTML header


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

 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

Inline Functions

        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)
            TClass* Class()
            TClass* IsA() const
               void ShowMembers(TMemberInspector& insp, char* parent)
               void Streamer(TBuffer& b)
              THtml THtml(THtml&)