chm backend for fpdoc: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		### Examples
2	2
3	3		This link has information about the TOC and Index files in chms: <http://www.nongnu.org/chmspec/latest/Sitemap.html>
4	4
5	5		These formats are based on HTML and use the following doctype:
6	6
7	7		```html4strict
8	8		<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
9	9		```
10	10
11	11		The \<HEAD\> tag contains a
12	12
13	13		tag providing information on the program that generated the files and a comment indicating the version of the file, e.g.:
14	14
15	15		```html4strict
16	16		<meta name="GENERATOR"content="Microsoft® HTML Help Workshop 4.1">
17	17
18	18		```
19	19
20	20		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.:
21	21
22	22		```html4strict
23	23		<BODY>
24	24		<OBJECT type="text/site properties">
25	25		<param name="Property Name" value="Property Value">
26	26		…
27	27		</OBJECT>
28	28		<UL>
29	29		<LI> <OBJECT type="text/sitemap">
30	30		<param name="Property Name" value="Property Value">
31	31		…
32	32		</OBJECT>
33	33		…
34	34		</UL>
35	35		</BODY>
36	36		```
37	37
38	38		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.
39	39
40	40		Note that the tags are mostly in uppercase and the \<LI\> tag is not closed; this is in compliance with the doctype.
41	41
42	42		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.
43	43
44	44		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.
45	45
46	46		```html4strict
47	47		<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
48	48		<HTML>
49	49		<HEAD>
50	50		<meta name="GENERATOR" content="Microsoft® HTML Help Workshop 4.1">
51	51
52	52		</HEAD><BODY>
53	53		<OBJECT type="text/site properties">
54	54		<param name="Auto Generated" value="Yes">
55	55		</OBJECT>
56	56		<UL>
57	57		<LI> <OBJECT type="text/sitemap">
58	58		<param name="Name" value="Reference for package 'rtl'">
59	59		<param name="Local" value="rtl/index.html">
60	60		</OBJECT>
61	61		<UL>
62	62		<LI> <OBJECT type="text/sitemap">
63	63		<param name="Name" value="Units">
64	64		<param name="Local" value="rtl/index.html">
65	65		</OBJECT>
66	66		<LI> <OBJECT type="text/sitemap">
67	67		<param name="Name" value="Description">
68	68		<param name="Local" value="rtl/index.html">
69	69		</OBJECT>
70	70		</UL>
71	71		<LI> <OBJECT type="text/sitemap">
72	72		<param name="Name" value="Reference for unit 'BaseUnix'">
73	73		<param name="Local" value="rtl/baseunix/index.html">
74	74		</OBJECT>
75	75		<UL>
76	76		<LI> <OBJECT type="text/sitemap">
77	77		<param name="Name" value="Overview">
78	78		<param name="Local" value="rtl/baseunix/index.html">
79	79		</OBJECT>
80	80		</UL>
81	81
82	82		......
83	83		</UL>
84	84		</BODY></HTML>
85	85		```
86	86
87	87		## Generating FPC CHM docs via fpdoc
88	88
89	89		As of October 2008, the fpdoc part of the documentation (the part that documents the various units) can be compiled to CHM fairly easily, a
90	90
91	91		``` bash
92	92		make clean html HTMLFMT=chm CSSFILE=/path/to/fpdoc.css
93	93		```
94	94
95	95		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). A script fixdocs.sh automates most of the CHM related options. (*nix, requires latex + tex4ht)
96	96
97	97		Significant fixes to the CHM, XML and makefiles backend were introduced in the sources (fpcdocs,chm, fcl-xml and fpdoc) from the 2.3.1 branch, July 31st 2009 and newer.
98	98
99	99		### Remaining problems
100	100
101	101		1. The text mode IDE crashes on loading the LCL.chm's index on all architectures and OSes. Other CHM viewers don't seem to suffer from this, but there is always a chance it is CHM pkg related. (fixed)
102	102		2. The prog and user documents don't have an index. Ref guide only has keywords.
103	103		3. FCL-XML generates UTF-8, which some CHM browsers (kchmviewer) don't seem to handle properly. Note: is this still applicable in March 2014? Workaround: ISO8859-1 default? KCHMviewer seem to work fine on windows.
104	104		4. compiling LCL finds a lot of unknown identifiers. These should be documented?
105	105		5. crosslinking between user,ref,prog and fpdoc?
106	106
107	107		And the major one:
108	108
109	109		1. How to combine the indexes to a master index (including duplicate handling)? Currently additional disambiguating context is only added to the index if a dupe _within_ a CHM is detected.
110	110
111	111		## Generating LCL CHM via build_lcl_docs
112	112
113	113		Lazarus provides the build_lcl_docs.lpr tool: a wrapper which simplifies calling fpdoc to generate an LCL CHM.
114	114
115	115		It can be run both in GUI mode and command line mode.
116	116
117	117		Useful command line parameters
118	118
119	119		1. `--fpdoc` \<fpdoc executable to be used to generate CHM\>
120	120		2. `--css-file=`\<css file to be used for layout, e.g. fpdoc.css\>
121	121		3. `--outfmt chm` Set output format to CHM
122	122
123	123		## Generating LCL CHM via fpdoc
124	124
125	125		Only tested on *nix
126	126
127	127		> Warning: this script enables all fpdoc bells and whistles, takes about 4 minutes and 400MB memory on a Core2-6600. If you want to do this regularly, make sure you have a fpdoc from trunk, preferably from a checkout that was compiled with optimization on which saves about half a minute
128	128
129	129		``` bash
130	130		export HTMLFMT=chm
131	131		cd lazarus/docs/html
132	132		sh build_lcl_html.sh "fpdoc" "" /path/to/fpcdocs
133	133		```
134	134
135	135		The generated .xct file is an index file for fpdoc cross file links, and is of no use to the end user, unless you want to link to the chm. That is also why we have to specify the fpcdocs archive. If we have previously built the FPC docs there, lcl will use this to craft cross CHM links.
136	136
137	137		## Generating FPC CHM docs for the latex documentation
138	138
139	139		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:
140	140
141	141		1. generate HTML from latex sources
142	142		2. compile HTML to CHM
143	143		1. raw compile
144	144		2. generating indexes and TOC
145	145
146	146		### Generating HTML
147	147
148	148		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.
149	149
150	150		For the moment, the "bad" output of tex4ht is fixed by a DOM based (FCL-XML) FPC tool, relinkdocs. Relinkdocs scans the HTML docs and relinks the next/up/prev links.
151	151
152	152		(*) to the degree that the version on the FPC front page is more often broken than not.
153	153
154	154		### Compiling and TOC generation
155	155
156	156		To compile the resulting HTML to CHM, another tool was written, called compilelatexchm, which also relies on FCL-XML for the TOC scanning. The CHM is searchable, but does not yet have an index. (I don't know a suitable algoritm to come up with the keywords)
157	157
158	158		A batch file that automates these steps is added to the fpcdocs repository (fixdocs.sh), but is not idiot proof yet. If you have troubles, ask me (Marco/oliebol) on IRC.
159	159
160	160		### Plastex
161	161
162	162		A week after I did the above fixing of tex4ht output, Andrew Haines came with a patch that supported using PlasTeX as tex2chm converter. I don't entirely like the output (chapter and paragraph numbers drop off, which makes it harder to correspond over documentation, and the template is a bit playful), but I haven't looked into customizing it at all, so maybe something can be done there. I haven't tested the generated CHMs with the textmode IDE yet too.
163	163
164	164		One can select PlasTeX by passing USEPLASTEX=1 to the make process.
165	165
166	166		## chmcmd understood options
167	167
168	168		While the chmcmd program responds to e.g. --help by outputting the command-line options it understands, it doesn't report what options are acceptable in the .hhp file. Refer to the OptionKeys constant in fpcsrc/packages/chm/src/chmfilewriter.pas, and documentation available at e.g. [1](http://www.nongnu.org/chmspec/latest/INI.html#HHP).
169	169
170	170		For anybody determined to "roll their own", an absolutely minimal .hhp file reads something like
171	171
172		-	~~`[OPTIONS]`\~~
173		-	~~`Compiled file=test.chm`\~~
174		-	~~`Contents file=./Default.hhc`\~~
175		-	~~`[FILES]`\~~
176		-	~~`./Borg-UI_MainForm_HelpButton.html`\~~
177		-	~~`./Borg-UM_MainForm_HelpButton.html`~~
	172	+	```text
	173	+	[OPTIONS]
	174	+	Compiled file=test.chm
	175	+	Contents file=./Default.hhc
	176	+	[FILES]
	177	+	./Borg-UI_MainForm_HelpButton.html
	178	+	./Borg-UM_MainForm_HelpButton.html
	179	+	```
178	180
179	181		with the TOC file being
180	182
181	183		```html4strict
182	184		<html><head></head><body><object type="text/site properties"></object><ul>
183	185		<li><object type="text/sitemap">
184	186		<param name="Name" value="Borg-UI_MainForm_HelpButton">
185	187		<param name="Local" value="Borg-UI_MainForm_HelpButton.html">
186	188		</object>
187	189		<li><object type="text/sitemap">
188	190		<param name="Name" value="Borg-UM_MainForm_HelpButton">
189	191		<param name="Local" value="Borg-UM_MainForm_HelpButton.html">
190	192		</object>
191	193		</ul></body></html>
192	194		```
193	195
194	196		## Troubleshooting
195	197
196	198		### Trouble viewing in Vista
197	199
198	200		The chm file could be marked as blocked. To unblock, use the chmls tool (included in \$(fpcdir)\packages\chm\src\\):
199	201
200	202		```dos
201	203		chmls unblockchm yourfile.chm
202	204		```
203	205
204	206		#### Alternative ways and background
205	207
206	208		Have a look at [this link](http://blog.crowe.co.nz/archive/2007/04/13/719.aspx). We still must find something that make the installer do this automatically.
207	209
208	210		Or turn it off entirely using:
209	211
210		-	~~`[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\HTMLHelp\1.x\HHRestrictions]`\~~
211		-	~~` "MaxAllowedZone"=dword:00000001`\~~
212		-	~~`[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\HTMLHelp\1.x\ItssRestrictions]`\~~
213		-	~~` "MaxAllowedZone"=dword:00000001`~~
	212	+	```text
	213	+	[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\HTMLHelp\1.x\HHRestrictions]
	214	+	"MaxAllowedZone"=dword:00000001
	215	+	[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\HTMLHelp\1.x\ItssRestrictions]
	216	+	"MaxAllowedZone"=dword:00000001
	217	+	```
214	218
215	219		You can add a registry key to repair this issue in XP and Vista by setting the ItssRestrictions.MaxAllowedZone to 3 or 4 or 5.
216	220
217	221		A simpler solution is to unzip with e.g. infozip, instead of Windows built-in support. (beware, newer infozips might conform at any time!)
218	222
219	223		Apparently this is an alternate filestream: <http://stackoverflow.com/questions/1617509/unblock-a-file-with-powershell>
220	224
221	225		---
222	226		From the Free Pascal wiki, page "chm backend for fpdoc", as it stood on 2020-12-21 after a change by Marcov, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
223	227		Category: CHM
224	228		Category: Help and Docs

Back to history