Experiences with Serna Free 4.1

Hi have been producing lots of DocBook text using the free Serna 4.1 editor.

Serna 4.1 is a great application - DocBook editing with WYSIWYM (... What You Mean) feedback which is much easier (and faster) to use than editing the raw XML and then generating the output to see what you are doing. Most of the time Serna does exactly what I want, and most of the time it is quite fast. Quite recently Serna decided to open source the free edition, and they are currently in the process of setting this up. Right now there is for instance no issue tracking system available, and what I am about to write about should really go into such a system (and it will as soon as they have set something up).

Anyway, here are some quite annoying things with Serna 4.1:

Paste pastes an old value (or nothing at all)

I think I have tracked this down to Serna not being able to paste clipboard content in certain formats. Pasting it in an intermediate container, and then changing it to a simpler text format helps. Using Paste as Text in Serna does not help - so something is probably wrong with how the clipboard contents gets parsed. Anyway - sometimes it is really difficult to tell which version got pasted. My solution now is to use a clipboard manager that can strip styling from the current content on the clipboard.

Frequent crashes.

Serna 4.1 crashes quite frequently, I have used it constantly for about three weeks now and there is at least one crash every day. Sometimes the user interface locks up, it is not possible to activate the window, and the menus does not appear. A Force Quit is the only option in these situations.

Confused "reload logic"

When explicitly asking Serna to reload a document it may trigger Serna’s automatic check for reload and it prompts with "the document has changed, do you want to download" - selecting "yes" in this case will cause Serna to crash (almost every time) - you get around the issue by instead selecting "ignore" (which works since you asked for a reload in the first place). My suspicion is that this happens because Serna closes the document to reload, and if the document that then (temporarily) becomes active includes a document that changed, the extra prompt will appear.

Pasting into ProgramListing and LiteralLayout drops end of line

Pasting text where line breaks should be preserved is a mystery. It sometimes work to use Serna’s "Edit as Text" and then pasting it there, but a lot of the time, the line ending are lost. I have a suspicion that this happens when there is something screwy going on with the clipboard format. Using Edit as Text does not work well when the text is XML (or contains special characters). Pasting it directly into the document editor has the advantage of getting transformation into > etc. The only way around this is to edit the examples first using Eclipse.

Irritated by Apache FOP footnote bug

I have managed to become quite productive with a combination of Serna for DocBook editing, and use of Apache FOP for producing PDF output. Except for some small snags that were easily worked around, there is a long standing Apache FOP bug for handling of footnotes in tables and lists - there simply is no easy workaround, so footnotes can't be used in these situations... (crap).

Starting to Use DocBook

I just recently started a documentation project and decided that DocBook was the lesser evil choice of:

• TeX / LaTeX - good formatting, but I want the text to be really reusable in help files, for the web, and for print. Maybe I am wrong, but it seemed backwards to go from typesetting to structured text.
• Wiki - really good for collaborative authoring, but markup gets horribly ugly after a while
• Word - everything in one big document - I guess some open XML format could be used so I can check files into SVN, but I would not want to be the one doing merging of a document that has been through word.
• Commercial Tools like FrameMaker (which is no longer available for Mac) - so I would both have to pay a lot for FrameMaker, and then have the dubious pleasure of running it on Windows.

Anyway, I found a good free tool called Serna that provides visual editing of DocBook in a sort of WYSIWYM (...What You Mean), which works really well.

I found several things to be really annoying, and it took a while to get used to how it works, but I managed to be quite productive (even if there is no spell check as you type).

In addition to using Serna's free distribution, I downloaded the latest XSLT stylesheets for DocBook. I also downloaded the latest Apache FOP (for formatting into PDF). Serna can invoke the FOP scripts, but does not include them in the distribution. Serna's scripts assume version 0.93, so I simply linked the 0.93 directory to the latest 0.95, and then thigns started to work.

It complained about hyphenation, and download of a jar from Offo (an apache project) was also required. I simply dropped the jar into the FOP lib directory to make it work.

Now I have two things to figure out:

• How to customize the style sheets - the output is almost useable as it is, but there are a couple of things I don't like.
• How the !#!#x@ to do cross ref linking between separate documents and still get generated text

The last time I undertook a major documentation project was 1992-1993. Earlier in 1989, I had to write the troff drivers myself as the printer was not supported, and I produced some finished 200 printed pages at the rate of about 2 (finished) pages a day. Working with 'vi' and troff is simply not a very productive environment.

In 1992 we started using Frame Maker, and I was delighted, it was simply the best piece of software I had used. With the release of FrameMaker 4 in 1993, I was very happy, and became very productive as I could do all the authoring, layout and graphics using a single tool. Not only did my productivity increase, the quality of the text increased as it was very fast to make illustrations inline with the text. Since pages were always rendered in full WYSIWYG it was possible to work at blazing speed. I produced some 2000 pages of documentation - about 1/3 was generated from program code (compare to java doc). When the project was all done, I calculated that I produced about 10 pages per day - but it is an unfair comparison as the earlier troff project had almost no graphics.

Today, I have spent about 4 days with DocBook, and I am struggling to learn Serna and the DocBook system, formatting etc. I have not yet started using graphics in my document. I seriously doubt that I will be able to create 10 quality pages per day including graphics.

Amazing how little has happened in 15 years - I am now back to hacking stylesheets to produce printed output... an exercise not very different from writing those troff drivers 20 years ago.

Finder -600 error - Mac OSx

Had some problems today:

• Safari hung when playing a youtube snippet in a Flash Player
• Had to force quit safari
• Safari was stuck in the dock (the blue light was still on), and when trying to click on it nothing happens - the menu shows "Application not responding" even when there is no Safari process running.

What I tried:

• Relaunching the Dock - did not help
• Relauncing Finder - now it is stuck too !
• Typing open -a Finder, and open -a Safari both result in an error that says "LSOpenFromURLSpec() failed error -600."
• From there things deteriorate
• I notice that Time Machine is taking a very long time to perform "finishing backup", and I try "stop backing up" - problem continues.
• I can't eject the backup drive since Finder will not start (sigh)

What solved the issue:

• Unplugging the USB cable to the backup drive !

Hopefully someone googling for poblems similar to what I had will find this OSx Leopard tip regarding "LSOpenFromURLSpec() failed error -600" and find it useful.