uwinhelpdoc.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 UWinHelpDoc;

{Contains the documentation generator ~[linkClass TWinHelpDoc] to generate
 documentation about the parsed data in a Windows Help project to compile it
 to a Windows Help file. }

interface

uses Windows, Classes,
{$IFNDEF LINUX}
     Graphics,
{$ELSE}
     QGraphics,
{$ENDIF}
     UPascalConsts,
     UBaseIdents,
     UOptions, UMakeDoc, UComments, UCommentDoc, UImages,
     UOldGUIHelpData, UFormatCommentDoc,
     UWinHelpFiles;


      //the extra part of the names of the different files
const HelpFileNamesExtra = '';



   { * * *  ***  * * *  ***   TWinHelpDoc   ***  * * *  ***  * * *  }


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
                wkSimpleType);   //list of all simple types (no record-likes)





  {This generator of documentation generates a Windows Help project to be
   compiled to a Windows Help file (.hlp).~[br]
   A big RTF (Rich Text Format) file (DelphiDoc.rtf) will be created containing
   the help and all documentation along with a help project file
   (DelphiDoc.hpj) (in the INI-file format) defining how to compile the RTF
   file to a help file with some bitmap (.bmp) files containing some small
   icons to mark identifiers. If documentation as a help on a GUI is generated
   for each screen shot a file with Structured Hyper-Graphics (.shg) containing
   it and all links is created. After the creation of the files the help
   compiler can automatically be invoked to compile the Help project and
   generate the Window Help file and even start it.~[br]
   The compiled Help file can be integrated in the help of Delphi. For that
   the program OpenHelp (oh.exe) in the bin directory of Delphi has to be
   started, the help project of Delphi (delphi4.ohp in the help directory of
   Delphi) be opened and after the activation of the tab "Index" the compiled
   help file can simply be added. After saving the project, help to the
   documented identifiers should be accessible in Delphi simply by F1 exactly
   like for all other identifiers of Delphi.~[br]
   The new windows help format with the file extension .chm uses "Compiled Help
   Files" packed into one big file. The generator
   ~[linkClass UHTMLHelpDoc.THTMLHelpDoc] to generate that format is also
   available, but beware, that even Delphi uses the old format. The new HTML
   Help WorkShop allows also ~[linkExtern
   http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/vsconprjcnvt.asp
   the conversion of old help projects]. }
  TWinHelpDoc = class(TFormatCommentDoc)
  private
    //the RTF file to write the documentation to
    FRTFFile: TextFile;
    //number in the browse index (of the page?)
    //~feature create several browse indices for the different topics?
    FBrowseNumber: Cardinal;

{$IFDEF Debug}
    //number of the page in the file
    FPageNumber: Cardinal;
{$ENDIF}

    //the table of contents for the help file
    FContentFile: TextFile;


    //the name of the Windows Help File to be generated
    FHelpFileName: String;

    //whether the file should not be compressed by the compiler
    FDisableHelpFileCompression: Boolean;
    //whether the project file shouldn't be overwritten
    FDontOverrideProjectFile: Boolean;       //(in case it has been customized)

    //whether the Help project should automatically be compiled
    FAutoCompile: Boolean;
    //the path and name of the help compiler "hcrtf.exe", it will compile the
    //Windows Help file from the RTF and other files
    FHelpCompilerPath: String;



  protected

    //Writes a BMP image in the given color.
    procedure WriteDotBmp(Color: TColor;
                          const FilePrefix: String; Darker: Byte = 0);
    //Writes a BMP image indicating an abstract method.
    procedure WriteAbstractBmp(const FilePrefix: String);
    //Writes a BMP image in the given color indicating a portability issue.
    procedure WritePortabilityBmp(Color: TColor; const FilePrefix: String;
                                  Darker: Byte = 0);


    //Begins a new page in the help file.
    procedure WritePageHeader(const Title, Name, KeyWords: String;
                              DefaultWindow: THelpWindow = hwMain);
    //Ends the header of a page in the help file.
    procedure WritePageHeaderEnd;
    //Ends a page in the help file.
    procedure WritePageFooter(Last: Boolean = False);

    //Begins a small pop-up page in the help file.
    procedure WritePopUpHeader(const Title, Name: String);
    //Ends a small pop-up page in the help file.
    procedure WritePopUpFooter(Last: Boolean = False);






    //Returns the token (formatted) in the format of the documentation.
    function FormatStringToken(const StringToken: String): String; override;






    //Returns the documentation of examples in comments.
    function ParseExampleComment(Comment: TComment;
                                 var HeaderLinks: String): String; override;







    //Returns a string containing a link to the given identifier/file.
    function GetFileNameLink(TheFile: TPascalFile): String; override;
    //Returns a string containing a link to the given identifier/file.
    function GetIdentNameLink(Ident: TIdentifier;
                              WriteFile: Boolean = False): String; override;
    //Returns a string containing a link to the given identifier inside a
    //record-like type.
    function GetRecordFieldNameLink(Ident: TIdentifier;
                                    WriteRecord: Boolean = False): String;
                                                                      override;
    //Returns the format needed to express the scope (as an icon).
    function GetScope(Scope: TScope): String; override;
    //Returns the format needed to express the portability issues (as icons).
    function GetPortabilityIssues(Issues: TIdentPortabilities): 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;



    //Write the documentaton about all identifiers of the given kind in the
    //file and a list of them.
    function WriteVarConstFuncTypesList(AFile: TPascalFile;
                                        const FileTopic: String;
                                        WriteType: TWriteKind): String;
    //Writes a list of record-like types of that kind in the file.
    function WriteRecordTypeList(AFile: TPascalFile; const FileTopic: String;
                                 Kind: TRecordKind): String;
    //Writes a pop-up with links to the lists created by ~[link
    //WriteRecordTypeList].
    function WriteRecordTypePopUp(AFile: TPascalFile;
                                  const FileTopic: String): String;

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








    //Gets the text of an indentation by the given depth.
    function ClassListIndent(Indent: Integer): String; 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;










    //Starts a list of exported identifiers.
    procedure StartExportsLists(var TheFile: TextFile; AFile: TPascalFile;
                                PreFirst: Boolean;
                                var First, Second, Third, Fourth, Fifth,
                                    Sixth: String); override;
    //Ends a list of exported identifiers.
    procedure EndExportsLists(var TheFile: TextFile; AFile: TPascalFile;
                              PostLast: Boolean); override;




    //Starts the list of all long functions.
    procedure StartLongFunctionsLists(var TheFile: TextFile;
                                      var Pre, Middle, Post: String); override;
    //Ends the list of all long functions.
    procedure EndLongFunctionsLists(var TheFile: TextFile); override;


    //Generates an index about all identifiers and files beginning with the
    //character.
    function DoGenerateIndex(List: TIdentifierFileList; EntryIndex: Integer;
                             Index: Char): Integer; override;

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







    //Writes a page with a list of identifiers.
    function WriteListTopics(const TopicName, Description, KeyWords: String;
                             List: TIdentifierFileList): Boolean;



    //Writes the topics of documentation as help for a GUI.
    function GenerateGUIHelpOnData(Data: TOldGUIHelpData): String; override;



    //Creates all needed image files.
    procedure CreateImages;

    //Writes all legends of images used in the help file.
    procedure WriteLegends;
    //Writes error pages to show when an invalid link is used.
    procedure WriteErrorPages;


    //Writes the main index (default) page of the help file.
    procedure WriteIndexTopic(const Content: String);





{$IFNDEF LINUX}

    //Compiles the help project.
    procedure CompileHelpProject;
{$ENDIF}



    //Begins the documentation.
    procedure StartDocumentation;
    //Aborts the documentation.
    procedure AbortDocumentation;
    //Ends the documentation.
    procedure EndDocumentation(Content: String);



    //Reinitializes any strings depending on current localization settings.
    procedure ResetLanguageStrings; override;


    //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;


    //Will be called for all reserved words.
    function ReservedWord(const Word: String): String; override;