ubasehtmldoc.pas

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

                     Localize(dtDocumentationExportedIdent),
                     '</th><th>', Localize(dtDocumentationExportedIndex),
                     '</th><th>', Localize(dtDocumentationExportedName),
                     '</th><th>', Localize(dtDocumentationExportedResident),
                     '</th><th>', Localize(dtDocumentationExportedDefFile),
                     '</th></tr>');
    //set separators and format of the entries
    First := '<tr><td>';
    Second := '</td><td>';
    Third := '</td><td>';
    Fourth := '</td><td>';
    Fifth := '</td><td>';
    Sixth := '</td></tr>' + FNewLine;
   end
 else
  begin
   //write the heading
   WriteLn(TheFile, '<h2 class=exported>',
                    Localize(dtDocumentationExportedByFilePre),
                    AFile.InternalFileName,
                    Localize(dtDocumentationExportedByFilePost), ':</h2>');

   WriteLn(TheFile, '<ul class=exported>');  //start the list

   First := '<li class=exported>';           //set format of the entries
   Sixth := '</il>' + FNewLine;
  end;
end;

{Ends a list of exported identifiers.
~param TheFile  the file the list has been written to (can be closed here)
~param AFile    the file whose exported identifiers are listed; nil for all
                exported identifiers
~param PostLast after the last file instead of the global list }
procedure TBaseHTMLDoc.EndExportsLists(var TheFile: TextFile;
                                       AFile: TPascalFile; PostLast: Boolean);
begin
 if not assigned(AFile) then         //is a global file?
  try
    if not PostLast then
     WriteLn(TheFile, '</table>');     //end the table here
  finally
   EndFile(TheFile);                   //and close the file
  end
 else
  WriteLn(TheFile, '</ul>');           //end the list
end;











{Starts the list of long functions.
~param TheFile the file to write the list to (is opened here)
~param Pre     the text before an entry is returned with this parameter
~param Middle  the text is an entry between the number of lines and the
               link to the function is returned with this parameter
~param Post    the text after an entry is returned with this parameter }
procedure TBaseHTMLDoc.StartLongFunctionsLists(var TheFile: TextFile;
                                               var Pre, Middle, Post: String);
begin
 //create the file for the list
 CreateFile(TheFile, 'LongFunctions', Localize(dtDocumentationLongFunctions),
                     Localize(dtKeyWordListLongFunctions));

 //write the heading and start the table
 WriteLn(TheFile, '<h1 class=longfunc>',
                  Localize(dtDocumentationLongFunctions), '</h1>');
 WriteLn(TheFile, '<table class=longfunc><tr><th>',
                  Localize(dtDocumentationLongFunctionsLinesLong),
                  '</th><th>', Localize(dtDocumentationLongFunctionsNames),
                  '</th></tr>');

 //set separators and formats of the entries
 Pre := '<tr><td align=right>';
 Middle := '</td><td>';
 Post := '</td></tr>' + FNewLine;
end;

{Ends the list of long functions.
~param TheFile the file the list has been written to (is closed here) }
procedure TBaseHTMLDoc.EndLongFunctionsLists(var TheFile: TextFile);
begin
 try
   WriteLn(TheFile, '</table>');    //end the table here
 finally
  EndFile(TheFile);                 //and close the file
 end;
end;



{Generates an index about all identifiers and files beginning with the
 character.
~param List       the list of all identifiers and files to generate the index
                  of
~param EntryIndex the index of the first entry with the letter
~param Index      the character to generate the index for
~result the first entry not in the index (i.e. EntryIndex for the next letter)}
function TBaseHTMLDoc.DoGenerateIndex(List: TIdentifierFileList;
                                      EntryIndex: Integer;
                                      Index: Char): Integer;
var      F           :TextFile;       //the file to write the index to
         c           :Char;           //counter through all index files
         Count       :Integer;        //number of identifiers in the index
         //if the end of the index of this character has been reached
         EndReached  :Boolean;
         Ident       :TIdentifier;    //the current identifier
         FileParser  :TPascalFile;    //current file
         S           :String;         //name/entry of current identifier
begin
 S := Localize(dtDocumentationIndexPre) + Index +
      Localize(dtDocumentationIndexPost);

 //create file for the index
 CreateFile(F, 'Index_' + Index, S,
               Localize(dtKeyWordIndexPrefix) + ', ' + Index + '; ' + Index);
 try
   //write the title
   WriteLn(F, '<h1>', S, '</h1>');
   //and links to all index files
   for c := 'A' to 'Z' do
    Write(F, '<a href="Index_', c, '.html">', c, '</a> ');
   WriteLn(F, '<a href="Index__.html">_</a>');

   WriteLn(F, '<h1 class=index>', Index, '</h1>'); //write header of this file

   //start the table
   WriteLn(F, '<table class=index><tr><th>',
              Localize(dtDocumentationIndexFile), '</th><th>',
              Localize(dtDocumentationIndexClass), '</th><th>',
              Localize(dtDocumentationIndexIdentifier), '</th></tr>');

   EndReached := False;                       //end not reached so far
   Count := List.Count;                       //get number of items
   //while not end of the list reached or character of new index found
   while (EntryIndex < Count) and not EndReached do
    begin
     //get the entry
     Ident := List.GetIdentIndex(EntryIndex, FileParser);
     if assigned(Ident) then                    //get name of the entry
      begin
       FileParser := Ident.InFile;
       S := Ident.Name;
      end
     else
      S := FileParser.InternalFileName;
     assert(S <> '');

     EndReached := UpCase(S[1]) <> Index;
     if not EndReached then                     //still in the current index?
      begin
       Write(F, '  <tr><td>');                    //start the entry
       //write the file
       if DoNotDocumentIdentifier(nil, FileParser) then
        Write(F, FileParser.InternalFileName)
       else
        Write(F, GetFileNameLink(FileParser));

       Write(F, '</td><td>');

       //if the identifier is in a record-like type, write it
       if assigned(Ident) and assigned(Ident.MemberOf) then
        begin
         assert(not DoNotDocumentIdentifier(Ident.MemberOf));
         Write(F, GetIdentNameLink(Ident.MemberOf));
        end;

       if assigned(Ident) then           //if entry is an identifier?
        //if identifier is in a record-like type, get link to it in it
        if assigned(Ident.MemberOf) then
         S := GetRecordFieldNameLink(Ident)
        else
         S := GetIdentNameLink(Ident)      //get link to it
       else
        S := '';                           //no identifier => nothing to write
       WriteLn(F, '</td><td>', S, '</td></tr>');  //write the entry

       inc(EntryIndex)                            //next entry
      end; //if not EndReached
    end; //while (EntryIndex < Count) and not EndReached

   WriteLn(F, '</table>');              //end the table
 finally
  EndFile(F);                           //close the file
 end;

 Result := EntryIndex;                  //return the current entry
end;




{Writes the current page of the user documentation. Will be called by
 ~[link CreateUserDocumentation] for each page. }
procedure TBaseHTMLDoc.CreateUserDocPage;
var       F           :TextFile;    //the file to write the documentation to
          Title       :String;      //the title of the page
          Content     :String;      //and its content
begin
 //get title and content of the page of user documentation
 Content := GetUserDocumentationPage(CurrentUserDocPage, Title);

 CurrentHelpContext := 0;                    //no help context defined so far

 //create the file with the correct URI (name) and title
 CreateFile(F, ChangeFileExt(GetPageURI(CurrentUserDocPage), ''),
               ParseCommentText(Title), Localize(dtKeyWordUserDocPage));
 try
   WriteLn(F, ParseCommentText(Content));    //write the content
 finally
  EndFile(F);                                //and close the file
 end;

 //check, if a help context was defined for this comment
 CheckHelpContext(GetPageURI(CurrentUserDocPage));
end;

















{Writes a file with a list of identifiers.
~param FileName    the name of the file to write to
~param Title       the title of the file
~param Description the description of the list
~param KeyWords    the keywords for the list
~param List        the list to write
~result if the list is not empty and has been written }
function TBaseHTMLDoc.WriteListFile(const FileName, Title,
                                          Description, KeyWords: String;
                                    List: TIdentifierFileList): Boolean;

var      F                     :TextFile;       //the file to write to

 {Write the list of files.
 ~param Files the list of files to write }
 procedure WriteFiles(Files: TIdentifierFileList);
 var       i               :Integer;        //counter through the list
           FileParser      :TPascalFile;   //the files in the list
 begin
  WriteLn(F, '<hr>');              //write a separator and heading
  WriteLn(F, '<a name="files"></a><h2 class=special>',
             Localize(dtDocumentationIdentListListOfFilesPre), Description,
             Localize(dtDocumentationIdentListListOfFilesPost), '</h2>');
  Files.SortFileAlphabetically;    //sort the list
  for i := 0 to Files.Count - 1 do //for each file
   begin                             //get it and write a link to it
    Files.GetIdentIndex(i, FileParser);
    WriteLn(F, GetFileNameLink(FileParser), '<br>');
   end;
 end;

 {Write the list of record-like types.
 ~param Classes the list of record-like types to write }
 procedure WriteClasses(Classes: TIdentifierList);
 var       i           :Integer;            //counter through the list
 begin
  WriteLn(F, '<hr>');                //write a separator and heading
  WriteLn(F, '<a name="classes"></a><h2 class=special>',
             Localize(dtDocumentationIdentListListOfClassesPre), Description,
             Localize(dtDocumentationIdentListListOfClassesPost), '</h2>');
  Classes.Sort;                      //sort the list
  for i := 0 to Classes.Count - 1 do //for each record-like type
   //get it and write a link to it
   WriteLn(F, GetIdentNameLink(Classes[i]), '<br>');
 end;

 {Write the list of simple identifiers.
 ~param Idents the list of simple identifiers to write }
 procedure WriteIdentifiers(Idents: TIdentifierList);
 var       InFiles        :TIdentifierList; //identifiers directly in files
           i              :Integer;         //counter through the lists
           Ident          :TIdentifier;     //identifiers in the list
 begin
  WriteLn(F, '<hr>');                    //write a separator and heading
  WriteLn(F, '<a name="idents"></a><h2 class=special>',
          Localize(dtDocumentationIdentListListOfIdentsAlphaPre), Description,
          Localize(dtDocumentationIdentListListOfIdentsAlphaPost), '</h2>');
  Idents.Sort;                           //sort the list
  for i := 0 to Idents.Count - 1 do      //for each identifier
   begin                                   //get it and write a link to it
    Ident := Idents[i];
    if assigned(Ident.MemberOf) then
     Write(F, GetRecordFieldNameLink(Ident, True))
    else
     Write(F, GetIdentNameLink(Ident));
    WriteLn(F, '<br>');
   end;


  //write a separator and heading of the alternatively sorted list
  WriteLn(F, '<hr>');
  WriteLn(F, '<a name="identsbyclasses"></a><h2 class=special>',
             Localize(dtDocumentationIdentListListOfIdentsByClassPre),
             Description,
             Localize(dtDocumentationIdentListListOfIdentsByClassPost),
             '</h2>');

  //split lists, two lists, for identifiers directly in files and
  //in record-like types

  //create list of identifiers directly in files
  InFiles := TIdentifierList.Create;
  try

    for i := Idents.Count - 1 downto 0 do //for each identifier
     begin
      Ident := Idents[i];                   //get it
      if not assigned(Ident.MemberOf) then  //not in a record-like type?
       begin
        //add the to list of identifiers directly in files
        InFiles.AddIdent(Ident);
        Idents.Remove(i, False);              //and remove from this list
       end;
     end;

    InFiles.Sort;                         //sort list of identifiers
    for i := 0 to InFiles.Count - 1 do    //for each identifier
     WriteLn(F, GetIdentNameLink(InFiles[i]), '<br>'); //write a link to it

  finally
   InFiles.RemoveAll(False);    //remove all identifiers (don't free them)
   InFiles.Free;                //free list of identifiers directly in files
  end;

  //sort list of identifiers in record-like types
  Idents.SortByClass;
  for i := 0 to Idents.Count - 1 do  //for each identifier
   WriteLn(F, GetRecordFieldNameLink(Idents[i], True), '<br>'); //write a link
 end;



var      Files                    :TIdentifierFileList; //all files of the list
         Classes, Idents          :TIdentifierList; //identifiers of the list
         i                        :Integer;         //counter through the list
         Ident                    :TIdentifier;     //identifiers in the list
         FileParser               :TPascalFile;     //files in the list
begin
 Result := not List.IsEmpty;
 if Result then                   //list not empty?
  begin

   CreateFile(F, FileName, Title, KeyWords);  //create the file
   try

     Idents := TIdentifierList.Create;