uicwinhelpdoc.pas

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

   { * * *  ***  * * *  ***   TICWinHelpDoc   ***  * * *  ***  * * *  }



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

  //the possible levels inside the content file of the help file
  TContentLevel = 1..4;



  {This generator of documentation generates a Windows Help project to be
   compiled to a Windows Help file (.hlp).~br
   This version does use the ~[linkUnit UICNodes COM] - Comment Object Model -
   to represent the comments and transform them to the documentation of each
   identifier and file.

   A big RTF (Rich Text Format) file (DelphiDoc.rtf) will be created containing
   the help and all documentation. It can now be split into several files
   with the option "ExtraWinHelpFilesFor" setting the field
   ~[link FExtraWinHelpFilesFor]. For each RTF file a help project file
   (DelphiDoc.hpj) (in the INI-file format) is written, defining how to compile
   the RTF file to a help file. And also some bitmap (.bmp) files containing
   some small icons are available to display attributes of 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.

   The compiled Help file can be integrated in the help of Delphi. For that use
   the menu "Help", then "Customize..." or start the program OpenHelp (oh.exe)
   in the bin directory of Delphi and open the help project of Delphi
   (delphi4.ohp in the help directory of Delphi). 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.

   The new windows help format with the file extension .chm uses "Compiled Help
   Files" packed into one big file. The generator
   ~[linkClass UICHTMLHelpDoc.TICHTMLHelpDoc] to generate that format is also
   available, but beware, that even Delphi uses the old format. The new HTML
   Help WorkShop also allows ~[linkExtern
   http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/vsconprjcnvt.asp
   the conversion of old help projects]. }
  TICWinHelpDoc = class(TICCommentDoc)
  private
    //the object used to write the nodes of the ~[linkUnit UICNodes COM] as RTF
    //into the file
    FVisitor: TICWinHelpVisitor;


    //the base RTF file to write the documentation to
    FBaseRTFFile: TBufferStream;
    //the extra RTF files to write the documentation to
    FExtraRTFFile: TBufferStream;

    //the current RTF file to write the documentation to, either
    //~[link FBaseRTFFile] or ~[link FExtraRTFFile]
    FRTFFile: TBufferStream;

    //the file to write the table of contents for the help file to
    FContentFile: TBufferStream;





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

    //for which parts of the documentation extra files should be generated to
    //split it into several files in case the documentation gets too
    //substantial to be compiled by the Windows Help compiler
    FExtraWinHelpFilesFor: TExtraWinHelpFilesFor;
    //prefix for the extra Windows Help files, if empty use
    //~[link FHelpFileName]
    FExtraWinHelpFilesPrefix: String;


    //whether the file(s) should not be compressed by the compiler
    FDisableHelpFileCompression: Boolean;
    //whether the project file (of the help compiler) 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;


    //whether a file mapping the help contexts to the help files containing the
    //topics they point to should be generated
    FGenerateHelpContextFileMapping: Boolean;








    //whether documentation of a named part is currently being generated,
    //if that is not the case the documentation is part of the main file,
    //the named part is specified by ~[link FCurrentPart]
    FInNamedPart: Boolean;
    //if ~[link FInNamedPart], the current named part
    FCurrentPart: TExtraWinHelpFileFor;


    //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 name of the Windows Help File to be generated
    FUsedHelpFileName: String;


    //a list mapping help contexts to the files containing their documentation
    //the text are the names of the files and the objects are the help contexts
    FHelpContextFileNames: TStringList;



    //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, its prefix-index is saved
    //in the object
    FImageNames: TStringList;



    //Returns the name of the help file a part of the documentation is defined
    //in.
    function GetHLPFileName(ForPart: TExtraWinHelpFileFor): String;

  protected

    //Writes a BMP image in the given color indicating a scope.
    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);




    //Makes sure the heading text for an entry in the content file is valid.
    function CleanContentHeading(const Heading: String): String;
    //Writes a heading into the content file.
    procedure WriteContentHeading(Level: TContentLevel; const Header: String);
    //Writes a mapping to a topic into the content file.
    procedure WriteContentMapping(Level: TContentLevel;
                                  const Header, Topic: String);







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

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





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









    //Writes the examples and returns the links to them.
    function HandleExamples(Examples: TICNCompound): String;





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




    //Writes the list of files.
    procedure WriteFileList(Node: TICNode); 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 the list of record-like types of that kind defined 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;






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


    //Generates the help on one data set of a GUI.
    procedure GenerateGUIHelpOnData(Data: TICGUIHelpData;
                                    AddContentTo: TICNCompound); override;