uhtmldoc.pas

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

{  JADD - Just Another DelphiDoc: Documentation from Delphi Source Code

Copyright (C) 2003-2008   Gerold Veith

This file is part of JADD - Just Another DelphiDoc.

DelphiDoc is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License version 3 as
published by the Free Software Foundation.

DelphiDoc is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
}


unit UHTMLDoc;

{Contains the documentation generator ~[linkClass THTMLDoc] to generate
 documentation about the parsed data in the HTML format. }

interface

uses Windows, Classes,
     UPascalConsts,
     UBaseIdents, UExtIdents,
     UMakeDoc, UCommentDoc,
     UFormatCommentDoc, UBaseHTMLDoc;




   { * * *  ***  * * *  ***   THTMLDoc   ***  * * *  ***  * * *  }



type

  //the different kinds of lists of identifiers in a file to write
  TWriteKind = (
                wkVar,        //list of all variables
                wkThreadVar,  //list of all thread-variables
                wkConst,      //list of all constants
                wkResString,  //list of all resource-strings
                wkSimpleType, //list of all simple types (no record-likes)
                wkFunc);      //list of all functions (must be the last one)



  {This generator of documentation generates HTML (Hypertext Mark-Up Language)
   files. This is the first of all generators, explaining, why most of the
   inline commands are similar to the corresponding HTML-tags.~[br]
   A lot of HTML files (*.html) will be created in the directory for the
   documentation along with some images (*.gif) and a Cascading Style-Sheets
   file (DelphiDoc.css). The index-file is called "index.html". Just try to
   open it with a browser of your choice. }
  THTMLDoc = class(TBaseHTMLDoc)
  private
  protected


    //Creates a new HTML file and writes its header.
    procedure CreateFile(var F: TextFile;
                         const FileName, TitlePart, KeyWords: String);
                                                                      override;
    //Writes the footer of a HTML file and closes it.
    procedure EndFile(var F: TextFile); override;










    //Writes a list of the functions documented in the current file.
    procedure ShowFunctionList(var F: TextFile; List: TIdentifierList);







    //Writes a short linked list of the given kind of identifiers in the file.
    procedure WriteVarConstFuncsList(var F: TextFile; AFile: TPascalFile;
                                     WriteType: TWriteKind);
    //Writes a short linked list of the record-like types in the file.
    procedure WriteRecordTypeList(var F: TextFile; AFile: TPascalFile;
                                  Kind: TRecordKind);
    //Writes the documentation about all identifiers of the given kind in the
    //file.
    procedure WriteVarConstFuncs(var F: TextFile;
                                 List: TIdentifierList; WriteType: TWriteKind);

    //Writes the documentation about the file.
    procedure WriteFileDocumentation(AFile: TPascalFile); override;










    //Writes the documentation of members of a record-like type.
    procedure WriteMembers(var F: TextFile; const Heading: String;
                           Kind: TMemberKind; FuncKind: TFunctionKind;
                           Ident: TRecordType);
    //Writes the documentation of the record-like type.
    procedure WriteClassDocumentation(Ident: TRecordType); override;

















    //Begins the documentation.
    procedure StartDocumentation;
    //Ends the documentation.
    procedure EndDocumentation;



    //Generate the help on a GUI.
    function DoGenerateGUIHelp(LogFiles: TStrings): Boolean; override;
    //Generate only the user documentation.
    function DoGenerateOnlyUserDocumentation: Boolean; override;
    //Process parsed data; generate some documentation about it.
    function DoGenerateDocumentation: Boolean; override;
  public

    //Returns a description of the documentation of the generator.
    class function GetDescription: TGeneratorDescription; override;


    //Returns the capabilities of this class of the generators.
    class function Capabilities: TGeneratorCapabilities; override;


    //Returns the unique ID of an identifier to be used in the documentation.
    function GetURIOf(Ident: TIdentifier;
                      TheFile: TPascalFile = nil): String; override;
  end;



implementation


uses SysUtils,
{$IFNDEF LINUX}
     ShellAPI,
{$ENDIF}
     General,
     UDocumentDoc, UComments, 
     UDocumentationTexts;




   { * * *  ***  * * *  ***   THTMLDoc   ***  * * *  ***  * * *  }


{Returns a description of the documentation of the generator.
~result a description of the documentation of the generator }
class function THTMLDoc.GetDescription: TGeneratorDescription;
begin
 Result.Name := 'HTML Files';
 Result.Identification := 'HTML_old';
 Result.Description :=
  'A lot of HyperText Markup Language (HTML)-files (*.html) will be created in the given directory along with some images (*.gif), a cascading style sheet-file (DelphiDoc.css) and some Xfig- (*.fig) and WMF-files (*.wmf).' + LineDelimiter + 
  'The index-file is called "index.html". Just try to open it with a browser of your choice.';
end;




{Returns the capabilities of this class of the generators.
~result the capabilities of this class of the generators }
class function THTMLDoc.Capabilities: TGeneratorCapabilities;
begin
 Result := inherited Capabilities + [gcGUIHelp];
end;










{Returns the unique ID of an identifier or file to be used in the
 documentation, for instance to create a link to it.
~param Ident   the identifier to return a link to (nil, to return a link to the
               file)
~param TheFile the file, if it is not an identifier
~result the unique ID of the identifier or file }
function THTMLDoc.GetURIOf(Ident: TIdentifier;
                           TheFile: TPascalFile = nil): String;
var      TheClass         :TRecordType;        //the class to link to/in
begin
 assert(assigned(Ident) <> assigned(TheFile));
 assert(not DoNotDocumentIdentifier(Ident, TheFile));

 //not a record-like type or a member?
 if not assigned(Ident) or
    (not assigned(Ident.MemberOf) and not (Ident is TRecordType)) then
  begin
   if assigned(Ident) then
    TheFile := Ident.InFile;                //get the file

   Result := 'File_';                       //set file prefix
   if TheFile.InternalNameIndex <> 0 then   //add number of file and add the
    Result := Result + IntToStr(TheFile.InternalNameIndex);
   Result := Result + TheFile.InternalFileName + '.html'; //name and extension
  end
 else
  Result := '';                     //no URI so far

  
 if assigned(Ident) then          //link to an identifier?
  begin
   if Ident is TRecordType then     //get the record-like type
    TheClass := TRecordType(Ident)
   else
    TheClass := Ident.MemberOf;

   if assigned(TheClass) then       //is (in) a record-like type?
    begin
     //is not in the same HTML file or need link to its top
     if not assigned(CommentIdent) or
        ((TheClass <> CommentIdent) and (TheClass <> CommentIdent.MemberOf)) or
        (Ident = TheClass) then
      begin

       { Record-like types and their members are in extra files. }

       Result := DescFilePreFix[TheClass.Kind] + '_'; //add type of record-like
       if TheClass.InternalNameIndex <> 0 then       //add number of identifier
        Result := Result + IntToStr(TheClass.InternalNameIndex);
       Result := Result + TheClass.Name + '.html';     //add name and extension
      end;
    end
   else
    //is in the same (HTML) file and no link to its top needed?
    if (Ident.InFile = LinkFile) and not (LinkIdent is TRecordType) and
       (not assigned(LinkIdent) or not assigned(LinkIdent.MemberOf)) then
     Result := '';                                   //remove file part

   //now add the link (anchor) to the identifier in the HTML file, if needed
   if Ident <> TheClass then
    begin
     Result := Result + '#I_';                 //add identifier-anchor prefix
     if Ident.InternalNameIndex <> 0 then      //add index of the identifier
      Result := Result + IntToStr(Ident.InternalNameIndex);
     Result := Result + Ident.Name;            //and add name of the identifier
    end;
  end; //if assigned(Ident)
end;

















{Creates a new HTML file and writes its header.
~param F         the file variable to open the file with
~param FileName  the name of the file to create
~param TitlePart the title of the HTML page
~param KeyWords  the keywords of the HTML page in the index }
procedure THTMLDoc.CreateFile(var F: TextFile;
                              const FileName, TitlePart, KeyWords: String);
var       Title   :String;             //the title of the page
          Keys    :String;             //the list of key-words for the page
          //counter through all kinds of record-like types
          rk      :TRecordKind;
          i       :Integer;            //counter through all characters
begin
 AssignFile(F, FDestPath + FileName + '.html');
 Rewrite(F);                           //open the file
 try
   if FProjectName <> '' then          //name of project defined?
    //append it to the title
    Title := TitlePart + ' - ' + HandleRawText(FProjectName)
   else
    Title := TitlePart;

   Keys := KeyWords;
   for i := 1 to Length(Keys) do       //translate all ";" to ","
    if Keys[i] = ';' then
     Keys[i] := ',';

   if TextHeaderFile <> '' then        //custom header supplied?
    WriteFileHeader(F, Title, Keys, '')  //write it
   else
    begin
     WriteLn(F, DTD_Text);                 //write the DTD of the files
     WriteLn(F, '<html>');
     WriteLn(F, '<head>');
     WriteLn(F, '  <meta http-equiv="Content-Type" content="text/html; charset=',
                CharacterEncoding, '">');
     WriteLn(F, '  <meta http-equiv="Content-Style-Type" content="text/css">');
     WriteLn(F, '  <title>', Title,        //write the title of the page
                ' - JADD - Just Another DelphiDoc</title>');
     if Keys <> '' then
      WriteLn(F, '  <meta name="keywords" content="', HandleRawText(Keys),
                 '">');
     WriteLn(F, '  <meta name="Generator" content="JADD - Just Another DelphiDoc">');
     WriteLn(F, '  <link rel="stylesheet" type="text/css" href="',
                CSSFileName, '" title="Style">'); //include CSS file
     WriteLn(F, '</head>');
     WriteLn(F, '<body>');
     //write links to main files
     WriteLn(F, '<table width="100%" class=headerlinks><tr>');
     WriteLn(F, '<td align=center><a href="index.html">',  //link to main index
                Localize(dtDocumentationLinkIndex), '</a></td>');

     //only if this kind of documentation is generated
     if GenerationKind = dgkDelphiDoc then
      begin                              //generate links to files and type
       //link to list of files
       WriteLn(F, '<td align=center><a href="FileList.html">',
                  Localize(dtDocumentationLinkFiles), '</a></td>');