Marco van de Voort wrote

When the recent discussion about git moved to fpc-other, that reminded me that the last to-fpc-other discussion had loose ends :-)

Oh boy, this sounds serious. Doesn't not replying, also answer a question. ;-) Just kidding.

- Don't compare compressed sizes if you must depack to use. OR at least         clearly annotate such (or provide both statistics)

Not 100% sure what you mean here. I thought I compared a INF file to a CHM file to the unpacked HTML help archive. 3 size comparisons. Lets use LCL.

lcl.inf -> 3.8MB

lcl.chm -> 10.9MB
but apparently you need the lcl.xct file too for keyword support which is already
included in the INF file, so lets add that file too. lcl.chm + lcl.xct -> 12.1MB

lcl help in HTML format -> 65MB (
This is the <lazarus>/docs/lcl/html/ directory after generating the LCL help in
HTML format.

So as you can see, having the same content, but in different formats, there is a big difference in size. So why download a larger archive, when a smaller archive contains the same help content, plus index, keyword search plus TOC etc...

At one stage (a couple months back), did a speed comparison between the help viewers for use with Lazarus IDE as well. I used EpikTimer, to wrap the code that loads a topic and displays that topic - ready for a end-user to start reading the content. I compared DocView against LHelp. In my tests, DocView was about 20+ times (on avg.) faster than LHelp, loading and displaying the same topics.

I then disregarding the "displaying of topics", and only timed the loading of topics. Again, DocView was considerably faster that LHelp.

I also did a speed comparison in loading of the help file itself, and simply populating the Table of Content and Index. Again DocView was some 20-25 times faster than LHelp. This I believe was after some binary tree addition to the CHM code which should have increased the CHM speed.

Another test I did was scrolling of loaded content. Load a large topic, then drag the scrollbar button from the top to the bottom. After all, help is there to me read, and the end-user is bound to scroll the help. So my thinking was to test what the end-user would experience. If memory serves me well, I used the LCL TApplication topic (in INF help, that would be the TApplication Method Overview node). LHelp was simply unusable, but apparently the HTML Viewer component used by LHelp is to blame for that. Never the less, that is the experience the end-user would get.

So if any of these tests and comparisons seem unfair in any way, please let me know, and suggest any alternative way I can do similar comparisons. My main point I was trying to get at was download size (myself and many others I have limited internet bandwidth per month), and end-user experience.

The main reason seems to be to make html usable without an index tab left to it.  This is useful for online use (though strictly, you could have an index

Just like the HTML or CHM help needs additional information to have some form of navigation like a Table of Content, so do does the INF format have additional information for TOC and Index support. A TOC does not appear magically in INF, the fpdoc IPF writer needs to add information in the IPF output for that. The Index is a different matter. You can have built-in Index information in the INF file, but DocView has a special ability to build it's own Index or or even use a combined Index (one from the INF file, and one it generates itself).

I can count on my one hand how many times I have used the textmode FP IDE. I was under the impression that the textmode IDE is a dying project. Either way, I fired it up at tried it for the first time with the INF files I generated recently. Attached is a screenshot of how I setup textmode FP IDE for INF. I included two more screenshots (in separate emails) showing what I saw. I used separate emails because I don't know the attachment size limit in fpc-other mailing list. Do you know?

Pressing F1 while the cursor was on TStringList, the help windows showed me an Index page. A rather large list. I took a guess and started typing TStringList, and it automatically jumped to TStringList in the Index. I pressed Enter and saw the TStringList overview page (image in part 1 email). The overview pages is what I would have expected to see if I searched any help for TStringList. So this is good so far.

I then tried the Prev / Next links you mentioned. These are not part of the INF topics content by the way, they are inserted by textmode IDE help system. I selected next, and it showed me the TStringList Method Overview. As I expected too. It seems the prev/next links are walking through the TOC tree - built into the INF file.

Then tabbing to one of the methods (Add() in this case), and pressing Enter, it indeed showed me a blank help window. This is clearly some bug in textmode IDE, because even the prev/next links inserted by textmode IDE is not there. I have tested the INF files I generated using various software. I used the iview program (IBM's official Windows INF Help Viewer), and with OS/2's VIEW (official IBM OS/2 viewer), and eComStation's NewView (open source replacement for IBM's view) and official help viewer of eComStation. In all these tests, navigating hyperlinks inside topics worked fine. I quickly tested rtl.inf and the TStringList.Add link with iview, and it does display the Add() method help topic correctly.

I can supply you with a download link for the IBM Windows INF viewer (iview) I use, if you want.

In short, this might become a problem for integrating INF into other 3rd party helpsystems (e.g. editors) too.

Like I said above, the blank help pages is a textmode IDE issue, not a issue in the INF files itself. DocView doesn't use any of the INF reading code from the textmode IDE.

Are prev/next provided by the reader systems (or e.g. by special macros), or are they in the content?  If the former, probably all in-content links don't

As I mentioned above, those prev/next links are inserted by the textmode IDE. They are not part of the actual INF files viewed. So indeed, there is something strange (read bug) with the textmode IDE code.

Seeing that I know the INF file structure quite well, I could take a look at the textmode IDE INF reading code, but this will not be a high priority for me. So it will be time permitting only.

BTW:
Is anybody actually using the textmode IDE?

In case those previous attachments don't go through (which it seems they didn't), here are some external links to those images.

How I setup INF files with textmode IDE:
http://opensoft.homeip.net/~graemeg/fp_ide_inf_setup.png

TStringList overview topic as shown in textmode IDE: http://opensoft.homeip.net/~graemeg/fp_ide_stringlist-1.png

After following the "next topic" link from the previous image http://opensoft.homeip.net/~graemeg/fp_ide_stringlist-2.png

PS to mailing list admin:
Could the attachment size be increased for this mailing list? My previous attachments where 22-25KB and they didn't seem to make it through to the mailing list. External links don't always last forever, so including images in messages is nice for archiving purposes.

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.

Graeme Geldenhuys wrote

On 6 September 2010 15:36, Marco van de Voort wrote:

.
.

Neither Lazarus IDE nor MSEide are available under OS/2 and I don't expect that to change any time soon. So if I use an IDE (rather than a standalone editor and command line tools - that is an option I occasionally use too depending on the particular task), it's the textmode IDE.

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

I'm not sure whether redesigning it is really necessary (especially if the goals, advantages and collateral damages are not known beforehand ;-) ), but I'd appreciate fixing whatever bugs are there.

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

That would be nice. Obviously, having the official IBM docs working there would be even better. ;-)

Tomas

Ah, a valid point. I forgot about the OS/2 developers. This brings me to another question I have been meaning to ask you (seeing that you are the only FPC developer under OS/2 I know). Sybil (or WDSybil) still runs under OS/2, does it not? It is open-source, so is it not possible to allow Sybil to call FPC instead of the Sybil compiler? This should give you an instant "object pascal friendly" IDE to work with - hopefully with relatively little effort.

Alternatively, and something that has been on my mind for a while. I was a big fan of OS/2 in the early 90's. I even did promotional work for IBM (not that it helped much). Does OS/2 support SDL? I'm seeing a gap in the market, and would like to kill two birds with one stone. I'm getting a renewed interest in OS/2, and I'm lately rather impressed with Haiku as well. I think Haiku supports SDL already. What I'm getting at, is writing a new fpGUI backend with SDL, so I can target all those "specialized" platforms with a single fpGUI backend - similar to what Pixel32 (photo editing software) project did.

In my spare time (when I wasn't arguing with Marco or the Lazarus developers <wink>), I starting writing a fpGUI based IDE. This was done two-fold: 1) to get the features I wanted in a IDE, 2) to create a more realistic "real world" application that can show off fpGUI a bit. Many developers still think fpGUI is pretty useless, but they are wrong. Hopefully DocView was a push in the right direction. As a side note, I would also like the efforts I put into the IDE, to help some platforms get more use out of FPC. Platforms like OS/2 and Haiku, by giving them a new GUI development framework and some tools to use it with. After all, they already have the excellent FPC compiler.

I'm not sure whether redesigning it is really necessary (especially if the goals, advantages and collateral damages are not known beforehand ;-) ), but I'd appreciate fixing whatever bugs are there.

Exactly my point. I would rather fix the few bugs in the textmode IDE, and then spend the bulk of my spare time developing a more up-to-date IDE and GUI framework for those niche/specialized OS's. OS's which Lazarus and MSEide are not currently targeting. The benefits will be much greater I think.

The effort would not be that little, unfortunately. (WD)Sybil class library is obviously based on (WD)Sybil RTL and that isn't completely compatible to FPC RTL (for various reasons). Yuri Prokushev tried to restructure the FPC RTL in order to improve the compatibility few years ago, but he didn't finish the task and even if he did, it wouldn't be so nice to have two different sets of RTL units (one based on the standard FPC structure and the other following the (WD)Sybil structure). Moreover, (WD)Sybil compiler parameters are completely different from that one of FPC, of course. Debug information is incompatible, executable format is incompatible, etc. Quite some work, in fact; possibly more than what would be necessary to port one of the FPC IDEs to OS/2 (especially if you consider that (WD)Sybil people are probably not really motivated to move to FPC and thus not much support could be expected from their side)...

.
.

Yes, some version of SDL is available and Pavel Kanzelsberger used it when porting Pixel32 to OS/2. I don't know much about its completeness and stability, though (but I believe that the person who performed the OS/2 port of SDL was quite supportive in removing any reported bugs).

Tomas