Re: Extending Gnumeric Documentation

On Wed, 2004-08-18 at 19:36, Donald Permezel wrote:
Hi All,

I'm writing this because in the lab I am in I am unable to get on IRC,
 so I thought I'd drop an e-mail to the list.

I noticed the 'Extending Gnumeric' section of the help document is
 mostly blank.  The 'writing functions' subsection has an equivilent
 document in /doc/developer (writing-functions.sgml), however for the
 project I am working on it became apparant that the natural
 one-cell-output of functions would be inappropriate (though I realize
 functions _can_ be made to output more).

As such with the help of Robert Jerrad I put together a menu item which
 calls a tool which analyses input data and outputs it to the selected
 range - which is much more appropriate for my (and I suspect other)

Anyhow, since there is nothing about creating tools and menu items in
 the help documentation currently (and I doubt I could improve on the
 orgional 'writing functions' help document), I decided to write a
 tutorial document which instructs the user on how to create a menu
 item and widget which accepts and input and output range - and where
 and how to code for performing analysis on the data.

As my knowlege of the C workings of Gnumeric is hardly very deep, being
 an EE rather than a Comp. Sci, the document isn't very technical, but
 I believe for engineers such as me wanting to perform mathematical
 operations on a dataset with simple C programming the tutorial could
 be of much use.

I was hoping I could get someone to look it over for me and suggest
 improvements?  And perhaps information on whether it would or could be
 suitable to include into the Gnumeric help documentation?

Hi Don,

We greatly appreciate any attempt to provide some developer
documentation. Unfortunately your documentation is based on some
questionable code (that I wrote).

Some general comments:

Functions cannot only return sigle values as you indicated in your
e-mail, but also whole arrays of values, so many `analysis tools' could
be better implemented using a single array returning function.

Moreover, a problem I see with all analysis tools in the 1.2.x release
and most in 1.3.x is that they provide constant values that do not
change with any values in the source data. In my mind this contradicts
the basic idea of a spreadsheet where values are recalculated whenever
the source values change. In the current cvs, you may notice that
various tools (One-way ANOVA, correlation, covariance, descriptive
statistics,...) allow the user to choose between formulas and values
with formulas being the default. These tools therefore build a formula
structure in the target range that will recalculate its values on the
fly as the source data changes. Users that want to freeze those values
can simply choose the `values' option.

I think any documentation should emphasize this version of the analysis
tools. I hope to change all tools to use this way of handling things.

Of course many parts of your documentation apply to this situation too.

On a more specific note, the use of dialog_tool_init requires that the
glade file uses specific field names otherwise chaos results.



The help document is on the gnumeric-snob wiki at -

Andreas J. Guelzow
Taliesin Software, Shelties, Pyr Sheps
and Shetland Sheep

Attachment: signature.asc
Description: This is a digitally signed message part

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]