Re: Successor to DocBook

[Shaun McCance <shaunm gnome org>]

On Wed, 2006-07-12 at 09:32 +0100, Joachim Noreiko wrote: 
> --- Karl Eichwalder <ke suse de> wrote:
> 
> > Shaun McCance <shaunm gnome org> writes:
> > 
> > > Why not just give all the elements simple and
> > consistent names
> > > to begin with?  Nobody can even remember the
> > DocBook elements,
> > > so what's the point of catering to that
> > experience?
> > 
> > The good thing about DocBook is, that it is by now
> > an accepted standard
> > in the free software and open source community. 
> > Many developers and
> > writers are sufficiently enough familiar with the
> > DocBook markup.  Even
> > if some element names are weird, it might make sense
> > to keep them
> > because we have learnt them (and beginners can learn
> > them as well
> > without too much trouble).
> > 
> > Yes, I'm quite conservative.  I'd say we should wait
> > another 10 years
> > before start to push the next DTD/Schema onto the
> > community.  ATM, the
> > problem is not the markup per se, but the lack of a
> > free XML editor.  We
> > need a combination of oxygen and emacs
> > (psgml/nxml/xml).
> 
> A combination of what...?
> 
> I haven't heard of Oxygen, but I found this: 
> http://www.oxygenxml.com/xml_editor_mac_os_x.html
> 
> That looks way too complex for what a docs writer like
> myself might need.
> I looked into xml editors when I started working on
> documentation. They mostly crashed. 
> The only time I found a real need for them is when I
> wanted to rearrange large chunks of the user guide: I
> wanted to collapse sections and then drag-and-drop
> them. Trying to do this usually moved only the title
> of the collapsed section... or crashed.

I have, in my head, what I think an ideal editor should
look like for non-presentational technical writing.
>From your description, I think we're on the same page.

> And as for emacs... The 1980s called. They want their
> software back.

/me hides his .emacs file

> That pretty much works for me. 
> I know <section>, <para>, <application>. Anything else
> I have to look up the DocBook reference, so even if I
> had a fancy editor that inserted them for me, I
> wouldn't know which to use.

A good editing environment would present to you some
buttons.  Having them in front of you will help you
remember them.  But if there are 50 buttons, you're
still pretty much screwed.  A dozen is the max.

> In particular:
> 
> Why is linking to other documents so awkward? In
> topic-based Mallard, nearly every link will be to
> another file. I want <xref> to a) be a nicer name and

You don't like the name xref?  Uh-oh.

> b) work with any sort of link to gnome docs, so I
> don't have to add the title manually.

This is hard only because of performance issues.
We don't want to have to load up every document
just to process one page.  But we *can* solve
external linking, and we will.

> Why do screenshots have to be wrapped in so much guff?

DocBook's media model was designed to allow content
selection.  Content selection is a very good thing,
and I consider the lack of it to be one of HTML's
greatest failures.

That said, there are less convoluted ways of doing
content selection.  Notably, the way XHTML2 does
it, which is approximately the way I'm doing it.

> How do I mark up commands the user should type into
> the terminal?

Funny.  I was just thinking about the best set of
markup for screen-like environments this morning.
I'm still trying to decide on the best balance on
this issue.

> What's the point of having so many different tags for
> menu items -- guimenu, submenu, menuchoice and so on?
> What information can feasibly be optained from this
> distinction?
> On the flip side, why only guilabel? I have to use
> this for window titles, for dialog labels, for things
> that aren't even labelled in the GUI (eg a folder's
> parent selector in Nautilus).

How about just one element?  That's what I'm giving
you.  If there's really a need to distinguish labels
for check boxes from labels for spin boxes, we can
use an attribute.  There is at least one case where
I think it would be nice to mark check boxes.

> > ;)  I still believe that DooBook is good enough.  If
> > you want "topics"
> > use unnumbered section elements; if special link
> > tags are actually
> > missing, import them using namespaces.
> 
> I wonder what Shaun has in mind for creating the
> contents pages -- I expect these would be in the same
> markup as the topics, since we currently often have
> intro text on our chapter contents pages. A list of
> topic nodes is itself a topic node.
> Can DocBook handle that?

Yes, the same block and inline markup would be used
on the linking nodes for introductory text.  Using
different markup there would be just plain silly.

And yes, linking nodes can be linked into other nodes
just like content pages can be.  If they couldn't, we
could never have anything but a single flat category.

Imagine files and directories.  Now imagine that every
file and every directory can be in any arbitrary number
of directories.

--
Shaun