uicbasehtmldoc.pas

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

    //Resets the attributes to ready the generator for a new generation.
    procedure ResetForNewGeneration; override;




    //Returns the format needed to express the scope (as an icon).
    function GetScope(Scope: TScope): String;
    //Returns the format needed to express the portability issues (as icons).
    function GetPortabilityIssues(Issues: TIdentPortabilities): String;
    //Returns the format needed to express an abstract method.
    function GetAbstractIcon: String;
    //Returns the format needed to express a property that can only be read.
    function GetReadOnlyIcon: String;

    //Writes the links to the generated files by ~[link WriteFileTreeFiles].
    procedure WriteFileListFileLinks(F: TBufferStream); virtual; //override;
    //Write the links to the generated files by ~[link WriteClassesTreeFiles].
    procedure WriteClassTreeFileLinks(Kind: TRecordKind; F: TBufferStream);
                                                           virtual; //override;



    //Gets the (internal) identification (for links) of pages in the user
    //documentation.
    function GetPageURI(PageIndex: Integer): String; override;
    //Gets the (internal) identification (for links) of topics of documentation
    //of a GUI.
    function GetGUIHelpURIByIndex(FileIndex, TopicIndex: Integer): String;
                                                                      override;
    //Includes an image in the documentation.
    function WriteImage(CharFormat, JPEGFormat: Boolean; Resolution: TPoint;
                        BMP: TBitmap; const FileName: String;
                        Links: TImageLinkList;
                        const AlternativeText: String): String; override;



    property DontQuoteSpecialCharacters: Boolean
                                              read FDontQuoteSpecialCharacters;
    property CharacterEncoding: String read FCharacterEncoding;
    property UseCSS: Boolean read FUseCSS;
    property XMLConformity: Boolean read FXMLConformity;
    property UseXHTMLHeader: Boolean read FUseXHTMLHeader;
    property FileExtension: String read FFileExtension;
    property TagConstants: TTagConstants read FTagConstants;

    property AddingDiagram: Boolean read FAddingDiagram write FAddingDiagram;
  end;




implementation


uses SysUtils,
     UFilePaths,
     UExtIdents,
     UICDeclarationAssembler,
     UILComment;





   { * * *  ***  * * *  ***   TICHTMLVisitor   ***  * * *  ***  * * *  }


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

 FGenerator := Generator;                 //save the reference

 //by default include links directly in Scalable Vector Graphics images 
 FSVGDiagramsWithLinks := True;
end;


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

{Has to be called after visiting a COM to perform follow-up operations. }
procedure TICHTMLVisitor.EndVisit;
begin
 //currently nothing has to be done
end;








{Returns the URI of the class or file of each box in a diagram.
~param TheClass the class to calculate the URI of, if not nil
~param TheFile  the file to calculate the URI of, if not nil
~result the URI to the documentation of the class or file or '' if none
        available }
function TICHTMLVisitor.GetDiagramLinkTarget(TheClass: TRecordType;
                                             TheFile: TPascalFile): String;
begin
 Result := FGenerator.GetURIOf(TheClass, TheFile);  //just ask the generator
end;

{Draws the created diagram on a bitmap and writes it with the generator.
~param Diagram      the created diagram to save as an image
~param DiagramIndex the number of diagrams generated so far, used to create a
                    unique (file) name for the diagram }
procedure TICHTMLVisitor.DrawDiagram(Diagram: TDiagram; DiagramIndex: Integer);
          //the extension of Scalable Vector Graphics depending on whether they
          //are compressed
const     SVGFileExtension: array[Boolean] of String = ('.svg', '.svgz');
var       FileName      :String;           //the file name of the SVG file
          //the handler to use links directly in
var       LinkHandler   :TGetLinkTargetCallBack;
          LinkList      :TImageLinkList;   //the list of links in the diagram
          ImageSize     :TPoint;           //the size of the image
begin
 if FDiagramsFormat <> dfPNG then          //save as Scalable Vector Graphics
  begin
   FileName := Format('Diagram%d%s',         //calculate file name
                      [DiagramIndex,
                       SVGFileExtension[FDiagramsFormat = dfSVGz]]);
   if FSVGDiagramsWithLinks then             //image should include the links?
    begin
     LinkHandler := GetDiagramLinkTarget;     //set handler to get link targets
     LinkList := nil;
    end
   else
    begin
     LinkHandler := nil;
     //use the previously extracted links to create an external image map
     LinkList := DiagramLinks;
    end;

   //now adding the diagram
   FGenerator.AddingDiagram := True;
   //draw the diagram in the SVG file
   ImageSize := Diagram.DrawWholeDiagramAsSVGFile(FGenerator.DestPath +
                                                  FileName,
                                           DocumentationTexts[dtDiagramHint].T,
                                           svgilkNoLinks, LinkHandler,
                                           FGenerator.CharacterEncoding);
   //and add the image of the diagram to the documentation
   FHTMLFile.WriteString(FGenerator.WriteImage(False, False, ImageSize, nil,
                                               FileName, LinkList,
                                         DocumentationTexts[dtDiagramHint].T));
   //finished adding the diagram
   FGenerator.AddingDiagram := False;
  end
 else
  //just draw the diagram normally (as BMP) and add it to the documentation
  inherited DrawDiagram(Diagram, DiagramIndex);                     //(as PNG)
end;


{Writes the created diagram.
~param DiagramCode the code as returned by ~[link FGenerator].~[link
                   TICBaseHTMLDoc.WriteImage WriteImage]
~param ImageSize   the dimensions of the diagram in pixels }
procedure TICHTMLVisitor.WriteDiagram(const DiagramCode: String;
                                      ImageSize: TPoint);
begin
 FHTMLFile.WriteString(DiagramCode);        //write code to insert the diagram
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 TICHTMLVisitor.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
   FHTMLFile.WriteString('<a href="');     //start the link to it
   if Assigned(Node.Identifier) then       //write the target
    FHTMLFile.WriteString(FGenerator.GetURIOf(Node.Identifier))
   else
    FHTMLFile.WriteString(FGenerator.GetURIOf(nil, Node.TheFile));
   FHTMLFile.WriteString('">');
  end;

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

 if not Ignore then                      //if not ignored
  FHTMLFile.WriteString('</a>');           //end the link
end;



{Ends the current line and starts a new one. }
procedure TICHTMLVisitor.EndLine;
begin
 FHTMLFile.WriteString(FGenerator.TagConstants.br);  //end the current line
end;

{Ends the current paragraph and starts a new one. }
procedure TICHTMLVisitor.EndParagraph;
begin
 FHTMLFile.WriteString(FGenerator.TagConstants.emptyp); //end current paragraph
end;







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








{Writes the text in the HTML file. Any special characters are encoded so the
 text will appear as it is.
~param Text the text to "quote" in the format }
procedure TICHTMLVisitor.WriteEncodedText(const Text: String);
var       p             :PChar;    //runner through the text
          LineBreak     :Boolean;  //whether line breaks should be preserved
          XMLConform    :Boolean;  //whether line breaks should conform to XML
          StartP        :PChar;    //start of normal text (no need to quote)
begin
 if Text <> '' then                //text not empty?
  begin
   //get whether line breaks should be preserved
   LineBreak := FGenerator.KeepRawLineBreaks;
   XMLConform := FGenerator.XMLConformity;
   p := Pointer(Text);
   while p^ <> #0 do                 //for each character in the text
    begin
     case p^ of
       #10: if LineBreak then          //line breaks should be kept?
             if XMLConform then          //treat a new-line as a new-line
              FHTMLFile.WriteString(#10'<br />')
             else
              FHTMLFile.WriteString(#10'<br>')
            else
             FHTMLFile.WriteString(#10);   //just add the character
       '<': FHTMLFile.WriteString('&lt;');
       '>': FHTMLFile.WriteString('&gt;');
       '&': FHTMLFile.WriteString('&amp;');
       '"': FHTMLFile.WriteString('&quot;');
     else
      StartP := p;                     //get start position of normal text
      repeat
        Inc(p);                         //skip all characters that don't need
      until p^ in [#0, #10, '<', '>', '&', '"'];  //to be quoted
      //decrement now, will be incremented again after the case-statement
      Dec(p);
      if StartP = p then               //was only one character?
       FHTMLFile.WriteCharacter(p^)      //write the character
      else                               //or write all characters
       FHTMLFile.WriteBuffer(StartP^, p - StartP + 1);
     end;
     Inc(p);                         //next character
    end; //while p^ <> #0
  end; //if Text <> ''
end;

{Writes the text in the HTML file. Any special characters are encoded so the
 text will appear as it is.~[p]

 <ul>
   <li>This is:</li>
   <li>A test for raw html code!</li>
   <li>a simple enumeration</li>
 </ul>

~param Text the text to "quote" in the format }
procedure TICHTMLVisitor.WriteText(const Text: String);

 {Writes the text unformatted but with line breaks in the HTML file.
 ~param Text the text to write with kept line breaks
 ~param F    the file to write the text to }
 procedure WriteTextWithLineBreaks(const Text: String; F: TBufferStream);
 var       LineBreak       :String;  //the format to start a new line
           p               :PChar;   //runner through the text
           StartP          :PChar;   //start of normal text (no need to quote)
 begin
  Assert(Text <> '');

  if FGenerator.XMLConformity then   //calculate needed line break once
   LineBreak := #10'<br />'
  else
   LineBreak := #10'<br>';

  p := Pointer(Text);
  while p^ <> #0 do                  //for each character in the text
   begin
    if p^ = #10 then                   //end a line?
     begin
      F.WriteString(LineBreak);          //start a new line
      Inc(p);                            //next character
     end
    else
     begin
      StartP := p;                       //get start position of normal text
      repeat
        Inc(p);
      //skip all characters that don't need to be quoted
      until p^ in [#0, #10];

      if p - StartP = 1 then             //was only one character?