Hi,

I know that the FP IDE (text mode) has support for reading OS/2 INF help files. This is pretty cool and it works with just about any INF file I threw at it. :-)

I read my old VisualAge for C++ for OS/2 docs and it says that to generate a INF you need to create the help markup (similar to HTML apparently) in the IFP file and then compile it with the IBM IPFC help compiler.

Does anybody know if there is an open-source IPFC help compiler? One implemented in Object Pascal maybe?

I'm been doing some reading on various help file format - to be used in my applications and possible Lazarus IDE. From my OS/2 2.1 and OS/2 Warp days I remember the INF help was very impressive. Searching was lightning quick even on old hardware and INF files a few megabytes in size. Apparently this is due to the very efficient INF help format.

Anyway, I want to try and implement a GUI version of the INF Help Viewer code available in the FP IDE. But ultimately, I would like to compile my own help as well, under Linux and Windows. Would this be possible?

Regards,
- Graeme -

Standard answer I give to my boss in such cases:
"Given time and money, anything is possible"

:-)

I suppose you'd need the INF specs in order to make a compiler for it.

Michael.

In our previous episode, Graeme Geldenhuys said:

Or maybe because it cached the search index to disk, like most helpfiles.

This is what I'm currently researching for CHM. (merged CHMs/.chw files) While currently it is fast enough, performancewise, "nice" results probably need to mine more info.

Anyway, I want to try and implement a GUI version of the INF Help Viewer code available in the FP IDE. But ultimately, I would like to compile my own help as well, under Linux and Windows. Would this be possible?

I'd go shopping by the OS/2 centric compilers like sybil and vpascal. But fat chance that they used some OS/2 tool for it that isn't ported.

Full specs for the binary format have never been made available by IBM as far as I know (as opposed to the IPF markup language specification, of course). There are some 3rd party documents based on reverse engineering of the binary files - see e.g. http://www.edm2.com/0308/inf.html.

Regarding available code - the more modern version of the INF viewer (NewView) distributed with eComStation (the latest versions of OS/2) nowadays is written in / compiled using Sibyl compiler, i.e. in Object Pascal, and the full source code is available as far as I know. However, I'm not aware of any IPF compiler apart from that one produced by IBM and included in OS/2 Developer Toolkit among others (still downloadable today, although not from IBM pages any longer, I believe). I found the following reference (it
refers to http://www.netlabs.org), but I suspect that the promise mentioned there has never materialized.

From technical point of view, I'd say that INF format capabilities in the

area of graphical layout might be considered outdated nowadays. Whether this is important for your needs or not is another question, of course. There were some very powerful capabilities (e.g. possibility of creating/using special plugins directly invokable from the particular document via a DLL call), but these have never been exploited fully even under OS/2 and are obviously not well portable across different operating systems.

Tomas

VP doesn't use .INF files even internally (proprietary help format, similarly to TP) and certainly doesn't provide an IPF compiler. For Sibyl I strongly believe that they rely on the IBM tool.

Tomas

Marco van de Voort het geskryf:

Or maybe because it cached the search index to disk, like most helpfiles.

As far as I can see, from reading various INF docs is that the IFP Compiler generates the index and keywords at compile-time and are built into the single .INF files. Also every single word only appears once in the INF files, all other instances are simply pointers. So this increases the lookup speed a lot as far as I can see. I guess this contributes to the size factor as well. The VisualAge C++ for OS/2 Users Guide is 1300 pages (with screenshots) and the INF file is only 4.5MB in size! God knows how they managed that!

PS:
It was so cool going through my old software boxes. VisualAge C++ for OS/2 came with 5 printed manuals and a CD-ROM. The box it came in is think cardboard and measures in around 30x30x30 centimetres. HUGE! :-) You don't see that these days!

PS #2:
I found the source code for Sibyl IDE which contains a GUI help viewer (NewView) implemented in Object Pascal (I think it's Free Pascal Compiler compatible).

Regards,
- Graeme -

Michael Van Canneyt het geskryf:

I suppose you'd need the INF specs in order to make a compiler for it.

The spec was never released by IBM as far as I know. But I see the Open Watcom project (actually one guy only - Lawrence Haynes) reverse engineered the IPFC compiler and rewrote a clean-room implementation so they can compile their documentation under OS/2, Windows, DOS and Linux. The new compiler is called 'wipfc' and the source code is available with Open Watcom project.

I'm downloading it now. So with no effort, I get a linux IPF Compiler. Cool!

Regards,
- Graeme -

Tomas Hajny het geskryf:

I'm not aware of any IPF compiler apart from that one produced by IBM and

Actually Lawrence Haynes, from the Open Watcom project re-engineered a clean-room implementation for the Open Watcom project. It is called 'wipfc' and source code is available. There now exists native IPF Compilers for OS/2, Windows, DOS and Linux.

>From technical point of view, I'd say that INF format capabilities in the area of graphical layout might be considered outdated nowadays. Whether

Can you explain this in more detail? I remember reading many years back an OS/2 e-Zine magazine which contained many images (logos, screenshots etc) and it worked fine.

Regards,
- Graeme -

In our previous episode, Graeme Geldenhuys said:

That's something that CHM does too, and nearly any format. I'm talking about when you press F1 in the IDE and those indexes must be combined in the IDE, and a popup must be shown if there are multiple entries over various files.

The entire FPC docs + the Lazarus LCL together is 10MB in CHM. (with the LCL chm being 40% or so of that number) You have been printing it, so you know the number of pages.

Note that this is without the binary TOC that Andrew implemented last night. (and the binary index still yet to come I hope)

I'm not yet entirely convinced what the interesting part of the .INF stuff is, what CHM doesn't provide.

PS #2: I found the source code for Sibyl IDE which contains a GUI help viewer (NewView) implemented in Object Pascal (I think it's Free Pascal Compiler compatible).

Don't forget licensing issues. Also keep in mind that portable editors and generators for HTML are plenty. What about .INF? Is there a Latex2inf?

Marco van de Voort het geskryf:

That's something that CHM does too, and nearly any format. I'm talking about when you press F1 in the IDE and those indexes must be combined in the IDE,

With OS/2's help viewer I can do the following...

view.exe lcl.inf rtl.inf fcl.inf

It will then combine all three "books" into one at runtime (no speed loss what-so-ever). Now the Find, Index, Contents etc pages in the help viewer contains all information from all books. No need for special compiling them into a single big .inf file.

This was often done under OS/2 to give you a kind-of "virtual" bookshelf.

I'm not yet entirely convinced what the interesting part of the .INF stuff is, what CHM doesn't provide.

Something else OS/2's INF did, and I think Windows .HLP also did. The application and help viewer can communicate with you can have something like a tutorial teaching somebody how to use an application. They click a button on menu option as the help tutorial described. As soon as the user clicked the appropriate option, the help window advanced to the next page in the tutorial.

I have never seen this done in CHM help. Is this at all possible still? This feature was often used under OS/2 and worked like a treat!

As far as I remember bookmarking and printing also worked much better under OS/2 help than under Windows Help.

Regards,
- Graeme -

Marco van de Voort wrote

In our previous episode, Graeme Geldenhuys said: > Marco van de Voort het geskryf:

.
.

There is Texinfo2Ipf and HTML2IPF and also probably some others, surely all with their limitations. Nevertheless, I'm not sure if .INF is more interesting/better than CHM nowadays (except for the fact that I'm not aware of a CHM viewer for OS/2, which is an important downside for me personally, of course ;-) ).

Tomas

In our previous episode, Tomas Hajny said:

Then fix the textmode IDE for OS/2 :-)

Point is the CHM support is quite far atm, and I don't think it makes sense to add another format. I'm also seriously thinking to cull some of the legacy formats out of the IDE when the transition is ready.

Maybe with a converter if they must really be supported. (like a TPH2CHM would be great, since that'd allow BP owners to integrate TV help)

Nice. I actually had a feeling that it was mentioned for Watcom, so I quickly checked the OpenWatcom site (in particular the release notes for individual versions) and couldn't find anything there, so I thought that I remembered it wrongly. I'm happy to be proven wrong.

Simple pictures are certainly no problem (although I believe that the INF format only supports BMP files - no JPG, no GIF or PNG, etc.). However, I was more referring to more advanced formatting possibilities; yet again, this may or may not be important depending on your needs and expectations.

Tomas

Would it start working as a general CHM viewer then (including e.g. display of embedded pictures in text mode)? ;-)

Point is the CHM support is quite far atm, and I don't think it makes sense to add another format. I'm also seriously thinking to cull some of the legacy formats out of the IDE when the transition is ready.

.
.

Fine, let's discuss this (dropping of formats) on case by case basis. E.g. OS/2 API documentation is only available in .INF. Dropping .INF automatically means dropping support for these documents.

Tomas

In our previous episode, Tomas Hajny said:

No. Lazarus lview then.

Not dropping the umpteen formats makes any progress on the helpfile front hard. The "portable" architecture based on integers doesn't fit well with formats that base on strings as topic-key. Also disambiguation of keywords in multi-file aggregates would have specific treatment and tradeoffs for all formats.

And since the supported formats already have readers, people still interested in them can make a converter app. Same result, same format support, but at the expensive of minimal work (converting legacy formats), the IDE-help can be easier optimized.

Note that this is still a vague notion. It was a bit pain to implement CHM sometimes (html cuts some corners, specially on inter-file links), but currently it works. It will depend on how the features just over the horizon will require changes to the helpsystem.

Most of that stuff is related to combining central indexes, full search, the caching of those and collecting enough context (_fast) to be able to show a proper disambiguation dialog when F1 is pressed on a keyword that has multiple entries.

That would be good news, shall I add OS/2 as supported targets in Lazarus, so you start to port the LCL to OS/2? ;-)

Vincent

In our previous episode, Vincent Snijders said:

I include that kind of work in my definition of "fix".

Seriously, how is Project Voyager nowadays?

Tomas Hajny het geskryf:

interesting/better than CHM nowadays (except for the fact that I'm not aware of a CHM viewer for OS/2, which is an important downside for me

Doesn't the 'lhelp' project, which is included with Lazarus IDE, compile under OS/2? Then again, does Lazarus actually run under OS/2? I have no idea.

Regards,
- Graeme -

Probably clear from the previous discussion in the meantime, but anyway - neither LCL nor Lazarus itself have been ported to OS/2.

Tomas

Tomas Hajny het geskryf:

remembered it wrongly. I'm happy to be proven wrong.

http://owbuilder.malakovi.cz/snapshot/

I downloaded the Linux IPF compiler from here... I don't know how recent that copy is though.

Simple pictures are certainly no problem (although I believe that the INF format only supports BMP files - no JPG, no GIF or PNG, etc.). However, I was more referring to more advanced formatting possibilities; yet again, this may or may not be important depending on your needs and expectations.

I do not understand "advanced formatting possibilities"? INF supports only BMP and MET (meta graphics). INF also supports hyperlinks via text and graphics. For the graphics you can also support segmented graphic links -- one image containing various links to different help topics or other help files etc... Similar thing to HTML's image map support.

http://tinyurl.com/nvjvdz

or

http://publibfp.boulder.ibm.com/cgi-bin/bookmgr/BOOKS/ej6c2b00/2.3.2.2.3?SHELF=&DT=19941104154554

What I am doing at the moment is reviewing various help formats so I can implement something that works for fpGUI based applications. I do not limit myself to the exact feature list of previous help formats. The INF is a case in point. If I want to support png images in INF, I will add such support in the viewer and compiler. Obviously, then I will change the help file extension as no to confuse other users thinking the INF I use is the same format as the INF used in OS/2.

I'm collecting a feature list for application help. Good compression, speed, size, easy help authoring etc... Obviously I start off with the stock help formats and add my personal needs from there - if the stock help format doesn't support what I want.

Regards,
- Graeme -

Tomas Hajny het geskryf:

Probably clear from the previous discussion in the meantime, but anyway - neither LCL nor Lazarus itself have been ported to OS/2.

Yup, sorry to hear that. I'll add OS/2 support as a feature request for fpGUI Toolkit. It's relatively easy to add new backends to fpGUI - at least much less work than LCL as far as I can see. Anyway, that will give me an excuse to dust off my copies of OS/2 2.1, Warp 3.0 Connect (still my favourite release) and Warp v4. Wow, that will bring back good memories. I was a huge OS/2 supporter in the day. :-)

How well does FPC support OS/2?

Regards,
- Graeme -

To be honest, the support is not so good as with some other platforms, there are several known issues and limitations. One of the problematic areas are limitations related to the ancient EMX (GNU) ld linker (and also other parts of the GNU toolchain like the debugger); it would be better to switch to another linker, but that is a non-trivial task, unfortunately, because it implies many changes also in other areas). One additional area is the well-known 32-bit/16-bit thunking (support of a special calling convention necessary for invoking some of the old 16-bit API still used for console support is not available in FPC, but that is solvable using wrapper DLL like emxwrap.dll). Finally, some parts of the RTL are not debugged that well (or not even finished completely) and some FCL packages have not been ported to OS/2 yet. I'm willing to assist in solving these areas, but my time available for FPC is unfortunately rather limited and thus the progress is very slow.

Tomas

Apparently more recent than the latest release (1.8), because it's the snapshot building machine for OpenWatcom.

One simple example - INF/IPF specifies the size in characters (see e.g. table column size). The format (IPF this time) is primarily based on the assumption of working with monospaced raster fonts (which btw makes the specification of fonts completely non-portable). There are many more examples for sure, I'd just need to dig through the documents to remember them. In any case, the limitations make the format very nice for stuff like our text mode IDE.

Neither BMP nor MET are very efficient from storage/compression point of view. Yet again - it was fairly advanced at its time, but its age is visible now. Still, it works pretty well, it's just not that "fancy" any longer.

OK, that is certainly a viable approach (with its obvious limitations stemming from the fact that it becomes a new format).

I'm collecting a feature list for application help. Good compression, speed, size, easy help authoring etc... Obviously I start off with the stock help formats and add my personal needs from there - if the stock help format doesn't support what I want.

OK, clear.

Tomas