Flow, State and Persistence

I gave a talk today discussing state and persistence in your work environment, for the No Grownups Seminar Series.. Here is a flash version of the talk, and here is the pdf one. Have a look !

RTFD

Well, I was idly thinking that I could move the HTML parsing code of HelpViewer in a GNUstep TextConverter bundle (so that *any* application using text would be automagically able to load html... or at leas the particular HelpViewer brand ;-), so I looked into the RTF TextConverter to see how that worked. It's fairly simple in fact :-)

But reading the code, I also realized that adding RTFD support (RTFD are basically RTF documents + Images) would be trivial. I am actually fairly surprised nobody did that before, particularly as I remember numerous complaint about its non-existence :-/

So, I modified the RTF parser to deal with the \NeXTGraphic tag, and it seem to work well -- at least reading RTFD documents that come from Mac OS X. Though, the actual grammar I used for dealing with it is pretty crude, so I wouldn't be surprised if some documents do not work (likely old NeXT documents... OS X documents produced by TextEdit seem fairly consistent with what I did). Anyway now the basic support is done, tweaking the grammar won't be difficult if it's needed.

Here is a screenshot showing two documents opened in Ink.app (and obviously no modifications were needed in Ink.app...):

It's committed on the gnustep repository, so you can try it by updating and reinstalling the RTF TextConverter bundle.

I'm thinking I'll perhaps commit my actual HelpViewer version (as it can use rtf files) without waiting for the html parser to be finished... plus "commit early commit often" is a good idea ;-) (which I don't follow enough...)

We could write a simple Text editor dealing with links, etc. as well. Oh well we'll see.. :-)

It doesn't hurt...

Things move quickly with etoile, so here's another screenshot... note that the shadows are ok now with xcompmgr and Azalea+EtoileMenu, that the menu items aren't displaced anymore, and that the info panel was updated (yeah, yeah, it doesn't improve the experience, but it's nice to have ^_^). Saso even added a small animation when you click on the etoile logo in the middle... pfff! ;-)

Anyway, time to work on helpviewer.

Etoile screenshot

Just for fun.. Here is a current screenshot of etoile, showing the EtoileMenuServer, Azalea (the windowmanager), Nesedah (the theme) and HelpViewer... Things start to work together ;-) [note that the shadow should not/will not appear under the helpviewer menu item...]

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