uhtmlhelpdoc.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 UHTMLHelpDoc;

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

interface

uses Windows, Classes, Graphics, 
     UPascalConsts,
     UBaseIdents, UExtIdents,
     UOptions, UMakeDoc,
     UImages, UOldGUIHelpData,
     UFormatCommentDoc, UBaseHTMLDoc;




   { * * *  ***  * * *  ***   THTMLHelpDoc   ***  * * *  ***  * * *  }

const DefaultCHMFileName = 'DelphiDoc';  //default name of help file
      CHMFileExtension = '.chm';         //extension of HTML help files
      HH_ProjectFile = 'DelphiDoc.hhp';  //HTML help project file
      HH_IndexFile = 'index.html';       //main file in help file
      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

  //if 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 write
  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. It can be downloaded free of charge at
   ~[linkExtern http://go.microsoft.com/fwlink/?LinkId=14188] (htmlhelp.exe). }
  THTMLHelpDoc = class(TBaseHTMLDoc)
  private
    //the table of contents for the help file
    FContentFile: TextFile;
    //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


    //Creates a new HTML file and writes its header.
    procedure CreateFile(var F: TextFile;
                         const FileName, TitlePart, KeyWords: String);
                                                                      override;
    //Writes the footer of a HTML file and closes it.
    procedure EndFile(var F: TextFile); 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(IsSymbol: Boolean): String; override;






    //Gets the links to the generated files by ~[link WriteFileTreeFiles].
    function GetFileListFileLinks: String; override;
    //Writes the list of files.
    procedure WriteFileList(const Text: String); override;

    //Writes the documentation about all identifiers of the given kind in the
    //file and a list of it.
    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;









    //Write the links to the generated files by ~[link WriteClassesTreeFiles].
    function ClassListFileLinks(Kind: TRecordKind): String; override;
    //Writes the hierarchy of the kind of the record-like types.
    procedure WriteClassList(Kind: TRecordKind; const Text: String); override;

    //Writes the documentation of members of a 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;


    //Writes a file of documentation as help for a GUI.
    function GenerateGUIHelpOnData(Data: TOldGUIHelpData): String; 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;



    //Generate the help on a GUI.
    function DoGenerateGUIHelp(LogFiles: TStrings): Boolean; override;
    //Generate 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 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 the 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;
    //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;



{$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,
{$IFNDEF LINUX}
     Registry, ShellAPI, Forms,
{$ENDIF}
{$IFDEF VER120}
     FileCtrl,
{$ENDIF}
     General,
     UFilePaths,
     UDocumentDoc,
     UDocumentationTexts;







    //list for the option "UseSubdirectories" of the generator
    //~[link THTMLHelpDoc]
var OptionItemsUseSubdirectories: TStringList = nil;



   { * * *  ***  * * *  ***   THTMLHelpDoc   ***  * * *  ***  * * *  }




{Creates the generator object and initializes its fields. }
constructor THTMLHelpDoc.Create;
begin
 inherited Create;                             //create the object

 FHelpFileName := DefaultCHMFileName;          //set name of help file
end;



{Returns a description of the documentation of the generator.
~result a description of the documentation of the generator }
class function THTMLHelpDoc.GetDescription: TGeneratorDescription;
begin
 Result.Name := 'HTML Help File (.chm)';
 Result.Identification := 'HTMLHelp_old';
 Result.Description :=
  'A compiled help file (.chm) is generated from a lot of HyperText Markup Language (HTML)-files (*.html), some images (*.gif), a cascading style sheet-file (DelphiDoc.css) and some Xfig- (*.fig) and WMF-files (*.wmf).'#13#10 +
  'CHM files are the new Windows help format. To compile it, you need to have the HMTL Help Workshop installed, you can download the "htmlhelp.exe" at http://go.microsoft.com/fwlink/?LinkId=14188 .';
end;




{Returns the number of available options in generators of this class.
~result the number of available "expert"-options
~see GetOptionDescription
~see GetOption
~see SetOption }
class function THTMLHelpDoc.GetOptionCount: Cardinal;
begin
 Result := inherited GetOptionCount + 4;
end;

{Gets a description of an "expert"-option.
~param Index index of the option to get data of
~param Desc  out: the description of the option (name, type, default value,
                  etc.)
~see GetOptionCount }
class procedure THTMLHelpDoc.GetOptionDescription(Index: Cardinal;
                                                 var Desc: TOptionDescription);
var             PreOptionCount :Cardinal;  //number of options in parent class
begin
 PreOptionCount := inherited GetOptionCount; //get number of options in parent
 if Index < PreOptionCount then              //an option in the parent class?
  inherited GetOptionDescription(Index, Desc)  //forward to parent's method
 else
  begin
   ClearDescription(Desc);               //clear structure
   case Index - PreOptionCount of        //depending on index of option
     0: begin                            //set the values describing the option
         Desc.Name := 'HelpCompilerPath';
         Desc.Category := 'Postprocessing';
         Desc.Description := 'The path and name of the help compiler "hhc.exe".';
         Desc.DataType := otString;
         Desc.DefaultValue.StrData := '';
        end;
     1: begin
         Desc.Name := 'AutoCompileHelpProject';
         Desc.Category := 'Postprocessing';
         Desc.Description := 'Compile the help project after generation.';
         Desc.DataType := otBoolean;
         Desc.DefaultValue.BoolData := False;
        end;
     2: begin