Re: Mallard 1.2 Ideas

[Shaun McCance <shaunm gnome org>]

On Fri, 2009-07-31 at 10:30 +0200, Milo Casagrande wrote:
> 2009/7/30 Shaun McCance <shaunm gnome org>:
> > 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?

So let's make the distinction here between sorting and grouping.
Grouping is the process of breaking down a big list into smaller
lists.  In the case of glossaries and indexes and such, this is
often done by taking sequential lists from a sorted list.  That
is, we break it into A,B,C,etc or maybe A-D,E-H,I-L,etc.

With this proposal, grouping is done manually with the xref
attribute on the term element.  This gives you the freedom to
do chunked grouping (A-D,E-H), and it allows translators to
completely change the grouping.  It also means you can do
grouping that has nothing to do with the sort order, if the
need should arise.

Inside of a group, we will automatically sort the terms that
we automatically put into the group.

As for translating the attributes, yes, we'll certainly need
to allow translators to translate the term attribute on inline
elements.  But since we make messages out of block elements,
and since I'm not proposing allowing the term attribute on
block elements, this shouldn't be a problem.

<p>This is some <span term="text">text</span>.</p>

This becomes this:

# foo.page:42(p)
msgid "This is some <span term=\"text\">text</span>.</p>"

Caveat: xml2po does this thing where if a non-final tag
contains the entirety of a final tag, it doesn't bother
showing you the non-final tag.  So:

<p><span term="text">text</span></p>

Becomes:

# foo.page:42(span)
msgid "text"

There are, frankly, a lot of issues with xml2po we're going
to have to address in the coming months.  I'm confident we
can get this right for translators.

(Does that answer your question?)

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

Sorry, when I said "explicit", I was contrasting this proposal
with another proposal that only exists in my head.  I suppose
a contrast isn't useful to people who aren't in my brain.

Another idea I'd had was that you wouldn't even have an actual
page for the glossary.  Instead, we'd make one by collecting
all the terms and automatically grouping and such.  There's a
certain appeal to such an implicit system, but I think we gain
a lot from the explicit glossary pages.

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

Right.  So which glossaries exist for which documents is a
choice we have to make as writers.  A document for a large
piece of software, especially one that demands a lot of
domain expertise, might want its own glossary.  Imagine,
for instance, the help for some small business accounting
software package.  A glossary would make sense there.

But I imagine we'd want to have a general computer terms
glossary we'd ship with the desktop.  And it's likely that
distros will want to add to that.

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

Totally.  Although I tend to think we should break things
apart and maintain chunks in different places.  So all the
file-management-related stuff could just be maintained in
Nautilus.  It would get installed into the same directory,
so it would be part of the User Guide.

I think this would help us better coordinate the efforts
of writers and editors.  We could have people responsible
for the Nautilus help, and they could just do their job
in their own place.  (Although obviously we'd need some
coordination between the User Guide contributors.)

This would be particularly useful for technical reviews.
We want to have maintainers or developers do a technical
review every release cycle, to check for incorrect or
outdated information.  Breaking things up would make it
simpler when we ask a Nautilus developer to review the
Nautilus stuff.

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

I think it absolutely makes sense, from an author's
organizational perspective, to put topic series into
pages files.  I'm not sure that I'd want to add extra
voodoo to automatically do next links based on that
though.  Too much voodoo is scary.

Thanks,
Shaun