Hi Everybody,

I am pleased to announce that fpGUI's DocView is available for download in a convenient binary executable from fpGUI's SourceForge project page. See the URL below.

I have also made available RTL, FCL, LCL and fpGUI class documentation in INF help format. The documentation downloads are grouped, so you only need to download what you really need.

http://sourceforge.net/projects/fpgui/files/

Download size:
--------------
DocView plus it's help file:
Linux 32-bit = 533KB
Linux 64-bit = 446KB
Windows 32-bit = 367KB

Class Documentation:
fpGUI [fpgui-20100826.zip] = 0.1MB
RTL + FCL [rtl_fcl-20100826.zip] = 1.3MB
LCL [lcl-20100826.zip] = 1.4MB

Why DocView and INF help?
-------------------------
INF is a very compact and very efficient file format created by IBM and was originally meant for OS/2. As an example of efficiency, let compare the LCL documentation. LCL class documentation in INF format is a mere 3.8MB in size - compare that to the same documentation in HTML format (65MB) or CHM format (12.1MB).

DocView + INF is a perfect match. Here are some of DocView's features:

* DocView's rich text component is custom built for viewing INF documents. It is also very fast. Just view something like LCL's Forms.TApplication method overview help and you will see. DocView can load it instantly, under a second. Scrolling such a large page is no problem either [unlike another help viewer I know ;-)].

* DocView can open a single INF file, multiple INF files, or a whole directory of INF files. DocView doesn't even blink.

* Opening multiple files means the Table of Content tab appends each help files TOC to the list. Indexes get merged as well.

* Searching is lightning fast, and across all open help files.

* Create a "virtual bookshelf" of documentation. Docview can open directories, or environment variables pointing to help files.

* DocView is customizable. Change the fonts, adjust the search highlighting color, hide the navigation tab etc.

* DocView comes with it's own help file to explain all it's features and has multiple examples of how it can be used.

* DocView is very easy to integrate with any programmer editor or IDE. No need to have support compiled into a IDE.
Attached are screenshots of how to set it up with Lazarus IDE and MSEide. Simply use the "external tools" feature of each IDE, and pass in the current token to edit cursor is on.

* The latest fpdoc (in FPC 2.5.1) has had a major rewrite of the IPF output writer. IPF is the markup language (similar to other markup languages) used to create INF help files.
fpGUI's source repository contains the IPF Compiler in binary form, for Windows and Linux. It also includes a IPF Reference Guide.

What's to come
--------------
* I have more features planned for DocView.

* I'm working on translating the Free Pascal Language Reference document to INF format. That way developers have syntax help as well in there IDE's

* Lots more fpGUI class documentation coming.

Please enjoy, and I welcome any feedback.

Regards,
- Graeme -

On Thu, August 26, 2010 17:55, Graeme Geldenhuys wrote:

Hi Graeme,

I am pleased to announce that fpGUI's DocView is available for download in a convenient binary executable from fpGUI's SourceForge project page. See the URL below.

.
.

Thanks!

Any idea why is your Win32 binary 100 kB (12%) larger than the one I compiled two days ago from your fpGui7.0 sources available in SourceForge? I assume you haven't made any changes in the sources in between, have you?

I tried opening some OS/2 INF files (in particular the "pascalized" version of the IBM OS/2 Control Program Reference/CPREF distributed with Virtual Pascal v1.0) and DocView displayed empty pages for just any of the Control Program APIs listed in the Contents pane. IBM's XVIEW (Win16 viewer) and IVIEW (Win32 viewer) both display the same file correctly.

Tomas

The rtl.inf downloaded from your site is 2MB, the fcl one is 800kb. rtl.chm 2.5MB the FCL one is 1.3MB. Aside from that, the .INF format simply holds less information, see below:

This is a bit misleading, since it is not just a matter of format, but mostly reduced content. The IPF documentation is generated differently, and the raw content is simply much less.

As an example I created a screenshot comparison of the TStringlist topic, with the IPF help inlayed to the HTML/CHM topic:

http://www.stack.nl/~marcov/strlst.png

Note that the html output screenshot was clipped, but the see-also section follows. (and is better formattted too, with descriptions for the links)

Note that Classes and other complex type are a special case, but it does account for the LCL size being so small, since that mostly is classes.

But e.g. the see also bit with description, and the links on top goes for every lemma.

Op 2010-08-27 14:04, Marco van de Voort het geskryf:

> > Class Documentation: > fpGUI [fpgui-20100826.zip] = 0.1MB > RTL + FCL [rtl_fcl-20100826.zip] = 1.3MB

These are zip file sizes. Not the unpacked sizes.

The rtl.inf downloaded from your site is 2MB, the fcl one is 800kb. rtl.chm 2.5MB the FCL one is 1.3MB. Aside from that, the .INF format simply holds less information, see below:

You forgot the .xct and .kwd files that go with the .chm files. INF is one file only. And no not less information - they hold the exact same documentation, just in a different layout.

mostly reduced content. The IPF documentation is generated differently, and the raw content is simply much less.

The internal INF structure is more efficient. The more text, the more efficient it becomes - hence the big size difference in the LCL help. A single word of text only appears once in the INF file - the other iterations are simply links to that word.

INF class docs are simply in a different layout, but all the same information is available as HTML or CHM. INF follows the layout of a book, but less so than the PDF docs. Currently the only missing item, is the inheritance tree, which I'm working on already. See attached screenshot that shows where all the other information is located. INF (like PDF) doesn't shove all information in one page (or section), but rather have various Overview sections. One for the Class or Type, then Interfaces, then Methods, then Properties and Events, then individual items of that class or type. Same info as your HTML screenshot, just split over various tree nodes.

As for cross-linking (one document to another), the INF format supports that too, I just haven't implement it in DocView yet. But that is not even a problem at the moment. Simply open RTL, FCL and LCL docs at the same time, search and index works across all opened documents.

Note that Classes and other complex type are a special case, but it does account for the LCL size being so small, since that mostly is classes.

12.1MB (CHM) vs 3.8MB (INF)
CHM then clearly has a crap load of duplicate/redundant information to make that a big size difference.

Anyway, nobody is forcing you to use INF. I simply made the option available for those that want really fast viewable and searches help, much smaller downloads, and most importantly... available offline with very easy integration in IDE's or other programmer editors.

Regards,
- Graeme -

In our previous episode, Graeme Geldenhuys said:

So is CHM.

.xct are general fpdoc files, and apply to inf as well as chm. These files are simply the info format that enable fpdoc packages to interlink. (and if you don't know that, check if fpgui->fcl->rtl links work with IPF/INF).

The (5kb!) ref.kwd files are not needed for CHM. It is generated by the latex process and lists the Pascal keywords.

It is folded into the keyword index of ref.chm. (in a similar way that I assume you use it for ref.inf, but I could not find that file to check it)

Since lazarus is still in the transformation process from online-only help to offline help, and this file is used by Lazarus to recognize keywords in the editor, it is provided, and enlarges the archive with a gigantic 2kb (5kb uncompressed).

And no not less information - they hold the exact same documentation, just in a different layout.

See the screenshot. It shows more than I can repeat here. It is the same keyword/lemma.

I agree it is partially redundant info, but that is a choice for hyperlinked documentation, vs printed documentation. (see the reply to Michael).

I didn't know IPF was for printing purposes only.

I know the blurb, but now I first got my hand on IPF files, I no longer believe that is the major difference. I think the major difference is that the HTML _writer_ simply generates more output, and a stronger hyperlinked result.

The easiest way to compare of course is if you duplicate the same output. But I assume that is too much work.

Sure. Just not so strongly hyperlinked. And that is my point. It is a different way of rendering, not efficiency of the format.

INF follows the layout of a book, but less so than the PDF docs. Currently the only missing item, is the inheritance tree, which I'm working on already. See attached screenshot that shows where all the other information is located.

Hmm, I'm currently logged on via console, so I can't view it. How far are you with the interface part? I fixed that bug, and the .xct files now contain enough info to also produce a inheritance tree including all interfaces. (except for the iinterface type-alias problem)

No. Html has those pages too (see the links at the top). It is simply that the class overview is really an overview of the whole class, rather than just the nodes attached directly to the class.

As for cross-linking (one document to another), the INF format supports that too, I just haven't implement it in DocView yet. But that is not even a problem at the moment. Simply open RTL, FCL and LCL docs at the same time, search and index works across all opened documents.

I had already guessed that. Btw, I also tried the inf files quickly in the IDE, and had a bit peculiar result:

1. the normal next/previous links seemed to work fine.
2. all other links seemed not to work. (e.g. jumping to random topics)

11.5MB vs 6.8, since you don't provide prog,ref,user,fpdoc, and on my disc the inf files are 6.8.

And I can't even bother trying to explain the sizes (though there are arguments enough). It is a non-issue.

The plain text ones are even smaller when compressed as a solid RAR, and I think you can also write a very small viewer for it in assembler. I don't care.

Anyway, nobody is forcing you to use INF.

And nobody is forcing you to make stupid size comparisons on each release. So please stop doing crooked comparisons all the time, and this will be the last time that we have this discussion.

I think I fixed enough passrc and fpdoc bugs recently, that I don't deserve this.

I simply made the option available for those that want really fast viewable and searches help, much smaller downloads, and most importantly... available offline with very easy integration in IDE's or other programmer editors.

Huh? Is there something else than the textmode IDE that supports it then?

What is docviewer good for then?

Op 2010-08-27 16:52, Marco van de Voort het geskryf:

Sure. Just not so strongly hyperlinked. And that is my point. It is a different way of rendering, not efficiency of the format.

Now that you have INF files to play with, please give me examples where HTML or CHM has hyperlinked items where INF doesn't. The two "see also" links in your screenshot (TStrings.Duplicates and TStrings.Sorted) are not hyperlinked because of fpdoc or documentation bugs (yes there are those too). Click on those links in the CHM or HTML help and you will see, they jump to the TStrings docs, and not to each individual property as the See Also section lists. INF doesn't show "incorrect" links as hyperlinks - done so by design.

How far are you with the interface part? I fixed that bug, and the .xct files now

Just started with that.

Regards,
- Graeme -