Archive for category mozilla
A long time ago, people were bitching about Hungarian notation in code. Its a rediculous convention perpetrated by Microsoft in the early nineties. During some debates on a mozilla newsgroup, circa 1999, I made this comment:
prepBut nI vrbLike adjHungarian! qWhat’s artThe adjBig nProblem?
Well, I had no idea how this goofy statement had been passed around. A quick search on google turns up all sorts of hits where people have used it in their e-mail signature. I even found a guy offering T-shirts with the quote.
Anyhow, I just found the whole thing funny.
So since I’ve been techwriting for a few months, and hating life with FrameMaker, I decided to see what open source alternatives were available out there.
The other day I happened upon DocBook. I had heard mention of it many times before but didn’t really get what it is. Here’s what it seems to be: a well defined XML schema for writing books and such. The idea behind it is to define your document semantically rather than worrying about layout and presentation. You define chapters and books and sections and paragraphs, and DocBook tools create any kind of output you want. You can include graphics and notes and warnings, footnotes, cross references and everything. Its all very exciting.
What I particularly like about it is that you can use so many existing tools. One thing I was thinking for the mozilla world was IDL / DocBook mapping. In its simplist form, you could make an IDL file generate a DocBook API reference skeleton. If you were feeling daring, you could take the JavaDoc comments out of the IDL, and dump them into the skeleton, initializing the whole skeleton.
But if the IDL changes, is there a way to keep things in sync? The problem is that after generating a skeleton, you’d want to be able to modify the XML to your heart’s content. But as long as the XML file retains a well understood structure (which DocBook has!) then you should be able to read in the IDL and the DocBook and alert the developer/writer if the docs don’t match the source. Neat.
But for now I’m going to explore some DocBook tools and see what I can make of them.
So in my DocBook exploration, I’ve discovered the beauty of sgml mode on Xemacs. If only I could get it to do validation. For that, I needed nsgmls, which is a part of James Clark‘s SP package. But it turns out he’s all but abandoned it and the OpenJade group has taken up the cause and made OpenSP, currently at version 1.5.1.
The problem I ran into there is that the freakin’ thing doesn’t compile on cygwin. What I kept running into were all sorts of link errors:
undefined reference to `__static_initialization_and_destruction_0(int, int)'
After hunting around quite a bit, I discovered that this is a common cygwin error, and to fix it you need to comment out all the references to
#pragma interface and
Of course! That’s what I thought it was all along. Well at least there are enough keywords here for google to index this highly, and help someone else.
Now back to mozilla doc hacking.
This morning I got a private e-mail in response to bug 178809. It went something like this…
Disclaimer: I do not speak for mozilla.org. I do not even claim to represent the views of any other mozilla developer other than myself.
Read the rest of this entry »
I’ll write more about some of the techwriting process that I think Mozilla could adapt, but I wanted to post about LiveDocs because it is so simple, but so brilliant.
Read the rest of this entry »