THtml


class description - source file - inheritance tree

class THtml : public TObject


    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 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) 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 THtml() virtual void ~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)

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

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:
 -------------

 (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 occurence of the string "%TITLE%"
 (without the quotation marks) in the user's header file will be replaced by
 a sensible, automatically generated title.

 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: Occurences 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




 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



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 '/' flag


void ClassTree(TVirtualPad * psCanvas, TClass * classPtr, Bool_t force)
 It makes a 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 CreateListOfTypes()
 Create list of all data types

void DerivedClasses(ofstream & out, TClass * classPtr)
 It creates a list of derived classes


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


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 'html_begin/html_end' 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)
 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 occurence 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

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.37 2003/02/15 05:41:04 brun Exp $
Copyright (C) 1995-2000, Rene Brun and Fons Rademakers. *


ROOT page - Class index - Top of the page

This page has been automatically generated. If you have any comments or suggestions about the page layout send a mail to ROOT support, or contact the developers with any questions or problems regarding ROOT.