Well, painfully hot day. I took around 4 cold showers. I had the impression that I’m better at ignoring heat. I’m not, Am I getting older ?
I’m struggling from some time to make a documentation framework for the project. The basic idea is that everyone writes the documentation as XML (lot’s of tags taken from HTML, so it’s really not that hard) and then processed during the build phase through ant using some XSLT styles. Why is that so important ? Because I really used to write HTML documentation and it sucks. It’s ok when the size of the documentation is small, but it’s a nightmare when the documents start to grow in size. Why XSLT and not some other type of process, like SGML, lyx, TEX, or whatever, just like I did with RUE ?
First of all because I don’t expect Windows users to have or to bother to install these tools. And, even if around me everyone uses UNIX flavors (Linux) the vast majority of development (even in Java) is done under Windows NT or 2000. That is a fact.
Back on track. I want to integrate the documentation generation in the building process, and to keep the build fully automatic. I want platform independence for the building process, I want to easily change (correct) the layout of documents (no formating duplication, because then every change becomes a nightmare). I want to support other mediums than HTML (PDF as an example, especially use fool for the books). I might need the same documents, among being provided as documentation with the packages, to also make the base for the project site, and that might mean that the document layout and navigation must be slightly changed.
All these where achieved using Xerces, which is fully supported by ant. But it wasn’t trivial. First of all because after almost one week of work, without any commits (how can I be that stupid) I managed to erase it all. Anyway that is not the point now. At the beginning I was impressed by the fast progresses I made, everything was quickly and easily done. However, in time, as I needed more functionality, things changes! I thought that basically a documentation, can be broke in presentation (layout, format, colors, fonts, …), content (provided by the original XML document) and navigation (how can you rich from one document to another one). The first idea was that I don’t want to mix content with presentation or navigation. Presentation has to come from the XSLT style sheets together with the navigation (with the help of some external parameters provided from the build environment).
Well, that was easy to say hard to make. It’s trivial, now, to build a table of contents from an document. But how can you link documents, with as less external help as possible. It is possible! Maybe the worse part was to find out the more advanced use of XSLT, documentation exists, but it’s rather difficult, and usually the tutorials or articles found, treated only simple or basic things.
Even if the whole system works now, I’m not happy with the way I done it, and I tried hard to make it as nice, simple and clear as I could. The code (XSLT) resulted is rather hard to follow and understand. That is mainly because I had to chose between duplicating functionality, and simplicity of code. I choose not to duplicate functionality. That means that I used a lot the xsl:import facilities. The result, some pieces of code (the core) is tricky and hackis. The same code does several things depending from the context, and the problem is that context is sometimes hard to follow.
Another aspect is that I had to use non standard functions. Take the example of a huge document (book). Because it is easier to write often it is written in separate chapters. Because we need a table of contents all these separate documents has to be unified during build into a big one (used redirect, but it’s not standard), and then broken again into several documents. Who want to read online an 1M document. Other nonstandard functions had also to be used, especially the tokenize function. I’m sure I would been able to find a way to code around, but why to do it ?
In conclusion, it’s there, it works. But I’m really happy that I don’t have to work to much again on it. It would have been a lot easier if some more functions where specified in the standard. It’s exhausting to always find ways to code around, not to mention that it’s not really productive. To program in XML is a nightmare, it sucks big time, even if I had excellent tools (XEmacs based). It’s soo slow and painful. I’m sure that it’s excellent for small and quick things, but it is not it, yet.
I told you before about our collective readings (a good way to nicely enforce the acceptance of good practices). It almost made miracles. We have a kind of flex program at the company. That means in theory that at 11:00 AM you have to be at work because we have a
small and very short team gathering (status check, readings, …) after which your are free to stay or leave at your discretion. In reality that means that we gather at 11 and we work till 1 AM. Anyway, we have this team made, who always used to be late (the 11 thing). We voted a rule. Who’s late, has to prepare the lessons for the next three days. He never was late again 🙂 On the other hand we have another team made, who really enjoys reading, now he is always late :). BTW: I ordered the next two books, the GOF , and Fowler’s UML
Fate! I was a big ICQ’zealot before it got really so wide spread ed. But I quit. The biggest reason was, that when I completely switched to
Linux, I didn’t found a really good client. The second reason was that everybody used me as some kind of encyclopedia. Why bother to look, read or search documentation when neuro’s on line and he knows. I don’t mind sharing what I know, but please, respect me, at least a bit, and let me do my job.
Anyway, on 9 July (my birthday) I turned it on, because of some obscure reason (I think I had to send someone some file, I was in a hurry and that seemed the simplest way), and then I left and left it on. When I came back I had a message. A girl who was about to visit Satu Mare asked for some informations. Because I felt Satu Mare is kind of my Internet Zone, I felt responsible to help her.
Natalie That is her name (don’t ask me her real name cose I don’t know it). She’s 17 and she left some serious marks on me. Why ? Well, during our chat we exchanged home page addresses. And I was amazed about how full of life, sensibility and smart she is. If you don’t believe me, check out her page at:
http://www.angelfire.com/stars/oracle1/ and her diary (blog) at: http://www.livejournal.com/users/nataliee/.
I was like her (not that good do :), but somehow and someway, that innocence and aliveness got lost. Why ? I want it, it makes me feel alive, I don’t want money, neither prestige. Somehow I got caught by the ugly creature called adult life (misery). Is it really bad to have and share our feelings, to be open and honest ? Yea I know I sound like an looser ! But why ?
Another thing on which the Natalie incident opened my eyes (beside the fact that I saw an completely unknown for me side of the Internet) is how naturally these young people use the Internet. Their journals, are blogs! And while the mature people still argue the idea, they are already embraced it and made it a beautiful and natural way to share, communicate and create communities. Go, http://www.livejournal.com/ and see some wander full blogs, and I’m telling you after I read a few of them, i found the mature ones dry and meaningless.
Also as a repercussion, I started to read the lyrics of songs. Poetry, the modern poetry.
you and me
 we're in this together now
 none of them can stop us now
 we will make it through somehow
 you and me
 if the world should break in two
 until the very end of me
 until the very end of you
awake to the sound as they peel apart the skin
 they pick and they pull
 trying to get their fingers in
 well they've got to kill what we found
 well they've got to hate what they fear
 well they've got to make it go away
well they've got to make it disappear
the farther i fall, i'm beside you
as lost as i get, i will find you
the deeper the wound, i'm inside you
...
all that we were is gone we have to hold on
when all our hope is gone we have to hold on
all that we were is gone but we can hold on
 ...
NIN, “We’re in this together”
Thank you Natalie !