uicbasehtmldoc.pas

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

       F.WriteCharacter(p^)                //write the character
      else
       F.WriteBuffer(StartP^, p - StartP); //or write all characters
     end;
   end; //while p^ <> #0
 end;

begin
 if Text <> '' then
  if not FGenerator.DontQuoteSpecialCharacters then //normal encoding needed?
   WriteEncodedText(Text)                           //encode special characters
  else
   //line breaks should nevertheless be preserved?
   if FGenerator.KeepRawLineBreaks then
    WriteTextWithLineBreaks(Text, FHTMLFile) //write with formatted line breaks
   else
    FHTMLFile.WriteString(Text);             //just write the text unencoded
end;


{Writes the dictionary.
~param Node     the dictionary node containing the terms and their descriptions
~param CSSClass the CSS class to be used for the terms and descriptions
~todo implement more options (via CSS?!) }
procedure TICHTMLVisitor.HandleDictionary(Node: TICNCompound;
                                          const CSSClass: String = '');
var       dt            :String;             //tag for starting the term
          dd            :String;             //tag for starting the definition
          i             :Integer;            //counter through all items
begin
 if CSSClass = '' then                       //no CSS class specified?
  begin
   dt := '<dt>';                               //use normal tags
   dd := '<dd>';
  end
 else
  begin
   dt := '<dt class="' + CSSClass + '">';      //define the class in the tags
   dd := '<dd class="' + CSSClass + '">';
  end;
       
 if Node.HasChildren then                    //dictionary is not empty?
  begin
   Assert(not Odd(Node.ChildCount));

   FHTMLFile.WriteString('<dl');               //begin the dictionary
   if CSSClass <> '' then                      //if CSS class specified
    begin
     FHTMLFile.WriteString(' class="');          //specify it for dictionary
     FHTMLFile.WriteString(CSSClass);
     FHTMLFile.WriteCharacter('"');
    end;
   FHTMLFile.WriteCharacter('>');
   FHTMLFile.WriteString(FGenerator.NewLine);

   for i := 0 to Node.ChildCount div 2 - 1 do  //visit each item as a pair
    begin
     FHTMLFile.WriteString(dt);                  //begin the term
     Node.Children[i * 2].Visit(Self);           //show term to be described
     FHTMLFile.WriteString('</dt>');             //end the term
     FHTMLFile.WriteString(FGenerator.NewLine);

     FHTMLFile.WriteString(dd);                  //begin the description
     Node.Children[i * 2 + 1].Visit(Self);       //show description of the term
     FHTMLFile.WriteString('</dd>');             //end the description
     FHTMLFile.WriteString(FGenerator.NewLine);
    end; //for i := 0 to Node.ChildCount div 2 - 1

   FHTMLFile.WriteString('</dl>');             //end the dictionary
   FHTMLFile.WriteString(FGenerator.NewLine);
  end; //if Node.HasChildren
end;








{Called for all text nodes in the ~[link UICNodes COM].
~param Text the text of the node }
procedure TICHTMLVisitor.Text(const Text: String);
begin
 WriteText(Text);                    //just write the text
end;

{Called for all raw text nodes/raw data in the ~[link UICNodes COM].
~param Text the raw data to be inserted unchanged in the documentation }
procedure TICHTMLVisitor.RawText(const Text: String);
begin
 FHTMLFile.WriteString(Text);        //just write it
end;

{Called for all nodes of all kinds of breaks in the ~[link UICNodes COM].
 This means line breaks or paragraph breaks.
~param BreakStyle the kind of the break }
procedure TICHTMLVisitor.Break(BreakStyle: TICBreakStyle);
begin
 case BreakStyle of                   //depending on the kind
   icbsLineBreak:      EndLine;         //end the line
   icbsParagraphBreak: EndParagraph;    //or the paragraph
 else
  Assert(False);
 end;
end;


{Called for nodes in the ~[link UICNodes COM] that change the style of the text
 for their contained nodes.
~param Node          the node representing a different text style
~param VisitChildren out: whether the children of the node should also be
                     visited; default is True }
procedure TICHTMLVisitor.TextStyle(Node: TICNTextStyle;
                                   var VisitChildren: Boolean);
begin
 case Node.TextStyle of                     //start the formatting of the text
   ictsEmphasize: FHTMLFile.WriteString('<em>');
   ictsStrong:    FHTMLFile.WriteString('<strong>');
 else
  Assert(False);
 end;
 VisitChildren := False;                    //will be visited manually
 Node.VisitChildren(Self);                  //visit the text

 case Node.TextStyle of                     //end the formatting
   ictsEmphasize: FHTMLFile.WriteString('</em>');
   ictsStrong:    FHTMLFile.WriteString('</strong>');
 else
  Assert(False);
 end;
end;


{Called for nodes in the ~[link UICNodes COM] that change the font of the text
 for their contained nodes.
~param Node          the node representing a different font
~param VisitChildren out: whether the children of the node should also be
                     visited; default is True }
procedure TICHTMLVisitor.FontStyle(Node: TICNFontStyle;
                                   var VisitChildren: Boolean);
begin
 case Node.FontStyle of                     //start formatting as code
   icfsCode: FHTMLFile.WriteString('<code>');
 else
  Assert(False);
 end;
 VisitChildren := False;                    //will be visited manually
 Node.VisitChildren(Self);                  //visit the text
 FHTMLFile.WriteString('</code>');          //end the format
end;


{Called for nodes in the ~[link UICNodes COM] that let their contained nodes
 keep their format. This means a fixed-width font should be used and line
 breaks should be preserved.
~param Node          the node causing its children to keep their format
~param VisitChildren out: whether the children of the node should also be
                     visited; default is True }
procedure TICHTMLVisitor.Preformatted(Node: TICNPreformatted;
                                      var VisitChildren: Boolean);

 {Separates the formatted text from the other text. }
 procedure Separate;
 begin
  case Node.PreformattedKind of          //depending on the format
    icpkSimple: EndLine;                   //just start a new line
    icpkSample: EndParagraph;              //or a whole new paragraph
  else
   Assert(False);
  end;
 end;

begin
 Separate;                               //add a vertical space

 FHTMLFile.WriteString('<pre>');         //use a fixed-width/mono-spaced font

 VisitChildren := False;                 //will be visited manually
 Node.VisitChildren(Self);               //visit the text

 FHTMLFile.WriteString('</pre>');        //use normal font and simple spaces

 Separate;                               //add a vertical space
end;



{Called for each link to an identifier or file.
~param Identifier the identifier to link to; nil if a link to a file
~param TheFile    the file to link to; nil if a link to an identifier }
procedure TICHTMLVisitor.LinkTo(Identifier: TIdentifier; TheFile: TPascalFile);
var       Ignore        :Boolean;      //whether the link should be ignored
begin
 //the target of the link should be excluded from documentation?
 Ignore := FGenerator.DoNotDocumentIdentifier(Identifier, TheFile);

 if not Ignore then                                //if not ignored
  begin
   FHTMLFile.WriteString('<a href="');               //start the link
   if assigned(Identifier) then                      //and write the target
    FHTMLFile.WriteString(FGenerator.GetURIOf(Identifier))
   else
    FHTMLFile.WriteString(FGenerator.GetURIOf(nil, TheFile));
   FHTMLFile.WriteString('">');
  end;

 if Assigned(Identifier) then                      //write name of the target
  FHTMLFile.WriteString(Identifier.Name)
 else
  FHTMLFile.WriteString(TheFile.InternalFileName);

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

{Called for each link to a file by one of its aliases (used in the uses
 clauses).
~param TheFile the file to link to
~param Alias   the used alias of the file }
procedure TICHTMLVisitor.LinkFileByAlias(TheFile: TPascalFile;
                                         const Alias: String);
begin
 Assert(not FGenerator.DoNotDocumentIdentifier(nil, TheFile));

 FHTMLFile.WriteString('<a href="');                //start link
 FHTMLFile.WriteString(FGenerator.GetURIOf(nil, TheFile)); //and the target
 FHTMLFile.WriteString('">');
 FHTMLFile.WriteString(TheFile.InternalFileName);   //write name of file
 FHTMLFile.WriteString('</a>');                     //end link

 Localize(dtUnitUsedByAliasPre);                    //add information of alias
 PascalCode(Alias, icpcIdentifier);
 Localize(dtUnitUsedByAliasPost);
end;

{Called for each link whose target could not be found.
~param Node          the node with the invalid/unknown link target
~param VisitChildren out: whether the children of the node (the link text)
                     should also be visited; default is True }
procedure TICHTMLVisitor.InvalidLink(Node: TICNInvalidLink;
                                     var VisitChildren: Boolean);
begin
 VisitChildren := False;                 //will be visited manually
 Node.VisitChildren(Self);               //visit the text

 WriteText(' @ ');                       //write separator
 WriteText(Node.LinkText);               //write text of the unknown target
end;

{Called for each link to a target outside of the generated documentation
 (either in the internet or in the local file system).
~param Node          the node of a link to an external target
~param VisitChildren out: whether the children of the node (the link text)
                     should also be visited; default is True }
procedure TICHTMLVisitor.LinkExtern(Node: TICNLinkExtern;
                                    var VisitChildren: Boolean);
begin
 FHTMLFile.WriteString('<a href="');        //start the link
 WriteText(Node.URI);
 FHTMLFile.WriteString('" class="external">');

 VisitChildren := False;                    //will be visited manually
 if Node.NoChildren then                    //no text of the link specified?
  WriteText(Node.LinkText)                    //write the text of the target
 else
  Node.VisitChildren(Self);                   //write the text

 FHTMLFile.WriteString('</a>');             //end the link
end;


{Called for each link to a page of the additional user documentation.
~param Node          the node of a link to a page of user documentation
~param VisitChildren out: whether the children of the node (the link text)
                     should also be visited; default is True }
procedure TICHTMLVisitor.LinkPage(Node: TICNLinkPage;
                                  var VisitChildren: Boolean);
begin
 FHTMLFile.WriteString('<a href="');        //start the link
 FHTMLFile.WriteString(FGenerator.GetPageURI(Node.PageIndex));
 FHTMLFile.WriteString(FGenerator.FileExtension);
 FHTMLFile.WriteString('">');

 VisitChildren := False;                    //will be visited manually
 if Node.NoChildren then                    //no text of the link specified?
  WriteText(Node.LinkText)                    //write the text of the target
 else
  Node.VisitChildren(Self);                   //write the text

 FHTMLFile.WriteString('</a>');             //end the link
end;


{Called for each link to a help topic in the documentation as a help on a GUI.
~param Node          the node of a link to a help topic
~param VisitChildren out: whether the children of the node (the link text)
                     should also be visited; default is True }
procedure TICHTMLVisitor.LinkGUI(Node: TICNLinkGUI;
                                 var VisitChildren: Boolean);
begin
 FHTMLFile.WriteString('<a href="');        //start the link, write the target
 FHTMLFile.WriteString(FGenerator.GetGUIHelpURIByIndex(Node.GUIIndex,
                                                       Node.CommentIndex));
 FHTMLFile.WriteString('">');

 VisitChildren := False;                    //will be visited manually
 if Node.NoChildren then                    //no text of the link specified?
  WriteText(Node.LinkText)                    //write the text of the target
 else
  Node.VisitChildren(Self);                   //write the text

 FHTMLFile.WriteString('</a>');             //end the link
end;






{Called for each node representing an image.
~param Data the node representing the options to include the image }
procedure TICHTMLVisitor.Image(Data: TICNImage);
var       Format        :String;       //the format to insert the image