No More CHM
Posted on:November 19 2009
I used to include the documentation of software I write, such as Irrlicht and irrKlang in the form of CHM files, a file format by Microsoft consisting of compressed HTML files with an index and table of contents.
The problem with this is that .chm viewers are only natively installed on Windows operating systems, users with Linux or Mac OS X usually have to download some external software to read the documentation. Additionally, it seems that because Microsoft now considers its own file format a security risk and instead of fixing the hole, sometimes the CHM Viewer (aka Internet Explorer) seems to refuse to show the content of those files, and in some cases (from my experience) it cannot even be forced to show the file nevertheless.
That's the reason why I now decided to stop using .chm files and include the .html and .png files directly, in uncompressed form in the SDKs. Anyone today knows how to open .html files and as doxygen now also includes a nice JavaScript based search functionality, the switch should be painless.
To begin with irrKlang, the next release (to be released in the next days) will no longer include .chm files.
The problem with this is that .chm viewers are only natively installed on Windows operating systems, users with Linux or Mac OS X usually have to download some external software to read the documentation. Additionally, it seems that because Microsoft now considers its own file format a security risk and instead of fixing the hole, sometimes the CHM Viewer (aka Internet Explorer) seems to refuse to show the content of those files, and in some cases (from my experience) it cannot even be forced to show the file nevertheless.
That's the reason why I now decided to stop using .chm files and include the .html and .png files directly, in uncompressed form in the SDKs. Anyone today knows how to open .html files and as doxygen now also includes a nice JavaScript based search functionality, the switch should be painless.
To begin with irrKlang, the next release (to be released in the next days) will no longer include .chm files.
Comments:
I always wondered when you would change that.. good to know you finally did it :)..
Rapchik
Quote2009-11-19 14:32:00
You should try a PDF format. It's quite nice.
Anthoni
Quote2009-11-19 14:34:00
Well, I actually find the CHM documentation quite useful, it's more compact than the HTMLs and in my opinion, it's just faster to search in it than looking in the tons of the HTML files. Maybe at least the PDF as a replacement as Anthoni advises wouldn't be bad ...
RedDragCZ
Quote2009-11-19 16:24:00
The PDF format wouldn't be bad at all. You can use SVG graphics from programs like Word and OpenOffice Writer to create some really nice things. CHM's are getting old, and PDF are new and support more, I truly believe it to be the correct choice.
Anthoni
Quote2009-11-19 17:13:00
Although I like the CHM documentation in Windows, it is a pain to use on Linux and OSX. The HTML documentation is also quite painful as there are far too many files, PDF isn't an ideal choice for API docs either.
Given the options I completely agree, HTML is the most flexible, cleanest and open solution. It would be nice if we had better DoxyGen scripts for Irrlicht, or some kind of post-processing to combine everything into a small number of sections
Given the options I completely agree, HTML is the most flexible, cleanest and open solution. It would be nice if we had better DoxyGen scripts for Irrlicht, or some kind of post-processing to combine everything into a small number of sections
Gaz
Quote2009-11-19 18:57:00
You can use the Qt Assistant, give it a try, works with Linux, Windows, Mac
http://doc.trolltech.com/4.5/assistant-details.html
http://doc.trolltech.com/4.5/assistant-details.html
Axel
Quote2009-11-19 20:25:00
PDF is much better considering you don't have to know HTML to write the documentation, you can include graphics that the CHM's don't support, and most people have a PDF reader on their computer. So PDF is the optimal choice.
Anthoni
Quote2009-11-19 21:06:00
We already had a pdf for Irrlicht 1.5. Check the Irrlicht download page, any feedback for improvements is welcome :-)
hybrid
Quote2009-11-19 22:08:00
The only reason why I often used the chm help is because of it's search feature. Now if doxygen provides that as well I see no problem in dropping chm.
Brainsaw
Quote2009-11-20 07:32:00
Have you considered an help authoring software such as HelpNDoc http://www.helpndoc.com which is available for free and produces CHM, PDF, RTF and HTML documentation from a single source ? We will gladly provide a license of the Professional Edition if you'd like, as a big thank you for the amazing work you are doing with Irrlicht.
John
Quote2009-11-20 09:18:00
@hybrid: hm, the 1.5 sdk doesn't include a pdf..? (just tried out)
@john: wow, that would be surely great. I'm not sure how that would work with irrlicht as open source project (were there are ~ 10 developers and we are using autogenerated docs) but for other projects like irrKlang or CopperCube it could really be interesting. I'll try helpndoc in the next weeks and have a look at it.
@john: wow, that would be surely great. I'm not sure how that would work with irrlicht as open source project (were there are ~ 10 developers and we are using autogenerated docs) but for other projects like irrKlang or CopperCube it could really be interesting. I'll try helpndoc in the next weeks and have a look at it.
niko
Quote2009-11-20 11:14:00
The pdf is a separate download, it's in the same "folder" as the SDK. I've also reorganized some files today, hope they're more easily found now.
hybrid
Quote2009-11-20 23:34:00
One advantage of using chm is the easy implementation of context sensitive help. At least when creating an MFC application. Not much in the case of developing dll's of course.
evo
Quote2009-11-22 16:26:00
Add comment:
|
|
Possible Codes
| Feature | Code |
| Link | [url] www.example.com [/url] |
| Bold | [b]bold text[/b] |
| Quote | [quote]quoted text[/quote] |
| Code | [code]source code[/code] |
Emoticons
 |  |  |  |  |  |  |  |
 |  |  |  |  |