Re: Mallard 1.2 Ideas

[Milo Casagrande <milo casagrande name>]

2009/7/31 Shaun McCance <shaunm gnome org>:
>
> 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.

> (Does that answer your question?)

This, plus the "explicit" explanation applied to my view of
glossaries, answers my question.

I was still thinking of a system wide glossary done  the old way, but
in Mallard:

C/

<page id="glossary" type="glossary">
 <section id="n">
   <title>N</title>
   ...
   ...
   <term id="network">
   <title>Network</title>
   <desc> ... </desc>
   <desc> ... </desc>
 </term>
 </section>
</page>

it/

<page id="glossary" type="glossary">
 <section id="n">
   <title>N</title>
  ...
  ...
   <term id="network">
   <title>Rete</title>
   <desc> ... </desc>
   <desc> ... </desc>
 </term>
 </section>
</page>

That was my "sorting" dilemma done with PO files.

Now I have a better picture of the glossary.

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

The idea of not having an actual glossary page is appealing and looks
like it could be the easiest way for translators to handle that.

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

I'm a bing fan of shipping per-application topic-based documentation:
if I don't have (for whatever reason) that particular application
that's part of the bigger desktop, why should I have its
documentation. And more, why should I have its glossary too.

You said that the files will be installed in the same directory of the
User Guide, so we won't really have a problem with seealso links and
all that stuff.  But if we would like to cross-reference a non User
Guide topic, say from Brasero, on how to burn a disc, how can we do
that? We should probably have a system topic search or ID search...
(maybe it's more Yelp related than Mallard).

-- 
Milo Casagrande <milo casagrande name>