uiclatexdoc.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 UICLaTeXDoc;

{Contains the documentation generator ~[linkClass TICLaTeXDoc] 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}
     General,
     UPascalConsts,
     UBaseIdents,
     UOptions, UMakeDoc,
     UICDocumentDoc, UICCommentDoc,
     UICNodes, UICBaseGeneratorVisitor,
     UImages,
     UDocumentationTexts;






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

      //the command to generate the symbol to mark abstract methods
      AbstractIconText = '\ddIconAbstract{} ';
      //the command to generate the symbol to mark read-only properties
      ReadOnlyIconText = '\ddIconReadOnly{} ';



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
  //the generator of documentation as LaTeX source files
  TICLaTeXDoc = class;





   { * * *  ***  * * *  ***   TICLaTeXVisitor   ***  * * *  ***  * * *  }

  {A visitor of the ~[link UICNodes COM]-hierarchy, it is used by the generator
   ~[linkClass TICLaTeXDoc] to write the COM to a file as LaTeX source. }
  TICLaTeXVisitor = class(TICBaseGeneratorVisitor)
  private
    //the LaTeX source file to write the nodes to
    FLaTeXFile: TBufferStream;

    //the generator for which the COM should be written as LaTeX code
    FGenerator: TICLaTeXDoc;

    //LaTeX allows only a nesting level of four for lists;
    //let's just assume that no-one will manually create deeper nested lists,
    //so only the class tree can be nested deeper, so any deeper level will
    //emulated by starting a new line for every item and indenting it
    //~todo implement this behaviour
    FListNesting: Integer;
    //the number of ancestry nodes causing the node to be formatted in a
    //pre-formatted way
    FPreformattedDepth: Integer;



    //Ends the current line and starts a new one.
    procedure EndLine;
    //Ends the current paragraph and starts a new one.
    procedure EndParagraph;


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

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

  protected
    //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: TICLaTeXDoc);


    //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 diagram of classes or files.
    procedure Diagram(Parameters: TStrings); 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 LaTeXFile: TBufferStream {read FLaTeXFile} write FLaTeXFile;
  end;



















   { * * *  ***  * * *  ***   TICLaTeXDoc   ***  * * *  ***  * * *  }


  {This generator of documentation generates 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, especially
   scientific and mathematical ones, etc. but can also be used for instance to
   produce PDF files or sets of HTML 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. }
  TICLaTeXDoc = class(TICCommentDoc)
  private
    //the object used to write the nodes of the ~[linkUnit UICNodes COM] as
    //LaTeX source into the files
    FVisitor: TICLaTeXVisitor;

    //the current LaTeX file to write the documentation to
    FLaTeXFile: TBufferStream;

    //whether 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
    //on paper)
    FUseSimpleTextAsLinks: Boolean;
    //whether the character translation table ~[link FCharTranslation] 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);




    //Writes the node of the ~[linkUnit UICNodes COM] into the file.
    procedure WriteNode(Node: TICNode);





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


    //Writes a link to the given identifier.
    procedure WriteIdentNameLink(Ident: TIdentifier);
    //Writes a link to the given identifier inside a record-like type.
    procedure WriteRecordFieldNameLink(Member: TIdentifier;
                                       LinkToRecord: Boolean);