CHM documentation

[Allen Titley]

Hello to all! Allen (new member) here,

I am a long time (OMG, when did I become so old!) Pascal (DOS) programmer - I "cut my teeth" on Turbo Pascal v3, and migrated to v5.5 and finally to Borland Pascal. I am extremely intrigued by Virtual Pascal - I discovered links to Virtual Pascal some years ago and have been "chasing them" off and on since. In the course of getting into V.P., I have prepared a CHM (compiled HTML help) file of EVERYTHING! The PDF documentation (and program's online docs) are good, but finding anything is somewhat troublesome to me.

I read with interest Marco van de Voort's posting of Dec. 15/08 re: CHM support. Hope I haven't stolen your fire, Marco! Also, I would like to respond to Robert AH Prins' comments about CHM...
- yes, CHM is proprietary, but Microsoft releases the compiler (old) for free!
- yes, there can be security risks, but no more than ordinary HTML (this is just compiled)
Microsoft has more-or-less adopted the CHM (and various new spinoff formats) method of delivering documentation. I think the biggest advantages to CHM over conventional HTML are:
- smaller "footprint"
- full text search (and index, if desired)
- FAST!

Gentlemen, I have attached a zip file containing the CHM documentation; I hope that you will critique it and offer any comments or suggestions as you see fit. I am looking forward to using V.P. and the contact this forum should provide. Perhaps I may even provide you with a picture... (hmmmm)

Note: documentation file updated (minor fixups, new image in User's Guide 8.9.11) Aug 4/09

[Marco van de Voort]

No problem, for comparison, here is FPC's docs in CHM format:

http://www.stack.nl/~marcov/doc-chm.zip

Also fulltext etc, and working from the textmode IDE.

[Marco van de Voort]

I've now studied it a bit more, and I think it looks really nice. Only comment I could have is that because now everything is in one band, the links could be fixed so that references between different manuals work. (instead of being just a mention of e.g. See "language reference"). CHM can also crosslink between files btw. The automatic generated files of the FPC distro are crossreferencing.

We don't use Microsofts help compiler btw, we have an own (Pascal/Delphi) library to generate CHMs that doesn't use anything from Microsoft, and that library is also used to read the CHMs in the textmode IDE (even on Windows).

I noticed btw that the default Linux helpviewers are horribly slow. The 6MB (22000 items or so) LCL chm opens in Windows without much fuzz, but is really loading over 10 seconds in Linux with kchmviewer (the gnome one is slightly better but still slower).

If people have problems viewing the downloaded CHMs under Vista, see

http://wiki.freepascal.org/chm_backend_for_fpdoc#Troubleshooting

[Allen Titley]

Marco,

The lack of crosslinks was deliberate - extracting HTML and other files from the CHM yields a zip file which contains individual control files (HHP and HHC) for separate compilation. In other words, you could compile the Users Guide separately, if you wish. This means, for example, that if you have no need for TIPS, etc., you could just compile the Runtime Library and Language Manual. Putting crosslinks in would mean keeping 2 sets of HTML; crosslinking separate files in CHM involves always having the correct files present, in known locations, and this may not always be the case.

If I felt that no one would be interested in anything but the entire documentation (ie. only 1.8mb file, as posted), I could easily create the necessary links and recompile.

I would be interested in more information on another method of developing CHMs - the Microsoft compiler has a few bugs (mostly regarding large TOCs) which can be worked around, but are troublesome. I have searched sometime for the fix from Microsoft (newer copy of HHA.DLL) - alas, it is not on the net (you must contact MS by telephone). Also, I do not believe that any other good products are out there which are freeware.

Thanks for your comments! I hope that others may find my file useful. The full-text search feature is worth the price of admission, in my view! I have been quite impressed with Virtual Pascal so far and have gleaned nearly everything "out there" on the Internet (different versions released, user-contributed apps, etc.) just in case in I need it for reference. I have experimented with Free Pascal in the past - good, but quite big and clunky, with a few bugs in the IDE.

- Allen

[Marco van de Voort]

About Crosslinking:

Well, I have some support for that in the tooling, and additionally FPC has DOM libraries that allow to load the html in a DOM model and do fixups. This is currently already done for the non-unit docs.

About CHM generation:

For the unit documentation we use a specific tool that parses source, extracts information (types, procedure headers etc) and combines it with help text in XML format to latex/html/whatever. The CHM generation is an option on top of the html support, to use the CHM lib and do some additional index generation.

IOW FPC has a CHM generating library, not a true compiler. The code is FPC/Delphi code, but probably contains too many D4+ features to be used with VP. On the other hand, adding all files in the directory to a chm, and doing fulltext search is maybe 50 lines. (fulltext search takes about 0.5 minute/MB on a fast machine though)

The TOC and Index are generated by the documentation program for the unit-docs. For the other docs, I generate the TOC, and they have no index (the default.hh*) files. They are simple XML files.

In other words, you can make nearly any CHM generating program in FPC. It just depends on how much you want to program. And it will also work on Linux and other systems. (maybe not DOS though, since SFN is too limiting)

About the FPC IDE:

Yes, the VP IDE is still friendlier. FPC's textmode IDE doesn't really improve atm, because all interested people keep working with VP or BP (while e.g. the RAD, Lazarus was greatly improved in the same timeframe)

Size is a non issue for me. Harddisks are gigantic, and the size comes from things that are directly usable. Even in this message there are two: the CHM lib and the DOM/XML units.

[Marco van de Voort]

My CHM notes (mostly the urls) are at http://www.stack.nl/~marcov/chm.txt IIRC somewhere on the helpware pages listed there, there was some URL to helpsystem updates.

If you need a certain transformation on an existing chm file, (e.g. relink it, charset fixes etc), ask, and I'll try to write a program. I have written several html fixup programs for FPC in the meantime. I might not be able to do it directly, but it gives me a target to work towards.

The above download URL has meanwhile been refreshed a few times.

[Robert AH Prins]

Just four words: Fantastic!

Typo in "Debugging OS/2 DLLs" While yoor process is on ots way to the breakpoint

Robert

[Allen Titley]

Thanks Robert, for the keen observation! There actually will be more (I assume) typos - this one (and probably others) appear in the original text from vpascal.com. I tried to proofread as I went (converting/formatting), but obviously I missed some. I have corrected the source, but haven't reposted; the correction will show up in any future re-compiles. By the way, I have collected nearly everything ever put out for Virtual Pascal (all relevent versions, sample apps, etc.) from a variety of sources. If anyone is missing anything, just ask!

- Allen