uichtmlhelpdoc.pas

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

{  JADD - Just Another DelphiDoc: Documentation from Delphi Source Code

Copyright (C) 2003-2008   Gerold Veith

This file is part of JADD - Just Another DelphiDoc.

DelphiDoc is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License version 3 as
published by the Free Software Foundation.

DelphiDoc is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
}


unit UICHTMLHelpDoc;

{Contains the documentation generator ~[linkClass TICHTMLHelpDoc] to generate
 documentation about the parsed data in the HTML format as a compiled help
 file for Windows (.chm).
}

interface

uses Windows, Graphics,
     General,
     UPascalConsts,
     UBaseIdents,
     UOptions, UMakeDoc,
     UImages, UICGUIHelpData,
     UICNodes,
     UICBaseHTMLDoc;


type

   { * * *  ***  * * *  ***   TICHTMLHelpVisitor   ***  * * *  ***  * * *  }

  {A visitor of the ~[link UICNodes COM]-hierarchy, it is used by the generator
   ~[linkClass TICHTMLHelpDoc] to write the COM to a file in the HTML-Format. }
  TICHTMLHelpVisitor = class(TICHTMLVisitor)
  public
    //Called for each node containing the declaration of an identifier.
    procedure IdentifierDeclaration(Node: TICNIdentifierDeclaration;
                                    var VisitChildren: Boolean); override;
  end;





   { * * *  ***  * * *  ***   TICHTMLHelpDoc   ***  * * *  ***  * * *  }

const DefaultCHMFileName = 'DelphiDoc';  //default name of help file
      CHMFileExtension = '.chm';         //extension of HTML help files
      HH_ProjectFile = 'DelphiDoc.hhp';  //HTML help project file
      HH_IndexFileBaseName = 'index';    //main file in help without extension
      HH_ContentsFile = 'DelphiDoc.hhc'; //file with the table of contents
      HH_LogFile = 'DelphiDoc.log';      //log file of compilation
      HH_KeyWordIndexFile = 'Index.hhk'; //file with key words (empty so far)






type

  //whether the documentation should be generated with sub-directories
  TSubDirectoryUsage = (
                        sduNone,            //don't use sub-directories
                        //create a sub-directory for each documented file
                        sduFiles,
                        //create a sub-directory for each documented file and
                        sduFilesAndTypes);  //record-like type


  //the different kinds of lists of identifiers in a file to be written
  TWriteKind = (wkVar,         //list of all variables
                wkThreadVar,   //list of all thread-variables
                wkConst,       //list of all constants
                wkResString,   //list of all resource-strings
                wkFunc,        //list of all functions (must be the last one)
                wkSimpleType); //list of all simple types (no record-likes)



  {This generator of documentation generates a compiled HTML
   (Hypertext Mark-Up Language) file (.chm).~[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). These will be compiled by the HTML Help Compiler to
   a .chm file. The compiler can be downloaded free of charge at
   ~[linkExtern http://go.microsoft.com/fwlink/?LinkId=14188] (htmlhelp.exe). }
  TICHTMLHelpDoc = class(TICBaseHTMLDoc)
  private
    //the table of contents for the help file
    FContentFile: TBufferStream;
    //the depth/level inside the content file
    FContentLevel: Integer;

    //number of created files
    FGeneratedFileCount: Integer;


    //the name of the Windows HTML Help file to be generated
    FHelpFileName: String;
    //if the Help project should automatically be compiled
    FAutoCompile: Boolean;
    //if the Help file should autmatically ba launched after the compilation
    FHelpCompilerPath: String;

    //spread files in sub-directories?
    FUseSubdirectories: TSubDirectoryUsage;
  protected


    //Gets the special object tag to register the key words as a string.
    function GetKeyWordsTagObject(const KeyWords: String): String;

    //Creates a new HTML file and writes its header.
    function CreateFile(const FileName, TitlePart, KeyWords: String;
                        HeaderContentProc: THeaderWriteProcedure
                                           = nil): TBufferStream; override;
    //Writes the footer of a HTML file and closes it.
    procedure EndFile(F: TBufferStream); override;


    //Inserts an entry into the content file.
    procedure AddContentEntry(const Text, Target: String);
    //Starts a new list of sub-topics in the content file.
    procedure StartContentList(const Text: String);
    //Ends a list of sub-topics.
    procedure EndContentList;







    //Returns the absolute unique ID of an identifier to be used in the
    //documentation.
    function GetFileName(Ident: TIdentifier; TheFile: TPascalFile = nil;
                         Local: Boolean = False): String;


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






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

    //Writes the documentation about all identifiers in the file of the given
    //kind and a list of them.
    function WriteVarConstFuncs(AFile: TPascalFile;
                                WriteType: TWriteKind): String;
    //Writes a short, linked list of all record-like types in the file.
    function WriteRecordTypeList(AFile: TPascalFile): String;

    //Writes the documentation about the file.
    procedure WriteFileDocumentation(AFile: TPascalFile); override;









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

    //Writes the documentation of the members of the record-like type.
    function WriteMembers(Kind: TMemberKind; Ident: TRecordType): String;
    //Writes the documentation of the record-like type.
    procedure WriteClassDocumentation(Ident: TRecordType); 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; override;
    //Generates the help on one data set of a GUI.
    procedure GenerateGUIHelpOnData(Data: TICGUIHelpData;
                                    AddContentTo: TICNCompound); override;



{$IFNDEF LINUX}

    //Compiles the help project.
    function CompileHelpProject: Boolean;

{$ENDIF}

    //Post processes the generated files to a .chm file.
    procedure PostProcess;



    //Begins the documentation.
    procedure StartDocumentation;
    //Ends the documentation.
    procedure EndDocumentation;
    //Handles the documentation after the successful generation.
    procedure SuccessfulEnd;


    //Is called when one of the special lists has been written.
    procedure ListFileCreated(ListKind: TSpecialListWritten); override;


    //Generates the help on a GUI.
    function DoGenerateGUIHelp: Boolean; override;
    //Generates only the user documentation.
    function DoGenerateOnlyUserDocumentation: Boolean; override;
    //Process parsed data; generate some documentation about it.
    function DoGenerateDocumentation: Boolean; override;
  public
    //Creates the generator object and the visitor and initializes its fields.
    constructor Create; override;

    //Returns a description of the documentation of the generator.
    class function GetDescription: TGeneratorDescription; 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;



    //Returns the capabilities of this class of generators.
    class function Capabilities: TGeneratorCapabilities; override;





    //Returns the unique ID of an identifier to be used in the documentation.
    function GetURIOf(Ident: TIdentifier;
                      TheFile: TPascalFile = nil): String; override;
    //Gets the (internal) identification (for links) of pages in the user
    //documentation.
    function GetPageURI(PageIndex: Integer): String; override;

    //not used, because GUI help can not be used with identifiers - so far,
    //so it can't be in a sub-directory
    //Gets the (internal) identification (for links) of topics of documentation
    //of a GUI.
//    function GetGUIHelpURIByIndex(FileIndex, TopicIndex: Integer): String;
//                                                                    override;


    //Includes an image in the documentation.
    function WriteImage(CharFormat, JPEGFormat: Boolean; Resolution: TPoint;
                        BMP: TBitmap; const FileName: String;
                        Links: TImageLinkList;
                        const AlternativeText: String): String; override;

    //Writes the links to the generated files by ~[link WriteFileTreeFiles].
    procedure WriteFileListFileLinks(F: TBufferStream); override;
    //Write the links to the generated files by ~[link WriteClassesTreeFiles].
    procedure WriteClassTreeFileLinks(Kind: TRecordKind; F: TBufferStream);
                                                                      override;



{$IFNDEF LINUX}
    //Searches the help compiler and returns its path.
    function SearchHelpCompiler: String;
{$ENDIF}


    //Resets the attributes to ready the generator for a new generation.
    procedure ResetForNewGeneration; override;

  end;



implementation


uses SysUtils, Classes,
{$IFNDEF LINUX}
     Registry, ShellAPI, Forms,
{$ENDIF}
{$IFDEF VER120}
     FileCtrl,
{$ENDIF}
     UFilePaths,
     UExtIdents,
     UILComment,
     UICDocumentDoc, UICCommentDoc,
     UDocumentationTexts;





   { * * *  ***  * * *  ***   TICHTMLHelpVisitor   ***  * * *  ***  * * *  }

{Called for each node containing the declaration of an identifier.
~param Node          the node containing the declaration of an identifier
~param VisitChildren out: whether the children of the node (the declaration)
                          should also be visited; default is True }
procedure TICHTMLHelpVisitor.IdentifierDeclaration(
                                               Node: TICNIdentifierDeclaration;
                                               var VisitChildren: Boolean);
          //the identifier whose declaration should be written
var       Ident      :TIdentifier;
          IsMember   :Boolean;             //whether identifier is a member
begin
 Ident := FGenerator.CommentIdent;         //get the identifier
 IsMember := Assigned(Ident.MemberOf);     //is a member?


 FHTMLFile.WriteString('<p class="identdecl">');

 //write its scope
 FHTMLFile.WriteString(FGenerator.GetScope(Ident.Scope));

 if IsMember then
  begin
   //if it is a property with read-only access write an indicating icon