Mallard 1.2 Ideas

[Shaun McCance <shaunm gnome org>]

The plan right now is to call the Mallard specification 1.0
around the time of the Gnome 2.30/3.0 release.  This will
be followed by Mallard 1.2 in about six months, which will
contain features that I've intentionally punted on for 1.0.

People have asked about things, so this email details what
I've been considering for Mallard 1.2.  Note that this is
about the specification.  There are many features I intend
to add to my XSLT implementation and to Yelp that don't
require any changes to the specification.

Table of Contents:
* Glossaries
* Conditional Processing
* Multi-page Files
* Anchors
* Next Links


Glossaries
============================================================
I'd like to do glossaries "the Mallard way", i.e. allowing
pages to insert terms into the glossary.  To accomplish
this, we can add glossary terms into the info element of
any page or section.  Something like this:

<info>
  <term id="frobnicate" xref="glossary#f">
    <title>frobnicate</title>
    <desc>short description of frobnication</desc>
    <p>long description of frobnication</desc>
  </term>
</info>

We then assemble these by having a glossary page:

<page id="glossary" type="glossary">
  <section id="f">
    <title>F</title>
  </section>
</page>

When processing a glossary page or section, a processor will
look for all terms that have an xref to that page or section.
It then sorts them and displays them.  Having an explicit
glossary page allows us to have multiple glossaries and to
control grouping.  Translators can also change the grouping
entirely, although this would require the entire page to be
translated as a whole.

We can also use term inline, like so:

<p>Click <gui term="frobnicate">Frobnicate</gui>.</p>

The term attribute can be used on almost all inline elements,
just like the xref and href attributes currently can.  This
gets turned into a link into the glossary.  Implementations
can also use the short description of the term as a tooltip
when you hover over the inline term.


Conditional Processing
============================================================
A lot of people have been asking for conditional processing.
I never did implement the conditional processing features
in DocBook for various reasons, so I wanted to make sure
that whatever we do is well-specified and implementable.

One of the requirements I have is fallback content.  I had
toyed around with if-else elements that could be put into
any block context, but it felt bloated.

My current thinking on this involves using a test attribute
with an XPath attribute.  I got this idea from Gentoo's
GuideXML, by the way.  There are a lot of things I don't
like about that format, but I think this idea has legs.

There are basically three options on how we can introduce
the necessary information into XPath:

1) Variables: $arch = "x86"
2) Extension Function: func:value("arch") = "x86"
3) Node Set: func = "x86"

(3) feels hacky to me, and with (1) I'm concerned about
conflicts with stylesheet-internal variables.  (2) is how
GuideXML does things, and I think it's what I'd prefer.
I need to do some tests.

Obviously, we also need to decide on which keys we want
to recommend.

To simplify processing, I only want to do conditional
processing on block-level elements and list items.  I'm
considering table rows, but I'll have to look at how that
will affect performance, since proper handling of tables
in Mallard generally requires row counting.

It might be useful to introduce a generic block container
element, much like <span> is a generic inline container
element.  This could be used to do conditional processing
on multiple blocks at once.  I'm tending to lean against
this unless anybody can convince me otherwise.


Multi-page Files
============================================================
Currently, each page is in its own .page file.  My plan from
quite some time ago was to have a way to put multiple pages
in a single file.  Basically, you'd have a .pages file that
looks like this:

<pages>
  <page id="fe">...</page>
  <page id="fi">...</page>
  <page id="fo">...</page>
  <page id="fum">...</page>
</pages>

This would function the same as if fe, fi, fo, and fum were
each defined in resp. fe.page, fi.page, fo.page, and fum.page.

One reason for doing this is that it can help authors better
organize their content.  They can keep series of content in
a single file without affecting readers.  This can be useful
particularly with multiple-author documents.

Another reason is that it can allow translators to completely
change what pages are available.  This would be necessary, for
instance, if you did a glossary as multiple pages, where each
page is a letter or letter range.


Anchors
============================================================
Mallard currently has no way for a page or section to assume
multiple IDs.  This is important for maintaining a stable
upgrade path for your document.  This means that applications
or other documents that link to your document don't have to
break when you change a page or section ID.

More importantly, since Mallard documents are pluggable, IDs
are effectively API.  If a third-party author drops a page
in that has a guide link to "foo", and you change the ID of
"foo" to "foobar", that third-party page gets orphaned.

Information gets reshuffled all the time.  That's the reality
of documentation, and we need to deal with it.


Next Links
============================================================
I'm planning on adding next links to help with sequenctial
series of topics.  Basically, you'd do this:

<page id="tutorial1">
  <info>
    <link type="next" xref="tutorial2"/>
  </info>
</page>

So far, most of what people have done with Mallard are on
what I call "tasks" and "solutions".  These types of topics
should really fit on one page.  But there is no reason to
be confined to those sorts of topics.  Other topic types
might include "concepts" and "tutorials".  (I'd like to
have a discussion with the team some time about defining
a set of topic types and making templates for them.)

For something like a tutorial, you might want to break it
into multiple pages.  That's where the next link comes in.
A page links to its next page, which automatically picks
that up and links back to the previous page.

Next links do not affect ordering of topic links in a guide
page or anything else.  There is no intention of allowing
third-party pages to plug themselves into a series.  These
are fairly static things, because we assume the author has
written these pages in a way that assumes the linear order.



That's all I can think of at the moment.  Remember that
this is 1.2 material, which means it's over a year away.
The current focus is on polishing 1.0.

Comments are absolutely welcome.  I'd really like this
to become a group effort.

--
Shaun