Re: Successor to DocBook

[Karl Eichwalder <ke suse de>]

Shaun McCance <shaunm gnome org> writes:

> By and large, when we do actually have people who
> want to contribute to Gnome documentation, they
> are not seasoned *Nix documentation folks.  They
> don't know DocBook, they don't know TeX, and they
> certainly don't know roff.

They can deliver ASCII, .rtf, or HTML, and a GNOME eidtor can convert it
into XML (DocBook).  Asking everybody to learn the documentation system
(and SVN) is not the most effective way.  Once the document is converted
into XML, the new writer will understand it very fast and can continue
writing XML.  That's my experience with new writers and I do not think
GNOME writers are that different.

> I completely agree that the lack of a free XML
> editor is a serious hindrance to our ability to
> recruit quality tech writers.  I've seen various
> people try to address this, and one thing that
> always causes problems is that DocBook is hard.

That's why I recommend to cut down the DocBook DTD.  As an example take
a look at novdoc coming with SUSE Linux (openSUSE); it is also available
from http://forge.novell.com/modules/xfmod/project/?novdoc as
http://forge.novell.com/modules/xfcontent/private.php/novdoc/1.0/novdoc-schema.tar.bz2

> Making pretty buttons for all the inline markup
> doesn't change the fact that you have too much
> inline markup.  Now you just have a cluttered
> user interface.

If there are not enough inline elements the other half of the writer
will whine ;)

> As for new formats and sticking with the old,
> I figure DocBook 4 has about three solid years
> of life left, and then another two years or so
> of a slow and agonizing death.  Anybody sill
> using DocBook will switch to DocBook 5.

I do not unterstand this argument.  A DTD will never die.  There is
nothing wrong with using version 4 for the next decade or even longer.

> DocBook 5 is a fairly fundamental departure
> from DocBook 4.  It shares many of the same
> markup elements, to be sure.  But there are
> radical changes in ways that will have huge
> impacts on folks like me that write tools.

Agreed.

> We will have to invest time into a transition
> within the next few years either way.  I would
> really rather spend that time transitioning to
> something that can really fulfill our needs.

I still believe it is better to stick with the defacto standard (the
DocBook elements and the DocBook structure).  Even version 5 is not that
radically different.  Most Gnome docs are quite simple (markup wise) and
are probably version 5 ready.

> This is perhaps a good time to point out that
> I consider the documentation system to be a
> core part of our platform offering.  As such,
> I take backwards compatibility very seriously.
> DocBook will continue to be a supported option
> for documentation for the foreseeable future.

Thanks for clarification.  This sounds good.  Under those circumstances
it is perfecty okay to work on next generation components and offer them
to the contributors.

-- 
Karl Eichwalder
R&D / Documentation                         SUSE Linux Products GmbH

Key fingerprint = B2A3 AF2F CFC8 40B1 67EA  475A 5903 A21B 06EB 882E