uicpdfdoc.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 UICPDFDoc;

{Contains the documentation generator ~[linkClass TICPDFDoc] to generate
 documentation about the parsed data in a big PDF file.~[br]
 PDF means ~[em Portable Document Format]; it is an open format
 copyrighted by ~[linkExtern http://www.adobe.com/ Adobe]. Read more
 ~[linkExtern http://www.adobe.com/products/acrobat/adobepdf.html about this
 format] on their website. PDF files can be viewed on several
 platforms with different viewers. The best known is of course Adobe's
 ~[linkExtern http://www.adobe.com/products/reader/ Acrobat Reader]. The used
 version of PDF is 1.2 (current: 1.6), that is quite old and it can be read
 with Acrobat Reader Version 3 (current: 8) (at least it should).
}

interface

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



const DefaultPDFFileName = 'DelphiDoc'; //default name of the file to generate
      PDFFileExtension = '.pdf';        //extension of PDF files

      //indentation of lists etc., index is whether the indentation should only
      //be small
      IndentationSizes: array[Boolean] of TPDFValue =
                        (0.8 * CmToPoint, 0.5 * CmToPoint);



type



  //the generator of documentation as a PDF file
  TICPDFDoc = class;





   { * * *  ***  * * *  ***   TICPDFVisitor   ***  * * *  ***  * * *  }


  {A visitor of the ~[link UICNodes COM]-hierarchy, it is used by the generator
   ~[linkClass TICPDFDoc] to write the COM into a PDF file. }
  TICPDFVisitor = class(TICBaseGeneratorVisitor)
  private
    //the writer used to write the nodes to the PDF file, only a reference
    FWriter: TPDFWriter;
    //the writer used to write text into the PDF file, only a reference
    FTextWriter: TPDFTextWriter;

    //the generator for which the COM should be written into a PDF file
    FGenerator: TICPDFDoc;


    //the number of ancestry nodes causing the node to be formatted in a
    //pre-formatted way
    FPreformattedDepth: Integer;


    //whether a diagram is currently beeing drawn directly via PDF commands
    FDrawingDiagram: Boolean;
    //the size of the current diagram in pixels
    FCurrentDiagramSize: TPoint;


    //Calculates the scaling factor for a centered image.
    function CenteredImageScale(ImageSize: TPoint): Single;
    //Draws a centered image.
    procedure DrawCenteredImage(const ImageName: String; ImageSize: TPoint;
                                Links: TImageLinkList);


    //Writes a heading for some information in the documentation.
    procedure AddSmallHeading(const Text: String; AfterParagraph: Boolean;
                              NewLineAfter: Boolean = True);
    //Writes a localized heading for some information in the documentation.
    procedure AddSmallLocalizedHeading(Text: TDocumentationTexts;
                                       AfterParagraph: Boolean;
                                       NewLineAfter: Boolean = True);

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


  protected
    //Draws the created diagram on a bitmap and writes it with the generator.
    procedure DrawDiagram(Diagram: TDiagram; DiagramIndex: Integer); override;
    //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: TICPDFDoc);


    //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(EndLine: Boolean);



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




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


    //just used to set the writer of text into the PDF file
    property TextWriter: TPDFTextWriter {read FTextWriter} write FTextWriter;
    //just used to set the writer of the PDF file
    property Writer: TPDFWriter {read FWriter} write FWriter;

    property DrawingDiagram: Boolean read FDrawingDiagram;
    property CurrentDiagramSize: TPoint read FCurrentDiagramSize;
  end;













   { * * *  ***  * * *  ***   TICPDFDoc   ***  * * *  ***  * * *  }


  //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 big PDF file containing the
   documentation about the parsed data.

   It handles only the part of generating the documentation itself. The overall
   PDF file is written by the helper class ~[link TPDFWriter]. The text in turn
   is written in the PDF file by another helper class, ~[link TPDFTextWriter].
   TPDFWriter provides low level PDF functions to do things in the PDF syntax
   and manage the overall structure of the PDF file while TPDFTextWriter is
   mostly responsible for writing text formatted, this means mainly breaking it
   into several lines when it does not fit in a single line and also creating
   links on the text. Additionally it also contains methods to create headings
   for chapters, sections, etc. and building the document outline with them
   which can also be written as the table of contents.

   PDF means ~[em Portable Document Format]; it is an open format
   copyrighted by ~[linkExtern http://www.adobe.com/ Adobe]. Read more
   ~[linkExtern http://www.adobe.com/products/acrobat/adobepdf.html about this
   format] on their website. PDF files can be viewed on several
   platforms with different viewers. The best known is of course Adobe's
   ~[linkExtern http://www.adobe.com/products/reader/ Acrobat Reader]. The
   used version of PDF is 1.2 (current: 1.6), that is quite old and it can be
   read with Acrobat Reader Version 3 (current: 8) (at least it should). }
  TICPDFDoc = class(TICCommentDoc)
  private
    //the object used to write text into the PDF file
    FTextWriter: TPDFTextWriter;
    //the object used to write the nodes of the ~[linkUnit UICNodes COM] in the
    //PDF format
    FVisitor: TICPDFVisitor;

    //the object to write the PDF file, only valid while generating it
    FWriter: TPDFWriter;



    //whether the compression of the PDF file should be disabled