ulatexdoc.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 ULaTeXDoc;

{Contains the documentation generator ~[linkClass TLaTeXDoc] to generate
 documentation about the parsed data in LaTeX source files. These can be used
 to build the documentation in many different output formats. }

interface

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





   { * * *  ***  * * *  ***   TLaTeXDoc   ***  * * *  ***  * * *  }



      //main file of the documentation
const MainFileName = 'DelphiDoc.tex';
      //project specific defines
      ProjectDefinesFileName = 'ProjectDefines.tex';
      //name of the file of the documentation of files and their identifiers
      FileFileName = 'Files.tex';
      //postfix of files of the documentation of record-like types and
      RecordLikePostFixFileName = 'File.tex';                  //their members
      //name of the file containing the index of all identifiers and files
      IndicesFileName = 'Indices.tex';
      //name of the file containing the user documentation
      UserDocFileName = 'UserDoc.tex';
      //name of the file including the file of the user documentation
      UserDocIndexFileName = 'UserDocIndex.tex';


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)


                
  //translation sequences for characters
  TCharTranslation = array[#127..#255] of String;


  //different types of sections in the LaTeX source files
  TSectionType = ord(low(TRecordKind))..ord(High(TRecordKind)) + 2;

const
  //the section type for the documentation of files
  SectionTypeFile = ord(High(TRecordKind)) + 1;
  //the section type for not specific documentation
  SectionTypeOther = ord(High(TRecordKind)) + 2;



type

  {This generator of documentation generates a several LaTeX source files
   containing the documentation about the parsed data. These can be used to
   build the documentation in many different output formats.

   TeX, the Greek letters Tau, epsilon and Chi, is a typesetting system. TeX
   documents are interpreted, not just parsed, it is a language on its own,
   comparable with macro languages. It was developed by one of the gurus of
   computer programming,
   ~[linkExtern http://www-cs-faculty.stanford.edu/~~knuth/ Donald E. Knuth],
   especially also for mathematical and scientific articles. As a free and
   portable system (and software) it is used for printing books etc. but can
   also be used for instance to produce PDF files. While TeX provides an
   interpreter, several (macro) packages expanding the capabilites to a more
   comfortable level are available. The most spread package is LaTeX by
   Leslie Lamport. This package is also used for the generated
   documentation.
   
   Just execute latex with the generated main file ~[em DelphiDoc.tex].
   Several macros/commands are defined in it which may be needed to be
   customized. }
  TLaTeXDoc = class(TFormatCommentDoc)
  private
    //the current LaTeX file to write the documentation to
    FLaTeXFile: TextFile;

    //if the main file ~[em DelphiDoc.tex] shouldn't be overridden, if it
    //already exists (in case it has been customized)
    FDontOverrideMainFile: Boolean;
    //generate text describing the position to link to instead of links;
    //useful if printing the documentation (you can't obviously press links
    FUseSimpleTextAsLinks: Boolean;           //on paper)
    //whether the character translation ~[link FCharTranslation] table should
    //be used to translate special characters
    FApplyCharacterTranslation: Boolean;
    //the character translation table; any character in the documentation in
    //this table (#127..#255) will be replaced by the value in it;
    //useful to generate special characters by LaTeX command sequences
    FCharTranslation: TCharTranslation;
  protected

    //Starts a new main section (\part) and prints its heading.
    procedure WriteNewMainSection(const Title, LabelName: String);
    //Starts a new section (\section) and prints its heading.
    procedure WriteNewSection(const Title, LabelName: String;
                              SectionType: TSectionType);
    //Starts a new sub section (\subsection) and prints its heading.
    procedure WriteNewSubSection(const Title, LabelName: String);
    //Starts a new item section (\subsubsection) and prints its heading.
    procedure WriteNewItemSection(const Title, LabelName: String);






    //Returns the string token with an applied format macro.
    function FormatStringToken(const StringToken: String): String; override;














    //Returns the format needed to express the scope (as an icon).
    function GetScope(Scope: TScope): String; override;
    //Returns the format needed to express the portability issues (as icons).
    function GetPortabilityIssues(Issues: TIdentPortabilities): String;
                                                                      override;












    //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.
    procedure StartLongFunctionsLists(var TheFile: TextFile;
                                      var Pre, Middle, Post: String); override;
    //Ends the list of all long functions.
    procedure EndLongFunctionsLists(var TheFile: TextFile); override;


    //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 legend of the special symbols/icons used in the documentation.
    procedure WriteLegend;





    //Writes the project specific data in a file.
    procedure WriteLaTeXProjectDefinesFiles;


    //Writes the beginning of the main file of the LaTeX project.
    procedure WriteLaTeXMainFileBeginning(var MainFile: TextFile);
    //Writes the title page in the main file of the LaTeX project.
    procedure WriteLaTeXMainFileTitlePage(var MainFile: TextFile);
    //Writes the begin of the actual document in the main file of the LaTeX
    //project.
    procedure WriteLaTeXMainFileDocumentStart(var MainFile: TextFile);
    //Writes the inclusion of a file in the main file of the LaTeX project.
    procedure WriteLaTeXMainFileIncludeFile(var MainFile: TextFile;
                                            const FileName: String);
    //Writes the end of the main file of the LaTeX project.
    procedure WriteLaTeXMainFileEnd(var MainFile: TextFile);

    //Writes the main file of the LaTeX project.
    procedure WriteLaTeXMainFile;


    //Reinitializes any strings depending on current localization settings.
    procedure ResetLanguageStrings; 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;


    //Will be called for all reserved words.
    function ReservedWord(const Word: String): String; override;
    //Will be called for all texts of identifiers.
    function IdentifierText(const Text: String): String; 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;






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

    //Returns the text in the format; text may already include other formats.
    function FormatText(TextFormat: TDocumentationTextFormat;
                        const Text: String;
                        var SkipWhitespaces: Boolean): String; override;

    //Writes a link to an identifier or file in the documentation.
    function InternalLink(const URI, LinkLabel: String): String; override;
    //Writes a link to an external URI.
    function ExternalLink(const URI, LinkLabel: String): String; override;

    //Includes an (no) image in the documentation.
    function WriteImage(CharFormat, JPEGFormat: Boolean; Resolution: TPoint;
                        BMP: TBitmap; const FileName: String;
                        Links: TImageLinkList;
                        const AlternativeText: String): String; override;


  end;




implementation

uses SysUtils,
//{$IFNDEF LINUX}
//     ShellAPI,        //ShellExecute (can execute ((PDF)La)TeX-compiler?)
//{$ENDIF}
     UExtIdents,
     UDocumentDoc,
     UDocumentationTexts;





   { * * *  ***  * * *  ***   TLaTeXDoc   ***  * * *  ***  * * *  }



{Creates the generator object and initializes its fields. }
constructor TLaTeXDoc.Create;
            //counter through the character translation table
var         c               :Char;
begin
 inherited Create;                     //create the object

 FApplyCharacterTranslation := True;   //by default translate characters

 //initialize the character translation table
 for c := Low(FCharTranslation) to High(FCharTranslation) do
  FCharTranslation[c] := Format('\symbol{%d}', [Ord(c)]);

// FCharTranslation['