== Creating and Using HTML Help (.CHM) Files ==

==Generate Files Using Doxygen==



===Setup Doxygen===
* [[http://www.microsoft.com/downloads/details.aspx?familyid=00535334-c8a6-452f-9aa0-d597d16580cc&displaylang=en|Download the HTML Help Compiler from Microsoft]]  and install it to ''C:\Program Files\HTMLHelp''.
* Make sure ezfit5/UserDoc/proj.cfg HHC_LOCATION property is set to the correct location.
* <del>Download Doxygen files from http://www.doxygen.org and install them.</del>
* <del>Download pas2dox from http://pas2dox.sourceforge.net</del>
* <del>Copy pas2dox executable into the same folder where doxygen was installed (by default ''C:\Program Files\doxygen\bin'').</del>
* Verify that the following preprocessor setting is enabled in the doxygen configuration file (for example, proj.cfg) used in a Delphi/Pascal project:
<code delphi>
...
ENABLE_PREPROCESSING   = YES
...
</code>

===Doxygen Configuration===
* Generate a configuration file (such as proj.cfg) by calling doxygen with the -g option: 
<code delphi>
doxygen -g <config_file>
</code>

* The doxygen configuration file (for example, proj.cfg) should have at least the following settings:
<code bash>
PROJECT_NAME           = "MyApplication"
PROJECT_NUMBER         = 1.0
OUTPUT_DIRECTORY       =
FILE_PATTERNS          = *.pas *.txt
IMAGE_PATH             = images
FILTER_SOURCE_FILES    = YES
ALPHABETICAL_INDEX     = YES

#---------------------------------------------------------------------------
# configuration options related to the HTML output
#---------------------------------------------------------------------------
GENERATE_HTML          = YES
HTML_OUTPUT            = html
HTML_FILE_EXTENSION    = .html
HTML_HEADER            = header.html
HTML_FOOTER            = footer.html
HTML_ALIGN_MEMBERS     = YES
GENERATE_HTMLHELP      = YES
CHM_FILE               = UserDoc.CHM
#HHC_LOCATION           = "C:\Program Files\accviz\help\hc\hhc.exe"
HHC_LOCATION           = "C:\Program Files\HTMLHelp\hhc.exe"
GENERATE_TREEVIEW      = YES

#---------------------------------------------------------------------------
# configuration options related to the LaTeX output
#---------------------------------------------------------------------------
GENERATE_LATEX         = YES
LATEX_OUTPUT           = latex
LATEX_CMD_NAME         = latex
MAKEINDEX_CMD_NAME     = makeindex
COMPACT_LATEX          = NO
PAPER_TYPE             = letter
PDF_HYPERLINKS         = YES
USE_PDFLATEX           = NO
LATEX_BATCHMODE        = YES
LATEX_HIDE_INDICES     = YES

#---------------------------------------------------------------------------
# configuration options related to the RTF output
#---------------------------------------------------------------------------
GENERATE_RTF           = YES
RTF_OUTPUT             = rtf
COMPACT_RTF            = NO
RTF_HYPERLINKS         = YES

#---------------------------------------------------------------------------
# Configuration options related to the preprocessor   
#---------------------------------------------------------------------------
ENABLE_PREPROCESSING   = YES

#--------------------------------------------------------------------------
# Custom Configuration files and Custom Variables
# Use variables as usual. For example: @CompanyName or \CompanyName
#--------------------------------------------------------------------------
ALIASES = "CompanyName=ACME, Inc." \
          "CompanyNameShort=ACME" \
          "CompanyWebsite=http://www.acme.com" \
          "CompanyLogoJPG=splash01.jpg" \
          "CompanyLogoEPS=splash01.eps" 
@INCLUDE_PATH = includes
@INCLUDE      = customproj.cfg

...
</code>

For software customization, create a ''includes\customproj.cfg'' file with the settings to override.  For example:
<code bash>
#--------------------------------------------------------------------------
# Custom Settings
#--------------------------------------------------------------------------
OUTPUT_DIRECTORY  = customoutput\transear
IMAGE_PATH        = images custom\images
ENABLED_SECTIONS  = StandaloneOnly Acme
HTML_HEADER       = includes\header.html
HTML_FOOTER       = includes\footer.html
CHM_FILE          = UserDoc.CHM

#--------------------------------------------------------------------------
# Custom Variables
#--------------------------------------------------------------------------
ALIASES = "CompanyName=ACME 2, Inc." \
          "CompanyNameShort=ACME 2" \
          "CompanyWebsite=http://www.acme2.com" \
          "CompanyLogoJPG=ezfit-splash01-acme2.jpg" \
          "CompanyLogoEPS=ezfit-splash01-acme2.eps" 

</code>


After this, you can run doxygen to generate help files using the following command:
<code delphi>
doxygen <config_file>
</code>
=== Generating PDF File ===

Download and install the required software:
  * Ghostscript (http://sourceforge.net/projects/ghostscript)
  * MiKTeX (http://www.miktex.org)

Create default Makefile (here it is called ''LatexMakefile''):
<code dos>
all: clean refman.dvi

ps: refman.ps

pdf: refman.pdf

ps_2on1: refman_2on1.ps

pdf_2on1: refman_2on1.pdf

refman.ps: refman.dvi
	C:\apps\miktex\miktex\bin\dvips -o refman.ps refman.dvi

refman.pdf: refman.ps
	"C:\Program Files\gs\gs8.71\bin\gswin32c" -q -dNOPAUSE -dBATCH -sDEVICE=pdfwrite -sOutputFile=refman.pdf -c save pop -f refman.ps

refman.dvi: refman.tex doxygen.sty
	echo "Running latex..."
	C:\apps\miktex\miktex\bin\latex refman.tex
	echo "Running makeindex..."
	C:\apps\miktex\miktex\bin\makeindex refman.idx
	echo "Rerunning latex...."
	C:\apps\miktex\miktex\bin\latex refman.tex

refman_2on1.ps: refman.ps
	C:\apps\miktex\miktex\bin\psnup -2 refman.ps >refman_2on1.ps

refman_2on1.pdf: refman_2on1.ps
	"C:\Program Files\gs\gs8.71\bin\gswin32c" -q -dNOPAUSE -dBATCH -sDEVICE=pdfwrite -sOutputFile=refman_2on1.pdf -c save pop -f refman_2on1.ps

clean:
	del -f *.ps *.dvi *.aux *.toc *.idx *.ind *.ilg *.log *.out *.pdf
</code>

Run a batch file:
<code dos>
REM ----------------------------------------------------------
REM script: make.bat
REM date  : 2006 jun
REM programmer: Siegwart Mayr
REM Description:
REM Make HTML, CHM, and PDF versions of the documentation
REM ----------------------------------------------------------
REM Requirements: 
REM - Microsoft HTML Help Compiler
REM - Doxygen (http://www.doxygen.org)
REM - Pas2dox.exe (http://pas2dox.sourceforge.net)
REM - Ghostscript (http://sourceforge.net/projects/ghostscript)
REM - MiKTeX (http://www.miktex.org)
REM ----------------------------------------------------------
@cls

@echo --- create HTML, CHM, and LaTEX documentation ---
doxygen proj.cfg

@echo --- create PDF document version ---
copy /Y LatexMakefile latex\Makefile 
@cd latex

REM --- Create PDF using Makefile (Optional) ---
REM make all
REM make ps
REM make pdf
REM make ps_2on1
REM make pdf_2on1

REM --- Creating PDF using commands directly ---
@echo "Running latex..."
C:\apps\miktex\miktex\bin\latex refman.tex
@echo "Running makeindex..."
C:\apps\miktex\miktex\bin\makeindex refman.idx
@echo "Rerunning latex...."
C:\apps\miktex\miktex\bin\latex refman.tex
@echo "Creating PDF from latex...."
C:\apps\miktex\miktex\bin\pdflatex refman.tex
C:\apps\miktex\miktex\bin\dvips -o refman.ps refman.dvi
"C:\Program Files\gs\gs8.71\bin\gswin32c.exe" -q -dNOPAUSE -dBATCH -sDEVICE=pdfwrite -sOutputFile=refman.pdf -c save pop -f refman.ps    

@cd ..

@pause
@echo --- open HTML and PDF document ---
start html\UserDoc.CHM
start latex\refman.pdf
rem start latex\refman_2on1.pdf

@pause

</code>

===Doxygen Example===

Main project file: index.txt
<code delphi>
/*! @mainpage ezFIT User Documentation
@image html myapp-splash01.jpg
@image latex myapp-splash01.eps "" width=7cm
@image rtf myapp-splash01.jpg

This manual is divided in the following sections:
- @subpage intro
- @subpage installation
    - @ref installrequirements "Hardware and Software Requirements"
    - @ref cdrominstall "Installation from CD-ROM"
    - @ref internetinstall "Installation from Internet"
    - @ref progboxdrvinstall "Installation of Programming Box drivers"
    - @ref hi_swreqmatrix "Products: Software Requirement Matrix"
    - @ref migratedata
- @subpage tutorial
- @subpage howto 
    - @ref migratedata
    - @ref backupdata
- @subpage support "Contact Support"
- @subpage sales "Contact Sales"
- @subpage FAQ_SwIssues "FAQ: Software Errors and Issues"
- @subpage releasenotes 
- @subpage glossaryterms "Glossary and Terms"
- @subpage glossary "Glossary (Index)"

*/
</code>

Secondary file: installation.txt
<code delphi>
/*! \page installation Installation

Summary \n
- @ref installrequirements
- @ref cdrominstall 
- @ref internetinstall
- @ref progboxdrvinstall
- @ref migratedata

<hr>
\section installrequirements Installation Requirements
<b>Hardware</b>

- 900 MHz Processor.
- 128 MB of RAM.
- Serial port or USB port (when using a USB port, you also need a USB-Serial Adapter 
  to connect to a Hi-Pro programming box).
- 30 MB of free hard disk space.

<b>Software</b>

- Windows 2000/XP/2003/Vista (Professional or Server) for the 
  @ref install_on_server "server installation".
- Windows 98/ME/2000/XP/2003/Vista for the @ref install_on_client "client installation".
- Drivers for @ref install_usbserialadapter "USB-Serial Adapter".



<hr>
\section cdrominstall Installing from CD-ROM
<b>Installing MyApp</b>

-# Place the MyApp software CD into CD-ROM drive. The CD menu should start automatically, 
   showing the ezFIT software installation, product catalog, workshop information and more.
-# If the CD does not start automatically, do the following:
    - On the Windows desktop, click on Start > Run. 
    - Type: D:\\setup.exe (assuming D: is the CD-ROM drive letter).
-# To install the MyApp software, click on Software Installation.  At the next screen, 
   click on Install Software.  
   During the installation process, any data from the earlier version will be 
   incorporated into this new version.  
-# Click on the MyApp icon on your desktop to start using the software.

<hr>
\section internetinstall Downloading and Installing from Internet
<b>Downloading and Installing MyApp</b>

-# Download a copy of MyApp from http://www.example.com
-# Run the downloaded installer and follow instructions on the screen.

*/
</code>


==Generate CHM File Supporting Context Sensitive Help==
Add the following lines to the end of the project file (index.hhp). For example:
<code bash>
. . .
[ALIAS]
IDH_LISTPRODUCTS=productlist.html
IDH_INSTALLATION=installation.html
IDH_INSTALLUSBADAPTER=install_usbserialadapter.html

[MAP]
#include ctxhelp.h
</code>

And create a header file (ctxhelp.h) with the context definitions.  For example:
<code ini>
#define  IDH_LISTPRODUCTS       1000
#define  IDH_INSTALLATION       1001
#define  IDH_INSTALLUSBADAPTER  1002
</code>

Compile the index file (index.hhp) to view changes.

====Automating the process====
Doxygen will overwrite the project file (index.hhp), so it is a good idea to do the following:
* Create a file with the context information:
<code bash>
[ALIAS]
IDH_LISTPRODUCTS=productlist.html
IDH_INSTALLATION=installation.html
IDH_INSTALLUSBADAPTER=install_usbserialadapter.html

[MAP]
#include ctxhelp
</code>


* Create a batch file to add the context information:
<code dos>
REM ----------------------------------------------------------
REM script: makechm.bat
REM Description:
REM Make CHM Help file supporting context sensitive help.
REM ----------------------------------------------------------
@cls

@echo --- create CHM documentation ---
copy html\index.hhp html\index.hhp.orig
copy html\index.hhp+html\index.hhp.footer.txt html\index.hhp

"C:\Program Files\accviz\help\hc\hhc.exe" html\index.hhp

@pause
@echo --- open CHM document ---
start html\UserDoc.CHM
</code>



==Generate CHM File Supporting Index Searching==
Create an index file (index.hhk) with an index.  For example:
<code html>
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<HTML>
<HEAD>
<meta name="GENERATOR" content="Microsoft&reg; HTML Help Workshop 4.1">
<!-- Sitemap 1.0 -->
</HEAD><BODY>
<OBJECT type="text/site properties">
	<param name="FrameName" value="right">
</OBJECT>
<UL>
	<LI> <OBJECT type="text/sitemap">
		<param name="Name" value="product list">
		<param name="Name" value="MyApp: List of Products">
		<param name="Local" value="productlist.html">
		</OBJECT>
	<LI> <OBJECT type="text/sitemap">
		<param name="Name" value="installation">
		<param name="Name" value="MyApp: Installation">
		<param name="Local" value="installation.html">
		</OBJECT>
	<LI> <OBJECT type="text/sitemap">
		<param name="Name" value="installation USB-Serial adapter">
		<param name="Name" value="MyApp: Installation: USB-Serial Adapter">
		<param name="Local" value="install_usbserialadapter.html">
		</OBJECT>
</UL>
</BODY></HTML>
</code>

Make sure the index file name (index.hhk) is referenced in the project file (index.hhp):
<code ini>
[OPTIONS]
Compiled file=UserDoc.CHM
Compatibility=1.1
Full-text search=Yes
Contents file=index.hhc
Default Window=main
Default topic=main.html
Index file=index.hhk
Language=0x409 English (United States)
Title=ezFIT

[WINDOWS]
main="MyApplication","index.hhc","index.hhk","main.html","main.html",,,,,0x23520,,0x387e,,,,,,,,0
. . .
</code>

Compile the project file (index.hhp) to view changes.

==Using CHM Help in Delphi==
===Setup: Create and Destroy===

In the main form, put the following code (if you need context sensitive help support):

<code delphi>
uses
  ...hh{HTML Help}, hh_funcs{HTML Help};
var
    mHHelp: THookHelpSystem;

procedure TfrmMain.FormCreate(Sender: TObject);
begin
  // set the defaul helpfile for the application and enable support for .chm help files
  HelpFile := ExtractFilePath(Application.ExeName) + ezFitHelpFile;
  mHHelp   := THookHelpSystem.Create(HelpFile, '', htHHAPI);
end;
</code>

On the main form's Destroy routine, put the following code (if you need context sensitive help support):
<code delphi>
procedure TfrmMain.FormDestroy(Sender: TObject);
begin
  // Unhook and free
  mHHelp.Free;
  HHCloseAll();     // Close help before shutdown or big trouble
end;
</code>

In the main form's FormCloseQuery() routine, include the following code:
<code delphi>
procedure TfrmMain.FormCloseQuery(Sender: TObject; var CanClose: Boolean);
begin
  //  **** Warning Warning ****
  //
  //  If you call the HH API directly from your application, and not via
  //  a second helper program like HH.EXE or KEYHH.EXE, then you MUST close any open help
  //  windows before shutting down the application or you will probably crash Windows.
  //
  //  The call to close all windows is simply:
  //     HH.HtmlHelp(0, nil, HH_CLOSE_ALL, 0);
  //
  //  Warning:
  //     Because of a bug in the HH API, make sure you call this in your
  //     main form's OnCloseQuery event, not OnClose or OnDestroy.
  //     For more info see:
  //       http://helpware.net/FAR/far_faq.htm#HH_CLOSE_ALL

  HH.HtmlHelp(0, nil, HH_CLOSE_ALL, 0);

end;
</code>

===Calling Help===

Create a routine to call help.  Here we have an example of a Help Action:
<code delphi>
procedure TfrmMain.actHelpContentsExecute(Sender: TObject);
var
  HelpFile: string;
begin
  // Invoke regular help (userdoc.hlp)
  // Application.HelpCommand(HELP_FINDER, 0);   // display help file index

  //----------------------------------------------------------------------------
  // Invoke CHM help (HTML Help) (userdoc.chm)
  //----------------------------------------------------------------------------
  // function HtmlHelp( hwndCaller: HWND;
  //                    pszFile: PChar;
  //                    uCommand: UInt;
  //                    dwData: DWORD): HWND;
  //
  //  EG. To open a CHM file
  //      HtmlHelp(GetDesktopWindow(), 'UserDoc.chm', HH_DISPLAY_TOPIC, 0);
  //
  //  EG. To open a CHM file at a particular Topic
  //      HtmlHelp(GetDesktopWindow, 'c:\Help.chm::/Intro.htm', HH_DISPLAY_TOPIC, 0);
  //
  //  EG. To open a CHM file at a particular Topic and use a Window definition
  //      called "Mainwin".
  //      HtmlHelp(GetDesktopWindow, 'c:\Help.chm::/Intro.htm>Mainwin', HH_DISPLAY_TOPIC, 0);
  //
  //  EG. To open a CHM file using context help = 1001
  //      HtmlHelp(GetDesktopWindow, 'c:\Help.chm', HH_HELP_CONTEXT, 1001);
  //
  //  Note: Most people tend to use 0 instead of GetDesktopWindow.
  //----------------------------------------------------------------------------

  HelpFile := ExtractFilePath(Application.ExeName) + AppHelpFile;
  if FileExists(HelpFile) then begin
    HtmlHelp(GetDesktopWindow(), PAnsiChar(HelpFile), HH_DISPLAY_TOPIC, 0);
    //HtmlHelp(GetDesktopWindow(), 
    //         PAnsiChar(ExtractFilePath(Application.ExeName) + 
    //         '\UserDoc.chm::/install_usbserialadapter.html', 
    //         HH_DISPLAY_TOPIC, 0);
  end else begin
    ShowMessage('No Help File available (' + format('file %s missing', [HelpFile]) + ')');
  end;

end;
</code>

===Calling Context Sensitive Help===

Make sure the help system is pointing to the application CHM help file.
<code delphi>
uses
  ...hh{HTML Help}, hh_funcs{HTML Help};
var
    mHHelp: THookHelpSystem;

procedure TfrmMain.FormCreate(Sender: TObject);
begin
  // set the defaul helpfile for the application and enable support for .chm help files
  HelpFile := ExtractFilePath(Application.ExeName) + AppHelpFile;
  mHHelp   := THookHelpSystem.Create(HelpFile, '', htHHAPI);
end;
</code>

Assign the appropriate context for the resource that needs the context sensitive help.  In this example, the form frmProducts needs context sensitive help, so we assign it 1000 (or whatever the code is) to the form:
<code delphi>
procedure TfrmProducts.FormActivate(Sender: TObject);
begin
  frmProducts.HelpContext := 1000;
end;
</code>

When the application runs, pressing < F1 > will activate help in the appropriate context.