uicbasehtmldoc.pas

DelphiDoc is a program for automatic generation of documentation on a Delphi-Project. At the momen

    emptyp: String;

    //Sets the tags to represent either HMTL or XHTML tags.
    procedure ChangeTags(AsXHTML: Boolean; const NewLine: String);
  end;



  {Procedures that can be called to write additional content into the header of
   HTML files, for instance CSS oder script data.
  ~param F the newly created HTML file in which the additional content can be
           written }
  THeaderWriteProcedure = procedure (F: TBufferStream) of object;



  //for the virtual method ~[link TICBaseHTMLDoc.ListFileCreated] to be called
  //when one of the special lists has been written
  //(if it is not filtered and not empty)
  TSpecialListWritten = (
                         //list of platform specific identifiers
                         slwPlatform,
                         //list of library specific identifiers
                         slwLibrary,
                         //list of deprecated identifiers
                         slwDeprecated,
                         //list of unfinished identifiers
                         slwToDo,
                         //list of identifiers missing a feature
                         slwFeature,
                         //list of exported functions
                         slwExporteds,
                         //list of long functions
                         slwLongFunctions);



  {This class is the base class of the generators of documentation in the HTML
   (Hypertext Mark-Up Language) format. HTML is the first format to be
   generated by ~[em DelphiDoc], explaining, why most of the inline commands
   are similar to the corresponding HTML-tags.~[br]
   A lot of HTML files (*.html) will be created in the directory for the
   documentation along with some images (*.gif) and a Cascading Style-Sheets
   file (DelphiDoc.css). }
  TICBaseHTMLDoc = class(TICCommentDoc)
  private
    //the name (and path) of the file, whose content should be used instead of
    //the default header of the HTML files
    FTextHeaderFile: String;
    //the name (and path) of the file, whose content should be used instead of
    //the default footer of the HTML files
    FTextFooterFile: String;
    //if the CSS file shouldn't be overridden, if it already exists;
    //useful if the default Cascading Style-Sheets has been customized
    FDontOverrideCSSFile: Boolean;
    //the character encoding to set for the HTML files; default: iso-8859-15
    FCharacterEncoding: String;
    //whether special characters should not be quoted, i.e. <>&"
    FDontQuoteSpecialCharacters: Boolean;
    //whether CSS should be used for presentation instead of (deprecated) HTML
    //tags
    FUseCSS: Boolean;
    //whether tags should be generated in an XML-conform way, easing the
    //transition to XHTML, f.e. instead of "~[code <br>]" "~[code <br />]" will
    //be used
    FXMLConformity: Boolean;
    //whether instead of the header and DTD for HTML 4.01 Transitional the
    //header and DTD XHTML 1.0 strict should be written in the HTML files,
    //in that case, the files should also be generated with
    //~[link FXMLConformity] and with ~[link FUseCSS CSS] instead of deprecated
    //attributes, the ~[link FFileExtension] may then also be set to
    //"~[code .xhtml]"
    FUseXHTMLHeader: Boolean;
    //the extension of all (X)HTML files to be generated
    FFileExtension: String;

    //whether a HTML file should be generated that can be called with the
    //number of a help context to redirect to the topic specified by it,
    //the help context should just be added after the file name and "#HC",
    //this is done with the help of ECMAScript (JavaScript), if this fails the
    //user will be left stranded on the page, to work at least partially around
    //that you might want to use ~[link FGenerateVisualHelpContextRedirector]
    //instead
    FGenerateHelpContextRedirector: Boolean;
    //whether a HTML file should be generated that can be called with the
    //number of a help context to redirect to the topic specified by it,
    //the help context should just be added after the file name and "#HC",
    //this is done with the help of ECMAScript (JavaScript)
    //
    //for each help context a visible link will be created which will be
    //automatically shown, so even if the redirection fails the user has only
    //to click the (highlighted) link to get to the actual documentation
    FGenerateVisualHelpContextRedirector: Boolean;




    //a list of constants for common tags in the generated HTML which change
    //depending on whether a HTML or XHTML document is generated
    FTagConstants: TTagConstants;

    //the number of inserted images in the documentation to create unique names
    FImageIndex: Integer;
    //the list of files names of all images inserted into the documentation,
    //file names are in their short, unique format, the used file names within
    //the documentation for each image is in ~[link FImageDocNames]
    FImageNames: TStringList;
    //the files names of the images inserted into the documentation, represents
    //the final names in the documentation itself for each entry in
    //~[link FImageNames]
    FImageDocNames: TStringList;


    //the number of used image maps, images with links inside them
    //(only used to create a unique name for the maps of links for the images)
    FImageMapIndex: Integer;

    //whether currently a diagram is beeing added
    FAddingDiagram: Boolean;



    //Called to write the ECMAScript into the header of the HTML files to
    //redirect to topics based on help contexts.
    procedure WriteHelpContextECMAScript(F: TBufferStream);
    //Generates a file to redirect to topics based on a specified help context.
    procedure GenerateHelpContextRedirectorFile(const FileName: String;
                                                Visual: Boolean);


    //Call back procedure to get links on files in SVG diagrams of their usage.
    function FileUsageDiagramLinkCallBack(AFile: TPascalFile): String;
    //Call back procedure to get links on class in SVG diagrams of the
    //hierarchy.
    function ClassTreeDiagramLinkCallBack(AClass: TRecordType): String;

  protected
    //the object used to write the ~[linkUnit UICNodes COM] as HTML
    FVisitor: TICHTMLVisitor;


    //the content of the file ~[link FTextHeaderFile]
    FTextHeader: String;
    //the content of the file ~[link FTextFooterFile]
    FTextFooter: String;






    //Writes a GIF image in the given color indicating a scope or portability
    //issue.
    procedure WriteGIFImage(Color: TColor; const FilePrefix: String;
                            Portability: Boolean; Darker: Byte = 0);
    //Writes a GIF image indicating an abstract method.
    procedure WriteGIFImageAbstract(const FilePrefix: String);




    //Writes the redefined header of a HTML file, replacing special strings
    //with others.
    procedure WriteFileHeader(F: TBufferStream;
                              const TitlePart, KeyWords, MainPath: String;
                              HeaderContentProc: THeaderWriteProcedure);
    //Reformats the key words to be used in the HTML files.
    function ReformatKeyWords(const KeyWords: String): String;


    {Creates a new HTML file and writes its header.
    ~param FileName          the name of the file to create
    ~param TitlePart         the title of the HTML page, already quoted for
                             HTML format
    ~param KeyWords          the keywords of the HTML page in the index, quoted
                             in HTML
    ~param HeaderContentProc a method to be called to write additional content
                             into the header of the new HTML file
    ~result the created file as a stream }
    function CreateFile(const FileName, TitlePart, KeyWords: String;
                        HeaderContentProc: THeaderWriteProcedure
                                           = nil): TBufferStream; virtual;
                                                                  abstract;
    {Writes the footer of a HTML file and closes it.
    ~param F the HTML file to end and close }
    procedure EndFile(F: TBufferStream); virtual; abstract;




    //Will be called for some reserved words.
    function AsReservedWord(const Word: String): String;


    //Encodes special characters of external URIs.
    function CodeURI(const Text: String): String;

    //Returns a prefix for all links to images.
    function GetImagePrefix: String; virtual;







    //Returns a string containing a link to the given file.
    function GetFileNameLink(TheFile: TPascalFile): String;
    //Returns a string containing a link to the given identifier.
    function GetIdentNameLink(Ident: TIdentifier;
                              WriteFile: Boolean = False): String;
    //Returns a string containing a link to the given identifier inside a
    //record-like type.
    function GetRecordFieldNameLink(Ident: TIdentifier;
                                    WriteRecord: Boolean = False): String;






    //Writes the node of the ~[linkUnit UICNodes COM] into the file.
    procedure WriteNode(Node: TICNode; HTMLFile: TBufferStream);






    //Handles text by encoding special characters.
    function HandleRawText(const Text: String): String; override;




    //Writes the list of files.
    procedure WriteFileList(Node: TICNode); override;


    //Writes the hierarchy of the record-like types of the specified kind.
    procedure WriteClassTree(Kind: TRecordKind; Node: TICNode); override;





    //Writes the lists of all exported identifiers.
    function WriteExportsList: Boolean;

    //Writes the list of all long functions.
    function WriteLongFunctionList: Boolean;





    //Writes the splitted up list of identifiers and files into the
    //documentation.
    function WriteListOfIdentifiersAndFiles(const TopicName: String;
                                          DescriptionText,
                                          KeyWordListText: TDocumentationTexts;
                                          Idents, Classes: TIdentifierList;
                                          Files: TIdentifierFileList): Boolean;
                                                                      override;

    //Generates an index about all identifiers and files.
    procedure DoGenerateIndex(List: TIdentifierFileList;
                              const CharIndices: array of TIndexCharIndex);
                                                                      override;

    //Writes the current page of the user documentation.
    procedure CreateUserDocPage; override;


    //Gets the key words for the documentation of the GUI.
    function GetGUIHelpKeyWords(Data: TICGUIHelpData): String; virtual;
    //Generates the help on one data set of a GUI.
    procedure GenerateGUIHelpOnData(Data: TICGUIHelpData;
                                    AddContentTo: TICNCompound); override;




    //Creates the Cascading Style-Sheets file of the documentation.
    procedure CreateCSSFile;
    //Creates all needed image files.
    procedure CreateImageFiles;


    //Is called when one of the special lists has been written.
    procedure ListFileCreated(ListKind: TSpecialListWritten); virtual;
    //Creates all files with lists of identifiers or files in it.
    procedure CreateListFiles(F: TBufferStream);


    //Prepares the generator for creating the documentation.
    procedure PrepareForDocumentation;
    //Generates files to redirect to topics based on a specified help context.
    procedure GenerateHelpContextRedirectorFiles;



    property TextHeaderFile: String read FTextHeaderFile;
    property TextFooterFile: String read FTextFooterFile;
    property DontOverrideCSSFile: Boolean read FDontOverrideCSSFile;
  public
    //Creates the generator object and initializes its fields, but does not
    //create the visitor.
    constructor Create; override;
    //Frees the visitor and the generator object.
    destructor Destroy; override;



    //Returns the number of available options in generators of this class.
    class function GetOptionCount: Cardinal; override;
    //Gets a description of an option.
    class procedure GetOptionDescription(Index: Cardinal;
                                         var Desc: TOptionDescription);
                                                                      override;
    //Gets the value of an option.
    function GetOption(Index: Cardinal): TOptionValue; override;
    //Sets the value of an option.
    procedure SetOption(Index: Cardinal; const Value: TOptionValue); override;