ubasepdfdoc.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 UBasePDFDoc;

{Contains the base class ~[link TBasePDFDoc] of the documentation generator
 ~[linkClass UPDFDoc.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, UImages, UCommentDoc, UFormatCommentDoc,
     UPDFWriter;






      //factor from centimeters to points (the PDF internal unit)
const CmToPoint = 28.34;




   { * * *  ***  * * *  ***   TBasePDFDoc   ***  * * *  ***  * * *  }




      {Starts a new format of the text, the following character selects the 
       kind of the format.

       Intermediary code is generated that is then parsed again and then the
       final formatted text is written to the file.~[br]
       String-functions of comments save special characters in the string for
       the formatting. When comment is completly parsed this special formating
       are parsed and the text is printed.
       ~[preformatted
       all WhiteSpaces are ignored besides single spaces
       #1'LFile_UMain.Class_TFormMain.I_FormCreate'#2'Some text with formats'#2
       #1'Ehttp://www.xfig.org/'#2'Some text with formats'#2
       #1'DUnitUse.fig'#2'Some text with formats'#2
       #1'Bsome bold text'#2
       #1'Isome italic text'#2
       #1'Fsome fixed width text'#2
       #1'S''some string'''#2
       #1'N'                      //new line
       #1'P'                      //new paragraph
       #1'A'                      //use alignment as a block (until #1'a')
       #1'a'                      //use left (no) alignment (until #1'A')
       #1' '<Byte>                //insert the number of spaces
       #1#9<Byte>                 //sets indentation to this number of chars
       #1'@'<TSymbol>             //inserts a special symbol
       #1'i'<DWORD(ImgNumber)><Boolean(AsChar)><WORD(LinkCount)><Link>*
         <Link> = <TShortRect(Position)><Boolean(Extern)>LinkTarget + #0
                                  //inserts an image ]
      ~see InternFormatEndCharacter
      ~see InternFormatLink
      ~see InternFormatExternLink
      ~see InternFormatFileLink
      ~see InternFormatBold
      ~see InternFormatItalic
      ~see InternFormatFixed
      ~see InternFormatString
      ~see InternFormatNewLine
      ~see InternFormatParagraph
      ~see InternFormatAlignBlock
      ~see InternFormatAlignLeft
      ~see InternFormatIndent
      ~see InternFormatIndention
      ~see InternFormatSymbol
      ~see InternFormatImage }
      InternFormatCharacter = #1;
      {ends a formatted text or a parameter for the format
      ~see InternFormatCharacter }
      InternFormatEndCharacter = #2;

      {formats the text a link inside the documentation; parameter gives the
       URI to link to; #1'L' + URI + #2 + Text + #2
      ~see InternFormatCharacter }
      InternFormatLink       = 'L';
      {formats the text an external link; parameter gives the URI to link to;
       #1'E' + URI + #2 + Text + #2
      ~see InternFormatCharacter }
      InternFormatExternLink = 'E';
      {formats the text a link to a file; parameter gives the file to link to;
       #1'D' + file + #2 + Text + #2
      ~see InternFormatCharacter }
      InternFormatFileLink   = 'D';
      {formats the text bold; #1'B' + Text + #2
      ~see InternFormatCharacter }
      InternFormatBold       = 'B';
      {formats the text italic; #1'I' + Text + #2
      ~see InternFormatCharacter }
      InternFormatItalic     = 'I';
      {formats the text with a fixed character width; #1'F' + Text + #2
      ~see InternFormatCharacter }
      InternFormatFixed      = 'F';
      {formats the text as a string; #1'S' + Text + #2
      ~see InternFormatCharacter }
      InternFormatString     = 'S';
      {inserts a line break/begins a new line
      ~see InternFormatCharacter }
      InternFormatNewLine    = 'N';
      {inserts a paragraph break/begins a new paragraph/inserts a blank line
      ~see InternFormatCharacter }
      InternFormatParagraph  = 'P';
      {aligns the following text up to the next ~[link InternFormatAlignLeft]
       as a block, i.e. stretches them to fill the whole page horizontally to
       its right margin
      ~see InternFormatCharacter }
      InternFormatAlignBlock  = 'A';
      {aligns the following text up to the next ~[link InternFormatAlignBlock]
       to the left, i.e. no special alignment
      ~see InternFormatCharacter }
      InternFormatAlignLeft  = 'a';
      {inserts the number of spaces given bei the ordinal value of the 
       following character
      ~see InternFormatCharacter }
      InternFormatIndent     = ' ';
      {sets the indentation of the text to the number of characters (spaces)
       given bei the ordinal value of the following character
      ~see InternFormatCharacter }
      InternFormatIndention  = #9;
      {inserts a special symbol given bei the ordinal value of the following
       character interpreted as ~[link TSymbol]
      ~see InternFormatCharacter }
      InternFormatSymbol     = '@';
      {inserts a previously added image; #1'i' + DWORD(ImgNumber) +
       Boolean(AsChar) + WORD(LinkCount) + (for each link:)
       TShortRect(Position) + Boolean(Extern) + LinkTarget + #0
      ~see InternFormatCharacter }
      InternFormatImage     = 'i';


type
      //the different symbols, that can be written in the PDF file
  TSymbol = (
             sPrivate,       //icon indicating a private member
             sProtected,     //icon indicating a protected member
             sPublic,        //icon indicating a public member
             sPublished,     //icon indicating a published member
             sAutomated,     //icon indicating a automated member
             //icon indicating an identifier in the implementation part of a
             //unot or in a file, that is not a unit (i.e. program or library)
             sUnitLocal,
             //icon indicating an identifier in the interface of a unit
             sUnitInterface,
             sReadOnly,      //icon indicating a read-only property
             sAbstract,      //icon indicating an abstract method
             sDeprecated,    //icon indicating a deprecated identifier
             sLibrary,       //icon indicating a library-specific identifier
             sPlatform);     //icon indicating a platform-specific identifier




  {Contains all data about an annotation, the only annotation kind used in the
   generated PDF file are Link/GoTo annotations. All Annotations in the
   current line will be saved in this structures and are written when the line
   is ended. Before they are written, the positions are adjusted for the used
   word spacing in that line. Images are also sometimes drawn at the end of the
   line with the help of this type. }
  TAnnotation = record
    StartWords: Integer;   //number of words before the annotation
    case IsImage: Boolean of       //whether it is an image instead of a link
      False: (AnnType: TLinkType;    //the kind of the link of the annotation
              Rect: TPDFRect;        //the position of the annotation
              //number of words before the end of the annotation
              EndWords: Integer;);
      True:  (XPos: TPDFValue;       //horizontal position of image in the line
              Scale: TPDFValue);     //scale factor of the image
  end;
  //pointer of a structure describing the data of an annotation
  PAnnotation = ^TAnnotation;


  //pointer on an entry (sub tree) of an outline
  POutlineEntry = ^TOutlineEntry;
  {Contains all values of an entry in an outline of the document structure and
   the tabel of contents. }
  TOutlineEntry = record
    Dest: String;          //internal link destination of the entry
    Title: String;         //title of the entry (chapter, section etc.)

    Next: POutlineEntry;   //the next outline entry on the same level

    Count: Integer;        //outline entries below this entry
    First: POutlineEntry;  //sub entries in the outline

    Page: Integer;         //the page of the entry
  end;





  {A procedure to be called for (each section of the) written text.
  ~param Rect position of the text }
  THandleTextRectProc = procedure (Rect: TPDFRect) of object;


  {This is the base class of the documentation generator ~[linkClass
   UPDFDoc.TPDFDoc] to generate documentation about the parsed data in a big
   PDF file. Some general methods to handle text and create the PDF file are
   defined in this class. 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 this
   class. The generation of the documentation is handled in ~[linkClass
   UPDFDoc.TPDFDoc] 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). }
  TBasePDFDoc = class(TFormatCommentDoc)
  private
    {the default font type to use for text in the document;
     for the header and footer another font can be defined with
     ~[link FPageFontType]; default: pftTimes
    ~see FNormalFontSize }
    FDefaultFontType: TPDFFontType;
    {the normal size of text in the document; default: 10 (point)
    ~see FDefaultFontType
    ~see FLineDistanceScale }
    FNormalFontSize: TPDFValue;     //10
    {the vertical distance between two lines of text in the document;
     default: 1 1/6, i.e. there is an extra vertical space of a sixth of a line
     between two lines
    ~see FNormalFontSize }
    FLineDistanceScale: TPDFValue;



    {the font type to use to write the header and footer of the pages
    ~see FPageFontSize
    ~see FPageFontStyle }
    FPageFontType: TPDFFontType;
    {thesize of the text to write the header and footer of the pages
    ~see FPageFontType
    ~see FPageFontStyle }
    FPageFontSize: TPDFValue;
    {the font style to use to write the header and footer of the pages
    ~see FPageFontType
    ~see FPageFontSize }
    FPageFontStyle: TPDFFontStyles;


    //The width of the pages in the documentation in centimeters.
    FPageWidth: Single;
    //The height of the pages in the documentation in centimeters.
    FPageHeight: Single;

    //The left margin of the pages in the documentation in centimeters.
    FLeftMargin: Single;
    //The right margin of the pages in the documentation in centimeters.
    FRightMargin: Single;
    //The margin at the top of pages in the documentation in centimeters.
    FTopMargin: Single;
    //The margin at the bottom of pages in the documentation in centimeters.
    FBottomMargin: Single;


    //the color of links inside the generated file; default: clGreen
    FLinkColor: TColor;
    //the color of links to external URIs (in the WWW); default: clBlue
    FExternLinkColor: TColor;
    //the color of links to additional files; default: clNavy
    FFileLinkColor: TColor;


    //if images that are included in documentation should be displayed
    //interpolated by the PDF viewers
    FInterpolateImages: Boolean;
    //maximum scale factor of images that are included in documentation
    FMaxImageScale: Single;




    //index of current image
    FImageIndex: Integer;
    //absolute unique paths of all images in the PDF file; the objects is the
    //internal index; this is just an optimization to not copy an image twice
    FImagePaths: TStringList;                 //into the PDF file

    //current number of words in the current line
    FWordsInLine: Integer;
    //if the last written character is a space
    FLastInLineIsSpace: Boolean;
    //the biggest used font size in the current line
    FBiggestFontSize: TPDFValue;
    //the current indention
    FIndention: TPDFValue;


    //number of the current section
    FSectionNumber: Integer;
    //number of the current subsection
    FSubSectionNumber: Integer;
    //number of the item section
    FItemSectionNumber: Integer;
    //title of the current chapter/part of the documentation
    FMainSectionName: String;
    //title of the current section
    FSectionName: String;
    //title of the current subsection
    FSubSectionName: String;
    //title of the current item of the documentation
    FItemSectionName: String;


    //the entry for the current section
    FSectionOutlineEntry: POutlineEntry;
    //the entry for the current subsection
    FSubSectionOutlineEntry: POutlineEntry;