Wednesday, February 23, 2005

» We're lacking a silver bullet for documentation

Good thoughts about tools/ways to write documentation blogged by Bruce though I can't agree with Matt Raible on Word being a better tool. First off, I've done a lot with and it's superior to Word in terms of robustness and styling options. It can handle large documents pretty well actually. As an example, at work, our product documentation is an 800 page thick MS Word document and sometimes even Word is choking on it. It just pops up an unhelpful error message (well, what would you expect from a Microsoft product anyway) and dies. There goes the document. It happened several times and on various Word versions, on different PCs. And how did we resurrect that document ? Import in in, export it to MS Word format and open it again in MS Word .. and.. yep, there it works again. That's pretty amazing when you think of it. Nevertheless, I (as Bruce) also think that markup languages are a superior option, as they also give the possibility to use simple text editors, process them in various means (e.g. include JavaDocs), etc... Having a closed, proprietary, binary format (read: Microsoft Office) is really unsustainable, as you're closing all of the options above (and much more) right from the start. might actually be something in-between, but even though its XML format is very clean and might even be hand-written, it's not as typesetting-oriented as Docbook XML or LaTeX (see below for some markup). I also wrote some documents and whitepapers with Docbook XML (mostly using the excellent Emacs nxml mode by James Clark) and although it's very nice for most things, some of them really are a pain in the ... My gripes mostly go with tables and lists. Especially lists ! It's not like they're uncommon, especially in technical documentation, but Docbook XML has chosen a very annoying markup, where you have to go 3 levels deep to write a list element (itemized-list » list-item » para). You may call me here but I use a lot of bullet lists in technical documents and e.g. XHTML's markup for that is much quicker to use (ul » li). Sure, I could just use my very own pseudo-Docbook format and write an XSL stylesheet that transforms it to "correct" Docbook XML but then I wouldn't stick with the standard. Furthermore, Apache FOP is very much stagnant and far from perfect. When generating PDFs, FOP doesn't have LaTeX' rendering quality in terms of paragraph layout. But on the other hand Docbook XML is XML, and LaTeX is not. LaTeX would prove to be very cumbersome and complex to parse, so forget about writing transformation or other purpose processors on that format. With Docbook you can simply use XSL stylesheets. Another option might be to use passivetex (which I haven't done (yet?)) but having an all-Java toolchain (e.g. with Ant tasks hiding away the complexity of XSL+FOP) would be much more interesting... also, I can imagine that installing passivetex on Windows isn't as easy as "apt-get install passivetex". I don't really care much about Windows... actually I don't care about Microsoft and Windows at all, but most people still use that inferiour operating system, so it has to be taken into account. Also tried Vex but... hmm... it's nice but... not that helpful actually. At least not yet. About having a WYSIWYG frontend... it may increase productivity, but that really depends on its quality. It's true that the word completion feature of is really helping a lot, but on the other hand those Word-like frontends (which includes MS Word and Writer) are way to unstructered and permissive. Things like changing font attributes should be banned, to enforce the use of styles. They're all just typing machines when you don't use them properly. not being very light on memory and resources isn't that much of an issue IMHO.. I mean, Eclipse is pretty heavy as well.'s file format is pretty nice, actually much cleaner than one would expect. I wrote a Java application at work that extracts content from (using JDOM) and generates very large Writer files (using XSLT). So, believe me, I really know what the format looks like ;)
<text:h style-name="Heading 1" text-level="1">This is a heading</text:h> <text:p style-name="Text body">This is a <text:span style-name="emphasized">really</text:span> stupid paragraph.</text:p>
Too bad it's not hierarchical like Docbook XML (paragraphs being children of section elements). It's more or less a flat format. The perfect solution ?
  • use an open, standardized, typesetting-oriented, XML-based format for storage (Docbook XML or maybe the Open Office XML Format)
  • play nice with version control (i.e. being a text format, which includes XML)
  • be well-suited for processing, transformation and generation (read: XML)
  • a WYSIWYG frontend that is explicitely restricted in its options to enforce the use of style catalogs, with maybe just bold, italic and underlined being permitted as inline styles (although... even using that is wrong: LaTeX has "emphasize" (em))
  • an all-Java, all-OpenSource toolchain
  • be able to output PDF and XHTML

Thursday, February 03, 2005

» XML Schema Editor Demo

Impressive new XML Schema Editor plugin for Eclipse, which is part of the Eclipse WTP (Web Tools Platform) Project, milestone 2. It requires Eclipse 3.1M4, though.

Wednesday, February 02, 2005

» Lori Firefox Extension

The Lori Firefox extension provides very valuable information when you're developing websites, as it shows time-to-first-byte, time-to-complete, the page size and the number of sub-requests used to build a page with every request. Comparing those values to some metrics (rules of thumb really) you know whether you're doing it right or not. Hmm... I'm not sure whether I want to try that on my own site ;-) (no download link for the XPI yet, probably have to wait a day or two until the author notices he forgot something)

» Saferfox Expanded theme for Firefox

Saferfox screenshot
For those who haven't tried Mankin's Saferfox Expanded theme for Firefox just yet: it's a killer. A little Safari-alike but very much a Firefox theme on its own. To install the theme, go grab the jar file and save it to some place on your harddisk. Then, download the Firefox offline theme installer (it's a HTML page, make sure to right-click and choose "Save Link As") and save it locally as well. Then, just open that HTML page from your disk (using File > Open File) and install the Saferfox jar file. It's definately worth it :-)

Tuesday, February 01, 2005

» Things to say when you're losing a technical argument

Well, haven't we all heard these before ... ? ;) A Java Geek's Diary : Weblog

» My RPM Presentation at L4L

I made a presentation about RPM recently at the L4L LUG. It's two-fold: first part about using RPM, and the second one about building packages with RPM. The 100, quite verbose slides are available for download (OOo Impress and PDF).