uwinhelpdoc.pas

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

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


    //Returns the number of available options in generators of this class.
    class function GetOptionCount: Cardinal; override;
    //Gets a description of an option.
    class procedure GetOptionDescription(Index: Cardinal;
                                         var Desc: TOptionDescription);
                                                                      override;
    //Gets the value of an option.
    function GetOption(Index: Cardinal): TOptionValue; override;
    //Sets the value of an option.
    procedure SetOption(Index: Cardinal; const Value: TOptionValue); override;


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





    //Handles text by encoding special characters.
    function HandleRawText(const Text: String): String; override;

    //Returns the text in the format; text may already include other formats.
    function FormatText(TextFormat: TDocumentationTextFormat;
                        const Text: String;
                        var SkipWhitespaces: Boolean): String; override;

    //Gets the (internal) identification (for links) of pages in the user
    //documentation.
    function GetPageURI(PageIndex: Integer): String; override;

    //Writes a link to an identifier or file in the documentation.
    function InternalLink(const URI, LinkLabel: String): String; override;
    //Writes a link to an external URI.
    function ExternalLink(const URI, LinkLabel: String): String; override;

    //Includes an image in the documentation.
    function WriteImage(CharFormat, JPEGFormat: Boolean; Resolution: TPoint;
                        BMP: TBitmap; const FileName: String;
                        Links: TImageLinkList;
                        const AlternativeText: String): String; override;







{$IFNDEF LINUX}
    //Searches the help compiler and returns its path.
    function SearchHelpCompiler: String;
{$ENDIF}

    //Resets the attributes to ready the generator for a new generation.
    procedure ResetForNewGeneration; override;
  end;




implementation

uses SysUtils,
{$IFNDEF LINUX}
     ShellAPI, Registry, Forms,
{$ENDIF}
{$IFDEF VER120}
     FileCtrl,
{$ENDIF}
     General,
     UExtIdents,
     UDocumentDoc,
     UDocumentationTexts;












   { * * *  ***  * * *  ***   TWinHelpDoc   ***  * * *  ***  * * *  }







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


 FHelpFileName := DefaultHelpFileName;         //set name of help file
end;














{Will be called for all reserved words. They are all formatted in a bold font,
 but "string" will just be replaced with a not bold "String".
~param Word a string of one ore more reserved words
~result Word formatted as reserved words }
function TWinHelpDoc.ReservedWord(const Word: String): String;
begin
 if Word = 'string' then           //is string?
  Result := 'String'                 //use this upper case variant, not bold
 else
  Result := '{\b ' + Word + '}';   //format the word bold
end;





{Returns a description of the documentation of the generator.
~result a description of the documentation of the generator }
class function TWinHelpDoc.GetDescription: TGeneratorDescription;
begin
 Result.Name := 'Windows Help File (.hlp)';
 Result.Identification := 'WinHelp_old';
 Result.Description :=
  'A Rich Text Format (RTF)-file containing the documentation (DelphiDoc.rtf) and a Help Project File (DelphiDoc.hpj) to compile this to a Help file (DELPHIDOC.HLP) will be created. Several images (*.bmp/*.shg) will also be created.'#13#10 +
  'These files are all temporary and can be deleted after compiling the Help file.'#13#10 +
  'To compile the Help file open DelphiDoc.hpj with the Microsoft Help Workshop and compile it (simplest: press "Save and Compile"). The in this process created Log-file (HelpCompile.log) can also be deleted.'#13#10 +
  'The Microsoft Help Workshop can be found in the Delphi-directory in \Help\Tools\ or at ftp://ftp.microsoft.com/softlib/mslfiles/hcwsetup.exe'#13#10 +
  'The also created Xfig- (*.fig) and WMF-files (*.wmf) can be kept with the Help file.';
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 TWinHelpDoc.GetOptionCount: Cardinal;
begin
 Result := inherited GetOptionCount + 5;
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 TWinHelpDoc.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 := 'DontOverrideProjectFile';
         Desc.Category := 'Generation';
         Desc.Description := 'Creates the help project file only if it does not exist yet.';
         Desc.DataType := otBoolean;
         Desc.DefaultValue.BoolData := False;
        end;
     1: begin
         Desc.Name := 'DisableHelpFileCompression';
         Desc.Category := 'Generation';
         Desc.Description := 'Disables compression of the help file (a bit faster, but the help file will be more than twice the size).';
         Desc.DataType := otBoolean;
         Desc.DefaultValue.BoolData := False;
        end;
     2: begin
         Desc.Name := 'HelpCompilerPath';
         Desc.Category := 'Postprocessing';
         Desc.Description := 'The path and name of the help compiler "hcrtf.exe".';
         Desc.DataType := otString;
         Desc.DefaultValue.StrData := '';
        end;
     3: begin
         Desc.Name := 'AutoCompileHelpProject';
         Desc.Category := 'Postprocessing';
         Desc.Description := 'Compile the help project after generation.';
         Desc.DataType := otBoolean;
         Desc.DefaultValue.BoolData := False;
        end;
     4: begin
         Desc.Name := 'FileName';
         Desc.Category := '';
         Desc.Description := 'The name of the Windows Help File to be generated.';
         Desc.DataType := otString;
         Desc.DefaultValue.StrData := DefaultHelpFileName;
        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 TWinHelpDoc.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.BoolData := FDontOverrideProjectFile;  //get the value
     1: Result.BoolData := FDisableHelpFileCompression;
     2: Result.StrData := FHelpCompilerPath;
     3: Result.BoolData := FAutoCompile;
     4: Result.StrData := FHelpFileName;
   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 TWinHelpDoc.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: FDontOverrideProjectFile := Value.BoolData; //set the value
    1: FDisableHelpFileCompression := Value.BoolData;
    2: FHelpCompilerPath := Value.StrData;
    3:
{$IFNDEF LINUX}
       FAutoCompile := Value.BoolData
{$ENDIF}
       ;
    4: FHelpFileName := Trim(Value.StrData);
  else
   assert(Index >= GetOptionCount);
   raise EInvalidOption.Create('Invalid index for option supplied!');
  end;
end;








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











{Returns the text formatted in the format of the documentation. Any special
 characters are encoded so the text will appear as is.
~param Text the text to "quote" in the format
~result the encoded text }
function TWinHelpDoc.HandleRawText(const Text: String): String;
var      p          :PChar;      //runner through the text
         LineBreak  :Boolean;    //if line breaks should be kept
begin
 Result := '';                   //no text encoded so far
 if Text <> '' then              //text not empty?
  begin
   LineBreak := KeepRawLineBreaks; //get if line breaks should be kept
   p := Pointer(Text);
   while p^ <> #0 do               //for each character in the text
    begin
     case p^ of
       #10:           if LineBreak then
                       //treat new-line as a new-line
                       Result := Result + #10'\line '
                      else
                       //treat new-line as whitespace
                       Result := Result + #10' ';
       '\', '{', '}': Result := Result + '\' + p^;   //quote with a backslash
                      //quote hexadecimal
       #128..#255:    Result := Result + Format('\''%.2x', [ord(p^)]);
     else
      Result := Result + p^;         //just add the character
     end;
     inc(p);                       //next character
    end; //while p^ <> #0
  end; //if Text <> ''
end;



{Returns the text in the format; text may already include other formats.
~param TextFormat      the format the text should be in
~param Text            the text to format
~param SkipWhitespaces out: if following white spaces should be
                            skipped/ignored
~result the formatted text }
function TWinHelpDoc.FormatText(TextFormat: TDocumentationTextFormat;