C:\Program Files\HTMLHelp.C:\Program Files\doxygen\bin).... ENABLE_PREPROCESSING = YES ...
doxygen -g <config_file>
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 ...
For software customization, create a includes\customproj.cfg file with the settings to override. For example:
#-------------------------------------------------------------------------- # 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"
After this, you can run doxygen to generate help files using the following command:
doxygen <config_file>
Download and install the required software:
Create default Makefile (here it is called LatexMakefile):
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
Run a batch file:
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
Main project file: index.txt
/*! @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)" */
Secondary file: installation.txt
/*! \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. */
Add the following lines to the end of the project file (index.hhp). For example:
. . . [ALIAS] IDH_LISTPRODUCTS=productlist.html IDH_INSTALLATION=installation.html IDH_INSTALLUSBADAPTER=install_usbserialadapter.html [MAP] #include ctxhelp.h
And create a header file (ctxhelp.h) with the context definitions. For example:
#define IDH_LISTPRODUCTS 1000 #define IDH_INSTALLATION 1001 #define IDH_INSTALLUSBADAPTER 1002
Compile the index file (index.hhp) to view changes.
Doxygen will overwrite the project file (index.hhp), so it is a good idea to do the following:
[ALIAS] IDH_LISTPRODUCTS=productlist.html IDH_INSTALLATION=installation.html IDH_INSTALLUSBADAPTER=install_usbserialadapter.html [MAP] #include ctxhelp
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
Create an index file (index.hhk) with an index. For example:
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> <HTML> <HEAD> <meta name="GENERATOR" content="Microsoft® 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>
Make sure the index file name (index.hhk) is referenced in the project file (index.hhp):
[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 . . .
Compile the project file (index.hhp) to view changes.
In the main form, put the following code (if you need context sensitive help support):
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;
On the main form's Destroy routine, put the following code (if you need context sensitive help support):
procedure TfrmMain.FormDestroy(Sender: TObject); begin // Unhook and free mHHelp.Free; HHCloseAll(); // Close help before shutdown or big trouble end;
In the main form's FormCloseQuery() routine, include the following code:
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;
Create a routine to call help. Here we have an example of a Help Action:
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;
Make sure the help system is pointing to the application CHM help file.
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;
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:
procedure TfrmProducts.FormActivate(Sender: TObject); begin frmProducts.HelpContext := 1000; end;
When the application runs, pressing < F1 > will activate help in the appropriate context.