RE: gcalc docs (unfinished)

[Gregory Leblanc <GLeblanc cu-portland edu>]

Thanks for all your help, I've got a few more questions (as always) inline
below.

> -----Original Message-----
> From: Dan Mueth [mailto:d-mueth@uchicago.edu]
> Sent: Wednesday, April 26, 2000 8:25 AM
> To: Gregory Leblanc
> Cc: Gnome Doc List (E-mail)
> Subject: RE: gcalc docs (unfinished)
> 
[snip]
> 
> Comments on the document:
> 1) I would use "GNOME Calculator" for the application name.  
> This is what
> it calls itself in the About dialog (and also in the window 
> title). Right
> now you refer to it as "gcalc".

Oops, there I go using the things in my brain as official again (I type in
'gcalc' for minicommander).  I'll change that right away, thanks for
pointing it out.

> 2) File, Edit, and Help each have one item.  I would make 
> them all nest
> lists or none of them.  (I know, this is a problem in the template
> itself.)

ok, that's fixed, and looks MUCH better now, thanks.  As a side note, I
think that documenting things as "which is self-explanatory" is terribly
unprofessional, and should be removed ASAP.  When writing documentation,
assuming that NOTHING is obvious, even something so simple and universal as
"quit".  Whoops, that seems to have been a rant, should have marked it as
such.  :)

> 3) It is an interesting challenge to describe all the buttons 
> in a clean
> and readable manner. 

I'll second that, but it won't be unique, I suspect.  

> I can see how using the lists may wind 
> up creating a
> very long page.  Is there a better way to do this?  Perhaps you could
> gather multiple items together?  You could group the trig functions
> (sin,cos,tan) together as one listitem.  You could group the power
> functions together (1/x, x^2, x^y). etc.  Or maybe there is another
> way?  (table?)

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

> Or, better yet, you could just use:
>    
>     <itemizedlist>
> 
>      <listitem>
>       <para>
>        <guimenuitem>x^2</guimenuitem> &mdash; text text text
>       </para>
>      </listitem>
> 
>        ...
> 
>    </itemizedlist>
> 
> which will allow you to keep your current format but will 
> take less space
> and may be a bit more readable.  (For example, see the Usage 
> section of
> Mixer applet to see how this looks.)

I'll give that a try, the current format doesn't look very good, although it
is structurally sound, I think.  I guess that's what ignoring presentation
gets me.

> I might also do away 
> with the use of
> <example> and just put the examples in a sentence to make things more
> readable:
> 
>       <listitem>
>        <para>
>         Calculates the square root. For example, pressing
>         <guibutton>SQRT</guibutton> while
>         <command><replaceable>81</replaceable></command> is
>         displayed will show the square root of 81, which is 9.
>        </para>
>       </listitem>
> 
> This will allow you to keep your current layout of each 
> button having its
> own entry and example (which is practical for the reader), 
> but should make
> a shorter, cleaner, and more readable document.

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