RE: gcalc docs (unfinished)

[Dan Mueth <d-mueth uchicago edu>]

On Sat, 22 Apr 2000, Gregory Leblanc wrote:

> Two more things, before I forget them again.  First, when I run nsgmls -s
> gcalc.sgml, it gripes about the <legalnotice> not being allowed there.
> Second, should I be emailing George Lebl, or Gregory McLean about gcalc not
> working?  If the latter does anybody have an email address?
> 	Greg

You can fix the <legalnotice> problem by changing the first line of the
file to refer to "V1.1" instead of "V1.0" and upgrade to dcm's new
gnome-doc-tools package.

Bugs should probably be sent to submit@bugs.gnome.org.  Of course it
wouldn't hurt to CC the author (George Lebl) or send him a separate note
pointing these out.

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

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

3) It is an interesting challenge to describe all the buttons in a clean
and readable manner.  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?)

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

Just some ideas.

Dan