uicwinhelpdoc.pas

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

    //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(ContentNode: TICNode; const Content: String);





{$IFNDEF LINUX}

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


    //Opens a new RTF file.
    function CreateRTFFile(const FileNameExtra: String): TBufferStream;
    //Finishes and closes a RTF file.
    procedure FinishRTFFile(TheFile: TBufferStream);

    //Begins the documentation.
    procedure StartDocumentation;
    //Aborts the documentation in case of an error.
    procedure AbortDocumentation;
    //Ends the documentation.
    procedure EndDocumentation(Content: String = '';
                               ContentNode: TICNode = nil);





    //Lets generators initialize themselves before comments are prepared.
    procedure BeforeCommentPreparation(GenerationKind: TDocGenerationKind);
                                                                      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 initializes its fields.
    constructor Create; override;
    //Destroys the visitor and the generator object.
    destructor Destroy; 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;





    //Defines the position to be shown when help is requested with the context.
    procedure DefineHelpContext(const URI: String; HelpContext: THelpContext);
                                                                      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;




    //Writes the format needed to express the scope (as an icon).
    procedure WriteScope(Scope: TScope);
    //Writes the format needed to express the portability issues (as icons).
    procedure WritePortabilityIssues(Issues: TIdentPortabilities);


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


    //Returns the part of the documentation the identifier is documented in.
    function GetIdentifierPart(Identifier: TIdentifier): TExtraWinHelpFileFor;
    //Writes the part of the file name for a link if it is Needed.
    procedure WriteHLPFileLinkIf(ForPart: TExtraWinHelpFileFor;
                                 Needed: Boolean);
    //Writes the part of the file name for a link if it is Needed.
    procedure WriteMainHLPFileLinkIf(Needed: Boolean);







    property InNamedPart: Boolean read FInNamedPart;
    property CurrentPart: TExtraWinHelpFileFor read FCurrentPart;
    property ExtraWinHelpFilesFor: TExtraWinHelpFilesFor
                                                    read FExtraWinHelpFilesFor;

    //public for the ~[linkClass TICWinHelpVisitor visitor]; ~[inheritDoc]
    property ICCommentDocMessagesID;
    property NewLine;
  end;




implementation

uses SysUtils,
{$IFNDEF LINUX}
     ShellAPI, Registry, Forms,
{$ENDIF}
{$IFDEF VER120}
     FileCtrl,
{$ENDIF}
     UFilePaths,
     UExtIdents,
     UILComment,
     UICDeclarationAssembler;








   { * * *  ***  * * *  ***   TICWinHelpVisitor   ***  * * *  ***  * * *  }



{Creates the visitor and saves the reference on its generator.
~param Generator the generator for which the COM should be written }
constructor TICWinHelpVisitor.Create(Generator: TICWinHelpDoc);
begin
 inherited Create(Generator);         //create the object

 FGenerator := Generator;             //save the reference

 FIndentationIndex := -1;             //no indentation currently
end;


{Resets the attributes to ready the visitor for a new generation. }
procedure TICWinHelpVisitor.ResetForNewGeneration;
begin
 inherited ResetForNewGeneration;     //reset inherited state

 FCurrentIdentation := 0;             //reset to initial state
 FPreformattedDepth := 0;
 FIndentationIndex := -1;
 FLastBreak := lbNew;
 FNeedNewLine := nnlNone;
end;


{Has to be called before visiting a COM to prepare the visitor. }
procedure TICWinHelpVisitor.StartVisit;
begin
 //currently nothing has to be done

 Assert(FCurrentIdentation = 0);      //just check the initial state is correct
 Assert(FPreformattedDepth = 0);
 Assert(FIndentationIndex = -1);
 Assert(FLastBreak = lbNew);
 Assert(FNeedNewLine = nnlNone);
end;

{Has to be called after visiting a COM to perform follow-up operations. }
procedure TICWinHelpVisitor.EndVisit;
begin
 Assert(FCurrentIdentation = 0);      //make sure everything has been closed
 Assert(FPreformattedDepth = 0);
 Assert(FIndentationIndex = -1);

 if FNeedNewLine = nnlParagraph then  //insert needed vertical spacing
  EndParagraph
 else
  if FNeedNewLine = nnlLine then
   EndLine;

 FLastBreak := lbNew;                 //next node will start text anew
end;



{Writes the created diagram.
~param DiagramCode the code as returned by ~[link FGenerator].~[link
                   FGenerator.WriteImage WriteImage]
~param ImageSize   the dimensions of the diagram in pixels }
procedure TICWinHelpVisitor.WriteDiagram(const DiagramCode: String;
                                         ImageSize: TPoint);
begin
 FRTFFile.WriteString(DiagramCode);      //write code to insert the diagram
 FLastBreak := lbParagraph;              //this works like a new paragraph
end;

{Called for each manual link to an identifier or file with a not empty text.
~param Node the node of a link to an identifier or file with some text }
procedure TICWinHelpVisitor.LinkIdentifierWithText(Node: TICNLinkIdentifier);
var       Ignore           :Boolean;     //whether the link should be ignored
          Part             :TExtraWinHelpFileFor; //part the link points to
begin
 //get whether the target of the link is documented
 Ignore := FGenerator.DoNotDocumentIdentifier(Node.Identifier, Node.TheFile);
 if not Ignore then
  begin
   FRTFFile.WriteString('{\uldb ');        //start the link
   FLastBreak := lbText;                   //normal text will be written
  end;

 Node.VisitChildren(Self);                //write the text

 if not Ignore then                      //link target documented?
  begin
   FRTFFile.WriteString('}{\v ');          //end the link to it
   if assigned(Node.Identifier) then       //write the target and
    FRTFFile.WriteString(FGenerator.GetURIOf(Node.Identifier))
   else
    FRTFFile.WriteString(FGenerator.GetURIOf(nil, Node.TheFile));
   FRTFFile.WriteCharacter('>');
   FRTFFile.WriteString(HelpWindowNames[hwMain]);

   if Assigned(Node.Identifier) then       //get part of the target
    Part := FGenerator.GetIdentifierPart(Node.Identifier)
   else
    Part := ewhfFiles;
   FGenerator.WriteHLPFileLinkIf(Part,
                                 (not FGenerator.InNamedPart or
                                  (FGenerator.CurrentPart <> Part)) and
                                 ((Part in FGenerator.ExtraWinHelpFilesFor) or
                                  (FGenerator.InNamedPart and
                                   (FGenerator.CurrentPart in
                                    FGenerator.ExtraWinHelpFilesFor))));
   FRTFFile.WriteCharacter('}');           //end the link

   FLastBreak := lbText;                   //normal text has been written
  end;
end;






{Inserts a break of the line in the text. }
procedure TICWinHelpVisitor.NewLineSimple;
begin
 FRTFFile.WriteString('\line');                  //end the current line
 FRTFFile.WriteString(FGenerator.NewLine);
 FLastBreak := lbLine;                           //line has been ended
end;

{Inserts a break of the paragraph in the text. }
procedure TICWinHelpVisitor.NewParagraphSimple;
begin
 FRTFFile.WriteString('\par');                   //end current paragraph
 FRTFFile.WriteString(FGenerator.NewLine);
 FLastBreak := lbParagraph;                      //paragraph has been ended
end;



{Ends the current line and starts a new one. }
procedure TICWinHelpVisitor.EndLine;
begin
 NewLineSimple;                                  //end the current line
 if FNeedNewLine = nnlLine then                  //new line was needed?
  FNeedNewLine := nnlNone;                         //not anymore
end;

{Ends the current paragraph and starts a new one.
~param NewMarker whether a new marker has to be written (if it is enabled) }
procedure TICWinHelpVisitor.EndParagraph(NewMarker: Boolean = False);
begin
 FRTFFile.WriteString('\par');                  //end the current paragraph
 if not NewMarker and            //marker is enabled but should not be written?
    (FIndentationIndex >= 0) and  FIndentation[FIndentationIndex].Marked then
  FRTFFile.WriteString('\tab');                   //skip the room of the marker
 FRTFFile.WriteString(FGenerator.NewLine);

 //a new paragraph or line was needed?