Friday, April 27, 2007

Doxygen to html to chm

Windows For those who like to use Doxygen to create some cool html help and who use source control you probably would like to create a unique file to be able to commit the file to your source control. The reason is that every time you will generate Doxygen new files will be generated based on your code change and you don't want to re-post all the html files every time. Doxygen itself can almost directly generate such a file!

The step-by-step howto:> Download the Microsoft HTML Help Workshop here: Microsoft MSDN page (the 'Download Htmlhelp.exe' link)

Install above program.

Edit the doxygen configuration file (located at 'doc\doxygen\html\doxygen.html.cfg') and change the following entries:

GENERATE_HTMLHELP = NO --> GENERATE_HTMLHELP = YES
BINARY_TOC = NO --> BINARY_TOC = YES
TOC_EXPAND = NO --> TOC_EXPAND = YES
HHC_LOCATION = --> HHC_LOCATION = "{path to MS HTML Help Workshop}\hhc.exe">

Follow the steps of generating the HTML version of the documentation: Online documentation page -- Or, if you don't like command line mucking about, ignore the above documentation link and use the Doxygen wizard called doxywizard which comes with the latest win32/linux doxygen version 1.3.9.1 (and maybe with earlier versions).

Run doxywizard>
Load the edited Doxygen configuration file (with the 'Load..' button)
Change the working directory to your project root dir (just strip off the 'doc\doxygen\html\') Click the 'Start' button
Let it munch a while-- And voila!

A nice and snappy myapp.chm file is waiting for you in the documentation directory!
Linux
On Linux such as Ubuntu if you need a solution to convert Doxygen to CHM you will have to use chmcmd
In this case you can't enable the CHM creation inside the doxy file because it won't work, doxygen will fail on executing hhc.exe on your Linux system. You couild use wine to emulate but this is like using a sledgehammer to kill a fly.... So the recommendation is to duplicate the doxyfile and disable all related CHM flag. Run doxygen once using the Windows doxy file to produce index.hhp, index.hhc and, index.hhk then edit the hhp file and remove unsupported options by chmcmd. See sample simple hhp file.
Maintain the hhp, hhc and hhk file in your source repository and each time you build the documentation on windows make sure to update the files to keep them in sync for your Linux CHM build Download fpc-2.6.0.x86_64-linux.tar from http://sourceforge.net/projects/freepascal/files/Linux/2.6.0/

android@U64:~$ cd pascal/
android@U64:~/pascal$ tar xvf fpc-2.6.0.x86_64-linux.tar
android@U64:~/pascal$ ls
fpc-2.6.0.x86_64-linux fpc-2.6.0.x86_64-linux.tar
android@U64:~/pascal$ cd fpc-2.6.0.x86_64-linux
android@U64:~/pascal/fpc-2.6.0.x86_64-linux$ ls
binary.x86_64-linux.tar demo.tar.gz doc-pdf.tar.gz install.sh
android@U64:~/pascal/fpc-2.6.0.x86_64-linux$
Install prefix (/usr or /usr/local) [/usr] : /usr/local
Installing compiler and RTL for x86_64-linux...
Installing utilities...
Install Textmode IDE (Y/n) ? Install FCL (Y/n) ? Y
Installing fcl-async
Installing fcl-base
Installing fcl-db
....
Install packages (Y/n) ? Y
Installing a52
Installing aspell
Installing bfd
Installing bzip2
Installing cairo
...
Installing zorba
Done.


Install documentation (Y/n) ? Y
Installing documentation in /usr/local/share/doc/fpc-2.6.0 ...
Done.

Install demos (Y/n) ? Y
Install demos in [/usr/local/share/doc/fpc-2.6.0/examples] :
Installing demos in /usr/local/share/doc/fpc-2.6.0/examples ...
Done.

Write permission in /etc.
Writing sample configuration file to /etc/fpc.cfg
Writing sample configuration file to /usr/local/lib/fpc/2.6.0/ide/text/fp.cfg
Writing sample configuration file to /usr/local/lib/fpc/2.6.0/ide/text/fp.ini
Writing sample configuration file to /etc/fppkg.cfg
Writing sample configuration file to /etc/fppkg/default

End of installation.

Refer to the documentation for more information.


Examples
This link has information about the TOC and Index files in chms: http://www.nongnu.org/chmspec/latest/Sitemap.html
These formats are based on HTML and use the following doctype:


The tag contains a tag providing information on the program that generated the files and a comment indicating the version of the file, e.g.:


The tag contains an tag that stores properties of the file in tags, followed by a
    tag, whose
  • tags have tags that store the properties of the Contents/Index items in tags. e.g.:


    Note that the Property Names and Property Values and tags are not case-sensitive, but HHW will always write all three in the default capitalization, when appropriate.
    Note that the tags are mostly in uppercase and the
  • tag is not closed; this is in compliance with the doctype.
    Some properties that were seen in HHA.dll that may or may not be used are Background Image, NumberImages, InformationTypeDecl, Secondary, Icon, Display, Keyword, Instruction, Section Title,
    Favorites, QueryType, SendEvent, SendMessage, HHI, Inclusive & Exclusive.
    This the beginning chunk of an autogenerated (the autogenerated TOC stinks) hhc (Table of Contents/TOC) file for the RTL: .hhk are in the same format but are for the Index pane and do not have
    subitems.


    For anybody determined to "roll their own", an absolutely minimal .hhp file reads something like


    chmcmd - creates a Compressed HTML help file (chm) using the hhp file

    android@U64:~/html/chmcmd index.hhp

    Will produce a nice index.chm file on an Android build system and use yoru favorite CHM APK viewer on your Mobile phone!
    at

    4 comments:

    Anonymous said...

    Thanx for tutorial. It worked! Greets, sarge.

    1:42 AM
    DS said...

    Thx... it's a good tutorial.

    5:45 AM
    DS said...

    Thx... it's a good tutorial.

    5:46 AM
    Anonymous said...

    Thanks!!

    10:25 AM

    Post a Comment

    Subscribe to: Post Comments (Atom)