Re: gcalc docs (unfinished)

[Telsa Gwynne <hobbit aloss ukuu org uk>]

On Thu, Apr 27, 2000 at 08:44:21PM -0700 or thereabouts, Gregory Leblanc wrote:
> Thanks for all your help, I've got a few more questions (as always) inline
> below.
[snip]
Dan wrote:> 
> > 3) It is an interesting challenge to describe all the buttons 
> > in a clean and readable manner. 

That's so beautifully put. "Interesting challenge", indeed!
 
> > I can see how using the lists may wind 
> > up creating a  very long page.  Is there a better way to do this? 

Greg wrote:
> My stuff is currently just going across the rows documenting each button in
> turn, because that seemed to be the easist way to get something there and to
> make sure I knew what I was talking about.  :)

I have just had a potentially sick idea :)

Make a table in the layout of the calculator.

Take your list of what each button does and put an id tag on each one:
"plus", for example. Put it after the calculator somewhere. Doesn't
even have to be in the same <sect> thingy. 

Go back to the table and put <link linkend="plus">+</link>, 
<link linkend="minus">-</link> and so on in each section of the
table that goes straight to the relevant part of the list. 

Then people can use the table as a table of contents, almost, and
just click on the buttons! Da-dah! 

Or is this a really bad idea and non-intuitive for readers and
stuff? (It's only because I got a table working the other day and
have now decided they're not quite as evil as I thought. :))

> > Or, better yet, you could just use:
[snip]
> >        <guimenuitem>x^2</guimenuitem> &mdash; text text text

Why does everyone love the em-dash so much? I was thinking about
this, because we seem to be using an <itemizedlist> and then
separating the name and the definition with em-dashes all the
time. What's wrong with <variablelist> if we want to separate
name and function?

> I like this idea better, but I'm a little concerned about removing the
> example markup.  Assuming that the DocBook tags really do get used for some
> good indexing (which is the whole point of DocBook, IMHO), then searching
> for an example on how to do something using GNOME Calculator would be a
> reasonable request.  Maybe it's not worth a fight, maybe I just need to
> modify how I'm marking the examples, or find a way to not have the examples
> be numbered.  I'll take a look at the DocBook: TDG a bit more and see what I
> can find, but opinions, either way, are appreciated.

I agree about the indexing, and future attempts to search documents,
very much. This is something we talked about quite a bit at GUADEC.

Telsa