uhtmlhelpdoc.pas

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

   CloseFile(F);                      //close the file, then
   raise;                             //forward the error
 end;
end;




{Writes the footer of a HTML file and closes it.
~param F the HTML file to end and close }
procedure THTMLHelpDoc.EndFile(var F: TextFile);
begin
 try
   if TextFooterFile <> '' then    //custom footer supplied?
    WriteLn(F, FTextFooter)          //just write it
   else
    begin
     WriteLn(F, '</body>');
     WriteLn(F, '</html>');          //end the HTML file
    end;
 finally
  CloseFile(F);                    //finally close the file
 end;
end;



{Inserts an entry into the content file.
~param Text   the text of the topic in the content file
~param Target the target of the topic }
procedure THTMLHelpDoc.AddContentEntry(const Text, Target: String);
begin
 Write(FContentFile, StringOfChar(' ', FContentLevel));
 WriteLn(FContentFile, '<LI><OBJECT type="text/sitemap"><param name="Name" value="',
                       Text,
                       '"><param name="Local" value="',
                       Target,
                       '"></OBJECT></LI>');
end;

{Starts a new list of sub-topics in the content file.
~param Text   the text of the list of topics }
procedure THTMLHelpDoc.StartContentList(const Text: String);
begin
 Write(FContentFile, StringOfChar(' ', FContentLevel));
 WriteLn(FContentFile, '<LI><OBJECT type="text/sitemap"><param name="Name" value="',
                       Text,
                       '"></OBJECT><UL>');

 Inc(FContentLevel);
end;

{Ends a list of sub-topics. }
procedure THTMLHelpDoc.EndContentList;
begin
 assert(FContentLevel > 0);

 Dec(FContentLevel);

 Write(FContentFile, StringOfChar(' ', FContentLevel));
 WriteLn(FContentFile, '</UL></IL>');
end;












{Returns the absolute unique ID of an identifier to be used in the
 documentation. Is is used as the name of the file to create for it.
~param Ident   the identifier to return a link to (may be nil, to return a link
               to the file)
~param TheFile the file the identifier is defined in
~param Local   if it should be local, without directory
~result the absolute unique ID of the identifier }
function THTMLHelpDoc.GetFileName(Ident: TIdentifier;
                                  TheFile: TPascalFile = nil;
                                  Local: Boolean = False): String;
var      TheRecord   :TRecordType;     //the record-like type of the file
begin
 if FUseSubdirectories <> sduNone then //uses sub-directories?
  begin
   assert(assigned(Ident) <> assigned(TheFile));
   assert(not DoNotDocumentIdentifier(Ident, TheFile));

   if assigned(Ident) then
    begin
     TheFile := Ident.InFile;
     if Ident is TRecordType then
      TheRecord := TRecordType(Ident)
     else
      TheRecord := Ident.MemberOf;
    end
   else
    TheRecord := nil;


   if Local then                         //should be local, without directory?
    Result := ''
   else
    begin
     //the name of the file (and its number) as the sub-directory
     Result := TheFile.InternalFileName;
     if TheFile.InternalNameIndex <> 0 then
      Result := Result + '.' + IntToStr(TheFile.InternalNameIndex);
     Result := Result + '/';
     if (FUseSubdirectories = sduFilesAndTypes) and assigned(TheRecord) then
      Result := Result + TheRecord.Name + '/';
    end;

   //if in record-like type
   if assigned(TheRecord) and (FUseSubdirectories <> sduFilesAndTypes) then
    Result := Result + 'I_' + TheRecord.Name; //add prefix + record-like type

   //identifier in file/record-like type?
   if assigned(Ident) and (Ident <> TheRecord) then
    begin
     //is inside a record-like type?
     if assigned(TheRecord) and (FUseSubdirectories <> sduFilesAndTypes) then
      Result := Result + '.';                //add separating dot
     Result := Result + 'I_';              //add prefix and index and its name
     if Ident.InternalNameIndex <> 0 then
      Result := Result + IntToStr(Ident.InternalNameIndex);
     Result := Result + Ident.Name;
    end
   else
    if not assigned(Ident) then          //just the file?
     Result := Result + 'File'             //use always this name for the file
    else
     if FUseSubdirectories = sduFilesAndTypes then //just the type?
      Result := Result + 'Type'              //this name for record-like types
  end
 else
  Result := inherited GetURIOf(Ident, TheFile); //use default URI
end;






{Returns a prefix for all links to images. Needed in order to use
 sub-directories.
~param IsSymbol if the image is a symbol
~result a prefix for all links to images }
function THTMLHelpDoc.GetImagePrefix(IsSymbol: Boolean): String;
begin
 Result := '';
 //may be in a sub-directory?
 if (FUseSubdirectories <> sduNone) and
    (IsSymbol or                           //either pre-definition?
     assigned(LinkFile)) then              //or current symbol?
  begin
   Result := '../';                          //have to go back one directory
   //currently in another sub-directory and need another one?
   if (FUseSubdirectories = sduFilesAndTypes) and //may be two levels deep?
      (not assigned(LinkFile) or              //pre-definition? (needs 2 "../")
       (assigned(LinkIdent) and               //or (in) a record-like type?
        (assigned(LinkIdent.MemberOf) or (LinkIdent is TRecordType)))) then
    Result := '../' + Result;                     //go up another one
  end;
end;




















{Gets the links to the generated files by ~[link WriteFileTreeFiles].
~result a text including (if possible) a link to the generated files in the
        format of the documentation }
function THTMLHelpDoc.GetFileListFileLinks: String;
begin
 if GenerateXFigFiles then               //Xfig files have been generated?
  inc(FGeneratedFileCount);
 if GenerateWMFFiles then                //WMF files have been generated?
  inc(FGeneratedFileCount);

 Result := inherited GetFileListFileLinks; //return links
end;

{Writes the list of files, the text is generated by ~[link GetFileListText].
~param Text the text of the list of files }
procedure THTMLHelpDoc.WriteFileList(const Text: String);
begin
 AddContentEntry(Localize(dtDocumentationLinkFiles), 'FileList.html');

 inherited WriteFileList(Text);
end;




          //header titles of the lists of different kinds of identifiers in
          //files
const     DeclName: array[TWriteKind] of TDocumentationTexts =
                    (dtDocumentationFileDeclarationsHeaderVar,
                     dtDocumentationFileDeclarationsHeaderThreadVar,
                     dtDocumentationFileDeclarationsHeaderConst,
                     dtDocumentationFileDeclarationsHeaderResourceString,
                     dtDocumentationFileDeclarationsHeaderFunctions,
                     dtDocumentationFileDeclarationsHeaderSimpleTypes);
          //the classes of the lists of different kinds of identifiers in files
          DeclTypeClass: array[TWriteKind] of TIdentifierClass =
             (TVariable,       TVariable, TConstant,
              TResourceString, TFunction, TType);
          //the name of anchors to the beginning of the lists of different
          //kinds of identifiers in files
          ListName: array[TWriteKind] of String =
             ('Variables',       'ThreadVariables', 'Constants',
              'ResourceStrings', 'Functions',       'SimpleTypes');


{Writes the documentation about all identifiers of the given kind in the file.
~param AFile     the file whose identifiers should be documented
~param WriteType the kind of identifiers to document
~result a link to the created list of all documented identifiers }
function THTMLHelpDoc.WriteVarConstFuncs(AFile: TPascalFile;
                                         WriteType: TWriteKind): String;
var      List        :TIdentifierList;     //list of the identifiers in the file

 {Gets the list of the kind of identifiers in the file. }
 procedure GetList;
 var       AClass :TIdentifierClass;      //class the identifiers have to be
           i      :Integer;               //counter through all identifiers
           Ident  :TIdentifier;           //each identifier
 begin
  AClass := DeclTypeClass[WriteType];     //get class of identifiers
  for i := 0 to AFile.Idents.Count - 1 do //for each identifier
   begin
    Ident := AFile.Idents[i];               //get it
    if (((Ident is AClass) and                //is of searched class and kind?
         (not (WriteType in [wkVar, wkThreadVar]) or
          (TVariable(Ident).IsThreadVar = (WriteType = wkThreadVar)))) or
        ((WriteType = wkConst) and (Ident is TEnumTypeItem))) and
       not DoNotDocumentIdentifier(Ident) then //documented?
     List.AddIdent(Ident);                       //add it to the list
   end;
 end;

 {Creates the documentation of all identifiers in the list. }
 procedure CreateDocumentation;
 var       i           :Integer;       //counter through all identifiers
           Ident       :TIdentifier;   //each identifier
           F           :TextFile;      //files for documentation of identifiers
           Dummy       :String;        //additional header links
 begin
  for i := 0 to List.Count - 1 do      //for each identifier
   begin
    Ident := List[i];                    //get it

    if not (Ident is TRecordType) then   //if not a record-like type
     begin
      CurrentHelpContext := 0;              //no help context defined so far
      SetCommentIdent(Ident, Ident.InFile); //set identifier for comment

      AddContentEntry(Ident.Name, GetFileName(Ident) + '.html');

      CreateFile(F, GetFileName(Ident),
                 AFile.InternalFileName + '.' + Ident.Name,
                 AFile.InternalFileName + ', ' + Ident.Name + '; ' +
                 Ident.Name);
      try
        //write links to file and to the list of all identifiers of the kind
        WriteLn(F, FileTypeNames[AFile.FileType], ' ',              
                   GetFileNameLink(AFile), '   ', Result);
        WriteLn(F, '<hr>');                //end the header


        Write(F, GetScope(Ident.Scope));   //write its scope
        if WriteType = wkSimpleType then   //if it is a simple type
         Write(F, Ident.Name, ' = ');        //write the name of the identifier
        //write the definition of the identifier
        WriteLn(F, Ident.GetDescriptionString(Self, Ident), '<br>');
        WriteLn(F, '<br>');

        Dummy := '';
        //write the documentation of the identifier
        Write(F, GetIdentComment(Dummy));
      finally
       EndFile(F);
      end;

      //check, if a help context was defined for this identifier
      CheckHelpContext(GetFileName(Ident) + '.html');
     end; //if not (Ident is TRecordType)
   end; //for i := 0 to List.Count - 1
 end;

 {Creates the linked list of identifiers in the file. }
 procedure CreateList;
 var       F         :TextFile;            //file for the list
           i         :Integer;             //counter through the list
           Ident     :TIdentifier;         //each identifier
           Port      :TIdentPortabilities; //its portability issues
 begin
  CreateFile(F,                            //create file for the list
             GetFileName(nil, AFile) + '.' + ListName[WriteType],
             Localize(DeclName[WriteType]) +
             Localize(dtDocumentationFileDeclarationsHeaderMiddle) +
             FileTypeNames[AFile.FileType] + ' ' + AFile.InternalFileName,
             AFile.InternalFileName + ', ' + Localize(DeclName[WriteType]));
  try
    //write links to the file
    WriteLn(F, FileTypeNames[AFile.FileType], ' ', GetFileNameLink(AFile));
    WriteLn(F, '<hr>');                      //end the header


    WriteLn(F, '<b>', Localize(DeclName[WriteType]),  //write the title
                      Localize(dtDocumentationFileDeclarationsHeaderMiddle) +
                      FileTypeNames[AFile.FileType] + ' ' +
                      AFile.InternalFileName, '</b><br>');


    WriteLn(F, '<ul>');                      //start the list
    for i := 0 to List.Count - 1 do          //for each identifier in the list
     begin
      Ident := List[i];                        //get it

      Write(F, '<li>', GetScope(Ident.Scope)); //write its scope

      Port := Ident.Portability;
      if FDeprecatedList.IsIn(Ident) then
       Include(Port, ipDeprecated);
      Write(F, GetPortabilityIssues(Port));    //write its portability issues

      if WriteType = wkFunc then
       Write(F, ReservedWord(FuncNames[TFunction(Ident).FuncKind]), ' ');

      //write linked name of the identifier
      WriteLn(F, GetIdentNameLink(Ident), '</li>');
     end;
    WriteLn(F, '</ul>');                     //end the list

  finally
   EndFile(F);                               //close the file
  end;
 end;


begin
 List := TIdentifierList.Create;           //create the list of the identifiers
 try
   GetList;                                //search identifiers of that kind

   if not List.IsEmpty then                //some identifiers found?
    begin
     List.Sort;                              //sort the list

     //include link to the list in the header of the file
     Result := '<a href="' + GetFileName(nil, AFile, True) + '.' +