Notes from the Mousepad

Here’s a somewhat quick run-down of some projects with-which I’ll be participating, and some other projects that, while I might not be a direct participant, I am curious to watch develop.

Xfce Updates

I see the LXDE project get a good amount of attention lately, in large part (I think) because it uses somewhat less memory than Xfce.  Xfce is still going on strong, though, and plans are in the words for the eventual release of Xfce 4.8.

Jérôme Guelfucci recently provided a brief update on what’s going on with Xfce, and one of the big things is a push for updated documentation.  I’ll be contributing to that, and will likely be borrowing some of the user-help topic “stubs” that have been put-together by the GNOME Documentation team.  I’ll be sure to share any relevant topic stubs with them, too.

Jannis Pohlman has also started the process of forming an Xfce foundation.  Jannis notes that this would make Xfce a legal entity with a board of directors, and that it would help to raise funds through sponsors and other contributors for hackfests and other events.

My Documentation Projects

Lately I have been continuing work on gedit documentation and have also done some initial work on updating the Ubuntu Packaging Guide.  I should have the gedit docs well-drafted within another week or so, but I welcome suggestions and contributions with regards to the Packaging Guide.

Thus far, I’ve drafted the Packaging Guide in Mallard, and although Mallard is XML-based, it is much simpler than DocBook.  It is not difficult to learn, and you can draft-up a nice-looking, topic-focused documentation set with it rather quickly. I also know that there was a UDS session about the Packaging Guide today, so I welcome any feedback that resulted from that session, too.

Other Documentation Projects of Note

In non-Linux-help news, there are a couple of interesting DITA-related projects that I’ve been wanting to mention. If you haven’t heard of it before, DITA* stands for the Darwin Information Typing Architecture, an XML-based syntax originally developed (and later open-sourced) by IBM. The toolkit that processes the syntax, the DITA Open Toolkit, is Java-based, though, which I think has somewhat slowed its adoption in the Linux community. (Currently, only OpenSUSE packages DITA and the DITA Open Toolkit, but their implementation is a bit broken, perhaps due to an outdated version of Saxon in the OpenSUSE repositories.)

When people ask me what the big deal is about DITA**, I like to point them to this white paper (PDF).  It seems to provide a pretty clear picture of what DITA can help you do, even if it does make it look easier to implement than it is in real life.

There are a couple of DITA tools on the horizon that look to make it a bit easier to work with, though.  A group of Drupal developers are working with DITA developers to build a Drupal-based DITA authoring platform.  From what I can tell, it will be released under an open-source license.  They are just in the planning stages now, but I’ve relayed the Ubuntu Documentation / Ubuntu Manual / Ubuntu Learning Team’s requirements from what we talked about this past summer when considering the Ubuntu Learning Center.

Also, Don Day, the chair of the OASIS DITA Technical Committee, has put together a Free-as-in-Freedom web-based DITA platform.  It’s in its early stages, too, but you can get a look at it here. You can log in as a guest, and then select topic tools from the bottom of the page to have a go at editing the document.

A Docs Conference?  In Ohio?

Finally, there is word on the street about the possibility of a docs conference in Cincinnati during the first weekend in June.  I’ve expressed interest in helping with planning and organizing that conference.  For now I will keep my calendar open, and will post more news here as conference plans solidify.

*Whenever you do a Google search for DITA, it’s typically a good idea to exclude the phrase “Von Teese” from your search query.  That is, unless you want your documentation searches to also include results for a fabulous burlesque dancer / entertainer. If you do want dancer / entertainer results in your documentation search queries, then make sure to include the phrase “Von Teese” in your queries.

** Generally, people do not ask me about DITA.

Edit: I recommend checking out Paul Frields’ post about Emacs and nXML mode, and also looking at the Fedora wiki page that he created.  I think his approach is a bit simpler and cleaner than what I’ve provided below.  Feel free to peruse what I’ve written, though, as some of my links to “getting started” references should still be helpful.

---

I’ve been doing some documentation work with Mallard and DocBook 5 recently, and have been looking for software that supports them well.  The trick is that both Mallard and DocBook 5 are based on RelaxNG schemas, and while there are many XML tools out there, there are few that are open source, and fewer still that support RelaxNG.

After perusing my options, I decided to try Emacs with nXML-mode.  Emacs’ nXML-mode provides real-time validation for RelaxNG-based documents, something which no other open source authoring tool provides. But while nXML-mode can validate XML documents on-the-fly, the default installation is not set up to validate against the recently-developed Mallard and DocBook 5 schemas.

Thus, to take full advantage of the latest in duck-based documentation technologies, I needed to modify my .emacs file and the nxml-mode files themselves.  What follows is an overview of exactly what I did in the hopes that others can make use of the same changes, too.

An nXML-mode foundation

Before we get started, though, you should know that much of what follows is derived from information on this website.  I encourage you to visit the site, as it provides an introduction to how nXML-mode is configured, and enough of an introduction to using nXML-mode to make you at least modestly productive right away.

Part One: Setting up your .emacs file

The first step in setting up nXML-mode for Mallard and DocBook 5 is to make a few changes to your .emacs file.  If you are new to Emacs, your .emacs file sits in your home directory, and serves as a personalized Emacs configuration file.  You may need to create the .emacs file if it doesn’t already exist.

;; /usr/share/emacs/site-lisp/tcc-nxml-emacs:  Add these lines
;;      to your .emacs to use nxml-mode.  For documentation of
;;      this mode, see http://www.nmt.edu/tcc/help/pubs/nxml/
;;--
;; Add the nxml files to emacs's search path for loading:
;;--
(setq load-path
      (append load-path
              '("/usr/share/emacs/site-lisp/nxml/")))
;;--
;; Make sure nxml-mode can autoload
;;--
(load "/usr/share/emacs/site-lisp/nxml/rng-auto.el")

;;--
;; Load nxml-mode for files ending in .xml, .xsl, .rng, .xhtml .page
;;--
(setq auto-mode-alist
      (cons '("\.\(xml\|xsl\|rng\|xhtml\|page\)\'" . nxml-mode)
            auto-mode-alist))

The above .emacs configuration tells Emacs where to look for detailed XML processing instructions, and also causes Emacs to automatically use nXML-mode for XML-related files.  (Did I tell you that Emacs might have a bit of a learning curve?  Yeah, that’s true.)

Part Two: Modifying the nXML-mode configuration files

The second step is to modify the nXML-mode configuration files themselves. This will add the appropriate nXML-mode secret sauce to handle Mallard and DocBook 5 documents.

Fortunately for you, I grabbed the latest nXML-mode source files from the nXML-mode website, and made the appropriate modifications myself.  You can download my customized nXML-mode files from this archive.

Here’s what I changed from the default setup:

• I added the docbookxi.rnc and mallard-1.0.rnc schemas to the schemas directory
• I modified the schemas.xml file, thus including the docbookxi.rnc and mallard-1.0.rnc schemas as part of the XML-validation process.

Note that I have used the DocBook 5 “docbookxi.rnc” schema which allows for xinclude functionality.  If you want to use the schema that does not allow for use of xinclude features, you’ll need to adjust the files accordingly.  The current DocBook 5 schemas are available here.

Part Three: Copy your nXML-mode files to the proper location
The final step is to copy the nXML-mode files to the proper location on your file system.  As indicated in our .emacs file, that location is:  /usr/share/emacs/site-lisp/nxml/.  Thus, you should copy all of the files in the downloaded “nxml” folder into that directory.  You will need administrative privileges (using root or sudo) to do this.

Wrapping up

That’s it, though.  You should now have a functioning nXML-mode environment that will allow you to fire-up Emacs and start writing Relax-NG-based documents, getting all of the real-time-validation features that Emacs provides. If you can think of any ways in which I could improve my approach, please let me know.  Otherwise, I encourage you to head-on over to the nXML-mode website, and view some of the nXML-mode information and resources that are available as you get started.

We’d like to get your input on where to focus documentation efforts on the Ubuntu Packaging Guide. There are all kinds of topics that need to be written, updated, or improved — so where should we start? What do you need most?

Give your input via the this Google Docs Survey. I’ve provided some direction by asking you to focus on tasks, concepts, and terminology that can be best documented in the Packaging Guide, but you’ll no doubt have other ideas.

If you’re interested in writing on a particular topic, please be sure to note that in the survey comments (and include your name and email address!).  I’ll be sure to ping you once we get the new guide outlined and stubbed out.

Also, if you have any suggestions for the packaging guide that aren’t encompassed in the survey, please feel free to leave a comment here.

Thanks!

P.S.  Oh, and wouldn’t you know that the Mozilla documentation team is updating their Mozilla Developer Network documentation, too? Janet Swisher from their docs team published a note seeking developer input on how their docs can be improved.  She publishes her blog content under a CC by SA 3.0 license, so I’ve “borrowed” some of her phrasing.  Hi, Janet!

This site lists who they’ve identified as the top 50 technical writers on the web, which I stumbled upon via a link from Scott Nesbitt’s blog.  While this list will certainly provide me with additional documentation resources, I notice a dearth of open-source documentation names in that list.  No Shaun McCance, no Emma Jane Hogbin, no Matthew East, and certainly no one with a name as cool as Milo Casagrande.

Paul Cutler, a member of the GNOME documentation team, has said that he wants to make documentation cool again.  He used some different phrasing (ok, he actually said, he wants to make it “sexy,” again, but I don’t really feel like going there), but what I take his comment to mean is that he wants to make documentation something that people see as technically innovative and relevant to users, even if most users instinctively turn to Google as their first line of support.  After all, Google’s search results don’t just grow on trees – the content that comes up in all of those search results has to come from somewhere.  Why shouldn’t the answers to user questions come from carefully prepared and researched documentation?

I don’t say this to denigrate blog posts, forums, or IRC support networks – that’s where users get most of their support these days.  Comprehensive documentation has its place, though.

With that in mind, I’m making initial, but steady progress on the Xfce 4.8 documentation, and really want to improve the Xubuntu documentation.  (I’m actually a bit ashamed of its current state given the beauty that is the rest of Xubuntu 9.10.)  I will be at UDS (though, unfortunately, only for the last two days), and look forward to meeting with fellow doc-team members, and anyone else who would like to discuss documentation and translations.

Greetings!  I hope everyone has been enjoying their summers, and that things are progressing along smoothly with the 9.10 release cycle.  I want to share a brief note regarding Xfce documentation licensing with the hopes that others could provide some additional points for us to consider.

Before I do that, though, let me pause to reflect on the fact that I haven’t updated this blog since the month of May.  In the words of a wise master, “Sorry, I’ve been trying to think of stuff to put here.”

Back to considering documentation, though.  Per my post to the Xfce developer mailing list, I have proposed that any newly-written Xfce end-user documentation be licensed under the Creative Commons CC-by-SA 3.0 Unported license.  This would be a change from the documentation’s current license of GPL v2.

My post to the mailing list covers several of the advantages of using a CC-by-SA 3.0 license for end-user documentation, but I’m hoping to get some additional input on items that we may want to consider as part of making such a switch.  For example:

• Although the CC-by-SA 3.0 license would apply to new content, what qualifies as “new content,” when some of our content may include instructing users where to click to perform certain actions?  Certainly, a good portion of this language may remain the same in such cases.
• Is it possible to license code snippets under the GPL, while the rest of the documentation is licensed as CC-by-SA 3.0?  If the answer to that question is, “Yes,” would a GPL-specific notice need to be provided alongside the code sample, or could the GPL notice be provided in a less visually-obtrusive spot within the documentation?  (As a note, I don’t forsee a great deal of code samples within the end-user system documentation, but I want to make sure we have our bases covered in this regard.)
• What else might the group need to consider as part of making such a switch?

Thus far, the reception to using CC-by-SA 3.0 has been good amongst the developers, and several of them have already indicated a willingness to relicense their GPL v2 documents as CC-by-SA 3.0.  That, combined with the fact that I think contacting any existing Xfce documentation contributors would be much easier than in larger projects, leads me to think that re-licensing existing content isn’t out of the picture, either.

I know that a number of other projects have recently made a switch to CC-by-SA 3.0, though, so I am hopeful that I’ll be able to get some good input from others, and we can get this settled in short order.  Thanks very much!

Good news on the wiki front.  : -)  As of this morning, apt-urls are enabled on the Ubuntu Wiki.  What does this mean?  In simple terms, this feature provides a simple, wiki-based interface for apt, the base of our software management system.  It means that we can now insert clickable links on the wiki that can prompt users to install software from the Ubuntu repositories.  How cool is that?

How can you use this new feature?  Here is an example of how you could use it in the wiki.  In this example, we’ll look at installing the xubuntu-artwork package:

If you are an Ubuntu user who wants to use the stylish Xubuntu artwork on your system, just [[apt:xubuntu-artwork|install the "xubuntu-artwork" package]].

Of course, the end user just sees, “If you are an Ubuntu user who wants to use the stylish Xubuntu artwork on your system, just install the "xubuntu-artwork" package." (If you are a Firefox user on Ubuntu, you will also note that the link I’ve provided here works, too.  This is because Firefox also allows apt-urls to work in regular web pages.)

After clicking on the link, the user would then be prompted to choose whether or not he or she wants to install the package.  If they select yes, they are prompted to enter their password, and the system installs their software. Easy enough!

Because it is using apt, it is relying on the user’s configured set of Ubuntu repositories.  (Note: if a user is using a PPA or another software repository, those software sources would also be available.)  The installed packages can still be uninstalled via any of the regular software maintenance tools (e.g., synaptic, apt-get, add-remove programs, etc.)  In this manner, it doesn’t introduce new tools, it just provides a great new way of interfacing with them.

So . . . wiki editors . . . I now call on you to go forth and make good use of this new feature.  : -)  Let’s start using apt-urls in our wiki documentation.

Thanks to the Canonical system administrators for putting this in place, and to Matthew East for following up on the support ticket.

I’m attending the WritersUA conference in Seattle this week, and yesterday was day one of the conference.  The conference started with Scott McCloud talking about how he created his Google Chrome comic, and I attended other talks on ISO documentation standards, as well as architecting your content so it can be reused.

McCloud’s talk was interesting in a number of ways, but one aspect of it that struck me was the volume of work went into what he did.  The initial basis of the work was 10 dvd’s worth of recorded interviews with developers.  They did not allow the content of the comic book form to be dictated by some kind of marketing storyline.  The comic still stood up as a form of documentation.

Additionally:
* The use of bubbles as text-placeholders in the comic created some difficulties for translators, but they were able to make things work. He didn’t provide a great amount of detail about this.
* He loved the mash-ups that resulted from the work being licensed under a Creative Commons license, even if the mash-ups didn’t follow the letter of the license.  Google did not attempt to sue people who made these mashups for noncompliance with the license.
* He demonstrated how comic book framing can keep the use focused on one item at a time, and make it easier to explain difficult concepts in an elegant, easy-to-understand way.
* I think he referenced XKCD at least 3 times.  He likes it.
* I can’t draw comics.  :/  Maybe I can use some of this stuff with screenshots, though.

I also attended a session on ISO standards for documentation and D.I.T.A., an open-source documentation toolkit similar to docbook.  The standard is maintained by OASIS, a not-for-profit standards organization – it looks great!  We got to see snippets of it, but it costs about $200 to get a single copy of the standard. :/  Even members of the OASIS committee who volunteer to maintain the standard have to pay to get a copy of it.  I am glad that at I don’t have to pay to contribute to Ubuntu.

The best session of the day for me was the session on architecting documentation for reuse.  The Ubuntu documentation team already has some of our content architected for reuse; for example, we use docbook “entities” for repetitive items such as system and software version numbers, Ubuntu website urls and certain procedures, but this showed how it’s possible to do more.  I’m a little green as a member of the Ubuntu documentation team, but I’m eager to learn more about this approach.

As I’m sure is the case with other Ubuntu-related development groups, the Xubuntu team has been quite active as of late.  We spent some time this weekend testing out configurations of system settings now that we have migrated to Xfce 4.6 for the 9.04 release, and have completed the transition to the new artwork for the release, too.  Much of these discussions took place over IRC, and it was fun to be a part of it.  We were able to hammer out patches, test them out, and then provide feedback to each other based on our findings.  The time spent proved to be very beneficial, and the Xubuntu 9.04 release is shaping up very nicely.

I’ve also been working on the documentation for Xubuntu 9.04, which has been rebased off of the Ubuntu 9.04 documentation for this release.  What this means is that I’ve been able to use bzr to merge in changes from the Ubuntu documentation as they happen, applying them directly to the current branch of Xubuntu documentation.  This is different from prior Xubuntu documentation efforts that had been based off of a much earlier set of Ubuntu docs.

In that sense, I was starting at a bit of a disadvantage – each release brings changes and updates, not only to X/K/Ubuntu itself, but also the associated documentation.  However, by using the current branch of Ubuntu docs as a starting point for this release, and merging in updates as they get applied to Ubuntu documentation, I’ve been able to leverage the ongoing contributions of the Ubuntu documentors and keep the Xubuntu docs more up-to-date.

Using this approach took a little bit of experimenting to find a good workflow for myself, but Bzr has proved to be a more-than-adequate tool for this particular scenario.  For example, the bzr command that I’ve used most frequently as of late involves merging in the specific changes from one Ubuntu documentation revision to another into the Xubuntu documentation branch.  To do that, I’ve just reviewed recent changes to Ubuntu documentation, navigated to my local folder of the Xubuntu documentation branch, and issued a command similar to this one:

bzr merge -r211..212 lp:ubuntu-doc

Here I’m telling bzr to merge in only the differences between revisions number 211 and 212 from the Ubuntu Documentation branch.  Merging in changes between specific revision numbers allows me to cherrypick – I can merge the changes that I want, and skip the changes that I don’t want.  This is helpful because Xubuntu docs will not include the Ubuntu Server Guide (my apologies to Adam Sommer, who has done a ton of great work on the Ubuntu Server Guide for this release), so I have skipped revisions that include updates to the Server Guide.  : /

If there are no conflicts between the merged files, bzr just identifies the changes as modified files – no problems.  Files that contain conflicts are identified by bzr, too, and it is up to me to resolve those conflicts.  Once fixed, I can then use bzr to mark the conflicts as resolved.  The process still requires some manual review on my part, but reviewing someone else’s changes is much easier than writing my own stuff, and gives me more time to focus on documenting the elements that are specific to Xubuntu.

I’m still writing additional documentation that is specific to Xubuntu, but have a little bit of time remaining before string freeze.  : )  At the end of next week, I am going to be travelling to Seattle to visit a friend and her husband, and also attend a documentation conference out there.  I’m going to focus on the Design Strategies, Content Development, and Open Standards tracks.  It should be a great time, and should make for a great learning experience, too.

Cody Somerville has been writing quite a bit lately about what’s going on with Xubuntu, focusing a lot on the strategy document and some technical goals for the next release, but we also have a couple of other things in the works – some items that are kind of on the fringes of the distro, but important nonetheless.

One item is an update to the website.  Xubuntu.org is in need of a refresh!  We’ve had a couple of starts and stops on updating it over the last two releases, but nothing noteworthy ever came of it, so this time I’m putting together a project plan that will break the tasks down into smaller chunks with a clear plan for getting things in place.

I’m not going to guarantee that things will work like clockwork, and I’m not even sure who we’re going to get to help out with the website, but I figure that setting a plan with individual bits that people can do one-by-one is more likely to garner success than handing someone the keys to a base Drupal installation and saying, “Have at it!  Let us know when you’re done!”

I’m sure I’ll have more news on that once I’ve got the basic project plan in order, and (of course) we’ll be seeking out help with the website then, too.  If you think you might want to help out, please make a note of it – place a bookmark in the Firefox 3.0 of your mind.  :]  Or you can just read this blog aggregator thingy, and look for more info about the website project plan when I write about it.  Perhaps that would be better than trying to integrate Firefox 3.0 with your brain.

For now, though, work continues on adding poetic, beautiful content to the wiki, and a few documentation ideas are being tossed around amongst Xubuntu folks.  It’s kind of hard(y) to believe that the first Alpha release for Intrepid is less than a week away, but I suppose it’s how things go.

The Xubuntu documentation for 8.04 is done, and the doc-centered folks are now working on updating the wiki.  There are still quite a few holes in it for now, but we’re working fairly quickly.  I like the new menu bar.  It makes it easy to get around.

Also, I know it’s not much notice, but tomorrow (Wednesday, 2008-03-26) Jono Bacon is leading a Xubuntu-focused meeting in the #ubuntu-meeting channel on the Freenode IRC network.  The meeting will be held at 1900 UTC (2pm Chicago time).  We’re going to discuss Xubuntu’s mission and strategy, and discuss how to pull in some additional development and packaging help.  The Xubuntu team has had a bit of turnover as a result of some internal disputes over default package selection recently, and we think that coming to some kind of a consensus on our project goals will help focus our efforts and help put some of the conflict to rest.

I feel like Xubuntu is moving in a good direction, though.  Cody Somerville looks to be the person who will be leading the project, and he has a good idea of what Xubuntu is about, is technically proficient, and knows how to argue a point rather than getting mixed up in a bunch of jibba jabba.  All good qualities to have in a project leader.  (Cody also made that wiki menu bar on the Xubuntu wiki.)  As much as anyone pays attention to a wiki, perhaps having a well-set wiki with clear paths to help people start getting involved will help things along a little bit, too.

I’m preparing an interblags post that will contain 8.04 reasons for why Ubuntu and Kubuntu users should consider using Xubuntu (it might be more like 8.04 reasons why I like Xubuntu . . . I’m not sure), but it’s not ready yet.  I only have 7.04 reasons so far.  My post should be Hardy, not Feisty.