uicwinhelpdoc.pas

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

 if FNeedNewLine in [nnlLine, nnlParagraph] then
  FNeedNewLine := nnlNone;                        //not anymore
 FLastBreak := lbParagraph;                     //paragraph has been ended
end;


{Starts a new level of indentation.
~param Small         whether only a small indentation should be added
~param MarkFirstLine whether a marker should be added in the first line
                     (/for each item)
~todo these todos are not specifically for this method, but for any structure
~todo dictionary - indentation ???
~todo keep track of "last" added node, ... whether it was a simple text, or
      a structural format, like list, dictionary, line- or paragraph break }
procedure TICWinHelpVisitor.AddIndentation(Small: Boolean = False;
                                           MarkFirstLine: Boolean = False);
var       Delta            :Integer;          //width of additional indentation
          Info             :TIndentationInformation; //the information about it
begin
 Info.Small := Small;                             //save information
 Info.Marked := MarkFirstLine;

 Delta := IndentationTwips[Small];                //get additional indentation
 assert(FCurrentIdentation >= 0);
 Inc(FCurrentIdentation, Delta);                  //set new indentation

 Info.SumIndent := FCurrentIdentation;            //and save it

 Inc(FIndentationIndex);                          //save information
 if FIndentationIndex = Length(FIndentation) then
  SetLength(FIndentation, FIndentationIndex + 8);
 FIndentation[FIndentationIndex] := Info;         //on the stack

 if FLastBreak <> lbParagraph then                //currently in a paragraph?
  EndParagraph(True);                               //end the paragraph
 //create the indentation
 FRTFFile.WriteFormatted('\li%d', [FCurrentIdentation]);
 FRTFFile.WriteString(FGenerator.NewLine);
 if MarkFirstLine then                            //marker at the first line?
  begin
   //set relatively negative indentation for the first line of each paragraph
   //and a tabulator at the current indentation
   FRTFFile.WriteFormatted('\tx%d\fi-%d', [FCurrentIdentation, Delta]);
   FRTFFile.WriteString(FGenerator.NewLine);
  end;
 FLastBreak := lbParagraph;                       //new paragraph begins
end;

{Ends the most recent level of indentation.
~param Small         whether only a small indentation was added
~param MarkFirstLine whether a marker was added in the first line
                     (/for each item) }
procedure TICWinHelpVisitor.EndIndentation(Small: Boolean = False;
                                           MarkFirstLine: Boolean = False);
begin
 //check whether indentation with same information was added before
 assert(FIndentationIndex >= 0);
 assert((FIndentation[FIndentationIndex].Small = Small));
 assert((FIndentation[FIndentationIndex].Marked = MarkFirstLine));

 Dec(FIndentationIndex);                          //remove from stack

 if FLastBreak <> lbParagraph then                //currently in a paragraph?
  EndParagraph(True);                               //end the paragraph
 FRTFFile.WriteString('\pard');                   //reset all values
 if FIndentationIndex >= 0 then                   //indentation still exists?
  begin
   //set the new (lesser) indentation
   FCurrentIdentation := FIndentation[FIndentationIndex].SumIndent;
   FRTFFile.WriteFormatted('\li%d', [FCurrentIdentation]);
   if FIndentation[FIndentationIndex].Marked then   //has a marker?
    //set relatively negative indentation for the first line of each paragraph
    //and a tabulator at the current indentation
    FRTFFile.WriteFormatted('\tx%d\fi-%d',
                            [FCurrentIdentation,
                             IndentationTwips[FIndentation[FIndentationIndex].
                                                                     Small]]);
  end
 else
  FCurrentIdentation := 0;                          //disable indentation
 FRTFFile.WriteString(FGenerator.NewLine);

 FLastBreak := lbParagraph;                         //paragraph has been ended
end;




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



{Writes the text in the RTF file. Any special characters are encoded so the
 text will appear as it is.
~param Text the text to "quote" in the format }
procedure TICWinHelpVisitor.WriteText(const Text: String);
var       p                :PChar;    //runner through the text
          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 line breaks should be preserved
   LineBreak := FGenerator.KeepRawLineBreaks or (FPreformattedDepth <> 0);
   p := Pointer(Text);
   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
                       FRTFFile.WriteString(#10'\line ')
                      else
                       //treat new-line as a simple space
                       FRTFFile.WriteString(#10' ');
       '\', '{', '}': begin
                       FRTFFile.WriteCharacter('\'); //quote with a backslash
                       FRTFFile.WriteCharacter(p^);
                      end;
       #128..#255:    //quote hexadecimally
                      FRTFFile.WriteFormatted('\''%.2x', [ord(p^)]);
     else
      StartP := p;                        //get start position of normal text
      repeat
        Inc(p);                             //skip all characters that don't
      until p^ in [#0, #10, '\', '{', '}', #128..#255];     //need to be quoted
      //decrement now, will be incremented again after the case-statement
      Dec(p);
      if StartP = p then                  //was only one character?
       FRTFFile.WriteCharacter(p^)          //write the character
      else                                  //or write all characters
       FRTFFile.WriteBuffer(StartP^, p - StartP + 1);
     end;
     Inc(p);                              //next character
    end; //while p^ <> #0

   FLastBreak := lbText;                //text has been added
   if LineBreak then                    //line breaks should be preserved?
    begin
     Dec(p);                              //check the last character
     if p^ = #10 then                     //was a line break?
      FLastBreak := lbLine;                 //a line break has been added
    end;
  end; //if Text <> ''
end;



{Called for all text nodes in the ~[link UICNodes COM].
~param Text the text of the node }
procedure TICWinHelpVisitor.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 TICWinHelpVisitor.RawText(const Text: String);
begin
 FRTFFile.WriteString(Text);          //just write it
 FLastBreak := lbText;                //assume some text has been written
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 TICWinHelpVisitor.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 TICWinHelpVisitor.TextStyle(Node: TICNTextStyle;
                                      var VisitChildren: Boolean);
begin
 case Node.TextStyle of                     //start the formatting of the text
   ictsEmphasize: FRTFFile.WriteString('{\i ');
   ictsStrong:    FRTFFile.WriteString('{\b ');
 else
  assert(False);
 end;
 FLastBreak := lbText;                      //normal text will be written
 VisitChildren := False;                    //will be visited manually
 Node.VisitChildren(Self);                  //visit the text
 FRTFFile.WriteCharacter('}');              //end the format
 FLastBreak := lbText;                      //some text has been written
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 TICWinHelpVisitor.FontStyle(Node: TICNFontStyle;
                                      var VisitChildren: Boolean);
begin
 case Node.FontStyle of
   icfsCode: FRTFFile.WriteString('{\f1 '); //start formatting as code
 else
  assert(False);
 end;
 FLastBreak := lbText;                      //normal text will be written
 VisitChildren := False;                    //will be visited manually
 Node.VisitChildren(Self);                  //visit the text
 FRTFFile.WriteCharacter('}');              //end the format
 FLastBreak := lbText;                      //some text has been written
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 TICWinHelpVisitor.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

 FRTFFile.WriteString('{\f1 ');          //use the fixed-width/mono-spaced font
 FLastBreak := lbText;                   //normal text will be written
 Inc(FPreformattedDepth);                //pre-formatted text will be written

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

 Dec(FPreformattedDepth);                //end writing pre-formatted text
 FRTFFile.WriteCharacter('}');           //use the normal font
 FLastBreak := lbText;                   //some text has been written

 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 TICWinHelpVisitor.LinkTo(Identifier: TIdentifier;
                                   TheFile: TPascalFile);
var       Ignore           :Boolean;    //whether the link should be ignored
          Part             :TExtraWinHelpFileFor; //part the link points to
begin
 //the target of the link should be excluded from documentation?
 Ignore := FGenerator.DoNotDocumentIdentifier(Identifier, TheFile);

 if not Ignore then
  FRTFFile.WriteString('{\uldb ');                 //start the link

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

 if not Ignore then                                //if not ignored
  begin
   FRTFFile.WriteString('}{\v ');                    //end the link
   if Assigned(Identifier) then                      //and write the target
    FRTFFile.WriteString(FGenerator.GetURIOf(Identifier))
   else
    FRTFFile.WriteString(FGenerator.GetURIOf(nil, TheFile));
   FRTFFile.WriteCharacter('>');
   FRTFFile.WriteString(HelpWindowNames[hwMain]);

   if Assigned(Identifier) then                      //get part of the target
    Part := FGenerator.GetIdentifierPart(Identifier)
   else
    Part := ewhfFiles;
   FGenerator.WriteHLPFileLinkIf(Part,
                                 (not FGenerator.InNamedPart or
                                  (FGenerator.CurrentPart <> Part)) and
                                 ((Part in FGenerator.ExtraWinHelpFilesFor) or
                                  (FGenerator.InNamedPart and
                                   (FGenerator.CurrentPart in
                                    FGenerator.ExtraWinHelpFilesFor))));
   FRTFFile.WriteCharacter('}');
  end;

 FLastBreak := lbText;                             //some text has been written
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 TICWinHelpVisitor.LinkFileByAlias(TheFile: TPascalFile;
                                            const Alias: String);
begin
 Assert(not FGenerator.DoNotDocumentIdentifier(nil, TheFile));

 FRTFFile.WriteString('{\uldb ');                //start link
 FRTFFile.WriteString(TheFile.InternalFileName); //write name of file
 FRTFFile.WriteString('}{\v ');                  //end link, write target
 FRTFFile.WriteString(FGenerator.GetURIOf(nil, TheFile));
 FRTFFile.WriteCharacter('>');
 FRTFFile.WriteString(HelpWindowNames[hwMain]);
 FGenerator.WriteHLPFileLinkIf(ewhfFiles,
                               (not FGenerator.InNamedPart or
                                (FGenerator.CurrentPart <> ewhfFiles)) and
                               ((ewhfFiles in