uwinhelpfiles.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 UWinHelpFiles;

{Contains some functions for the documentation generator
 ~[linkClass UWinHelpDoc.TWinHelpDoc], that generates documentation about the
 parsed data in a Windows Help project to compile it to a Windows Help
 file.~[br]
 The functions are primarily for additional files needed for the help files,
 this is for one this is the project files used to assemble and compile the
 needed data and general information, and also functions to create SHG files
 as bitmaps with multiple hot-spots (links) in it.
}

interface

uses Windows, Classes,
{$IFNDEF LINUX}
     Graphics;
{$ELSE}
     QGraphics;
{$ENDIF}





const DefaultHelpFileName = 'DelphiDoc'; //file name of the help file
      HelpFileExtension = '.hlp';        //extension of the help file
      //extension of file with the table of contents
      ContentFileExtension = '.cnt';
      RTFFileExtension = '.rtf';         //extension of the main file
      HPJFileExtension = '.hpj';         //extension of the help project file
      LogFileExtension = '.log';         //extension of compilation log file

      //format of the names of the RTF files to be generated
      RTFFileNameFormat = 'DelphiDoc%s' + RTFFileExtension;
      //format of the names of the help project files to be generated
      HPJFileNameFormat = 'DelphiDoc%s' + HPJFileExtension;
      //format of the names fo the help project files to be generated
      HelpContextMappingFileNameFormat = 'DelphiDoc%s.hcx';
      //format of the names of the log files from compiling the help projects
      HelpCompileLogFileNameFormat = 'DelphiDoc%s' + LogFileExtension;

{
      RTFFileBaseName = 'DelphiDoc';     //base file name of the main file
      HPJFileBaseName = 'DelphiDoc';     //base file name of the help project
      //file name with mapping from help contexts to topics
      HelpContextMappingFileName = 'DelphiDoc.hcx';
}
      //file name with mapping from help contexts to the files containing them
      HelpContextFileNameMappingFileName = 'HelpContextFileMap.ini';



      //the three help windows used in the help file
type  THelpWindow = (
                     hwMain,     //the main window
                     //window showing identifiers inside the identifier of the
                     hwClassSub, //main window
                     hwExample); //shows examples of identifiers


      //the names of the used windows in the generated help file
const HelpWindowNames: array[THelpWindow] of String =
                       ('Main', 'ClassSub', 'Example');






//Writes a simple file mapping help contexts to the files containing them.
procedure GenerateHelpContextFileMappingFile(Mapping: TStrings;
                                             const DestPath: String);





//Write the help project file (DelphiDoc.hpj).
procedure WriteHelpProjectFile(const DestPath, FileNameExtra,
                                     CNTFileName, HLPFileName,
                                     Title, DefaultTopic: String;
                               FileCompression: Boolean);

//Appends the mapping of help contexts to topics to the help project file.
procedure WriteHelpContexts(const DestPath, FileNameExtra: String;
                            Contexts: TStringList;
                            const HLPFileName: String; FilterWith: TStrings);




//Parses the log of a compilation of the Windows Help file.
function ParseHelpCompileLogFile(const LogFileName, HPJFileName: String;
                                 var FilteredLog: String): Boolean;





//Calculates the hash value of a name of a topic in the help file.
function GetTopicNameHashValue(const TopicName: String): String;

//Creates a Segmented Hyper-Graphic file from a bitmap and a list of hot
//spots.
procedure CreateSegmentedHyperGraphic(BMP: TBitmap; const BMPFileName: String;
                                      HotSpots: TStrings;
                                      const SHGFileName: String);


//Returns the position of a link region in SHG format.
function GetSHGRectString(Rect: TRect): String;










implementation


uses SysUtils,
     General,
     UDocumentationTexts;





//{$DEFINE UseRunLength}
//{$DEFINE UseLZ77}




{$IFDEF UseRunLength}
 {$DEFINE UseSomeCompression}
{$ENDIF}
{$IFDEF UseLZ77}
 {$DEFINE UseSomeCompression}
{$ENDIF}



//Writes the compressed content of the bitmap into the stream.
procedure GetCompressedBitmapContent(Bitmap: TBitmap;
                                     Compressed: TMemoryStream); forward;

















{Writes a simple file mapping help contexts to the files containing them.
~param Mapping  the mapping from the help contexts in the objects to the files,
                the files are the strings, the help contexts are in the objects
~param DestPath directory to create the file in }
procedure GenerateHelpContextFileMappingFile(Mapping: TStrings;
                                             const DestPath: String);
var       IniFile    :Textfile;      //the file to be written
          SingleName :String;        //name of the first file in the list
          i          :Integer;       //counter through all entries
begin
 //create and open the file
 AssignFile(IniFile, DestPath + HelpContextFileNameMappingFileName);
 Rewrite(IniFile);
 try
   WriteLn(IniFile, '[ContextFileMapping]');  //start section for the mapping
   if Mapping.Count > 0 then
    begin
     SingleName := Mapping[0];         //get the first name
     i := Mapping.Count - 1;           //check the whole list for other entries
     while (i >= 1) and (Mapping[i] = SingleName) do
      Dec(i);
     if i = 0 then                     //only one file used?
      WriteLn(IniFile, 'all=', SingleName);     //create special entry

     for i := 0 to Mapping.Count - 1 do //write the mapping
      WriteLn(IniFile, THelpContext(Mapping.Objects[i]), '=', Mapping[i]);
    end;
 finally
  CloseFile(IniFile);             //close the file
 end;
end;



















{Write the help project file (DelphiDoc.hpj).
~param DestPath        directory to create the documentation in
~param FileNameExtra   additional part for the names of the different files
~param CNTFileName     the name of the Content file for the Windows Help file
~param HLPFileName     the name of the Windows Help file to be generated
~param Title           title of the help file
~param DefaultTopic    the topic to show when simply opening the Help file
~param FileCompression if the help file should be compressed }
procedure WriteHelpProjectFile(const DestPath, FileNameExtra,
                                     CNTFileName, HLPFileName,
                                     Title, DefaultTopic: String;
                               FileCompression: Boolean);
var       HPFFile     :TextFile;  //the file to write
          UsedTitle   :String;    //the title to write
          i           :Integer;   //index of double quote chracters '"'
begin
 //create and open the file
 AssignFile(HPFFile, DestPath + Format(HPJFileNameFormat, [FileNameExtra]));
 Rewrite(HPFFile);
 try
   WriteLn(HPFFile, '[OPTIONS]');               //write general options
   WriteLn(HPFFile, 'ERRORLOG=.\',
                    Format(HelpCompileLogFileNameFormat, [FileNameExtra]));
   WriteLn(HPFFile, 'LCID=0x409 0x0 0x0 ; Englisch (USA)');
   WriteLn(HPFFile, 'REPORT=Yes');
   WriteLn(HPFFile, 'CONTENTS=', DefaultTopic);

   Write(HPFFile, 'TITLE=');                    //write title of the help file
   UsedTitle := Title;
   if UsedTitle <> '' then
    UsedTitle := UsedTitle + ' - ';
   UsedTitle := UsedTitle +
                'Helpfile generated by JADD - Just Another DelphiDoc';
   WriteLn(HPFFile, Copy(UsedTitle, 1, 50));

   WriteLn(HPFFile, 'COPYRIGHT=', DocumentationTexts[dtWinHelpCompiledAt].T);

   //use this content file
   WriteLn(HPFFile, 'CNT=', CNTFileName);

   if FileCompression then                       //compression not disabled?
    WriteLn(HPFFile, 'COMPRESS=12 Hall Zeck');     //set maxmimum compression

   //will be added when copy&pasting (I think this can be really annoying)
//   WriteLn(HPFFile, 'CITATION=Generated with DelphiDoc');

   WriteLn(HPFFile, 'HLP=.\', HLPFileName);
   WriteLn(HPFFile);

   WriteLn(HPFFile, '[FILES]');                  //write source RTF files
   //just this one
   WriteLn(HPFFile, '.\', Format(RTFFileNameFormat, [FileNameExtra]));
   WriteLn(HPFFile);



   //define all windows used in this help file
   WriteLn(HPFFile, '[WINDOWS]');

// WriteLn(HPFFile, 'Main="Help generated with DelphiDoc",,27904,,(r12632256),f2');
   Write(HPFFile, HelpWindowNames[hwMain], '="');

   UsedTitle := Title;
   if UsedTitle <> '' then              //get title of main window
    begin
     i := Pos('"', UsedTitle);            //double quotes are not allowed
     while i <> 0 do
      begin
       Delete(UsedTitle, i, 1);             //delete all double quotes
       i := SearchString('"', UsedTitle, i);
      end;
    end;

   //there is a maximum length on window titles
   if Length(UsedTitle) <= 43 then      //if possible add a generator notice
    begin
     case Length(UsedTitle) of
        1..15: UsedTitle := UsedTitle + ' - by JADD - Just Another DelphiDoc';
       16..17: UsedTitle := UsedTitle + ' - by JADD-Just Another DelphiDoc';
           18: UsedTitle := UsedTitle + ' - JADD - Just Another DelphiDoc';
       19..20: UsedTitle := UsedTitle + ' - JADD-Just Another DelphiDoc';
       21..28: UsedTitle := UsedTitle + ' - by JADD - DelphiDoc';
       29..30: UsedTitle := UsedTitle + ' - by JADD-DelphiDoc';
           31: UsedTitle := UsedTitle + ' - JADD - DelphiDoc';
       32..33: UsedTitle := UsedTitle + ' - JADD-DelphiDoc';
       34..40: UsedTitle := UsedTitle + ' - by JADD';
       41..43: UsedTitle := UsedTitle + ' - JADD';
     else