Re: Successor to DocBook

[Shaun McCance <shaunm gnome org>]

On Mon, 2006-07-10 at 11:41 +0100, Matthew East wrote:
> * Don Scorgie:
> > (Resend.  Hopefully it'll go through this time)
> >
> > On Fri, 2006-07-07 at 13:45 -0500, Shaun McCance wrote:
> >> On Fri, 2006-07-07 at 14:19 +0200, karderio wrote:
> > <snip>
> >> Now here's everybody's first chance to get in on the fun:
> >> The code name for the project-as-a-whole is Project Mallard.
> >> This is sort of an inside poke at DocBook.  But Mallard is
> >> a dumb name for a help format.  So everybody:
> >>
> >> NAME MY XML FORMAT!
> 
> I am really happy that lots of thought and action seems to be happening
> in relation to improving the structure of the help system and making it
> easier to have upstream and distro documentation sitting alongside each
> other.
> 
> However, if I might add a word of caution. I have not seen anything in
> the recent threads which documents *why* a move away from docbook is
> actually necessary for a better help system to work.
> 
> I haven't seen any discussion of it either.
> 
> I have to say, that with all the progress that has been made on the
> toolset around docbook [1], a sudden move away from docbook just feels
> slightly like moving the goalposts.
> 
> [1] Especially the fact that we will soon have tools available to allow
> people to work on a WYSIWYG basis in a collaborative way (via a Moin
> wiki) and produce docbook.
> 
> This isn't really a criticism, but I'd really like to know why docbook
> has been rejected as inadequate for the implementation of a modular help
> system. I'm not attached to a particular format as such, but I think
> that now that some good work has been put in to supporting docbook, I'd
> like to see a move away from it justified more carefully.

It's not really so sudden.  The idea of replacing DocBook has been
floating around for years now.  Discussions have happened in lots
of places, including IRC.  (Sidebar: somebody please create an IRC
client that doesn't suck.  Allow me to select a range of discussion
and send it to a mailing list for public consumption and archival
with no more than three clicks.)

The original manifesto for Mallard is dated 2005-10-01:

http://www.gnome.org/~shaunm/quack/mallard.xml

That was only the first coherent article, though.  Discussions and
ideas had been going around well before I wrote that.  Do read it.
It will provide some answers to your questions.

DocBook is inherently linear.  Doing anything non-linear with it
is a royal pain.  We want standalone pages, each interlinked into
one or more navigational pages.  We could hackishly provide this
with DocBook and a huge pile of processing instructions, but then
our DocBook isn't really DocBook anymore.  Plus, writers would be
burdened with trying to keep a structure in their head that isn't
really reflected in the format they're dealing with.

I had originally intended to make a topic-oriented format that
used DocBook as its within-the-page content model.  Use the same
block and inline elements, etc.  Years of working with DocBook,
both as a writer and an implementor, have convinced me that this
will cause more harm than good.  DocBook's content model is so
horribly obtuse in so many places.

There will be a learning curve for writers already well-versed
in DocBook.  The impact of this is dampened by two points:

1) I don't even fully understand DocBook, and I've written an
   implementation of it.  I'll bet nobody else on this list
   knows all of DocBook.
2) What I'm providing can be learned in an evening, mastered
   in a weekend.  It's an extra weekend of time for existing
   tech writers, but so much time saved for new writers, who
   will never have to learn DocBook.

Bear in mind that nobody on this list has invested more time
than I have in DocBook tools.  I understand that it sucks to
have so much of your hard work sunk.  But it's my hard work
too.  And it's not completely sunk.  A lot of stuff can be
reused, and we've learned a lot.  Change is just the nature
of the software industry.

As for new development on Moin<->DocBook conversions, I am
highly (HIGHLY) skeptical about round-tripping between Moin
and DocBook.  Put bluntly, I don't believe it's even possible
without semi-intelligent natural language processing.  It's
like trying to round-trip between XCF and GIF.  I am wholly
open to being proven wrong.

I do believe the format I'm putting together will be very
conducive to WYSIWYG-esque[1] editors.  It is explicitly
written to be tool-friendly.  Flat block structures make
life so much easier.  There's a big pool of untapped
possibilities for user interactions for writers.  I'm
talking like Olympic swimming pool here.

Finally, we have lost momentum.  Paradigm shifts have a
way of galvanizing people.  It gets them excited.  They
start doing things they would never have thought to do
before the shift.

[1] It will never be fully WYSIWYG, of course.  WYSIWYG
implies that you have complete presentational control,
which you don't have.  It's more like What You See Is
A Faithful Representation Of How This Document Might
Be Rendered, WYSIAFROHTDMBR.  wih-sia-froth-dum-ber!

--
Shaun