Re: Successor to DocBook

[David Malcolm <dmalcolm redhat com>]

On Mon, 2006-07-10 at 12:04 -0500, Shaun McCance wrote:
> 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.

BTW, have you looked at DITA?  It appears to be designed more around
collections of short articles on topics, rather than humongous top-down
sections, with subsections ad inifitum:
http://xml.coverpages.org/dita.html
http://www-128.ibm.com/developerworks/xml/library/x-dita3/#N257

> 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
> 
> 
> _______________________________________________
> gnome-doc-list mailing list
> gnome-doc-list gnome org
> http://mail.gnome.org/mailman/listinfo/gnome-doc-list