Tools for documentation writing

Technical documentation writing

I’m about to write the technical documentation for the current project. I’ve already tried serveral formats for storing documents, but every one has disadvantages. What I need from the tool is:

• Have a WYSIWYG editor, because of the pointy-haired who needs to just open the file and see it.
• Allow collaboration over a Subversion code repository.
• Generate a PDF file.
• Generate a table of contents (TOC)
• If there’s no WYSIWYG, then it should allow easy code editing.

I considered many formats, but each of them has serious drawbacks. Here’s the lattice that shows it:

(Lattice created with conexp)

Tools

The perfect fit would be DocBook with a WYSIWYG editor. It has form of a repository-friendly XML code and it allows creation of nice looking PDF documents.

There are some tools for DocBook authoring, some of them tagged as WYSIWYG.

XXE

I checked XXE which was close to what I wanted, but I have doubts if it’s easy enough for the pointy-haired. Editing DocBook in XXE feels much like filling a form, and this is nice. What isn’t that nice is that it’s not that easy to add more fields to this form. There should a very straigh-forward way to add a new chapter or section, and maybe change order of sections. Unfortunately, XXE makes it confusing.

AbiWord

I don’t know why isn’t AbiWord listed there, because is able to read and write DocBook documents. It doesn’t support all of the DocBook features, but that’s OK. It allows to create headings, paragraphs and fragments of code. It’s able to write a valid DocBook document and then read it back.

So far, AbiWord seems to be the best fit. It is a WYSIWYG editor and it supports DocBook.

There’s only one thing I dislike about AbiWord’s DocBook support. A single paragraph of the document becomes a single line of the XML code and therefore is a single atom for the cource code repository. Should the paragraph be splitted into more lines, the code repository would allow nicer changes tracking. XXE does that, AbiWord doesn’t.

Weird sed behavior when matching capital letters

Gentoo

maciej@matilda ~ $ cat /etc/gentoo-release

Gentoo Base System version 1.6.14

maciej@matilda ~ $ sed –version

GNU sed version 4.1.4

maciej@matilda ~ $ echo ' <Field name="hospital_id">VHI</Field>' | sed -e 's/^\(.*\)\([A-Z]\{3\}\)/\2/'

VHI</Field>

Debian

krok:~# cat /etc/debian_version

3.1

krok:~# sed –version

GNU sed version 4.1.2

krok:~# echo ' <Field name="hospital_id">VHI</Field>' | sed -e 's/^\(.*\)\([A-Z]\{3\}\)/\2/'

eld>

Difference

So Gentoo sed 4.1.4 returns “VHI</Field>” while Debian sed 4.1.2 returns “eld>”. How is that?

Is it the sed itself or some underlying regular expression library?

Solution

Don't use [A-Z]. Use [[:upper:]].

Problem was caused by locale. The script was originally written under POSIX locale and failed on pl_PL.

debian:~# export LC_ALL=POSIX
debian:~# echo abcdz | sed 's/[A-Z]/x/g'
abcdz
debian:~# export LC_ALL=pl_PL
debian:~# echo abcdz | sed 's/[A-Z]/x/g'
xxxxz

Looks like the collation order under pl_PL is much different than under C or POSIX locale.

Conclusion: don't use [A-Z] for matching the capital letters.

My thesis’ presentation

I'm going to present idea of my thesis this Saturday, during class. Each presentation should be about 10 minutes long. I rehearsed and I find it difficult to make it short. I started with 16 minutes and after throwing slides out managed to get down to 11 minutes. There are two problems.

1. It's still too long. I really want to explain key ideas in my thesis. Maybe I shouldn't?
2. The first half is about the EACTS Database itself and existing reports, like Aristotle Score. It's still to long. It should be more about my stuff.
3. I need to draw more pictures to illustrate my idea. It'll save me words.

I'll try to rehearse more and shorten the introduction. There are still some things that I can throw out.

Kdissert

I’ll have to make a presentation of my thesis next weekend. With help of kdissert I managed to finally start with my presentation. I don’t have a clue about what the mind mapping is, but I do know what a table of content is.

Sooner or later, you need to decide what your table of contents will look like. If you do it in LaTeX or a word processor¹, you just type in your chapters and sections into the document and you get the TOC as a result. When you see it, you notice that it needs to be changed, so you go back to your document, make changes and generate the TOC again.

Why not concentrate on the TOC alone? I know that you can just play around with a nested bulleted list, but you can’t apply changes to the bulleted list as easily and quickly as in Kdissert. And you can’t transform your list into an OpenOffice document, or presentation, or LaTeX. With Kdissert, you can.

¹ What is a word processor? You ever seen a food processor, what it does to food?

UPDATE: There’s another  mind-mapping tool, Freemind, which I like more than kdissert.

How to make somebody agree

A: “2 + 2 = 5, therefore you should brush your teeth.”

B: “Two plus two doesn't equal five.”

A: “Why you don't want to brush your teeth?”

B: “I do, but not because two plus two equals five, since it doesn't!”

A: “You have to brush your teeth because two plus two equals five!”

B: “I won't!”

A: “You won't brush your teeth?”

B: “I will, but not because 2 + 2 = 5.”

(B brushes her teeth)

A: Hah! You brushed your teeth! So you agree that 2 + 2 = 5!

Inspired by discussions with my boss.

KArm loses data

At first, I wanted the title to be “KArm is pathetic”, but I decided the title to be more informative.

I have switched to KDE because of this single application which was supposed to perform a simple task for me. I've switched the whole graphical environment and it turned out that the key application not usable because it loses data.

KArm was supposed to count the time that I spend on each desktop, so I could see the monthly totals. Bur every time I reboot the time values are different. And my billing was supposed to base on that! Phew.

Application I need: A time tracker

The closest application to what I need is KArm, but it has some disadvantages.

• It's KDE-based, while I prefer GNOME
• It has lost data on system crashes
• It misses some functionality I'd like to have

There is a time tracker for GNOME, named GnoTime, but it's lacking one of the most important features: automatic timing based on virtual desktops. Without it, the application is pretty useless, as I'm not going to start and stop the timers manually because I switch between tasks a lot and it would consume too much time.

So, here's a description of my ideal time tracking application:

• A list of projects (with names).
• Each project can be bound to (any) virtual desktops. One project can be bound to many desktops and one desktop can be bound to many projects.
• When a desktop is active (user is on the desktop), the time is counting for all the projects assigned to this desktop.
• Time grain is small (5 seconds?).
• When the system or application crashes, only the small amount of time should be lost. It means that changes should be written to the disk very often. Losing the time counts from the whole day is unacceptable.
• Idleness detection. If user was idle for specified period of time, a dialog window is displayed. User can choose, whether to count or not count the idle period.
• Time counts for projects are automatically divided by days, so user can view counts for each day. The day starts at 5 am.
• The user can view aggregated time counts, for example monthly.

I don't really need a graphical user interface for this. The program can read text configuration files, run as a daemon and store the timings somewhere, so I can read them. The only necessary interaction with the graphical environment are a detection of the current desktop and the idleness dialog box.

Wengophone frustration

Wengophone says that the audio device is already in use. That's right, because artsd is using it, but my soundcard has hardware mixing, so it's capable of accepting output from many programs at the same time.

I pulled the sources and built Wengophone myself. The same results.

When I try to stop artsd with artsshell terminate, the whole system crashes. WTF?

Sorry, no Wengophone for me. Going back to Skype.

Ubuntu startup

When starting, Ubuntu Breezy Badger starts some services and displays the login manager, announcing it with a sound. You can start logging in. If you switch quickly to the virtual console (CTRL+ALT+F1) you'll notice that there are some more services still being started.

Ubuntu still isn't too quick to boot up, but they made the user wait a little less.

Gentoo on the server

I decided to install Gentoo on the main server. The installation is easy, as I can do it in chroot environment without interfering with the running system. It’s exactly how I migrated my desktop computer from Slackware to Gentoo.

There are some flaws. If the doc flag is specified, nasm needs ps2pdf utility, which comes with ghostscript. Unfortunately, ghostscript needs nasm to be emerged first. So I specified -doc for nasm in /etc/portage/package.use and emerge went on. But if I didn’t know how to do that I’d be in trouble.