[fpc-other] Re: inf files and textmode IDE (fwd)

[Graeme Geldenhuys]

On 6 September 2010 15:36, Marco van de Voort  wrote:
> No, you compared a compressed INF to a CHM, on the basis that they had the
> exact same context, while in fact the content generating routines are
> different (html vs linear, with html repeating more code, e.g. for the
> larger class overviews).

I'm working on the premiss that they have the same content
(originating from the fpdoc XML description files). Whatever is
available in the XML files _are_ in the final help format.

Of course you can't compare INF content to CHM content (not referring
the help content here, but to file structure content), because they
are different file formats with different file structures to
ultimately produce the same result to the end user.

So to be clear:  same content = same xml description files.

As for the "larger class overviews". I consider them the same, just
presented differently to the end-user. CHM and HTML shows one LARGE
page with Class summary, Method overview and Event overview and
implemented Interface overview.  One big ass page (which doesn't do
LHelp any favours).  In INF, that _exact_ same information is split
across three/four tree nodes in the TOC. Again using the TStringList
as an example.

  TStringList    ---->  Class summary page: used units, short & long description
     Interface Overview       ------> list implemented interfaces with
descriptions
                                                   if no interfaces
are used, this node does not exist
     Method Overview         -----> list all methods of the class with
descriptions
     Event Overview             -----> list all events of the class
with descriptions


So CHM "class overview"  =   INF's Class summary + Interface Overview +
                                                Method overview + Event overview

And if we really want to nitpick, the only thing INF doesn't currently
show (which I'll be adding before the next INF docs release) is the
class declaration. But surely something as small as the class
declaration can't contribute for a 3.8MB vs 11.9MB difference. And by
class declaration, the only physical text strings that are missing in
INF is the keywords 'type', 'class', 'destructor', 'constructor',
'procedure', 'function' and 'property'. The actual identifier for the
class name, and its methods and properties, including descriptions for
each of those _are_ in XXX Overview pages in INF.


> I'm not interested in the unpacked .html, since I don't consider it a help
> system.

Good, we agree on something.  :)


> But _is_ it equal? Since the CHM files had the following (uncommitted) patch
> to the build systems applied:

I use the same build scripts included with Lazarus, and I call it as follows:

./build_lcl_docs --outfmt ipf --fpdoc /opt/fpc-2.5.1/src/utils/fpdoc/fpdoc


And yes I know about the flaw in the Lazarus docs build script where
they disregard order. I actually created a console docs build app for
fpGUI to fix a similar issue. It doesn't use scripts (so runs on all
platforms), and I specify the correct order of units inside the
console app.


> where you can insert your advocacy. .xct are related to fpdoc only, and
> not part of the helpsystem. The fact that you don't know that doesn't bode
> well for inter-inf links.

OK, so that's probably where the confusion came in. I call those files
.cnt where you call them .xct
So if they are not part of the help system, why did you include them
in the latest chm zip archive you published?  It was part of your
published zip archive, so I count them as part of the download size
comparison.


> A 100% difference in archive size is about true. A significant part of that
> is due to a bigger class overview, and links from topic to topic outside the

See above, I already explained that. The information IS in the INF
file, just over 3 or 4 TOC nodes.  It's simply a difference in
presentation/layout, not in help content.


> A small price to pay for a format that comes with multiple viewers default
> on various operating systems and a portable compiler.

Don't even go there... Multiple CHM viewers under Linux! Yeah right!
Lets see... some don't display the CSS stylesheets, some don't support
Indexes and Searching, some don't display the TOC, most don't support
cross-chm links (unknown ms-its: protocol errors), and if they do
support it, the Back button doesn't take you back to the original CHM
file, most can't load multiple CHM files, and the list goes on.   A
pretty huge mess - and a good example of the failure of open-source
software. Sh**ty levels of implemented features - or the lack thereof.

Hence I compare something closer to home... something written in FPC's
Object Pascal. Hence... LHelp and DocView.


> The CHM support is not really optimized at all atm, but pitted for

For your information, I haven't even started profiling or optimizing
DocView. The only profiling I done (a few days ago after the docview
release) was to see where the slow initial loading bug was under Linux
(reported by one or two people). No other profiling has been done.  So
I think we are on equal ground there.


> I don't even need hands to count the number of times I used fpgui.
> (Sebastians period excluded, since that was before Lazarus worked on win32)

I really don't care if you don't use fpGUI to develop software. What I
did care about was giving end-users a "offline help system", that is
small and fast. Ever seen how many complain about Lazarus only having
online help. Hence the reason I released pre-build binaries for the
docs (INF files) and for the help viewer (Docview), and included
instructions on how to integrate it with Lazarus and MSEide.
Otherwise I would have simply said: compile it yourself.



> I assume the inf stuff is easily fixable if sb could be bothered, but the
> problem is also a bit that the whole helpsystem is too simplistic.

Like I said, I don't mind taking a look. But you keep talking about
redesigning the textmode IDE help system. Is that effort really worth
in for that one or two developers still using it. I thought everybody
moved to greener pastures (where development still occurs) and now use
Lazarus IDE or MSEide.

I'll fix the INF help in the textmode IDE, but I really don't see the
point in redesigning something that is ultimately not use by anybody.
Silent developers don't count - they might already be dead for all we
know.  :-)


> enthusiast) are going to fix .INF in the textmode IDE, or if I can
> delete/disable it otherwise ;)

Because it's probably something small, I'll fix it.



-- 
Regards,
  - Graeme -


_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/