Virtual Pascal

Classic Object Pascal for free

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

Note: Nov 14/2011 - documentation file updated, with the following changes:

  • fixed (overcame) a bug in the settings/Help compiler which prevented the Search/"Match similar words" from actually doing anything!  It works now.  Microsoft's Help Workshop (compiler) actually has some bad bugs, but most can be overcome.  Who knew...!
  • enhanced the "Using Search" page (tips on usage)
  • fixed bad tags in Tips/Tip # 10 (they were there in the original Wayback Machine page)
  • added a "Font" button to the toolbar (5 font sizes, for those with 'bad vision') and modified the style sheet accordingly.  This feature also added to control files in the embedded file "separate_control.zip".  Default is size "3" of 5 sizes.  Note: changing font size affects all (future) pages viewed with Internet Explorer, but you can change back easily in IE by using Ctrl+scroll (mouse) or View/Text size.

Note: April 4/2012 - documentation file updated, with the following changes:

  • removed separate compilation files (embedded zip file)
  • removed navigation buttons at bottom of pages, now a link to top of page instead (buttons there)
  • added many new cross-links to Language Reference and User's Guide books
  • miscellaneous minor additions, fixes

 

Views: 1776

Attachments:

Reply to This

Replies to This Discussion

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.
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
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
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.
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.
Just four words: Fantastic!

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

Robert
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
Allan,

I've made some progress in creating a standalone CHM compiler. Would it possible that I get your original .hhp project with all files to test?

Thanks.
Marco,

Have a look at the opening page of the CHM - "About Virtual Pascal Documentation". All the files you need are embedded in the final CHM. I recommend downloading 7-Zip (if you don't already have it - excellent!) to extract everything to a separate folder somewhere. The HHP file for the main CHM is embedded in there, as well as a zip file containing other HHP files (and HHC files) for separate compilation of User's Guide, Reference, etc. If I sent you a zip of the source, it would just be what you will extract from the CHM!

By the way, I have found the Microsoft compiler, although not supported, fairly acceptable EXCEPT for a bug in table-of-contents handling. Large TOCs (> 32K) must be created separately, combined using a text editor, then compiled, to avoid a crash in editing. I believe also you can avoid the crash (for a while) by editing the TOC separately - just double click on the HHC file, NOT the HHP!

Cheers,

Allen
Will do thanks. 7-zip is not necessary, Free Pascal can extract them too.

I don't know the Microsoft compiler that well, but we have an almost working compiler already (in library form, for our own documentation systems), which is nearly feature complete, so that it is more a matter of adding a frontend binary and ironing out bugs.

Note that this is only a compiler, not a workshop. (Lazarus can pop up windows where you can enter help for identifiers (reference guide help, no more documentation comments polluting source), and we are working to add this to the designer for application level help too.

If I can get it up to a decent initial level, the usage of non-windows users alone might be valuable beta-testing for us. (specially people that host their doc building on cheaper *nix hosting, even if they target Windows). Besides the CHM package, XML and html parsing is also stressed.

The FPC help compiler is still slower (portable, no asm), but the compression can use multiple cores, so probably with a quadcore it will be significantly faster (again more important for the nightly documentation generators than for the occasional user)
Hmm, I'm happy I've looked at this. It seems that MS compiler automatically adds all files in the TOC to the chm. Something tha tour compiler doesn't do yet. One step closer to compatibility :-)

Probably index too, but this CHM doesn't have any.
Marco,

Yes, the MS compiler DOES add files (and index - .HHK) contained in the TOC to the chm. Valid hyperlinks on any page (text or image links) also cause the target page to be included; references to style sheets (CSS) in the page header cause the CSS to be compiled. The only thing I have found that is a problem is two scenarios:

1. if the style sheet contains references to images, such as page backgrounds, usually using the URL method, the image is NOT automatically included, and
2. rollover images (or other images/pages) which are part of a Javascript mechanism - ie. hover the mouse, ONMOUSEOVER causes Javascript to load an image or ? - the image is NOT automatically compiled.

Both of these (and other situations, ie. including files withoutout a link from any page) can be overcome by making sure the file is contained in the HHP [FILES] section. ANY file in that section will be included in the final compile, regardless. Just a note, re: this - if multiple files in a folder are to be included, it is ok to use (eg.) C:\BOOK\HTML\*.htm as a [FILE] entry, but don't use C:\BOOK\HTML\*.*. The *.* method tries to find the current folder (\ .) and the parent folder (\ ..) which would be displayed by doing a DIR command. This always leads to a compiler error, although the final output file is fine!

I trust that you have some detailed info, re: format of CHM files - there is a little info (very few sites!) on the Internet which details some of the formats, mostly by experimentation and reverse engineering.

If I can answer any HTML/CHM questions, feel free to ask. I might actually know! BTW, my previous post about HTML compiler bugs is correct, but most of the bugs are in the EDITING part of the program as opposed to the actual compile, although I AM aware of a few odd behaviours.

Cheers,
Allen

RSS

© 2020   Created by Allan Mertner.   Powered by

Report an Issue  |  Terms of Service