uichtmlhelpdoc.pas

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

   if (Ident is TProperty) and TProperty(Ident).IsReadOnly then
    FHTMLFile.WriteString(FGenerator.GetReadOnlyIcon);
   //if it is an abstract method, write an indicating icon
   if (Ident is TFunction) and (faAbstract in TFunction(Ident).Attributes) then
    FHTMLFile.WriteString(FGenerator.GetAbstractIcon);
  end;

 //write its portability issues
 FHTMLFile.WriteString(FGenerator.GetPortabilityIssues(Ident.Portability));

 FHTMLFile.WriteCharacter(' ');

 if not IsMember and (Ident is TType) then //if it is a simple type
  begin                                      //write the name of the identifier
   FHTMLFile.WriteString(Ident.Name);
   FHTMLFile.WriteString(' = ');
  end;

 VisitChildren := False;                   //write the declaration
 Node.VisitChildren(Self);

 FHTMLFile.WriteString('</p>');
 FHTMLFile.WriteString(FGenerator.NewLine);
end;















    //list for the option "UseSubdirectories" of the generator
    //~[link TICHTMLHelpDoc]
var OptionItemsUseSubdirectories: TStringList = nil;



   { * * *  ***  * * *  ***   TICHTMLHelpDoc   ***  * * *  ***  * * *  }




{Creates the generator object and the visitor and initializes its fields. }
constructor TICHTMLHelpDoc.Create;
begin
 inherited Create;                             //create the object

 FVisitor := TICHTMLHelpVisitor.Create(Self);  //create the visitor

 FHelpFileName := DefaultCHMFileName;          //set default name of help file
end;



{Returns a description of the documentation of the generator.
~result a description of the documentation of the generator }
class function TICHTMLHelpDoc.GetDescription: TGeneratorDescription;
begin
 Result.Name := 'HTML Help File (.chm)';
 Result.Identification := 'HTMLHelp';
 Result.Description :=
  'A compiled help file (.chm) is generated from a lot of HyperText Markup Language (HTML)-files (*.html), some images (*.gif), a cascading style sheet-file (DelphiDoc.css) and some additional diagram images.' + LineDelimiter +
  'CHM files are the new Windows help format. To compile it you need the HMTL Help Workshop, you can download the "htmlhelp.exe" at http://go.microsoft.com/fwlink/?LinkId=14188 .';
end;




{Returns the number of available options in generators of this class.
~result the number of available "expert"-options
~see GetOptionDescription
~see GetOption
~see SetOption }
class function TICHTMLHelpDoc.GetOptionCount: Cardinal;
begin
 Result := inherited GetOptionCount + 4;
end;

{Gets a description of an "expert"-option.
~param Index index of the option to get data of
~param Desc  out: the description of the option (name, type, default value,
                  etc.)
~see GetOptionCount }
class procedure TICHTMLHelpDoc.GetOptionDescription(Index: Cardinal;
                                                 var Desc: TOptionDescription);
var             PreOptionCount :Cardinal;  //number of options in parent class
begin
 PreOptionCount := inherited GetOptionCount; //get number of options in parent
 if Index < PreOptionCount then              //an option in the parent class?
  inherited GetOptionDescription(Index, Desc)  //forward to parent's method
 else
  begin
   ClearDescription(Desc);               //clear structure
   case Index - PreOptionCount of        //depending on index of option
     0: begin                            //set the values describing the option
         Desc.Name := 'HelpCompilerPath';
         Desc.Category := 'Postprocessing';
         Desc.Description := 'The path and name of the help compiler "hhc.exe".';
         Desc.DataType := otString;
         Desc.DefaultValue.StrData := '';
        end;
     1: begin
         Desc.Name := 'AutoCompileHelpProject';
         Desc.Category := 'Postprocessing';
         Desc.Description := 'Compile the help project after generation.';
         Desc.DataType := otBoolean;
         Desc.DefaultValue.BoolData := False;
        end;
     2: begin
         Desc.Name := 'FileName';
         Desc.Category := '';
         Desc.Description := 'The name of the HTML Help file to be generated.';
         Desc.DataType := otString;
         Desc.DefaultValue.StrData := DefaultCHMFileName;
        end;
     3: begin
         Desc.Name := 'UseSubdirectories';
         Desc.Category := 'Generation';
         Desc.Description := 'Spread the source HTML files in several sub-directories?';
         Desc.DataType := otEnumeration;
         Desc.EnumNames := OptionItemsUseSubdirectories;
         Desc.DefaultValue.EnumData := 0;
        end;
   else
    Assert(Index >= GetOptionCount);
    raise EInvalidOption.Create('Invalid index for option supplied!');
   end;
 end;
end;

{Gets the value of an option. Call ~[link GetOptionDescription] to get the type
 and the meaning of the option.
~param Index index of the option to get the value of
~result the value of the option
~see GetOptionCount
~see GetOptionDescription
~see SetOption }
function TICHTMLHelpDoc.GetOption(Index: Cardinal): TOptionValue;
var      PreOptionCount        :Cardinal;    //number of options in parent class
begin
 PreOptionCount := inherited GetOptionCount; //get number of options in parent
 if Index < PreOptionCount then              //an option in the parent class?
  Result := inherited GetOption(Index)         //forward to parent's method
 else
  begin
   case Index - PreOptionCount of              //depending on index of option
     0: Result.StrData := FHelpCompilerPath;     //get the value
     1: Result.BoolData := FAutoCompile;
     2: Result.StrData := FHelpFileName;
     3: Result.EnumData := Ord(FUseSubdirectories);
   else
    Assert(Index >= GetOptionCount);
    raise EInvalidOption.Create('Invalid index for option supplied!');
   end;
  end;
end;

{Sets the value of an option. Call ~[link GetOptionDescription] to get the type
 and the meaning of the option.
~param Index index of the option to set the value
~param Value the new value of the option
~see GetOptionCount
~see GetOptionDescription
~see GetOption }
procedure TICHTMLHelpDoc.SetOption(Index: Cardinal; const Value: TOptionValue);
var       PreOptionCount        :Cardinal;   //number of options in parent class
begin
 PreOptionCount := inherited GetOptionCount; //get number of options in parent
 if Index < PreOptionCount then              //an option in the parent class?
  inherited SetOption(Index, Value)            //forward to parent's method
 else
  case Index - PreOptionCount of               //depending on index of option
    0: FHelpCompilerPath := Value.StrData;       //set the value
    1:
{$IFNDEF LINUX}
       FAutoCompile := Value.BoolData
{$ENDIF}
       ;
    2: FHelpFileName := Trim(Value.StrData);
    3: if (Value.EnumData >= Ord(Low(TSubDirectoryUsage))) and
          (Value.EnumData <= Ord(High(TSubDirectoryUsage))) then
        FUseSubdirectories := TSubDirectoryUsage(Value.IntData);
  else
   Assert(Index >= GetOptionCount);
   raise EInvalidOption.Create('Invalid index for option supplied!');
  end;
end;





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







{Returns the unique ID of an identifier to be used in the documentation, for
 instance to create a link to 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
~result the unique ID of the identifier }
function TICHTMLHelpDoc.GetURIOf(Ident: TIdentifier;
                                 TheFile: TPascalFile = nil): String;
var      TheRecord     :TRecordType;   //the record-like type to link to
         LinkRecord    :TRecordType;   //the record-like type to link from
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 Assigned(CommentIdent) then
    if CommentIdent is TRecordType then
     LinkRecord := TRecordType(CommentIdent)
    else
     LinkRecord := CommentIdent.MemberOf
   else
    LinkRecord := nil;



   //currently in a sub-directory and another one?
   if not AddingDiagram and
      Assigned(CommentFile) and (TheFile <> CommentFile) then
    Result := '../'                        //go back to the main directory
   else
    Result := '';
   //currently in a sub-sub-directory and another one?
   if not AddingDiagram and (FUseSubdirectories = sduFilesAndTypes) and
      (Assigned(LinkRecord) and (TheRecord <> LinkRecord)) then
    Result := Result + '../';              //go back/up one directory


   //another file, need sub-directory?
   if AddingDiagram or (TheFile <> CommentFile) then
    begin
     //the name of the file (and its number) as the sub-directory
     Result := Result + TheFile.InternalFileName;
     if TheFile.InternalNameIndex <> 0 then
      Result := Result + '.' + IntToStr(TheFile.InternalNameIndex);
     Result := Result + '/';
    end;

   if Assigned(TheRecord) then           //if in record-like type
    if FUseSubdirectories <> sduFilesAndTypes then //in same directory?
     Result := Result + 'I_' + TheRecord.Name   //add prefix & record-like type
    else
     if AddingDiagram or (TheRecord <> LinkRecord) then  //different type?
      Result := Result + TheRecord.Name + '/';             //add sub-directory

   //identifier in file/record-like type?
   if Assigned(Ident) and (Ident <> TheRecord) then
    begin
     //is member of 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(TheRecord) 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

 //add the file extension ".html"
 Result := Result + FileExtension;
end;


{Gets the (internal) identification (for links) of pages in the user
 documentation.
~param PageIndex the number of the page (-1 for index)
~result the identification (internal URI (without file extension)) of the page
}
function TICHTMLHelpDoc.GetPageURI(PageIndex: Integer): String;
begin
 Result := inherited GetPageURI(PageIndex); //get URI
 //in a sub-directory?
 if (FUseSubdirectories <> sduNone) and Assigned(CommentFile) then
  begin
    Result := '../' + Result;                 //go back to main directory
   //currently in another sub-directory and need another one?
   if (FUseSubdirectories = sduFilesAndTypes) and Assigned(CommentIdent) and
      (Assigned(CommentIdent.MemberOf) or (CommentIdent is TRecordType)) then
    Result := '../' + Result;                   //go back another directory
  end;
end;


{Includes an image in the documentation.
~param CharFormat      if the image should be included as a simple
                       character instead of centered in an own paragraph
~param JPEGFormat      if the file should be converted to JPEG instead of
                       PNG (only for HTML formats)
~param Resolution      resolution to use, (0,0) means auto-detect;
                       only for JPEG images for PDF-generator if no JPEG
                       support is available
~param BMP             the image to include or nil
~param FileName        the name of the file with the image to include, if BMP
                       is nil
~param Links           list of links inside the image
~param AlternativeText alternative text/description of the image
~result the format to include the image }
function TICHTMLHelpDoc.WriteImage(CharFormat, JPEGFormat: Boolean;
                                   Resolution: TPoint;
                                   BMP: TBitmap; const FileName: String;
                                   Links: TImageLinkList;
                                   const AlternativeText: String): String;
begin
 Inc(FGeneratedFileCount);             //count the image file

 //write the image
 Result := inherited WriteImage(CharFormat, JPEGFormat, Resolution,
                                BMP, FileName, Links, AlternativeText);
end;


{Writes the links to the generated files by ~[link WriteFileTreeFiles].
~param F the file to write the links to }
procedure TICHTMLHelpDoc.WriteFileListFileLinks(F: TBufferStream);
          //runner through file formats