chm backend for fpdoc
Examples
Hi from this link this is all the 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:
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
The <HEAD> tag contains a <meta> tag providing information on the program that generated the files and a comment indicating the version of the file. e.g.:
<meta name="GENERATOR"content="Microsoft® HTML Help Workshop 4.1">
The <BODY> tag contains an <OBJECT> tag that stores properties of the file in <param> tags, followed by a UL> tag, whose <LI> tags have <OBJECT> tags that store the properties of the Contents/Index items in <param> tags. e.g.:
<BODY>
<OBJECT type="text/site properties">
<param name="Property Name" value="Property Value">
…
</OBJECT>
<UL>
<LI> <OBJECT type="text/sitemap">
<param name="Property Name" value="Property Value">
…
</OBJECT>
…
</UL>
</BODY>
Note that the Property Names and Property Values and tags are not case-sensitive, but HHW will always write all three in the default capitilization, when appropriate.
Note that the tags are mostly in uppercase and the <LI> 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(TOC) file for the rtl: .hhk are in the same format but are for the Index pane and do not have subitems.
<!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="Auto Generated" value="Yes">
</OBJECT>
<UL>
<LI> <OBJECT type="text/sitemap">
<param name="Name" value="Reference for package 'rtl'">
<param name="Local" value="rtl/index.html">
</OBJECT>
<UL>
<LI> <OBJECT type="text/sitemap">
<param name="Name" value="Units">
<param name="Local" value="rtl/index.html">
</OBJECT>
<LI> <OBJECT type="text/sitemap">
<param name="Name" value="Description">
<param name="Local" value="rtl/index.html">
</OBJECT>
</UL>
<LI> <OBJECT type="text/sitemap">
<param name="Name" value="Reference for unit 'BaseUnix'">
<param name="Local" value="rtl/baseunix/index.html">
</OBJECT>
<UL>
<LI> <OBJECT type="text/sitemap">
<param name="Name" value="Overview">
<param name="Local" value="rtl/baseunix/index.html">
</OBJECT>
</UL>
......
</UL>
</BODY></HTML>
Generating FPC CHM docs via fpdoc
At the moment (october 2008), the fpdoc part of the documentation (the part that documents the various units) can be compiled to CHM fairly easily, a
make clean html HTMLFMT=chm CSSFILE=/path/to/fpdoc.css
will generate rtl.chm and fcl.chm. Note that the cssfile is currently in a different repository (I used fpc/utils/fpdoc/fpdoc.css since it has the correct name)
During october, some minor fixes were made to fpdoc, so preferably use a fully up to date version.
Generating LCL CHM via fpdoc
(I only did this on *nix)
Warning: this script enabled all fpdoc bells and whistles, and before 28feb took 40mins to complete on a core2-6600. After the cleanup still 4minutes and 400MB memory. If you want to do this in a nightly build, make sure you have a fpdoc from trunk, preferably from a checkout that was compiled with optimization on. That knocks off another half minute. ( 12.5%)
export HTMLFMT=chm cd lazarus/docs/html sh build_lcl_html.sh
The generated .xct file is an index file for fpdoc cross file links, and is of no use to the user.
Generating FPC CHM docs for the latex documentation
Building CHMs for the documentation that is not in fpdoc format (but normal latex files) is harder. The process can be fairly easily be separated into two stages:
- generate HTML from latex sources
- compile HTML to CHM.
- raw compile
- generating indexes and TOC
The first is currently the hard part. During the years several converters have been tried, the current one used is tex4ht. While the theory is easy (install latex, install tex4ht, run make html), the practice is difficult (*), and the generated docs are usually corrupt (ligatures converted to pics or unicode escapes, bad "next" links etc). Luckily, these docs mutates less often, so one probably can use a generated set of CHMs for the entire duration of a release cycle. Still it would be great to have a definitive, reproducable solution.
The second part can also be split to the principle conversion (packing the HTML into a chm file), and all additional processing, like TOC, indexes (and maybe correcting errors in the initial latex -> html conversion).
The base conversion is easily done, since the great chm package does all of the heavily lifting, so a simple 40 line script can do the job. A rough first attempt is here. Further steps require fixing the main step (latex -> html first).
(*) to the degree that the version on the FPC front page is more often broken than not.
