Month: December 2010

More Faceted Navigation

I blogged earlier this year about doing faceted navigation with Mallard. The idea sat dormant for a while, but with the new GNOME developer demos, I had a really fun use case.

Here’s the basic idea: Topic pages declare values for facets. These are basically just categorized tags. So my Message Board tutorial has some simple markup that says it’s written in C and it’s teaching you WebKit. You then have a page that collects all the topics and provides selectors to narrow what you’re looking at.

So as I browse the demos, I can say that I’m only interested in C. And perhaps I’m looking at GTK+ and Clutter to see which one is a better fit for a project I’m starting. I can uncheck everything else. Then I’m looking at only demos in C that teach either GTK+ or Clutter. Screencast:

All of the scripting is handled by Yelp. Document authors only need to write some simple declarative markup in a Mallard extension format.

(Aside: When I try to upload an ogv file to WordPress, it tells me the file type doesn’t meet security guidelines. If I rename it to ogg, I can upload it, but WordPress inserts it as audio. I have to write the HTML for the video by hand. Could somebody please make it easier to use Ogg Theora on blogs.gnome.org?)

Open Help Conference

Developer Documentation Hackfest

I attended the GNOME developer documentation hackfest in frigid Berlin last week. This was, I think, a very successful hackfest. We came out of it with a concrete plan, a new documentation effort firmly started, and a host of improvements to tools in the pipelines.

The plan: We will have an updated Platform Overview. We will have a large and continually growing set of demo tutorials. We will have conceptual overviews for all libraries and major subsets of libraries. We will have complete API references. And we will have a beautiful new developer.gnome.org that acts as a portal to all this information.

Everybody kicked in to create an initial set of demo tutorials. The initial demos focus on getting you up to speed with one of our platform libraries. Further demos will build on this knowledge and help you dive deeper into what the GNOME platform can offer. The demos are in git.gnome.org/gnome-devel-docs/demos/C. We will do our best to make all demos available in multiple programming languages.

Get involved by contacting the GNOME documentation team.

The demos are written in Mallard. This is interesting to me, because it’s pushing Mallard in places where it hasn’t been pushed before. This helps me develop useful features. (As a rule, I do not add language features without real-world use cases.)

Jonh asked for line numbering, so I’ve added that in Yelp using a simple style hint. Chris wondered about starting line numbers, continuations, and line number references. These sorts of features require more than an on/off style hint, and I want to think about them more. I think that, with dynamic pages, we can do better than callout lists. Regardless, any improvements there should be in a Mallard extension.

Everybody wanted syntax highlighting. Fortunately, Mallard allows you to provide the MIME type of the content of code blocks, so we already have a way of declaring what should be parsed and highlighted. I looked through half a dozen JS libraries to do syntax highlighting. In the end, I chose jQuery.Syntax. This is now integrated into Yelp, and syntax highlighting works with appropriate values of the mime attribute. Obligatory screenshot:

Line numbering and syntax highlighting in Yelp

A big thanks to Openismus for hosting the hackfest, and to Kat and David for putting up Phil and me. And of course, thanks to the GNOME Foundation for their sponsorship.

Sponsored by the GNOME Foundation

Creative Commons Attribution 3.0 United States
This work by Shaun McCance is licensed under a Creative Commons Attribution 3.0 United States.