updfdoc.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 UPDFDoc;

{Contains the documentation generator ~[linkClass TPDFDoc] 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/acrobat/readermain.html Acrobat
 Reader]. The used version of PDF is 1.2 (current: 1.5), that is quite
 old and it can be read with Acrobat Reader Version 1.3 (current: 1.6)
 (at least it should). }


interface

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




   { * * *  ***  * * *  ***   TPDFDoc   ***  * * *  ***  * * *  }





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


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)


  //level of detail in the table of contents, i.e. sub-topics on what level
  //will be listed in it
  TTableOfContentsDetailLevel = 1..4;



  {This generator of documentation generates a big PDF file containing the
   documentation about the parsed data.

   General methods to handle text and create the PDF file are defined in its
   base class ~[link TBasePDFDoc]. The text is assembled in an intermediary
   code and then the resulting code is parsed again and written to the PDF
   file. Because this needs some bigger methods the PDF generator was splitted
   up in two parts. The general handling of this intermediary code is handled
   in the base class. The generation of the documentation is handled here and
   the general creation of PDF files and writing of the PDF format is done by
   the used class ~[linkClass TPDFWriter].
   
   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/acrobat/readermain.html Acrobat
   Reader]. The used version of PDF is 1.2 (current: 1.5), that is quite
   old and it can be read with Acrobat Reader Version 1.3 (current: 1.6)
   (at least it should). }
  TPDFDoc = class(TBasePDFDoc)
  private
    //if the compression of the PDF file should be disabled
    FDisablePDFCompression: Boolean;       //(raises the size by about 66%)

    //the name of the Windows Help File to be generated
    FPDFFileName: String;
    //to which level the sup-topics should be in the table of contents
    FTableOfContentsDetailLevel: TTableOfContentsDetailLevel;

    //the entry of the table of contents in the outline
    FTableOfContentsOutlineEntry: POutlineEntry;

  protected




    //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 documentation about all identifiers of the given kind in the
    //file.
    procedure WriteVarConstFuncTypes(AFile: TPascalFile;
                                     const FileTopic: String;
                                     WriteType: TWriteKind);
    //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.
    procedure WriteMembers(Kind: TMemberKind; Ident: TRecordType);

    //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;
    //Writes the lists of all exported identifiers.
    function WriteExportsList: Boolean;




    //Starts the list of all long functions. Does nothing.
    procedure StartLongFunctionsLists(var TheFile: TextFile;
                                      var Pre, Middle, Post: String); override;
    //Ends the list of all long functions. Does nothing.
    procedure EndLongFunctionsLists(var TheFile: TextFile); override;
    //Write a list of all long functions.
    function WriteLongFunctionList: Boolean; //reintroduce;


    //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 list of identifiers.
    procedure WriteListSection(const Description, TopicName: String;
                               List: TIdentifierFileList);


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



    //Writes the legend of the special symbols/icons used in the documentation.
    procedure WriteLegend;

    //Writes the title page of the document.
    procedure WriteTitlePage;

    //Writes the table of contents.
    procedure WriteTableOfContents;





    //Begins the documentation.
    procedure StartDocumentation;
    //Writes the end of the documentation.
    procedure EndOfDocumentation;
    //Ends the documentation.
    procedure EndDocumentation;
    //Postprocesses the generated documentation.
    procedure PostProcess;



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


    //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 the generators.
    class function Capabilities: TGeneratorCapabilities; override;
  end;



implementation

uses SysUtils,
{$IFNDEF LINUX}
     ShellAPI,
{$ENDIF}
     General,
     UExtIdents,
     UDocumentDoc,
     UDocumentationTexts;








     


   { * * *  ***  * * *  ***   TPDFDoc   ***  * * *  ***  * * *  }



{Creates the generator object and initializes its fields. }
constructor TPDFDoc.Create;
begin
 inherited Create;                   //create the object

 FPDFFileName := DefaultPDFFileName; //use the default name
 //all topics are in the table of contents by default
 FTableOfContentsDetailLevel := High(FTableOfContentsDetailLevel);
end;






{Returns a description of the documentation of the generator.
~result a description of the documentation of the generator }
class function TPDFDoc.GetDescription: TGeneratorDescription;
begin
 Result.Name := 'Portable Document Format (.pdf)';
 Result.Identification := 'PDF_old';
 Result.Description :=
  'A PDF file (Portable Document Format) is generated that can be viewed on a lot of platforms, for example for free with Adobe''s Acrobat (Reader) or with other tools.'#13#10 +
  'The Portable Document Format is copyrighted by Adobe.';
end;



{Returns the number of available options in generators of this class.
~result the number of available "expert"-options
~see GetOptionDescription
~see GetOption
~see SetOption }
class function TPDFDoc.GetOptionCount: Cardinal;
begin
 Result := inherited GetOptionCount + 3;
end;

{Gets a description of an "expert"-option.
~param Index index of the option to get data of
~param Desc  out: the description of the option (name, type, default value,
                  etc.)
~see GetOptionCount }
class procedure TPDFDoc.GetOptionDescription(Index: Cardinal;
                                             var Desc: TOptionDescription);
var             PreOptionCount  :Cardinal; //number of options in parent class
begin
 PreOptionCount := inherited GetOptionCount; //get number of options in parent
 if Index < PreOptionCount then              //an option in the parent class?
  inherited GetOptionDescription(Index, Desc)  //forward to parent's method
 else
  begin
   ClearDescription(Desc);               //clear structure
   case Index - PreOptionCount of        //depending on index of option
     0: begin                            //set the values describing the option
         Desc.Name := 'DisablePDFCompression';