DocBook Wishes '05

Volume 8, Issue 3; 03 Jan 2005; last modified 08 Oct 2010

With almost an entire calendar year ahead, I have a couple of hopes and aspirations for DocBook in 2005.

We are at the very beginning of time for the human race. It is not unreasonable that we grapple with problems. But there are tens of thousands of years in the future. Our responsibility is to do what we can, learn what we can, improve the solutions, and pass them on.

Richard Feynman

I fully expect DocBook to be the subject of requests for enhancement and incremental improvements for quite a while yet, but I have a few explicit hopes for DocBook in 2005. Three, in fact.

I'm going to do my best to drive the first two:

  1. Publish DocBook V5.0. The 5.0 plan is a big shift, moving away from DTDs to RELAX NG. I expect it to be, and it has been, a slow process. But we've got a stable schema, a stable schema language, and a few months of testing under our belts. We ought to be able to do this.

    I think there are a couple of technical road blocks ahead. One is the inability to produce any sort of DTD version of 5.0. I've been working on that, but didn't get as much time over the recent break as I expected. More news when I have some. The other is documentation, which leads me to, the next item.

  2. Publish DocBook 5.0: The Definitive Guide. I don't think we can move to 5.0 without reasonably adequate reference documentation. That means getting The Definitive Guide revised for V5.0. I spent a few days working on that over the break and I have a first attempt ready.

    If there's any hope of getting this ready in a timely fashion, I think it's going to require cutting most of the introductory material, making this even more of a pure reference than the first edition. I've started to work on that, but there's still more to be done.

    One thing I need to know is, do the content models make any sense as I've presented them? If you've got suggestions for more concise representations, please pass them along.

    A few notes to save myself some comments:

    • Yes, most of the “purposes,” the one-sentence summaries of what each tag is for, are missing. They're going to come out of annotations in the actual schema, but I only have a few in place.

    • There are no attribute descriptions for the same reason, they're going to be in the schema.

    • Almost all the examples are currently missing.

    • There's a bug in the presentation of attribute co-constraints, (see, for example, biblioid ). All the attributes are presented at the same level when it should be a choice of one attribute or all of a group of attributes.

    It's a work in progress.

Every now and then, someone writes something scathing about DocBook. I try not to avert my gaze. You have to listen to the critics if you want to know where you need to improve. (That said, abusive, vitriolic temper tantrums go in the bit bucket with the rest of the trash. In my book, if you can't say it without being rude, don't bother to say it.)

Sometimes the author is clearly confused about what structured markup is, or he or she is trying to do something for which XML, or at least DocBook, is not really the right tool. That's a misunderstanding, not really a problem.

The ones that really bother me are the ones where the author says he downloaded DocBook and Java and some stylesheets and a couple of other tools and he can't tell where to start and nothing works and how the heck are mortals supposed to use this stuff. I wince. And I know it's true. That's the third thing on my list:

  1. Better Packaging for Users. We need to make it possible for a motivated writer to get DocBook, hack out a few paragraphs, and produce something on the screen and on paper without having to decipher six different packages and eleven command lines. I think we've got most of the core bits of functionality, thanks to the DocBook Open Repository team, and I know that there are packages for some operating systems, but I think it's still more than a bit rough around the edges.

    This is an area where I can't really do much to help. Not for lack of wanting to, you understand, but there just aren't enough hours in the day.

    I put this in my ’05 wish list because I think there's really hope we could be a in a lot better shape this time next year. As I said, there are already some packages available on some platforms and there are some editing tools that are distributed with customizations for doing the transformations. But I think we need to do better and I'm sure we can do better. Please help, if you can.

Do you have DocBook wishes for ’05?

Comments

For me, the most frustrating issue relating to packaging was the DTD-based toolchain. So, I have my document with its doctype declaration and I want to transform it. I rummage around and figure out how to get an xslt processor working. But wait, I can't actually run the damned process because the processor wants to know where the DTD is.

Now I have to figure out how to deal with catalog files (not at all fun!), or I just remove the declaration and try again. But wait, the document contains entities, and the processor again chokes.

Perhaps with v5, the task can be made easier for new users by simplifying the above mess? Maybe a simple shell script for running the transformation would help too?

—Posted by Bruce D'Arcus on 04 Jan 2005 @ 04:10 UTC #

FreeBSD has a textproc/xmlcatmgr (which I think comes from NetBSD) that automates registration of new DTDs in the catalogs. Might be useful?

—Posted by Jeroen Ruigrok van der Werven on 09 Jan 2005 @ 06:43 UTC #

IMO, xmlto (http://freshmeat.net/projects/xmlto/) is a great and stable wrapper for xml processing. Is available for years in all main Linux distros AFAIK. I feel using something like:

    $ xmlto pdf document.xml
    $ xmlto xhtml document.xml
is not so hard for a user.

Thus, xmlto and the the related packages is a present packaging solution in *IX, where we have a well structured catalog registry system and filesystem standar which keeps things clear and easy to use with the remote package updaters like yum, urpmi or apt.

An about whishes, I think the present stylesheets still needs a lot of love. The present output, specially the PDF one is not as beauty as I think it could be. And nicer PDF and HTML would be an eternal gift for the users :-D

—Posted by Ismael Olea on 10 Jan 2005 @ 07:04 UTC #

"Better Packaging for Users." The "Docbook Element Reference" in the Docbook 5.0 Definitive Guide is a _big_ improvement in this area. The content model is now formatted for eyeball parsers. I found the reference section (operator definitions!) and the examples in Chapter 2 (the cookbook) essential to getting started, and would have found it easier with the new Definitive Guide.

—Posted by Ian E. Gorman on 17 Jan 2005 @ 03:33 UTC #

Docbook reference as info file for Emacs.

—Posted by Matej Cepl on 14 Mar 2007 @ 10:12 UTC #