uiclatexdoc.pas

DelphiDoc is a program for automatic generation of documentation on a Delphi-Project. At the momen

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



    //Writes the list of files.
    procedure WriteFileList(Node: TICNode); 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 of a file.
    procedure WriteFileDocumentation(AFile: TPascalFile); override;








    //Writes the hierarchy of the record-like types of the specified kind.
    procedure WriteClassTree(Kind: TRecordKind; Node: TICNode); override;

    //Writes the documentation of the 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;










    //Writes the lists of all exported identifiers.
    function WriteExportsList: Boolean;

    //Writes the list of all long functions.
    function WriteLongFunctionList: Boolean;




    //Writes the splitted up list of identifiers and files into the
    //documentation.
    function WriteListOfIdentifiersAndFiles(const TopicName: String;
                                          DescriptionText,
                                          KeyWordListText: TDocumentationTexts;
                                          Idents, Classes: TIdentifierList;
                                          Files: TIdentifierFileList): Boolean;
                                                                      override;

    //Generates an index about all identifiers and files.
    procedure DoGenerateIndex(List: TIdentifierFileList;
                              const CharIndices: array of TIndexCharIndex);
                                                                      override;

    //Writes the current page of the user documentation.
    procedure CreateUserDocPage; override;








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


    //Starts generating the documentation.
    procedure StartDocumentation;
    //Finishes the documentation.
    procedure EndDocumentation;


    //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;
    //Destroys the visitor and the generator object.
    destructor Destroy; 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;





    //Writes the format needed to express a scope (as an icon).
    procedure WriteScope(Scope: TScope);
    //Writes the format needed to express the portability issues (as icons).
    procedure WritePortabilityIssues(Issues: TIdentPortabilities);

    //Writes the links to the generated files by ~[link WriteFileTreeFiles].
    procedure WriteFileListFileLinks; //override;
    //Write the links to the generated files by ~[link WriteClassesTreeFiles].
    procedure WriteClassTreeFileLinks(Kind: TRecordKind); //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;


    property ApplyCharacterTranslation: Boolean
                                               read FApplyCharacterTranslation;
    property CharTranslation: TCharTranslation read FCharTranslation;
  end;




implementation

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








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



{Creates the visitor and saves the reference on its generator.
~param Generator the generator for which the COM should be written }
constructor TICLaTeXVisitor.Create(Generator: TICLaTeXDoc);
begin
 inherited Create(Generator);         //create the object

 FGenerator := Generator;             //save the reference
end;


{Resets the attributes to ready the visitor for a new generation. }
procedure TICLaTeXVisitor.ResetForNewGeneration;
begin
 inherited ResetForNewGeneration;     //reset inherited state

 FListNesting := 0;                   //reset to initial state
 FPreformattedDepth := 0;
end;


{Has to be called before visiting a COM to prepare the visitor. }
procedure TICLaTeXVisitor.StartVisit;
begin
 //currently nothing has to be done

 Assert(FListNesting = 0);            //just check the initial state is correct
 Assert(FPreformattedDepth = 0);
end;

{Has to be called after visiting a COM to perform follow-up operations. }
procedure TICLaTeXVisitor.EndVisit;
begin
 Assert(FListNesting = 0);            //make sure everything has been closed
 Assert(FPreformattedDepth = 0);
end;


{Called for each manual link to an identifier or file with a not empty text.
~param Node the node of a link to an identifier or file with some text }
procedure TICLaTeXVisitor.LinkIdentifierWithText(Node: TICNLinkIdentifier);
var       Ignore         :Boolean;       //whether the link should be ignored
begin
 //get whether the target of the link is documented
 Ignore := FGenerator.DoNotDocumentIdentifier(Node.Identifier, Node.TheFile);
 if not Ignore then                      //link target documented?
  begin
   FLaTeXFile.WriteString('\ddDocLink{');  //start the link and
   if Assigned(Node.Identifier) then       //write the target
    FLaTeXFile.WriteString(FGenerator.GetURIOf(Node.Identifier))
   else
    FLaTeXFile.WriteString(FGenerator.GetURIOf(nil, Node.TheFile));
   FLaTeXFile.WriteString('}{');
  end;

 Node.VisitChildren(Self);               //write the text

 if not Ignore then                      //link target documented?
  FLaTeXFile.WriteCharacter('}');        //end the link
end;




{Ends the current line and starts a new one. }
procedure TICLaTeXVisitor.EndLine;
begin
 FLaTeXFile.WriteString('\\');                     //end the current line
 FLaTeXFile.WriteString(FGenerator.NewLine);
end;

{Ends the current paragraph and starts a new one. }
procedure TICLaTeXVisitor.EndParagraph;
begin
 FLaTeXFile.WriteString(FGenerator.NewLine);       //end current paragraph
 FLaTeXFile.WriteString(FGenerator.NewLine);
end;





{Writes the localized version of the text.
~param Text the text to be written in its localized version }
procedure TICLaTeXVisitor.Localize(Text: TDocumentationTexts);
begin
 WriteText(DocumentationTexts[Text].T);        //get and write the text
end;



{Writes the text in the LaTeX file. Any special characters are encoded so the
 text will appear as it is.
~param Text the text to "quote" in the format
~todo handle preformatted text, with multiple spaces, ... correct? different? }
procedure TICLaTeXVisitor.WriteText(const Text: String);

 {Handles whitespaces in preformatted text.
 ~param p         pointer to the first white space
 ~param LineStart whether the space is at the beginning of a line
 ~result pointer on the last white space }
 function HandleSpace(p: PChar; LineStart: Boolean): PChar;
 var      Number     :Integer;      //number of consecutive spaces
          Ignore     :Boolean;      //whether the spaces can be ignored
 begin
(*
  Result := p;
  repeat                              //for each space
    FLaTeXFile.WriteString('\ ');       //write it quoted
    Inc(Result);                        //next character
  until Result^ <> ' ';
  Dec(Result);                        //return pointer on last space
*)
(*
  //this code has a problem, at the beginning of a line, a single space has to
  //be quoted, because before it "\\ " is used, so any normal white space after
  //it is ignored (/merged into a single space)

  //either add a new parameter "after new line",
  //      {change "\\ " to "\\{}" (does not work!)} or
  //      {use the code above
  //           (does not work, '\ ' seems to be ignored a beginning of line)}
*)

  Result := p;
  repeat                            //skip all spaces
    Inc(Result);
  until Result^ <> ' ';

  Number := Result - p;             //get number of spaces
  Ignore := Result^ in [#13, #10];  //at the end of the line?

  Dec(Result);                      //move the last space again

  if not Ignore then                //not at end of the line?
   if (Number = 1) and not LineStart then //only a single space and no indent?
    FLaTeXFile.WriteCharacter(' ')         //write the space
   else
    //make a horizontal space equivalent of the size of the number of spaces

    //there seems to be a bug in (La)TeX!!!
    //The doubled width of a character is used as 1em instead of the width
    //of just one character. So I have to use the half number as the width.
    FLaTeXFile.WriteFormatted('\hspace*{%d.%dem}',
                              [Number div 2, 5 * (Number mod 2)])
 end;


var       TextPointer    :PChar;      //the pointer to the text
          p              :PChar;      //runner through the text
          Preformatted   :Boolean;    //whether format should be preserved
          LineBreak      :Boolean;    //whether line breaks should be preserved
//        StartP         :PChar;      //start of normal text (no need to quote)
begin
 if Text <> '' then                   //text not empty?
  begin
   //get whether the format of the text should be preserved
   Preformatted := FPreformattedDepth <> 0;
   //get whether line breaks should be preserved
   LineBreak := Preformatted or FGenerator.KeepRawLineBreaks;

   TextPointer := Pointer(Text);        //get text as stream of characters
   p := TextPointer;
   while p^ <> #0 do                    //for each character in the text
    begin
     case p^ of                           //needs to be quoted?
       #10:                   if LineBreak then
                               //treat new-line as a new-line
                               FLaTeXFile.WriteString(#10'\\ ')
                              else                     //just add the character
                               FLaTeXFile.WriteCharacter(p^);

       ' ':                   if not Preformatted then
                               FLaTeXFile.WriteCharacter(p^) //write the space
                              else
                               //keep the format, use same number of spaces
                               p := HandleSpace(p,
                                                (p <> TextPointer) and
                                                ((p - 1)^ = #10));

// " becomes something