uicwinhelpdoc.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 UICWinHelpDoc;     

{Contains the documentation generator ~[linkClass TICWinHelpDoc] to generate
 documentation about the parsed data in a Windows Help project to compile it
 to a Windows Help file. 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. The class
 ~[linkClass TICWinHelpVisitor] is used internally by the generator to write
 the generated COM to the source file of the help file. This is done in RTF,
 the Rich Text Format. }

interface

uses Windows, Classes,
{$IFNDEF LINUX}
     Graphics,
{$ELSE}
     QGraphics,
{$ENDIF}
     General,
     UPascalConsts,
     UBaseIdents,
     UOptions, UMakeDoc,
     UICDocumentDoc, UICCommentDoc,
     UICNodes, UICBaseGeneratorVisitor,
     UImages, UICGUIHelpData,
     UWinHelpFiles,
     UDocumentationTexts;




      //Don't remove the plus sign "+" from the following two constants!
      //Or when compiling as Windows Help File the compiler will warn about
      //a missing file (probably interpreting it as "abstract.bmp\" as a path
      //without a file)!

      //the text/format to add an icon for abstract classes in help file
const AbstractIconText = '\{' + 'bmct abstract.bmp\}';
      //the text/format to add an icon for read-only properties in help file
      ReadOnlyIconText = '\{' + 'bmct readonly.bmp\}';

      //depth of indentation, the index is whether the indentation is "small";
      //720 twips seem to be an inch = 2.54 cm
      IndentationTwips: array[Boolean] of Integer = (360, 180);

      //format for images to be prefixed with to create unique file names
      ImageSavePrefix = 'Img%d_';


type
  //the type to select what parts of the documentation should be in extra files
  //in order to split the documentation in case it gets too substantial to be
  //compiled by the Windows Help compiler
  TExtraWinHelpFileFor = (
                          //documentation of files and simple identifiers
                          //inside them should be in an extra file
                          ewhfFiles,
                          //documentation of records should be in an extra file
                          ewhfRecord,
                          //documentation of classes of the object-modell
                          //should be in an extra file
                          ewhfObject,
                          //documentation of classes should be in an extra file
                          ewhfClass,
                          //documentation of interfaces should be in an extra
                          //file
                          ewhfInterface,
                          //documentation of dispatch interfaces should be in
                          //an extra file
                          ewhfDispInterface,
                          //additional user documentation should be in an extra
                          //file
                          ewhfUserDoc);

  //the type of the option to select which parts are in separate files
  TExtraWinHelpFilesFor = set of TExtraWinHelpFileFor;


      //special post-(middle-)fix for the extra files with documentation
const ExtraWinHelpFileNames: array[TExtraWinHelpFileFor] of String =
      ('Files',
       'Records', 'Objects', 'Classes', 'Interfaces', 'DispInterfaces',
       'UserDoc');


      //headers for the extra files with documentation
const ExtraWinHelpFileTopics: array[TExtraWinHelpFileFor]
                              of TDocumentationTexts =
      (dtDocumentationLinkFiles,
       dtRecordsHeader, dtObjectsHeader, dtClassesHeader,
       dtInterfacesHeader, dtDispInterfacesHeader,
       dtDocumentationUserDocumentationHeader);





type
  //the generator of documentation as a Windows Help file
  TICWinHelpDoc = class;



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


  {Used to save the information about a level of indentation. It is used in a
   stack of the levels. }
  TIndentationInformation = record
    Small: Boolean;       //whether it is only a small indentation
    Marked: Boolean;      //whether the indentation has a marker
    SumIndent: Integer;   //the summed up width of all (nested) indentations
  end;

  {A visitor of the ~[link UICNodes COM]-hierarchy, it is used by the generator
   ~[linkClass TICWinHelpDoc] to write the COM to a file in the
   RichText-Format. }
  TICWinHelpVisitor = class(TICBaseGeneratorVisitor)
  private
    //the RTF file to write the nodes to
    FRTFFile: TBufferStream;

    //the generator for which the COM should be written as RTF
    FGenerator: TICWinHelpDoc;
    //the current level of indentation, same as Max(~[link FIndentation])
    FCurrentIdentation: Integer;
    //all nested indentation levels, used as a stack, the current values can be
    //accessed with the index in ~[link FIndentationIndex]
    FIndentation: array of TIndentationInformation;
    //the current index in the stack of nested indentation levels in
    //~[link FIndentation], -1 if no indentation active
    FIndentationIndex: Integer;
    //the number of ancestry nodes causing the node to be formatted in a
    //pre-formatted way
    FPreformattedDepth: Integer;

    //the kind of the most recently inserted break of the text
    FLastBreak: (
                 //visiting the COM has just been started, no text available
                 lbNew,                                             //so far
                 //some text has just been added (no breaks)
                 lbText,
                 //a new line has just been started
                 lbLine,
                 //a new paragraph has just been started
                 lbParagraph);
    //what kind of break of the text is needed
    FNeedNewLine: (
                   nnlNone,        //no break at all is needed
                   nnlLine,        //a new line has to be started
                   nnlParagraph);  //a new paragraph has to be started




    //Inserts a break of the line in the text.
    procedure NewLineSimple;
    //Inserts a break of the paragraph in the text.
    procedure NewParagraphSimple;

    //Ends the current line and starts a new one.
    procedure EndLine;
    //Ends the current paragraph and starts a new one.
    procedure EndParagraph(NewMarker: Boolean = False);


    //Starts a new level of indentation.
    procedure AddIndentation(Small: Boolean = False;
                             MarkFirstLine: Boolean = False);
    //Ends the most recent level of indentation.
    procedure EndIndentation(Small: Boolean = False;
                             MarkFirstLine: Boolean = False);

    //Writes the localized version of the text.
    procedure Localize(Text: TDocumentationTexts);

    //Writes some text in the RTF file.
    procedure WriteText(const Text: String);


  protected
    //Writes the created diagram.
    procedure WriteDiagram(const DiagramCode: String;
                           ImageSize: TPoint); override;
    //Called for each manual link to an identifier or file with a not empty
    //text.
    procedure LinkIdentifierWithText(Node: TICNLinkIdentifier); override;

  public
    //Creates the visitor and saves the reference on its generator.
    constructor Create(Generator: TICWinHelpDoc);


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

    //Has to be called before visiting a COM to prepare the visitor.
    procedure StartVisit;
    //Has to be called after visiting a COM to perform follow-up operations.
    procedure EndVisit;


    //Called for all text nodes in the ~[link UICNodes COM].
    procedure Text(const Text: String); override;
    //Called for all raw text nodes/raw data in the ~[link UICNodes COM].
    procedure RawText(const Text: String); override;
    //Called for all nodes of all kinds of breaks in the ~[link UICNodes COM].
    procedure Break(BreakStyle: TICBreakStyle); override;

    //Called for nodes in the ~[link UICNodes COM] that change the style of the
    //text for their contained nodes.
    procedure TextStyle(Node: TICNTextStyle; var VisitChildren: Boolean);
                                                                      override;
    //Called for nodes in the ~[link UICNodes COM] that change the font of the
    //text for their contained nodes.
    procedure FontStyle(Node: TICNFontStyle; var VisitChildren: Boolean);
                                                                      override;
    //Called for nodes in the ~[link UICNodes COM] that let their contained
    //nodes keep their format.
    procedure Preformatted(Node: TICNPreformatted; var VisitChildren: Boolean);
                                                                      override;

    //Called for each link to an identifier or file.
    procedure LinkTo(Identifier: TIdentifier; TheFile: TPascalFile); override;
    //Called for each link to a file by one of its aliases (used in the uses
    //clauses).
    procedure LinkFileByAlias(TheFile: TPascalFile;
                              const Alias: String); override;


    //Called for each link whose target could not be found.
    procedure InvalidLink(Node: TICNInvalidLink; var VisitChildren: Boolean);
                                                                      override;
    //Called for each link to a target outside of the generated documentation.
    procedure LinkExtern(Node: TICNLinkExtern; var VisitChildren: Boolean);
                                                                      override;
    //Called for each link to a page of the additional user documentation.
    procedure LinkPage(Node: TICNLinkPage; var VisitChildren: Boolean);
                                                                      override;
    //Called for each link to a help topic in the documentation as a help on a
    //GUI.
    procedure LinkGUI(Node: TICNLinkGUI; var VisitChildren: Boolean); override;

    //Called for each node representing an image.
    procedure Image(Data: TICNImage); override;

    //Called for each node representing a short token of pascal code.
    procedure PascalCode(const Code: String; Kind: TICPascalCode); override;






    //Called for each node representing a list. Each child node is an item in
    //the list.
    procedure List(Node: TICNList; var VisitChildren: Boolean); override;

    //Called for each node representing a dictionary.
    procedure Dictionary(Node: TICNDictionary; var VisitChildren: Boolean);
                                                                      override;

    //Called for each node representing a topic in the documentation of
    //identifiers or files as derived from its comment.
    procedure TopicComment(Node: TICNTopicForComment;
                           var VisitChildren: Boolean); override;
    //Called for each node representing a topic of the additional attributes in
    //the documentation of identifiers or files as derived from its comment.
    procedure TopicCommentAdditional(Node: TICNTopicForCommentAdditional;
                                     var VisitChildren: Boolean); override;

    //Called for each node containing the declaration of an identifier.
    procedure IdentifierDeclaration(Node: TICNIdentifierDeclaration;
                                    var VisitChildren: Boolean); override;
    //Called for each node representing a topic in the documentation of
    //identifiers.
    procedure TopicCommentIdentifier(Node: TICNTopicForIdentifier;
                                     var VisitChildren: Boolean); override;

    //Called for each node representing a topic in the documentation of files.
    procedure TopicCommentFile(Node: TICNTopicForFile;
                               var VisitChildren: Boolean); override;
    //Called for each node representing a topic in the documentation of classes
    //(record-like types).
    procedure TopicCommentClass(Node: TICNTopicForClass;
                                var VisitChildren: Boolean); override;

    //Called for each node representing the list of parameters of a function or
    //function type as a dictionary.
    procedure ParameterList(Node: TICNParameterlist;
                            var VisitChildren: Boolean); override;
    //Called for each node representing the list of exceptions raised by a
    //function or functions of a function type as a dictionary.
    procedure ExceptionList(Node: TICNExceptionlist;
                            var VisitChildren: Boolean); override;

    //Called for each node representing a token in the list of ancestors of a
    //class or interface.
    procedure AncestorListToken(Token: TICAncestorListToken); override;
    //Called for each node representing a token in the hierarchy of classes
    //(record-like types).
    procedure ClassListToken(Token: TICClassListToken; Kind: TRecordKind);
                                                                      override;

    //Only used to set the reference of the file to write to.
    property RTFFile: TBufferStream {read FRTFFile} write FRTFFile;
  end;