[fpc-pascal] DocView and FPC documentation release

[Marco van de Voort]

In our previous episode, Graeme Geldenhuys said:
> > 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.

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.
 
> > 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.

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.

> > As an example I created a screenshot comparison of the TStringlist topic,
> > with the IPF help inlayed to the HTML/CHM topic:
> > 
> > Note that the html output screenshot was clipped, but the see-also section
> > follows.  (and is better formattted too, with descriptions for the links)
> 
> INF class docs are simply in a different layout, but all the same
> information is available as HTML or CHM. 

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)

> 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.

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) 
 
> > 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.

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?