Commit b29440f1 authored by Pablo Saratxaga's avatar Pablo Saratxaga
Browse files

Finished moving english help files to C/ subdirectory

parent bd73aedb
<!DOCTYPE book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
]>
<book id="gnumeric-design">
<bookinfo>
<title>The Gnumeric Spreadsheet Internal Design</title>
<releaseinfo>September 2, 1998</releaseinfo>
<author>
<firstname>Miguel</firstname>
<surname>de Icaza</surname>
<affiliation>
<shortaffil>Instituto de Ciencias Nucleares, Universidad
Nacional Autónoma de México
</shortaffil>
</affiliation>
</author>
<address><email>miguel@gnu.org</email></address>
<date>September 2, 1998</date>
</bookinfo>
<chapter>
<title>Gnumeric Internal Design</title>
<sect1>
<title>Design Goals</title>
<para>
The Gnumeric Spreadsheet is a spreadsheet that is intended to
grow in the future to provide all of the features available in
commercial-grade spreadsheets.
</para>
<para>
I am not only intending to provide Gnumeric with a very good
computation engine, but I am also interested in making the GUI
experience for the user as pleasant as possible, and that
includes taking a lot of ideas from existing spreadsheets.
</para>
</sect1>
<sect1>
<title>Target</title>
<para>
Gnumeric should be compatible as much as possible with
Microsoft Excel in terms of the user. This means formulas and
expressions should be compatible unless we find a serious
design problem in Excel.
</para>
<para>
An example of a design problem in Excel is the fact that
various internal functions have limits on the number of
arguments they can take: this is just bad coding and this sort
of limitations is unacceptable in Gnumeric. When writing code
for Gnumeric, no hard coded limits should be set (currently
Gnumeric breaks this rule by having hardcoded in a few places
the maximum number of columns to be 256).
</para>
<sect1>
<title>Basic organization</title>
<para>
The Gnumeric spreadsheet is basically organized as Workbooks
(see src/sheet.h for the definition of the workbook object).
There might be various workbooks loaded at the same time.
Every one of these workbooks might have a variable number of
Sheets (see src/sheet.h for the definition of the Sheet
object), and finally each sheet contains cells (The definition
of a Gnumeric Cell is in src/cell.h).
</para>
<itemizedlist>
<listitem><para> Workbooks only take care of keeping various
sheets together and giving a name to them.</para>
<listitem><para>item Sheets are the repository of information:
cells are kept here, information on the columns and rows
is kept here, and the styles attached to the regions is
also kept here.</para>
<para>Sheets might have multiple views, this is required to
support split views and in the future to support the GNOME
document model. The actual front-end to the Sheet object
is the SheetView object: SheetView object each one has a
number of components:</para>
<itemizedlist>
<listitem><para>
Their scrollbars.</para>
<listitem><para> Their cell display engine (more in a
second).</para>
<listitem><para> Their bar display (column and row
display).</para>
</itemizedlist>
<para>The cell display engine is basically a modified
GnomeCanvas that can deal with keystrokes and can do some
extra spreadsheet oriented tasks. This cell display
engine is of type GnumericSheet.</para>
<para>GnumericSheet objects usually contain a number of
Gnome Canvas items specially designed to be used for a
spreadsheet: the Grid Item and the Cursor Item:</para>
<itemizedlist>
<listitem><para> The Grid item takes care of rendering the
actual contents of the Sheet object and displaying the
Cells in the way the user requested, this is the
actual "core" display engine.</para>
<listitem><para> The Cursor item is the item that actually
draws the spreadsheet cursor. This item, as every
other Gnome Canvas item can take events and this one
is specially interesting, as it provides the basic
facilities for dragging a region of cells. </para>
</itemizedlist>
<para>During the course of a user session, Gnumeric will
create Items of type Editor, a special item designed to
display the contents of a cell as it is being typed and it
is syncronized with a GtkEntry (to provide an Excel-like
way of typing text into the cells).</para>
</itemizedlist>
<para> Sheets contain information for columns and rows in doubly
linked lists to facilitate their traversal (in the future,
when bottlenecks are identified, we will provide an alternate
quick access method based on hash tables, but the information
will still be linked forward and backwards).</para>
<para>The column and row information is stored in GList's that
contain ColRowInfo structures. These structures include a
number of interesting bits:</para>
<itemizedlist>
<listitem><para> Their assigned position (or -1 if they are
the "default" style), field name "pos".</para>
<listitem><para> The actual width used in pixels (for the
current magnification setting) as well as their logical
size, plus the margins required in pixels for displaying
various cell adornements.</para>
</itemizedlist>
<para>When a cell is allocated, both ColRowInfos (for column and
row) are allocated and properly linked, the cell is made to
point to these new structures.</para>
<para>The column ColRowInfos have a field called "data", this is
a linked list of Cells for every row where a cell
exists. </para>
<para>Cells are stored in a hash table inside the Sheet data
structure for quick retrieval and they are also linked
properly in their respective columns. </para>
<para>A cell might display information in more than one column,
so Gnumeric needs to keep track of which cells (column, row
pairs) are being managed by which cell. This information is
kept in a per-row fashion in the data pointer in the
ColRowInfo structure for the rows. The registration and
unregistration of the view areas code is on the cellspan.c
file.
</sect1>
<sect1>
<title>Formula storage</title>
<para>When a formula is encountered, Gnumeric parses the formula
into a tree structure. The tree structure is later used to
evaluate the expression at a given location (each cordinate in a
cell references is stored as either an absolute reference or a
relative reference to the cell position).</para>
<para>To speed up formula duplication, Gnumeric reference counts
the parsed expression, this allow for quick duplication of
expressions. It should be noted that some file formats (the
Excel file format) uses formula references, which can preserve
the memory saving features of reference counting.</para>
<para>Currently Gnumeric does not provide any way to keep these
references, a possible scheme for saving correctly these cells
would be to keep in a special list any formula being saved that
has a reference count bigger than one and keep track of these
duplicates and generate formula references in the output file
rather than outputing the actual formula.
<para>
</sect1>
<sect1>
<title>Resource management</title>
<para>Data structures in Gnumeric are lightweight, they are
designed to consume little memory by reusing as much
information as possible. This is achieved by making common
information be hashed and reference-counted. This is done
with strings, parser/interprester symbols and styles.</para>
<para>To read more about this, check:
<itemizedlist>
<listitem><para>for strings: src/str.c and src/str.h</para>
<listitem><para>for styles: src/style.c and
src/style.h</para>
<listitem><para>for symbols: src/symbol.c and src/symbol.h</para>
</para>
</sect1>
<sect1>
<title>Plugins</title>
</sect1>
</chapter>
</book>
Graphics:
Embedding of graphics will be done by using first
Guppi and eventually Guppi trough the Baboon document model.
Guppi information:
http://www.gnome.org/guppi
gnumeric_helpdir = $(datadir)/gnome/help/gnumeric/C
## Process this file with automake to produce Makefile.in.
gnumeric_help_DATA = \
gnumeric.html \
topic.dat
SGML_FILES = \
autofill.sgml \
cell_refer.sgml \
dndselection.sgml \
editing.sgml \
files.sgml \
formats.sgml \
formulas.sgml \
func-header.sgml \
func-footer.sgml \
functions.sgml \
gnumeric.sgml \
number-format.sgml \
selections.sgml \
text-entry.sgml \
translating.sgml \
worksheet.sgml
TEXT_FILES = \
Design \
Future-Roadmap \
saving.txt
PERL_FILES = \
make-index.pl \
make-docbook.pl
EXTRA_DIST = \
topic.dat \
func.defs \
$(SGML_FILES) \
$(PERL_FILES) \
$(TEXT_FILES)
all:
gnumeric.html: gnumeric/gnumeric.html
-cp gnumeric/gnumeric.html .
gnumeric/gnumeric.html: $(SGML_FILES)
-db2html gnumeric.sgml
functions.sgml: func-list.sgml func-index.sgml func-header.sgml func-footer.sgml
cat $(srcdir)/func-header.sgml func-index.sgml func-list.sgml $(srcdir)/func-footer.sgml > functions.sgml
func-list.sgml: func.defs $(srcdir)/make-docbook.pl
perl $(srcdir)/make-docbook.pl func.defs > func-list.sgml
func-index.sgml: func.defs $(srcdir)/make-index.pl
perl $(srcdir)/make-index.pl func.defs > func-index.sgml
make-func.defs:
$(top_builddir)/src/gnumeric --dump-func-defs=func.defs
dist-hook:
mkdir $(distdir)/gnumeric
-cp gnumeric/*.html gnumeric/*.css $(distdir)/gnumeric
-cp gnumeric.html $(distdir)
mkdir $(distdir)/images
-cp images/*.gif images/*.jpg $(distdir)/images
install-data-local: gnumeric.html
$(srcdir)/../mkinstalldirs $(gnumeric_helpdir)/images
-for file in $(srcdir)/gnumeric/*.html $(srcdir)/gnumeric/*.css; do \
basefile=`basename $$file`; \
$(INSTALL_DATA) $(srcdir)/$$file $(gnumeric_helpdir)/$$basefile; \
done
-for file in $(srcdir)/images/*.jpg $(srcdir)/images/*.gif; do \
$(INSTALL_DATA) $(srcdir)/$$file $(gnumeric_helpdir)/images;\
done
gnumeric.ps: gnumeric.sgml
-db2ps $<
gnumeric.rtf: gnumeric.sgml
-db2rtf $<
SUBDIRS = C
<sect1 id="autofill">
<title>Autofill</title>
<para>When dealing with spreadsheets it's pretty typical to want to
add a set of cells that contain a series of numbers or dates or other
values. While this can be done by hand, Gnumeric implements an autofill
option to allow these sorts of series to be easily fill in.</para>
<para>A typical example of when you want to use this feature is to fill
a series of numbers maybe a list of part numbers, or a perhaps a list
of TV channels. To create a list like this, all the user needs to do
is to enter the first number into a cell and click on the autofill
cursor in the bottom right corner of the cell border and drag it in
the direction to fill. If the first cell contains a '1', for example,
dragging the autofill button(see <xref linkend="celltobautofilled">) down three or four cells
will fill the cells with 1,2,3,4 automatically.(see <xref linkend="cellsautofilled">)</para>
<procedure>
<title>Autofilling a range of cells</title>
<step performance="required">
<para>Select the cell that marks the beginning of the
area to autofill</para></step>
<step performance="required">
<para>Enter the starting value into this cell</para></step>
<step performance="required">
<para>Click the small rectangle in the bottom right corner
of the first cell, and drag it to the end of the area to fill.</para></step>
<step performance="required">
<para>Release the mouse button. The cells in the selected area should
now be field with autofilled values</para></step>
</procedure>
<figure id="celltobautofilled">
<title>A cell with the seed for an autofill.</title>
<screenshot>
<graphic fileref="images/autofill-1.jpg"></graphic>
</screenshot>
</figure>
<figure id="cellsautofilled">
<title>A set of cells being autofilled</title>
<screenshot>
<graphic fileref="images/autofill-2.jpg"></graphic>
</screenshot>
</figure>
<para>As handy as being able to simply and quickly generate series of
numbers incremented by one, autofill can do much much more. The next simplest
example is autofilling with a series with an increment other than 1. For example,
to create a series that consist of odd numbers starting at 11, just enter 11 into
a cell and 13 into the next cell. Then select both cells, and stretch it to the
cover the cells to be filled. If you select the next 5 cells for example, it will
fill with values 11,13,15,17,19,21,23. See <xref linkend="seedcellautofillsequence">
and <xref linkend="autofillsequence"> for example.</para>
<figure id="seedcellautofillsequence">
<title>A seed cell for a date autofill.</title>
<screenshot>
<graphic fileref="images/autofill-3.jpg"></graphic>
</screenshot>
</figure>
<figure id="autofillsequence">
<title>A set of cells being filled with a sequence.</title>
<screenshot>
<graphic fileref="images/autofill-4.jpg"></graphic>
</screenshot>
</figure>
<sect2>
<title>Filling with Dates</title>
<para>Oh, but numbers are easy you say! The real painful stuff is entering
in cell by cell dates and times and other info. But never fear, Gnumeric is there
to help you. Gnumeric has the ability to autofill dates, months, days of the week,
and more. </para>
<para> For an example, think of a typical business invoice, where everything is
logged by the month. So it is quite typically to want to fill a series of cells
with the months of the year in order. To do this is quite simple, essentially the
same steps as making a numerical fill.</para>
<para>Starting from cell B2 for example, if you want to fill the next 12 cells
with the months, just enter the string "January" in B2. Then, click the fill button
and stretch it over the next 12 cells, and release. Simple as that. See <xref
linkend="datefillseed">, <xref linkend="datebeingfilled">, and
<xref linkend="cellsfilled">. </para>
<figure id="datefillseed">
<title>A cell with a date in it, ready to be the seed for a fill.</title>
<screenshot>
<graphic fileref="images/autofill-5.jpg"></graphic>
</screenshot>
</figure>
<figure id="datebeingfilled">
<title>A set of cells being filled.</title>
<screenshot>
<graphic fileref="images/autofill-6.jpg"></graphic>
</screenshot>
</figure>
<figure id="cellsfilled">
<title>A range of cells autofilled with the months.</title>
<screenshot>
<graphic fileref="images/autofill-7.jpg"></graphic>
</screenshot>
</figure>
<para> Other examples of strings that can be autofilled include days of
the week (Monday, Tuesday,...), short weekdays (Mon, Tues, ....),
short months (Jan, Feb,...) </para>
<para> More string fill types to follow </para>
</sect2>
<sect2>
<title>String And Number autofill</title>
<para>Gnumeric tries to be intelligent about autofilling number values that
embedded into text strings. So its possible to autofill cells with values
like "9 lives to live","8 lives to live", etc. </para>
<para>See <xref linkend="autofillexamples"> for some contrived examples.</para>
<figure id="autofillexamples">
<title>Some simple autofill examples.</title>
<screenshot>
<graphic fileref="images/autofill-8.jpg"></graphic>
</screenshot>
</figure>
</sect2>
<sect2>
<title>Formula autofill</title>
<para>Probably the most useful of all the autofill capabilities is
the ability to autofill functions. In practice it works essentials the
same as all the other autofill methods, it just transfers the functions
of course. </para>
<para>See <xref linkend="autofillfunction1"> and <xref linkend="autofillfunction2">
for a simple example.</para>
<figure id="autofillfunction1">
<title>Formula to be autofilled.</title>
<screenshot>
<graphic fileref="images/autofill-9.jpg"></graphic>
</screenshot>
</figure>
<figure id="autofillfunction2">
<title>Formula autofilled to several cells.</title>
<screenshot>
<graphic fileref="images/autofill-10.jpg"></graphic>
</screenshot>
</figure>
</sect2>
<sect2>
<title>Other Notes on autofill</title>
<itemizedlist>
<listitem>
<para>Autofills only work to the down and to the right of a cell.</para>
</listitem>
<listitem>
<para>To make a series that decrements instead of incrementing, enter the
highest value into the first cell, then the next value in the second cell and select
them both in the first step outlined above. </para>
</listitem>
<listitem>
<para>Starting a series with more than two initial values can result in
some unexpected results. Use with care.</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
<sect1 id="cell-referencing">
<title>Cell Referencing</title>
<para>To reference the value stored in a single cell, say B1, just enter "B1"
in the function argument.</para>
<para>Cells are reference in a format like C4, where C is the column label
and 4 is the row label.</para>
<example id="simplecellrefer">
<title>Some examples of function syntax</title>
<programlisting>
=EXP(B1)
=COS(A2)
</programlisting>
</example>
<sect2>
<title>Absolute cell referencing</title>
<para>Cells can be referenced in the default way (relative referencing),
or with absolute referening. Absolute referencing means that when the cell
is copied, the cell reference doesnt change. Normally, autofill'ing a cell
range or moving cell will change its cell reference to so that it maintains
a relation to the original cell. With sbsolute cell referencing this behaviour is
overridden. </para>
<para>The format to use absolute cell refencing is to use a '$' in front of the
cell coordinate that the user wants to stay constant. The col, row, sheet, or
any combination of these can be held constant.</para>
<example id="cell-refer-absolute-reference">
<title>Absolute cell referencing examples</title>
<programlisting>
A1 Normal cell reference
$A2 Hold the column value constant
A$2 Hold the row value constant
$A$2 Hold row and columns constant.
</programlisting>
</example>
</sect2>
<sect2>
<title>Referencing multiple cells</title>
<para>Many functions can take multiple cells as arguments. This can either
be a comma separated list, an array, or any combination thereof.</para>
<sect3>
<title>Multiple individual cells</title>
<para>A comma separated list of cell references can be used to
indicate cells that are discontinuous.</para>
<example id="cellrefermutiplecells">
<title>Some examples of function syntax</title>
<programlisting>
=SUM(A1,B2,C4)
=MIN(A1,B2, C4,C5,D6)
</programlisting>
</example>
<screenshot>
<graphic fileref="images/cells-1.jpg"></graphic>
</screenshot>
</sect3>
<sect3>
<title>Referencing a continuous region of cells</title>
<para>For functions that take more than one argument, it is often
easier to reference the cells as a group. This can include
cells in sets horizontally, vertically, or in arrays.</para>
<para>The ':' operator is used to indicate a range of cells. The basic
syntax is upper left corner:bottom right corner. </para>
<example id="cellrefercontin">
<title>Referencing blocks of cells</title>
<programlisting>
=SUM(A1:E1)
=AVERAGE(B4:E7)
=MIN(A1:A5)
</programlisting>
</example>
<screenshot>
<graphic fileref="images/cells-2.jpg"></graphic>
</screenshot>
</sect3>
<sect3>
<title>Referencing non-continuous regions</title>
<para>For referencing cells that are in non-continuous regions
you can use any combination of the above methods to get
the needed cells.</para>
<example id="cellreferdiscontin">
<title>Referencing blocks of cells</title>
<programlisting>
=SUM(A1:E1, B19, L14:L17)
=AVERAGE(A1,A3, A5:C5)
</programlisting>
</example>
</sect3>
</sect2>
<sect2>