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.

From flickr user tsmall. Attribution-ShareAlike 2.0 Generic license

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.

Fellow Chicagolander, nixternal, provided the Ubuntu-Chicago local community team with a few links to packaging-related articles that are available from some Debian and Kubuntu websites:

1) http://www.debian.org/doc/devel-manuals#policy
2) http://www.debian.org/doc/devel-manuals#devref
3) http://www.debian.org/doc/devel-manuals#maint-guide
4) https://wiki.kubuntu.org/PackagingGuide
5) https://wiki.kubuntu.org/PbuilderHowto
6) https://wiki.kubuntu.org/PackagingGuide/Lists/DocumentationResources

He sent them out to the mailing list in advance of a packaging session that’s being held this Sunday at the College of DuPage, in Glen Ellyn, Illinois.

I’m not sure how much we’ll be able to cram into our session that day, but it should be a good start for those of us who aren’t familiar with packaging at all.  As someone who has primarily been focused on assisting with documentation, hopefully some day I’ll at least know how to package the set of docs that we create.