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.

Terminal.app disappears - Charlessoft to the rescue

I just noticed that the Terminal.app disappeared from my OS x Leopard installation! Oh No! And this just as I was switching backup solution! (Damn). I googled, and found reports that claim that doing "something funny" like accidentally dragging Terminal out of the dock can cause it not only to be removed from the dock, but from Utilities as well ! HORROR !!

Well, I don't want to restore my entire machine - some 100 GB of stuff, and wondered if there was a way to select just Terminal.app from the installation CDs. And it turns out there is a free/shareware called Pacifist from Charlessoft that can pick individual files from .pkg files. Decided to give it a try.

I downloaded and installed the Pacifist package without problems, and started it up. It asks for a 20$ donation/fee to get rid of the nag that otherwise appears each time it is started, which I will donate if it helps me fix my problems ;)

There is an option in Pacifist to open Apple install disks which I used. After inserting install disk 1 and 2 a couple of times, a browser appeared with all of the packages. Used search to locate Terminal, a right click over the package said "Install to Default Location..." which I did, and it restored Terminal.app. The app data was apparently intact, because all my previously used locations where remembered.

Thanks Charlessoft, a check for 20$ is in the mail :)

Blush - I found the missing Terminal - it was a tiny icon on the desktop hidden behind the dock! f this is not what Pacifist did when it installed the new copy then I must have managed to drag it out of the dock and dropped it there, causing it to disappear. Searching for it did not help though...

NTFS on Mac OSx using Mac Fuse and NTFS 3G

When I switched over to using a Mac it was because my PC had crashed. Two of the disks survived though, and now I wanted to mount them on my mac to salvage some documents, and use of of the disks as a backup disk for my mac book pro.

I got an IceBox to mount the drive, and hooked it up using USB. This worked like a charm, and I could access my documents. But hey - the NTFS driver on Leopard does not support write! My idea was to first clean out all the garbage from the disk and then copy it to my Mac (the disk is larger than the internal one). Crap!

Googled and found the cure - use Mac Fuse, an umbrella for plugging in support for various file system types, and NTFS-3g, a driver for Mac Fuse that support both reading and writing.

I found this blog-post how to do this.

First download and install Mac Fuse, then download a NTFS-3G as instructed in this blog-post.

Again everything worked fine - Except - it failed to mount one of the partitions on my disk because apparently I did not shut down the NTFS properly before installing NTFS-3G (merde).

This was a bit tricky to fix. An error message appears with instructions, but they are not accurate. Basically what is needed is a mount with "-o force" to make it clear the "unclean shutdown".

Googled, and found the answer in this forum. To get rid of the problem you need to do two things:

Create the directory where the drive is to be mounted by opening a Terminal window and typing:

mkdir -p /Volumes/C-DRIVE

Where C-DIRVE is the name of the volume, and then forcing it to be mounted by typing (all on one line):

sudo /usr/local/bin/ntfs-3g /dev/disk1s1 /Volumes/C-DRIVE
-olocale=en_US.UTF-8,force,auto_xattr,defer_auth,defer_permissions,volname="C-DRIVE"

Where C-DRIVE is the name of the volume. and "/dev/disk1s1" is the device name as shown in the error message displayed by NTFS-3G.

In my case this produced an error, as apparently /Volumes/C-DRIVE was already inside an ntfs-3g mounted partition (there are two partitions on my drive), but it did at least tell me that it cleared the Log File.

After this, it worked find to just eject the drives, and plug in the USB cable - no need to run the commands again. But I guess they will come in handy when there is an unclean shutdown sometime in the future....

Got my iPhone 3G - Love it, but why the US number format?

Absolutely love the iPhone 3G - the design and user interface is amazing. Syncing it with contacts from p900 worked like a charm, downloaded my entire music library, it synced email, and did everything on its own! The entire process went very smooth.

But what did they do with phone number formatting?!! It has US style formatting even though the international setting is Swedish. It is almost impossible to decipher the numbers - did I enter the correct number or not?

08 123 45 67 becomes 081 345 567 (sigh).

Telia's iPhone 3G pages says nothing about support - but refers to apple's pages. Apple on the other hand, refers to Telia for repair. I guess the packaging for Sweden is done by Apple - so this must be their problem. I reported this as "a bug" on apple's feedback pages.... wonder what will happen next...

Love everything about the device except:

• US phone number formatting of Swedish numbers
• Why does it take so damned long to sync when I just synced 5 minutes ago and nothing has changed in contacts (syncing contacts takes for ever - or at least that is what iTunes says...)?
• Would like to see the photos of my contacts in the Favourites list
• Battery life is a bit short...

Migrating from Sony Ericsson P900 to iPhone 3G

My iPhone 16G Black finally arrived after first having received two 8 GB iPhones (could it be because some idiot thought that two 8GB iPhones = one 16GB?).

Anyway, before jumping into all the fun with the iPhone, I needed to sync my old faithful Sony Ericsson P900. I did not really want to install the Sony Ericsson software for this, and I was very pleased when I found that Mac OS x Leopard ISync supports the device!

First hurdle - when scanning for devices in iSync having marked that I wanted to scan for "phones" produced no result, but scanning for "Any" worked, and the mac and p900 started talking ok.

iSync installs an iSync agent on the phone, and first attempt failed, because instructions where not 100% clear. You are supposed to "open" the message to install it - not just accept it with "ok". After a second install it worked ok.

Starting iSync - it quickly gets to 33% done receiving changes from P900, but then it is stuck there for a long time (several minutes), and I thought something was wrong, googled for possible solutions, and while reading some articles, iSync popped up a report with what it wanted to sync!

Worked just fine, and it even got the images for the contacts. Neat.

Heading out to pick up my iPhone... I hope I am going to be happy with it - I really liked the way the P900 was manageable with just one hand using the the wheel on the side.

Testing Publishing using Ecto offline publishing tool

This is a test of using the Ecto offline publishing tool. I found it quite tedious to write longer articles using the blogger web interface.

So here is a small test:

Dependency Icon

Dependent Icon

And a larger screen short of Buckminster showing embedded OPML and the new Component Outline View.

Works quite well.