Helpviewer and Help System in GNUstep

I -- finally !! -- started reworking on helpviewer lately -- as the last official version (0.3) doesn't work properly with gnustep (due to changes in GSHTMLParser...). The first goal was to have something working again -- that was fairly easy, by replacing GSHTMLParser by GSXMLParser. Though, it meant that you couldn't use single tags like "br", as you (obviously) need to close them in xml.

I then decided to more or less deprecate the hold "help" xmlish document format and its custom tags, and implement an xhtml parser instead, and while I was here, by using NSXMLParser rather than GSXMLParser.

Exit "intelligent" tags that deal with figures or references, but on the other hand we can reuse html documents -- eg it's probably easier to write documents now than it was with the previous custom xml tags, as you should be able to use standard html editor... or if you want to write your documents by hand, well, html is a slightly more known format anyway !

As we remove "dynamic" behavior, we need to have document completely generated beforehand; eg it will be the document creator application's duty (or the writer) to generate proper references, etc. And yes I somehow plan to write such an editor, but in the meantime you'll be able to easily write/convert your existing html documentation anyway ;-)

Though I'm not entirely fixed -- some of those dynamic behaviour could be coded as specific div tags after all...

Anyway, the importance for the help is to be displayed in the same, standard way. So basically at the moment it's a bit like if helpviewer would provide its own css style to display documentation, that you can't change.

Another feature that need to be added is a proper search function using indexation (LuceneKit, here we are !). Didn't do anything about that yet, but I will probably write a command line tool that take a help document, generate an index and put the index in the document..

So.. apart from ditching the old xml format to use more common html tags name, what changed ? Well, the structure of the help document changed quite a bit too :-)

Before, a help document was basically a bundle (==a folder) containing .xlp files (xml files using the previous syntax) and other resources (images). One file was mandatory, "main.xlp", that was loaded by default; other files were loaded following links written in main.xlp.

Now, it's different :-)

A help document is still a bundle, obviously -- what better way to distribute a help file : you can have various resources in various languages, all in the same place !

But the organisation inside is different. The document can still be segmented in multiple files (now html files), but the structure of the document simply reflect the actual content of the bundle -- eg helpviewer will simply show you the files and directories contained in the bundle. Directories act as a way of having different parts in a document, as they contain other html files. You can (actually it's mandatory for the moment, although I will support /not/ having an index.plist) use an index.plist to choose which file/directory is displayed in helpviewer, and with which name, and in which order. The index.plist file contains a simple ascii plist containing a list of key values, where keys are the filenames and values are the displayed names.

Of course, you can still use links in the html documents too, but the actual structure of the document doesn't depend on that.

One nice thing with it is that you are not at all tied to html documents -- in fact, the first thing I implemented was an "txt" document and later on a "rtf" document (a shame rtfd doesn't work). And anyway I find this new structure much cleaner and simpler...

So... what's the plan now ? Well, I ported nearly all the previously existing functionalities to the new parser (links, etc), so once it's done and usable, I will commit a 0.4 version on the étoilé repository; then it will be nice to add proper support for search/indexing using LuceneKit. After that... well, what would be good to do, is to modify gnustep to have NSHelpManager directly use something like helpviewer -- eg, instead of using helpviewer as a separate application, you'll find the same functionalities of helpviewer, directly in a NSHelpPanel, so that help acts as "private" to an application, like it did on openstep. Probably the good approach would be to modify gnustep to easily support bundles to implement this kind of additional behavior (actually, very similar to GSAppKitUserBundles, but.. I don't know, something perhaps slightly more formalized..), and code such a bundle :-)

After all that, I'd like to rework on my "semantic" editor, and extend it to a nice document (and help) writer. We'll see...