uwinhelpdoc.pas

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

          //the palette entry of the black color
          BMPFileBlackColor = #$00#$00#$00#$00;
          //the body of the image file (after the palette)
          BMPFileBody = #$00#$00#$00#$00#$57#$77#$77#$75#$71#$11#$45#$57#$51#$32#$64#$55#$07#$23#$21#$70#$00#$72#$27#$00#$00#$07#$70#$00#$00#$00#$00#$00;



          //number of entries in the palette of the image
          PalSize = 8 - 1 - 1;


          //an entry in the palette the value of a color component to use, if
          //the color is R/G/B-value is activated or not
type      TPaletteColorEntry = packed array[Boolean] of Char;
          //for each palette entry the value to use, if the color component
          //R/G/B is activated or not
const     PalCols: array[0..PalSize-1] of TPaletteColorEntry =
                  ({(#$FF, #$FF),} (#$00, #$FF), (#$3F, #$FF),  (#$7F, #$FF),
                    (#$00, #$E0),  (#$00, #$C0), (#$20, #$FF){, (#$00, #$00)});



var       F               :TextFile;           //the file to write
          i               :Integer;            //counter through the palette
          R, G, B         :Boolean;            //if R/G/B-value is activated
          NoYes           :TPaletteColorEntry; //the R/G/B-values to use
begin
 AssignFile(F, FDestPath + FilePrefix + '.bmp'); 
 Rewrite(F);                                   //open the file
 try
   Write(F, BMPFileHeader);                    //write the header of the image
   Write(F, BMPFileWhiteColor);                //and the first, white color

   R := (Color and $FF) <> 0;                  //get what color component R/G/B
   G := (Color and $FF00) <> 0;                //should be set
   B := (Color and $FF0000) <> 0;
   //for each palette entry
   for i := low(PalCols) to high(PalCols) do
    begin
     NoYes := PalCols[i];                          //get its color values
     if ord(NoYes[True]) < Darker then             //darken it
      NoYes[True] := #$00
     else
      dec(NoYes[True], Darker);
     Write(F, NoYes[B], NoYes[G], NoYes[R], #$00); //write the palette entry
    end;
   Write(F, BMPFileBlackColor);                //write the last, black color
   Write(F, BMPFileBody);                      //write the body of the image
 finally
  CloseFile(F);                                //close the file
 end;
end;





{Begins a new page in the help file.
~param Title         the title of the page
~param Name          the internal name of the page (for links etc.)
~param KeyWords      the keywords of the page in the index
~param DefaultWindow the default window wo use, when chosen from the index }
procedure TWinHelpDoc.WritePageHeader(const Title, Name, KeyWords: String;
                                      DefaultWindow: THelpWindow = hwMain);
begin
 WriteLn(FRTFFile, '\keepn');              //start a new page and its header

{$ifdef Debug}
 //write number of the page
 Write(FRTFFile, 'A{\footnote ', Format('%0.5u', [FPageNumber]), '}');
 inc(FPageNumber);
{$endif}

 //write name and title of the page
 Write(FRTFFile, '#{\footnote ', Name, '}${\footnote ', Title, '}');

 //write keywords, if available
 if KeyWords <> '' then
  Write(FRTFFile, 'K{\footnote ', KeyWords, '}');

 if DefaultWindow = hwMain then     //only browse through main topics
  begin
   //write browse sequence number
   Write(FRTFFile, '+{\footnote :', Format('%0.5u', [FBrowseNumber]), '}');
   inc(FBrowseNumber);
  end;

 //write default window, if necessary
 if DefaultWindow <> hwMain then
  Write(FRTFFile, '>{\footnote ', HelpWindowNames[DefaultWindow], '}');

 WriteLn(FRTFFile);

 //write/show the title of the page in the header
 WriteLn(FRTFFile, '{\fs24\cf2\b ', Title, '}\line');
end;

{Ends the header of a page in the help file and begins the part of the content.}
procedure TWinHelpDoc.WritePageHeaderEnd;
begin
 WriteLn(FRTFFile, '\par\pard');       //the \pard ends the part of the header
end;

{Ends the page in the help file.
~param Last if it was the last page in the help file }
procedure TWinHelpDoc.WritePageFooter(Last: Boolean = False);
begin
 WriteLn(FRTFFile);
 if not Last then
  WriteLn(FRTFFile, '\page');         //end the page and start a new one
end;


{Begins a small pop-up page in the help file.
~param Title the title of the page
~param Name  the internal name of the page (for links etc.) }
procedure TWinHelpDoc.WritePopUpHeader(const Title, Name: String);
begin
{$ifdef Debug}
 //write number of the page
 Write(FRTFFile, 'A{\footnote ', Format('%0.5u', [FPageNumber]), '}');
 inc(FPageNumber);
{$endif}

 //write name and title of the page
 WriteLn(FRTFFile, '#{\footnote ', Name, '}${\footnote ', Title, '}');

 //write/show the title on the page
 WriteLn(FRTFFile, '{\b ', Title, '}\par');
end;

{Ends a small pop-up page in the help file.
~param Last if it was the last page in the help file }
procedure TWinHelpDoc.WritePopUpFooter(Last: Boolean = False);
begin
 WriteLn(FRTFFile);
 if not Last then
  WriteLn(FRTFFile, '\page');         //end the page and start a new one
end;








{Returns the token of a string (formatted) in the format of the documentation.
 It is colored with the third color (red).
~param StringToken the string token
~result the encoded string token in a special format }
function TWinHelpDoc.FormatStringToken(const StringToken: String): String;
begin
 Result := '{\cf3 ' + HandleRawText(StringToken) + '}';
end;

















{Returns the documentation of examples in comments.
~param Comment the comment to parse the examples of
~param HeaderLinks  some links to the examples may be appended to this variable
~result the documentation of the examples }
function TWinHelpDoc.ParseExampleComment(Comment: TComment;
                                         var HeaderLinks: String): String;
var      Text       :String;     //the text of the example
         Number     :Integer;    //the number of the example
         PageName   :String;     //the internal name of the page
         Thing      :String;     //name of the identifier/file of the example
begin
 Number := 0;                    //no examples so far

 //for each example, get it
 while Comment.GetAndDeleteSection(csExample, Text) do
  begin
   inc(Number);                    //increment number of examples

   //generate an URI for the page of the example
   if assigned(CommentIdent) then
    PageName := GetURIOf(CommentIdent)
   else
    PageName := GetURIOf(nil, CommentFile);

   PageName := PageName + '.Example' + IntToStr(Number);


   if assigned(CommentIdent) then  //get name of the subject of the example
    Thing := CommentIdent.Name
   else
    Thing := CommentFile.InternalFileName;

   //start page of the example (start its header)
   WritePageHeader(Localize(dtDocumentationExampleForPrefix) + Thing, PageName,
                   Thing + ', ' + Localize(dtKeyWordExample), hwExample);

   if assigned(CommentIdent) then    //write link to the subject of the example
    if assigned(CommentIdent.MemberOf) then
     WriteLn(FRTFFile, GetRecordFieldNameLink(CommentIdent, True))
    else
     WriteLn(FRTFFile, GetIdentNameLink(CommentIdent))
   else
    WriteLn(FRTFFile, GetFileNameLink(CommentFile));
   WritePageHeaderEnd;             //end the header of the page

   WriteLn(FRTFFile, ParseCommentText(Text)); //write the example

   WritePageFooter;                //end the page of the example


   //let a link to the example be included in the header of the subject
   HeaderLinks := HeaderLinks + '   {\uldb ' +
                                Localize(dtDocumentationExampleLinkPrefix);
   if Number <> 1 then
    HeaderLinks := HeaderLinks + ' ' + IntToStr(Number);
   HeaderLinks := HeaderLinks + '}{\v ' + PageName +
                                '>' + HelpWindowNames[hwExample] + '}';
  end;

 Result := '';              //don't include examples directly in documentation
end;













{Returns a string containing a link to the given file.
~param TheFile the file to link to
~result a string containing a link to the file }
function TWinHelpDoc.GetFileNameLink(TheFile: TPascalFile): String;
begin
 assert(assigned(TheFile));
 assert(not DoNotDocumentIdentifier(nil, TheFile));

 //return link to the file
 Result := '{\uldb ' + TheFile.InternalFileName + '}{\v ' +
           GetURIOf(nil, TheFile) + '>' + HelpWindowNames[hwMain] + '}';
end;

{Returns a string containing a link to the given identifier/file. The
 identifier can't be declared inside a record-like type (use ~[link
 .GetRecordFieldNameLink] for that) but must be top-level declared inside the
 file.
~param Ident     the identifier to link to (can be nil to generate a link to
                 the file)
~param WriteFile if the file (also as a link) should be written
~result a string containing a link to the identifier (and the file) }
function TWinHelpDoc.GetIdentNameLink(Ident: TIdentifier;
                                      WriteFile: Boolean = False): String;
begin
 assert(assigned(Ident));
 assert(not assigned(Ident.MemberOf));
 assert(not DoNotDocumentIdentifier(Ident));

 if WriteFile then             //file should be written?
  begin                          //generate link to the file
   if DoNotDocumentIdentifier(nil, Ident.InFile) then
    Result := IdentifierText(Ident.InFile.InternalFileName)
   else
    Result := '{\uldb ' + Ident.InFile.InternalFileName + '}{\v ' +
              GetURIOf(nil, Ident.InFile) +
              '>' + HelpWindowNames[hwMain] + '}';
   Result := Result + '.';       //add separating dot "."
  end
 else
  Result := '';

 //generate a link to the identifier
 Result := Result + '{\uldb ' + Ident.Name + '}{\v ' +
           GetURIOf(Ident) + '>' + HelpWindowNames[hwMain] + '}';
end;

{Returns a string containing a link to the given identifier inside a
 record-like type (a member of it).
~param Ident       the identifier to link to
~param WriteRecord if the type (also as a link) should be written
~result a string containing a link to the identifier (and the type) }
function TWinHelpDoc.GetRecordFieldNameLink(Ident: TIdentifier;
                                         WriteRecord: Boolean = False): String;
begin
 assert(assigned(Ident));
 assert(assigned(Ident.MemberOf));
 assert(not DoNotDocumentIdentifier(Ident));
 assert(not DoNotDocumentIdentifier(Ident.MemberOf));

 if WriteRecord then                  //record-like type should also be linked?
  Result := '{\uldb ' + Ident.MemberOf.Name + '}{\v ' +  //generate link on it
            GetURIOf(Ident.MemberOf) + '>' + HelpWindowNames[hwMain] + '}.'
 else
  Result := '';
 //generate link to the member
 Result := Result + '{\uldb ' + Ident.Name + '}{\v ' +
           GetURIOf(Ident) + '>' + HelpWindowNames[hwMain] + '}';
end;


{Returns the format needed to express the scope (as an icon).
~param Scope the scope to show
~result the format to express the scope }
function TWinHelpDoc.GetScope(Scope: TScope): String;
         //the base names of all icons of the scopes
const    ScopeFileName: array[TScope] of String =
                   ('', 'unitinterface', 'unitlocal',
                    'private', 'protected', 'public', 'published', 'automated',
                    '');
begin
 Result := ScopeFileName[Scope];       //get name of file of the scope
 if Result <> '' then                  //icon available?
  //return the format for including the image
  Result := '\{bmct ' + Result + '.bmp\}';
end;

{Returns the format needed to express the portability issues (as icons).
~param Issues the portability issues to show (may be the empty set)
~result the format to express the portability issues }
function TWinHelpDoc.GetPortabilityIssues(Issues: TIdentPortabilities): String;
         //the base names of all icons of portability issues
const    IdentPortabilityFileName: array[TIdentPortability] of String =
                                    ('deprecated', 'library', 'platform');
var      p          :TIdentPortability; //runner through all portability issues
begin
 Result := '';                         //no icons needed so far
 for p := low(p) to high(p) do         //for each portability issue
  if p in Issues then                    //that is requested