Neil's Place

December 24, 2003

11:50 AM Parsing and Serializing XML Documentation

I finished the first piece of documentation that I have been working on, Parsing and Serializing XML, which describes how to parse and write out XML in Mozilla.

There are a number of other documents and have half-finished each of them, including the rest of the RDF stuff.

Comments ( 35 )

December 20, 2003

12:10 AM Want some documentation?

I'm now in documentation writing mode. I've been working on a couple of new Mozilla documents. I thought I'd ask if anyone had anything specific they want documented so that I can focus on that instead of writing something that no one wants.

Comments ( 21 )

December 19, 2003

12:36 AM Best Topicalla Screenshot Ever

I've added a much nicer looking screenshot of Topicalla, now with images and anti-aliased fonts. It shows a UI of a single FOAF file. The UI elements to use are determined from the data in the FOAF file. Some additional data is loaded from musicbrainz.org, although the loading part isn't handled automatically yet. One can select the Detail drop-down to show more detail such as the song titles on the albums, and the descriptions from the weblog.

I recently also added support for templates using XPath and XML datasources as well as the existing ReoPath and RDF support. It is generic enough now that support may be added for other kinds of datasources as well. This allows one to create a UI that is bound to some XML data. For instance, the following:

<hbox rp:repeaton="//td">
  <label rp:assign="text()"/>
</hbox>

Comments ( 43 )

December 15, 2003

5:27 PM About Documentation Seekers

There are two groups of people looking for technical documentation. The first are those looking to learn the technology. These people need to have straightforward information presented in a manner that allows them learn and understand the technology step by step. They need to start with simple examples and build to more complex ones. The documentation needs to be explanatory and not rush into introducing too many things too quickly.

This is the way I designed the XUL tutorial. It starts with simple concepts and explains them in detail so that the reader can understand them. It gradually adds new concepts over the course of the tutorial. It doesn't cover everything, but instead it tries to cover most things with more detail, as well as presenting some basic information for things like XPCOM that really need a separate guide.

The other group of documentation seekers already understand the technology and are using it. They are stuck on some problem they are having and have turned to the documentation for help. The XUL tutorial isn't designed for these people. There are two problems with a tutorial approach for this group.

First, the user doesn't know what could be causing the problem, so they won't know where to look. For instance, recently someone had a problem with a tree not rendering properly. It turned out that the problem was that the tree columns didn't have ids on them, and it was suggested that a note about this should be added to the tutorial. Actually, it's mentioned twice in the tutorial and once in the reference that ids are needed on treecol elements. The issue is that this information isn't presented where the user wanted it, especially since the user didn't know that this was the problem. I could add more notes about tree columns, but, in the context of a tutorial, it would need to be repeated in too many places.

Secondly, people looking at the documentation are looking for a answer to the problem they are having. If the documentation doesn't provide a specific answer to the specific problem the user is having, they might consider the documentation inadequate. In many cases, it's because the question is too specific to be answered by documentation. The documentation can only provide a limited number of direct responses. For instance, a topic about how to change the spacing between the icon and label in a toolbar button may be a suitable question for a theming guide, but for the XUL tutorial, this is a little specific for a direct answer. (For XUL, the actual answer is: you don't)

Anyway, here is a review of the recently published book Rapid Application Development with Mozilla. I haven't read the book yet myself, but it may provide some additional help for XUL and Mozilla developers. Although, as I said above, the problem isn't the lack of documentation, finding help depends on whether the solution to the problem is available.

Comments ( 7 )

December 11, 2003

Chrome Registry Thoughts
Some interesting ideas for better handling of Seamonkey/Firebird apps and extensions.

8:40 PM Buying a CD

I have never bought any audio CDs. Nor have I bought any audio tapes nor any records. Neither have I bought audio on any other medium. Nor, for that matter, any DVDs or videos. I don't own a CD player. And I don't have an MP3 player. I have also, if you would believe, never downloaded any music illegally.

Recently, I listened to some music that I found on the Internet. Yesterday, I decided that I liked what I heard enough that I decided to buy the CD for myself. Of course, I've never done that before.

Recording studios would have you believe that no-one would do that. They would rather tell you over and over that people download lots of illegally copied music instead. That may be true, but that isn't true for me. I'd imagine that the music industry wouldn't even believe me. Well, I have only one thing to say to that.

Comments ( 5 )

December 8, 2003

User Interface Hierarchies Rant
Interesting thoughts on simplifying UI.

December 6, 2003

1:08 AM I've changed all URIs in the XUL tutorial

When I originally wrote most of the XUL tutorial, I really didn't understand RDF that well. Now I do. At the time, I used URIs in my example RDF that were of the form 'urn:something:thing', since that is the form that some of resources in Mozilla used. That was actually a bad idea. Specifically, you're not supposed to make up the parts of a 'urn', except for the last part. The word between the two colons ('something' in 'urn:something:thing') is supposed to be one of a specific set of values as defined in RFC 3406.

Secondly, 'urn:animals:root' for instance, is very generic. Much too generic for a resource URI, since it should be globally unique. Better would be to include the domain of the person or entity that created the resource, which is what is usually done. I myself might use 'http://www.xulplanet.com/rdf/' as the base of all URIs. So, I have searched through the tutorial and have changed all 'urn' references to 'http://www.xulplanet.com/rdf/' including those in the animals example.

I originally wasn't going to change them, as I figured they were just examples. But, of course, after four years of questions and confused people, I realize that very few people using XUL, RDF and templates, even seem to take time to understand RDF very well.

I've noticed that many people are using 'urn' resources such as 'urn:music:item1', which are not good resource URIs. So hopefully, by changing the tutorial, I can discourage that usage.

Comments ( 26 )

December 5, 2003

Bug 53673 is fixed
The 'multiline textbox does not accept initial value' bug

December 4, 2003

12:08 AM First draft of canvas tag patch

I put together a first draft of the XUL canvas tag patch. I also added a few examples. I haven't tested patching and then compiling since I've never been able to get patches to apply properly. So I can't guarantee that it will work right. I can only compile on Linux myself but I've hopefully got the Windows/Mac/OS2 changes right. The patch was created against Mozilla 1.5 since that's what I'm using for something else.

The canvas works fairly well, although some features crash (drawing polygons). If anybody has a chance to try it, let me know. Or, if you have bug fixes, especially on various platforms.

Comments ( 30 )

November 29, 2003

Is Mozilla Development Too Hard?
Not really. There's over 100 extensions that show it can't be that difficult.

12:22 AM Canvas Tag Update

I tend to get carried away when I work on something I think is really useful and interesting. Such is the case with the XUL canvas tag I'm working on. Joe Hewitt's original version creates a simple image buffer which can be drawn into using a few drawing functions. My updated version can do that, but also quite a bit more. It supports lots of drawing functions to draw lines, text and images, as well as pixel drawing.

The canvas also supports custom layouts, which can be used to position and size the children of the canvas in interesting ways. XUL doesn't really need this capability -- it's various layout types are quite suitable. However, there was another task I was working on where I realized it would be very useful to be able to use a simpler set of layout tags, where the complexity was hidden behind a custom layout. With the canvas, this custom layout is done in XBL. Actually, I designed the canvas such that one could create custom elements where the actual painting and layout was hidden in XBL.

In fact, I managed to implement a few XAML elements such as GridLayout using the canvas, and was successfully able to display some of the XAML examples from the MSDN documentation completely unmodified. OK, I only implemented the very basics of the examples, but there's potential for some interesting things. Note that I'm not trying to create a XUL-XAML layer -- that would be almost impossible.

Since I don't have CVS write access to the Mozilla, I'm not sure if there's an easy way of creating a patch. So I may have to zip everything up and then hope that I haven't missed something.

Comments ( 13 )