Re: Mallard 1.2 Ideas

[Milo Casagrande <milo casagrande name>]

Hi Sahun,

2009/7/30 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.

first of all, thanks for writing all the ideas down!


> 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:

> 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.

I'm fast-thinking about the l10n aspect of this and the sorting of it.

We obviously need to extract the "term" attributes in order to let
translators rework the sorting and the glossary inserting thing when
dealing with the term-in-info kind of glossary.

But when dealing with an explicit glossary page, with terms in it, how
can we handle that? Should we have translators do that by hand,
working directly on the Mallard file? Translate PO files, recreate the
Mallard structure and then sort by hand?

BTW, when you talk about an "explicit" glossary, do you mean a system
wide glossary where we can have common desktop and computer terms, or
a per-application glossary, different from the topic-glossary one?

Anyway, the topic-glossary thing would be really useful even for
downstreams, inserting their terms, maybe without touching the system
wide one.

> 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.

I love this!

I would really like to have all the glossary materials for 3.0, but we
can wait...


> 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:

This would be really great. Having lots of small topic files will
probably going to be a mess one day or the other.

The problem is that I'm thinking about the User Guide here. Take
Empathy Mallard doc: we have something like 22 topic files right now,
and it's not 100% complete. It's not that big, it's still easy to
handle, but writing down file-per-file in the Makefile can get tedious
with lots of files, and is error-prone (and you realize that only at
compile time). Plus, you can really see how many of those topics could
really fit into one single file (if they will be shown separately).

Think about the User Guide and how it can change with a topic based
approach: lots and lots of small files. Grouping them together would
be awesome.

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

> 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.

Use this with the multi-pages in one file, and we win! :)

Thinking with multi-pages:

<pages type="tutorial">
 <page id="step1">
 ...

since if I think about a tutorial, I really think of multiple steps
that will guide me (like an assistant) grouped together. And maybe in
this way we don't need the "next" link: XSLT can probably take care of
that (am not saying to avoid the next link, still useful if we want to
send the user to another topic without being in a "tutorial"... but
probably it's getting complicated).

Ciao.

-- 
Milo Casagrande <milo casagrande name>