Hi,

I've been working on a new help system for fpGUI and Lazarus (IDE & apps). Attached is a screenshot of the Help Viewer I am working on. (please ignore the floating button - it's only there for debugging) It is showing the FPC Language Reference documentation (not fully converted from LaTeX yet). Currently the help viewer is written using fpGUI Toolkit, but the bulk of the help system is GUI toolkit independent classes and units, so it should be very easy to create a LCL based help viewer if the need arises. The help viewer could even be used for MSEgui - it seems all FPC based projects have a lack of a decent help system / viewer.

Why a new help system?
----------------------
* Wiki pages as a help system is awful.
- You have to edit it while online
- Help in applications only exist if you have a internet connection. No Offline Help!!

* HTML is designed for the web, not as a help system.
- HTML viewers are bulky (Firefox, Internet Explorer etc.)
- HTML text is inefficient, verbose and large in size.
- Various HTML viewers do not present the content in a consistent manner. Some HTML viewers show the content looking different.

* No offence to Michael. :-) PDF's are great for books etc. That's if you plan to print them at some stage. They do not work well for a help system though. That was not what they where designed for.

My Help Viewer features consist of:
-----------------------------------
* Very fast viewer
* Purpose built help format which optimises size and speed. HTML as used in CHM is not optimised for a help system. That's my opinion.
* Purpose build help viewer window for consistent displaying of help.
* The viewer can load multiple files and concatenate their Indexes and Table of Contents to make a "virtual bookshelf". So you could load the Ref, Prog and LCL help files together and see one large TOC and Index pages.
* Searching works across the "virtual bookshelf".
* The help format has built-in Full Text Search. Each word in the help contents only appear once in the compiled help file. The rest is dictionary lookup pointers. This causes a huge increase in speed and size of the compiled help file.
* No unpacking of help content before they can be viewed.
* External notes can be added to help pages, so when you load those pages at a later date, you can view your notes again.
* Bookmarking is supported
* Printing sections or all content will be supported.

Please note that not all features have already been implemented. TOC, Indexes, Searching and viewing multiple files already works.

You plan to convert the FPC docs each time something is changed ? I hope you have a latex->something converter program :-)

Michael.

Graeme Geldenhuys wrpte:

I've been working on a new help system for fpGUI and Lazarus (IDE & apps). Attached is a screenshot of the Help Viewer I am working on.

What is wrong with lhelp? Please evaluate solution which lazarus will have in the next release (0.9.30).

http://wiki.lazarus.freepascal.org/IDE_Development#Builtin_CHM_help

Best regards,
Paul Ishenin.

2009/10/1 Michael Van Canneyt :

You plan to convert the FPC docs each time something is changed ? I hope you have a latex->something converter program :-)

That would be stating the obvious. ;-) The new help format is a hybrid INF format (from OS/2 INF help files). INF is an excellent format with many build-in features. I'm adding a few customizations of my own to bring it into the 21st century. The FP Text IDE was a great source of information regarding various help file formats.

Conversion from latex would be the first external format I support. MediaWiki importing will probably follow after that. I am also going to supply patches for 'fpdoc'. The current IPF output (uncompiled INF format) from fpdoc looks pretty horrible - a lot of space for improvement there. :-)

Good. Maybe you can add a compiled INF format then as well...

Did you write the converter program yourself or is it something external ?

Michael.

2009/10/1 Paul Ishenin :

What is wrong with lhelp? Please evaluate solution which lazarus will have in the next release (0.9.30).

See my comments regarding HTML help formats...

OK, lhelp seems to have improved and now support Indexes - last time I checked, it did not. lhelp also seems to be rendering the content better that before. But the general issues of CHM still exists. It will will be an improvement though, over the current "online only" help support that the IDE has.

See attached image for some issues I just found.

2009/10/1 Paul Ishenin :

What is wrong with lhelp?

Searching sucks in any CHM viewer! See attached image and associated help content as an example. One think pro about lhelp compared to other CHM viewers under Linux - it includes a "search" tab, even though searching doesn't work. ;-)

Regards,
- Graeme -

_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: LHelp-Search.png
Type: image/png
Size: 9786 bytes
Desc: not available
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20091001/b9f5d5cb/attachment.png>

2009/10/1 Michael Van Canneyt :

Good. Maybe you can add a compiled INF format then as well...

I'm will be working on a Object Pascal implementation of the IPF compiler. Currently I'm using the WIPFC complier from the the Open Watcom v1.9 (beta) project. They implemented their own IPF compiler to overcome bugs in the original IBM IPFC compiler. Plus the new WIPFC compiler is available for more platforms.

Did you write the converter program yourself or is it something external ?

Custom written, but far from complete.

By the way, why did you use line drawing in the syntax format diagrams? During my help format research I played around with OpenOffice and could duplicate the ref.pdf with OpenOffice and using DejaVu font, and use Unicode block drawing symbols to end up with a slightly better looking output than the LaTeX line drawing. Maybe "slightly better looking" is a biased statement. :-) I can send you a ODT & PDF document in private if you want to compare. Unicode block drawing symbols are very handy for just such things - old ASCII Art style. ;-)

Regards,
- Graeme -

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

2009/10/1 Paul Ishenin :

What is wrong with lhelp?

Another bug.... I ran lhelp. Then opened the "Beyond Compare 2" CHM help file. Browsed around a bit in the help. Then I did "File > Open" and selected the PINs.CHM help file. The title of lhelp changed, but the content and the tab at the bottom still show BC2's help.

Do you have an overview of what works and what not, and practical aspects of the system?

E.g.
- what the "key" is, that identifies a topic
- how links over module bounderies work,
- if you can have abstract aliases (that automatically aggregate over multiple help modules)
- do you support legacy "id" based numeric keys?
- How are the index and toc organized? Do they support multiple entries per key? Can an (index) search return multiple entries?
- How is the fulltext search organized? Does it add up with multiple files?
- Does you system need write access (e.g. for cache files)?
- What is the time to load the LCL index file and merge it with the FCL and RTL files?
- Can you create combined TOCs?
- Are big tocs loadable in stages?
- Can you pack arbitrary HTML into a file?

These are only the ones I can think of quickly.

Note that my CHM experience have made me doubt "generalized" systems of help a bit (multi format ones) like the current textmode IDE and the Lazarus IDE. As always with general systems, you get only the lowest common denomitor.

Graeme Geldenhuys wrote

By the way, why did you use line drawing in the syntax format diagrams?

There is no drawing in the FPC source. These diagrams are written by a package. The PDF versions should be pretty hires. The png renderings for html are bit less beautiful.

2009/10/1 Marco van de Voort :

There is no drawing in the FPC source. These diagrams are written by a package. The PDF versions should be pretty hires. The png renderings for html are bit less beautiful.

I know the syntax diagrams are not Images in the PDF. But I am simply a pain in the butt when it comes to details. See attached image of the ref.pdf document (which I just generated).

* Note the not-aligned lines next to the text. This appears throughout the PDF.
* Note that some horizontal lines are more fuzzy than others. The 3rd and 4th horizontal lines are clearly more fuzzy than the 1st horizontal line. I have no explanation for this. :-(

I viewed the PDF with Acrobat Reader 9 at 125%. Using the Ascii Art style with Unicode block drawing characters the ODT, PDF and Printed output all look the same - aligned lines and sharp.

Hats off... I've been waiting for something like this for years... :)

A latex package was used to create the diagrams.

Michael.

2009/10/1 Marco van de Voort :

Do you have an overview of what works and what not, and practical aspects of the system?

How do I generate the FCL and RTL documentation in INF (actually IPF) format?

  $ make rtl.chk fcl.chk

This generates the HTML output. Not what I want.

- what the "key" is, that identifies a topic

Similar to HTML. The H<n> tags. You can then specify document wide which H<n> tags should appear in the Table of Content. You can also explicitly hide any topic from the TOC.

- how links over module bounderies work,

Explain "module"?

- do you support legacy "id" based numeric keys?

Yes, text and numeric keys are supported.

- How are the index and toc organized? Do they support multiple entries per ?key? Can an (index) search return multiple entries?

See my first answer. Yes and Yes. The Index is based a lot on the information from the TOC data structure. Also if you do not explicitly specify index key words, it's not the end of the world either. The INF file format stores a dictionary of ALL unique words and symbols. So a search will work on all content. The actual help
contents/topics/articles data structure are simply pointers to the dictionary. This is VERY efficient and very fast!

- How is the fulltext search organized? Does it add up with multiple files?

See previous answer. Yes.

- Does you system need write access (e.g. for cache files)?

No cached files are required, so no write access needed to view help. The only time the help viewer writes to the disk is when you added custom user Notes to the help topics while viewing the help, or adding Bookmarks. Those notes and bookmarks will be stored in the users AppData (writeable) location. So you can view help directly from a CD-ROM and still see your Notes or Bookmarks with the help.

- What is the time to load the LCL index file and merge it with the FCL and ? RTL files?

I have loaded 10+ help files (totalling about 9000+ help pages), all over 2MB in size each. Loading time was instant. I'm waiting on instructions on how to generate alternative output formats of the FCL and RTL documentation, so I can do actual tests with those help files. Format of loading multiple files as a single "virtual bookshelf" is as follows

   $ helpviewer <file-1>+<file-2>+...+<file-n>

The Table of Content is then a concatenation of all the files individual TOC's. The TOC items will appear in the order of how the files where specified. So based on this, it will probably be a good idea to structure the FPC and Lazarus help with one top level TOC item (name of the document) and then the general TOC one level down. That should give you a "global" TOC looking as follows:

Contents
+ Free Pascal Language Guide
+ FCL documetation
+ RTL documentation
+ LCL documentation

- Can you create combined TOCs?

Yes, see previous answer.

- Are big tocs loadable in stages?

No need, the load time is instant. The storage structure of INF is very efficient, and are only a few bytes to extract. Good [efficient] programming from the 80's and 90's! Something that is lacking hugely in today's software.

- Can you pack arbitrary HTML into a file?

I don't see the use of this. Can you explain why you would want too? The INF has a very easy to learn mark-up language (48 tags to be exact) - similar to HTML and XML tags so should be easy to learn. I will probably be extending these as the need arises. Also a front-end GUI for writing documentation might be nice. Alternatively, a IPF pre-processor could be written (similar to fpdoc now), taking one format and generating IPF output.

Note that my CHM experience have made me doubt "generalized" systems of help a bit (multi format ones) like the current textmode IDE and the Lazarus IDE. As always with general systems, you get only the lowest common denomitor.

I've always said it, and I'll say it again. HTML was NOT design as a help medium. Microsoft just took the quick route in slapping them into a single archive and call it a new help format. Also note, that yes the FP Text IDE help code was an inspiration to me, but I did *not* follow that design. The help viewer I am writing can only view OS/2 INF & HLP files (both are actually identical formats except for 1 bit flag change). In the future it should probably be able to view the original OS/2 help formats and the newer hybrid help format. I am not guaranteeing backward compatibility with OS/2 at all - it is simply a launching point.

Graeme Geldenhuys wrote

2009/10/1 Paul Ishenin : > What is wrong with lhelp?

Thanks for the help in spotting these errors. Most of them have been fixed in r21945.

Can you send me the chm which has the Indy License Agreement over and over in the TOC? I would like to fix this bug.

Thanks,

Andrew

The reason for this is probably simple. When a chm is generated with the ms help workshop a list can be specified of words not to index. likely "are" was in that list as well as "the" "a" etc.

Regards,

Andrew

2009/10/1 Andrew Haines :

ms help workshop a list can be specified of words not to index. likely "are" was in that list as well as "the" "a" etc.

I see. I tried a few other words and lhelp did seem to find things ok. I'll start using lhelp instead of xCHM, CHMSee etc.. to help bugtest things.

2009/10/1 Marco van de Voort :

- What is the time to load the LCL index file and merge it with the FCL and ? RTL files?

I haven't managed to generate INF files for RTL, LCL or FCL yet, but I took 7 of the largest files from the IBM Visage C++ for OS/2 cd-rom. Copied them to my hard drive so the CD-ROM speed doesn't affect the timing. I also used EpikTimer to do the timing from start of loading, to end of displaying the complete "merged" TOC.

-------------------
$ ../src/units/helpviewer
cppclsug.inf+cppvbref.inf+cppvbug.inf+evfeclsh.hlp+gpi3.inf+pm2.inf+pm3.inf Elapsed time: 000:00:00:00.177130
-------------------

So that's not bad. :-) 0.177 milliseconds to load 10.3MB of help and display the TOC to the user. In total, that was 13,197 topics (pages of help) and 45,397 dictionary lookup words (each individual file dictionary added to the next - the global dictionary should have only unique words).

Graeme Geldenhuys wrote

See attached image for some issues I just found.

All of these are now fixed in r21950

Is the TOC sorted or are the files appended together?

Regards,

Andrew

Andrew Haines wrote

Is the TOC sorted or are the files appended together?

Sorry I was thinking of an index not a toc

Regards,

Andrew

2009/10/1 Graeme Geldenhuys :

Oops, that should actually say 0.177 seconds. ;-)

2009/10/1 Andrew Haines :

Excellent service!!! :-) Thanks, I'll get an update tomorrow.

2009/10/1 Andrew Haines :

> > Is the TOC sorted or are the files appended together? Sorry I was thinking of an index not a toc

That's the users choice... It can do alphabetically (mixed helpfiles) or grouped by help file.

Graeme Geldenhuys wrote

> Do you have an overview of what works and what not, and practical aspects of > the system? How do I generate the FCL and RTL documentation in INF (actually IPF) format?

You tell me! I'm not the IPF expert. I assumed you had found some way to export one of the existing formats to it.

Actually, on CHM it is external. One can try to get them from the content, but there are separate tables. The stuff about toc and index below seems to indicate that it is so there either.

> - how links over module bounderies work, Explain "module"?

Bundles of help generated separately from eachother.

This is roughly how CHM works too, but the efficient versions of certain parts are not implemented yet. Fulltext search is fine and efficient, except for the generation (LCL takes 4 minutes to generate)

TOC is binary since weeks, and the binary (B+Tree) index is half finishes.

(I assume that means with index, search and TOC combination)

I'm waiting on instructions on how to generate alternative output formats of the FCL and RTL documentation, so I can do actual tests with those help files.

There are none.

CHM also allows to have a "toplevel" CHM that overrides the TOC and Index for the "slave" CHMs.

So is CHM.

> - Can you pack arbitrary HTML into a file? I don't see the use of this. Can you explain why you would want too?

You already encountered that. There only is HTML of ref,user etc. (there might be others, but other converters might be an adventure. And after that with fixing HTML layout, I don't want to ever go there again)

The INF has a very easy to learn mark-up language (48 tags to be exact) - similar to HTML and XML tags so should be easy to learn.

And nobody knows them. And no system outputs them.

I will probably be extending these as the need arises. Also a front-end GUI for writing documentation might be nice. Alternatively, a IPF pre-processor could be written (similar to fpdoc now), taking one format and generating IPF output.

fpdoc has a logical structure. Most html has only a markup related structure.

It was meant for hyperlinked text. I don't see why it can't be html.

Microsoft just took the quick route in slapping them into a single archive and call it a new help format.

Then obviously you have not studied CHM thoroughly, since all features you name are supported by CHM.

I'm thinking about changing the Text IDE to CHM only in time. But not yet for the upcoming release. Not all features are already realised in our own CHM support (even though CHM generally supports it). Andrew is getting close though.

I meant with the existing Makefile in the fpc docs repository. But Michael confirmed in private that the current Makefile setup only supports HTMl output for RTL and FCL.

I'll knock together a few scripts tomorrow the generate IPF outpuf from the RTL and FCL.

It's possible, and I have seen INF files that do that, but I don't know the tag format involved. I'll search the INF Reference manual for clues tomorrow.

parts are not implemented yet. Fulltext search is fine and efficient, except for the generation (LCL takes 4 minutes to generate)

I'll report back tomorrow after I generated the IPF files. But I can't imagine the IPF Compiler taking that lock. I have thrown quite large help docs at it and they normally complete in seconds. I'll give exact figures tomorrow.

> I have loaded 10+ help files (totalling about 9000+ help pages), all > over 2MB in size each. Loading time was instant. (I assume that means with index, search and TOC combination)

Yes, and user notes and user bookmarks - if they existed.

CHM also allows to have a "toplevel" CHM that overrides the TOC and Index for the "slave" CHMs.

Does that mean you have to compile a special "toplevel" CHM? You can't simply concat them from the command line, at runtime? If CHM can't at runtime, then the "toplevel" idea is pretty useless. When you buy products that come with CHM help, you don't have the source of the CHM. Also every time you want to add a new CHM to the "toplevel", you have to edit and recompile the toplevel CHM. Definately not ideal.

The current ref and user docs are not in HTML, they are originally in LaTeX. And just as you have a LaTeX to HTML converted, so you can have a LaTeX to IPF converted.

Also the benefit of INF is that it's similar to LaTeX in the regards that the document writer doesn't need to bother much about the layout. Simply specify a few things and the layout is generated for you. I have seen CHM help which was completely rubbish simply because the document writer had no clue about layout, color choice and CSS stylesheets. This never happens in INF help - just like it never happens in LaTeX generated documents.

> The INF has a very easy to learn mark-up language (48 tags to be > exact) - similar to HTML and XML tags so should be easy to learn. And nobody knows them. And no system outputs them.

They are pretty self explanitory. Not to mention, I will probably implement some preprocessor or GUI editor for it (like FPDOC Editors hiding the XML structure). This is a no-brainer to do.

I'm thinking about changing the Text IDE to CHM only in time. But not yet

I heard many objects about that. Of one, other platforms have all there class and api help in different (non CHM) formats, so they will not be able to integrate that with the IDE.

2009/10/1 Marco van de Voort :

This is roughly how CHM works too, but the efficient versions of certain parts are not implemented yet. Fulltext search is fine and efficient, except for the generation (LCL takes 4 minutes to generate)

I managed to modify the Makefile's of the RTL and FCL documentation.

rtl.inf (1.6Mb) and generated in 9 seconds
fcl.inf (0.4Mb) and generated in 1 second.

I managed to generate the IPF file for LCL. Raw ipf file size was 6.6Mb, but I was unable to compile it into an INF file. The IPF output of fpdoc simply has too many mistakes and eventually the WIPFC compiler gives up.

Soon I will start work on fpdoc by improving the generated IPF output (currently it's very bad) and then try LCL again.

Till you told me what the IPF exactly is, I had no idea what it was, I 'inherited' fpdoc from Sebastian Guenther, and it was not documented.

Soon I will start work on fpdoc by improving the generated IPF output (currently it's very bad) and then try LCL again.

That would be hugely appreciated.

If you want, I have still some items in my todo list which you could look at ;-)

Michael.

2009/10/2 Michael Van Canneyt :

Till you told me what the IPF exactly is, I had no idea what it was, I 'inherited' fpdoc from Sebastian Guenther, and it was not documented.

:-)
I'm actually busy updating the readme file now, highlighting the new IPF make option. Expect a patch in the fpc-devel mailing list in a few minutes. That makefile.fpc is one complicated beast, but I followed the path of CHM and managed to get the IPF output working.

If you want, I have still some items in my todo list which you could look at ;-)

Ha! I'm trying to knock down a few items on my *huge* list first. My clones finally gave up and abandoned me - so now I'm left with all the work. :-/

I think that is an important concept because of e.g. the non-synchronous nature of FPC and Lazarus.

MS' help compiler is probably a lot faster too, this is the own lib.

> CHM also allows to have a "toplevel" CHM that overrides the TOC and Index > for the "slave" CHMs. Does that mean you have to compile a special "toplevel" CHM?

Yes.

You can't simply concat them from the command line, at runtime? If CHM can't at runtime, then the "toplevel" idea is pretty useless.

You can merge the indexes and concat the TOCs at load time. For maximum speed you can even cache the result (keep in mind that CHM collections of Borland and MS go into the tens or even up to 100MB)

But that is not the same as a master CHM where you can e.g. rearrange the contents.

When you buy products that come with CHM help, you don't have the source of the CHM.

Afaik not much info gets lost, so you can simple decompile. At least when CHM lib will support all features (though it is not that far off)

Also every time you want to add a new CHM to the "toplevel", you have to edit and recompile the toplevel CHM. Definately not ideal.

Yes. But that is the burden of custom content. Still, the number of main manuals of FPC/Lazarus doesn't change that often so a nice customized toplevel CHM (one for FPC alone, one also for Lazarus) could be nice.

I know it is latex. I also know it is particularly hard to convert, I was merely being practical.

Since as far as analogies go, LaTeX to HTML still sucks after 10 years, and I considered waiting 10 years for IPF a bit too much.

As 50 competing wiki formats, non of which really work.

Sure, just convert.

2009/10/2 Marco van de Voort :

MS' help compiler is probably a lot faster too, this is the own lib.

I did not look at 'lhelp' code yet. Do you guys have your own CHM reader library, or do you use a publicly available library like libchm.so?

Since as far as analogies go, LaTeX to HTML still sucks after 10 years, and I considered waiting 10 years for IPF a bit too much.

You wouldn't have to wait 10 years. :-) I'm working on it now. I have a very basic conversion tool already (though many features not implemented yet). But more importantly for me now is fixing the fpdoc generated ipf output.

As 50 competing wiki formats, non of which really work.

As far as I know there is just one INF (IPF) tag format.

So are you going to write INF -> CHM converter too? Or any of the other formats FP IDE supports? I just think dropping that support is silly. The hard work has already been done, and the help works in the FP IDE. So simply extend it to fulfill your CHM needs - no need to drop all other formats.

In our previous episode, Graeme Geldenhuys said:
(several of these msgs ended up in my suspect box due to their mime aspects)

As far as I can see, the only issue is HTML. And that is then only your opinion.

own reader and writer.

> As 50 competing wiki formats, non of which really work. As far as I know there is just one INF (IPF) tag format.

Well, it is similar in the sense that the average developer has to learn it, contrary to basic HTML.

No. _I'm_ not interested in INF. The only one I'm considering doing myself is TPH, because of the turbo vision help.

I just think dropping that support is silly.

I think that reforming the help and doing all work 10 fold for helpsystems that to my knowledge are only used on paper (no bugreports in 10 years) is insane. It is not even known if they are still in working order.

Currently, the pluriformity only is worth a lot on paper, and nothing in practice.

The hard work has already been done, and the help works in the FP IDE. So simply extend it to fulfill your CHM needs - no need to drop all other formats.

It is about redoing the core part, IOW all backends have to be revised, and some way to map them on the functionality has to be found.

The current readers can be converted with way less work to a <format>2chm file, than refitting them to a new abstraction.

So just starting with anything random new is better? It will again have its own flaws. And more in the beginning.

If you really care so much, try to notify the synt package author, and work towards a solution instead of playing in fixed fonts. (knowing that there is no real cross-platform font support)

2009/10/4 Marco van de Voort :

As far as I can see, the only issue is HTML. And that is then only your opinion.

HTML as a help format is my issue yes. I don't believe perfectly good help contents must be in a format that a developer can screw up beyond recognition. HTML is so non-standard in the REAL world, though a push for standards adhering browsers is having an effect - but a small one. My other issue is that having too much formating capability in a help system is stupid. What is the goal about help systems - get the help content across. I have seen to many CHM help files that look horrendous because the developers writing the help is or color blind, has no designing skills etc.. Also the help content is inconsistent. Some places plain HTML tags are used, then in other places CSS is use... But wait, now the HTML rendering component needs to support HTML (all versions) and CSS (all versions). Where do you draw the line on what should be supported by the renderer? Not even the latest Web Browsers support all HTML and CSS features.

IPF tags are similar in principal to LaTeX. Simple tags that are easy to remember and that only describes the content - not so much the layout and formatting. The renderer does the bulk of the "pretty" formatting. Hence the reason LaTeX articles have a nice consistent look (though the BuildFAQ is the exception). And that is exactly why most INF documents also have a consistent look, and get the important point across - the help content.

Anyway, I'm not interested in a help format war. You do what you do, and I do what I do.

2009/10/4 Marco van de Voort :

> reader library, or do you use a publicly available library like > libchm.so? own reader and writer.

Good.

> As far as I know there is just one INF (IPF) tag format. Well, it is similar in the sense that the average developer has to learn it, contrary to basic HTML.

And looking at some of the websites out there, it seems developers and web designers still need to learn HTML. There is a lot of crap out there!

As a test, I asked my wife (a professional photographer, not web designer) to look at an IPF file and see if she can figure out the tags without even looking at the IPF Tag documentation. Within five minutes to guessed most of the tags functions correctly. So no, IPF tags are not that hard to read / learn. And if you are an HTML developers (HTML + CSS have a lot more tags than IPF), you will understand IPF tags without a hitch!

Also creating a preprocessor or WYSIWYG app is also very simple to do. Most content management systems and many wiki sites even have WYSIWYG editors for the more complex HTML, so the same would be quite simple for IPF.

No. _I'm_ not interested in INF. The only one I'm considering doing myself is TPH, because of the turbo vision help.

So that is YOUR opinion only, and forcing CHM on everybody that uses the Text IDE. That's not very nice. I don't use the Text IDE much, so to me it would not matter. But when it was mentioned a while back that all help formats are considering being dropped and only CHM used, instantly there were replies showing concern. One such reply referred to the hordes of API documentation for OS/2 which are all in INF format. Another mentioned the Turbo Vision help. So judging from those replies, you are not the only one using the Text IDE - there are others. To them, having the ability to view whatever format help they help seems to be important.

2009/10/4 Marco van de Voort :

I simply stated that the diagrams don't look as good as they could be. And no, I have no interest in debugging the synt package - I don't even know the language etc. such packages are written in.

I simply stated that Unicode has specific characters to do such simple drawings, so no external packages would have been required. ASCII art has been around as long as computers have, so NO, that is not something new. There is a whole Unicode Block of characters which is ideal for such simple diagrams. And as a test I created a mockup of one section using OpenOffice and drew the diagrams with no effect using those unicode drawing characters.

If you are unsure of what I am talking about, see the attached Unicode demo text file. You can view it with Lazarus IDE, gEdit etc... Any text editor that correctly supports Unicode. At the bottom of the file are a few box drawing characters including a FPC syntax diagram recreated using those block drawing characters. I could even have used condensed text characters (no extra font needed) to make the text portions smaller.

Doesn't matter.
- you don't need to know _full_ html to write help, and more importantly, tools to help you (and other tools that export it) are plenty.
- Most people will already know enough html.

> No. _I'm_ not interested in INF. The only one I'm considering doing myself > is TPH, because of the turbo vision help. So that is YOUR opinion only

Correct.

and forcing CHM on everybody that uses the Text IDE.

Nobody else has cared about text IDE help in the last 10 years, so I think that is reasonable.

If you threaten to remove something, it suddenly is always used. I bet they even didn't test if it actually worked, just replyed out of reflex.

But if you ask "hey, I updated something about the IDE, please test if .INF still works" you get no reply. Let alone if you need to change the helpfile abstraction, and the .INF needs updating. It is all dead weight for imaginary use.

I thought that you of all people would understand this, since what good are fast indexes and TOC's if they aren't used? Same for fast concatenation and the like.

This because the generic helpsystem has to stick to the lowest common denomitor and loads all lists and sorts and processes them again (after a few times copying them).

I see the html in chm as a backend. One generates it usually.

Then you would need a format that stores the logical structure, more like LaTeX macro system, not a layouting one based on fixed set of tags.

I have seen to many CHM help files that look horrendous because the developers writing the help is or color blind, has no designing skills etc..

Choosing a different help format doesn't absolve you from stupid people. No matter what you make it will be abused.

This is a good point that I asked myself too. And the answer is simple: what we generate must be more or less accepted.

_IF_ you only build one viewer. If you build multiple, and you don't have singular control of the format where people start extending, you end up in exactly the same situation.

HTML is complicated because it is used so much, not because the original designers wanted it to be complicated.

Anyway, I'm not interested in a help format war. You do what you do, and I do what I do.

IMHO you are right in some of your points. But IMHO they are simply not worth the duplicate effort, and reviving an helpformat that isn't even on lifesupport anymore. If all this happened 5 years ago, before the CHM libs appeared, I'd have joined you.

For what it is worth: The CHM-only decision in the textmode IDE had been taken before you started with .INF

2009/10/5 Marco van de Voort :

- you don't need to know _full_ html to write help, and more importantly, tools to help you (and other tools that export it) are plenty.

You also don't need to know full IPF tags to write help. The least amount of tags you would need to write INF help would be 2 IPF tags: userdoc, h1

If you want paragraphs in your content, then it would need 3 IPF tags in total: userdoc, h1, p :-)

As for wysiwyg editors, there are plenty - but only for OS/2. :-) I plan change that though!

Nobody else has cared about text IDE help in the last 10 years, so I think that is reasonable.

Maybe it just worked for the last 10 years. ;-)

But if you ask "hey, I updated something about the IDE, please test if .INF still works" you get no reply. Let alone if you need to change the helpfile

That applies to any project with any feature. Help systems are definitely not an isolated case.

I thought that you of all people would understand this, since what good are fast indexes and TOC's if they aren't used? Same for fast concatenation and the like.

I don't know other exotic help formats, so I really cannot comment. What I can say though, is that FPC Text IDE is a really nice "library" of code for reading / learning help formats. It would be a shame to loose that library of code. So maybe if we can archive the help format code somewhere and not simply delete it - that would be nice.

For example: The INF format has never been officially released by IBM. It was reverse engineered with a lot of hours and pain. Having a working code example on how to read INF is a real plus point! The same would apply for all those other formats. That is probably the single biggest reason I say, not do just delete the code. Next year some developer might join the Free Pascal community, but he has thousands of documents in Virtual Pascal Help format. If he wanted to write a tool to do the conversion, he could have looked at FP Text IDE's help system.

Maybe cleaning up and moving that code into FCL as a "help format" package etc might be nice.

This because the generic helpsystem has to stick to the lowest common

I fully understand this point. That is my issue with LCL as well. :-)

PS:
My INF help viewer now supports searching too. It can search a single file, concat help files passed in via the command line, or a global library of help files (library path defined via HELPLIBRARY environment variable). The search results are also tagged with a "relevance" rating and sorted accordingly.

We can dump it in our "attic" the fpcprojects repo. I planned that anyway, in case sb wanted to base a <something>2chm converter on them.

Maybe cleaning up and moving that code into FCL as a "help format" package etc might be nice.

I'm not going to touch the move them, IF I will introduce this.

2009/10/1 Marco van de Voort :

This is roughly how CHM works too, but the efficient versions of certain parts are not implemented yet. Fulltext search is fine and efficient, except for the generation (LCL takes 4 minutes to generate)

I finally got the rewrite of the fpdoc IPF writer to a level where I can compile it to binary INF format.

Note that I only have the Windows Open Watcom IPF Compiler (WIPFC) that I have to run under WINE on Linux. I haven't started implementing my own IPF Compiler yet. Anyway, WIPFC choked trying to compile the 9MB lcl.ipf file - saying something about it's to big. I am not sure if that's a WIPFC limitation or the INF internal structure limit. (I'll fix this issue in future)

Either way, all is not lost. I split the 9MB file into two parts and compiled each part. Then at runtime you can concatenate the two parts to become one LCL document inside DocView. Compile time for both parts came to just under 1 minute. So that's not too bad for the whole LCL.

$ time ipfc lcl_part1.ipf
real 0m21.908s
user 0m19.541s
sys 0m0.260s

$ time ipfc lcl_part2.ipf
real 0m29.914s
user 0m28.518s
sys 0m0.296s