Re: Return of the Template Revisions, part MDMXCII

[Telsa Gwynne <hobbit aloss ukuu org uk>]

On Thu, Jul 13, 2000 at 09:47:05PM -0600 or thereabouts, John Fleck wrote:
> On Wed, Jul 12, 2000 at 07:48:55PM -0400, Aaron Weber wrote:
> > Hey all--
> > I've posted an sgml file of my stab at template revisions at
> > http://primates.helixcode.com/~aaron/gdp.html
> > and eagerly await your flames, er, constructive criticism.
> > 
> Your style guide additions and this template prototype have been very
> useful. Thanks. It's got me thinking about moving away from the
> document structure I've been using, which has been based too narrowly
> on the GUI, and toward structuring the document around how the app is
> used. As for the menus, I'm agnostic.

Echoed. However, I do think you need to describe everything _somewhere_. 
I just discovered a feature of gnome-terminal which wasn't documented 
fully. I suspect it was either oversight or an effort not to confuse the
reader. The oversight would be fine. The effort not to confuse ended
up irritating me. For GNOME apps, we currently have only the help
docs as the obvious source of full documentation (don't anyone dare
suggest the source :)), and missing things out silently because "most 
people won't use it" seems to me to be a mistake. If there had been
a "some other options are available and described elsewhere" comment,
I would have been happier.

My other gripe is, as ever:

Why on earth are we still using <itemisedlist>s with a word, an 
em dash and an explanation when we can use <variable> lists and the
<term> and <listitem> tags?

We tend to have: 
   <itemizedlist>
    <listitem>
     <para>
       SOMEWORD &mdash; Some explanation

And I don't see why we're not doing: 
   <variablelist>
    <varlistentry>
     <term>SOMEWORD</term>
     <listitem>
      <para>
        Some explanation

I really do think that this is what <variablelist> was designed for.
Saying "the first one uses less screen space in the finished product"
is cheating: we won't always be using the same stylesheet, and it's
the stylesheets fault :)

I know, this is an old gripe. But hey, I have been good recently. I 
haven't mentioned mousebuttons for months. :)

Telsa