2001-05-09 Dave Peticolas <dave@krondo.com>

* src/doc/design/user-preferences.texinfo: update docs

	* src/doc/design/reports.texinfo: update docs

	* src/doc/design/top-level.texinfo: update docs

	* src/doc/design/register.texinfo: update docs

	* src/doc/design/component-manager.texinfo: update docs


git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@4139 57a11ea4-9604-0410-9ed3-97b8803252fd

ChangeLog

@@ -1,3 +1,15 @@
+2001-05-09  Dave Peticolas  <dave@krondo.com>
+
+	* src/doc/design/user-preferences.texinfo: update docs
+
+	* src/doc/design/reports.texinfo: update docs
+
+	* src/doc/design/top-level.texinfo: update docs
+
+	* src/doc/design/register.texinfo: update docs
+
+	* src/doc/design/component-manager.texinfo: update docs
+
 2001-05-09  Christian Stimming  <stimming@tuhh.de>
 
 	* src/scm/report/price-scatter.scm: Added new option: get weighted

README.cvs

@@ -64,4 +64,3 @@ Owen Taylor.
 
 Dave Peticolas
 May 2, 2001
-

src/doc/design/component-manager.texinfo

@@ -336,6 +336,10 @@ This routine may only be invoked when the suspend counter is zero. It
 should never be mixed with the suspend/resume refresh routines.
 @end deftypefun
 
+@deftypefun gboolean gnc_gui_refresh_suspended (void)
+Returns TRUE if GUI refreshing is currently suspended.
+@end deftypefun
+
 
 @node Finding Components, Iterating over Components, Controlling Refreshes, Component Manager
 @section Finding Components

src/doc/design/engine.texinfo

@@ -39,24 +39,24 @@ be created as a shared library for use by other programs.
 
 Splits (@pxref{Splits}), or "Ledger Entries" are the fundamental
 accounting units. Each Split consists of a quantity (number of dollar
-bills, number of shares, etc.), the price of that quantity (the price of
-one dollar is 1.00 dollars, etc.), a Memo, a pointer to the parent
-Transaction, a pointer to the debited Account, a reconciled flag and
-timestamp, an "Action" field, and a key-value frame which can store
-arbitrary data (@pxref{Key-Value Pair Frames}).
+bills, number of shares, etc.), the value of that quantity expressed in
+a (possibly) different currency than the quantity, a Memo, a pointer to
+the parent Transaction, a pointer to the debited Account, a reconciled
+flag and timestamp, an "Action" field, and a key-value frame which can
+store arbitrary data (@pxref{Key-Value Pair Frames}).
 
 Transactions (@pxref{Transactions}) embody the notion of "double entry"
 accounting. A Transaction consists of a date, a description, a number, a
 list of one or more Splits, and a key-value frame. When double-entry
-rules are enforced, the total value of the splits is zero.  Note that if
+rules are enforced, the total value of the splits is zero. Note that if
 there is just one split, its value must be zero for double-entry
 accounting; this used to be used for storing prices, but with the advent
-of the pricedb, zero-valued splits are probably best avoided. If there
-are two splits, then the value of one must be positive, the other
-negative: this denotes that one account is credited, and another is
-debited by an equal amount. Positive Split values are 'debits' and
-negative Split values are 'credits'.  Ensuring the Splits to 'add up' to
-zero causes a double-entry accounting system to always balance.
+of the Price DB, this is no longer the case. If there are two splits,
+then the value of one must be positive, the other negative: this denotes
+that one account is debited, and another is credited by an equal
+amount. Positive Split values are 'debits' and negative Split values are
+'credits'. Ensuring the Splits to 'add up' to zero causes a double-entry
+accounting system to always balance.
 
 The engine does not enforce double-entry accounting, but provides an API
 to enable user-code to find unbalanced transactions and 'repair' them so
@@ -65,20 +65,19 @@ that they are in balance. @xref{Scrub}.
 Note the sum of the values of Splits in a Transaction is always computed
 with respect to a currency; thus splits can be balanced even when they
 are in different currencies, as long as they share a common currency.
-The conversion price is simply the price stored in the Split. This
-feature allows currency-trading accounts to be established.
+This feature allows currency-trading accounts to be established.
 
-Every Split must point at its parent Transaction, and that Transaction
+Every Split must point to its parent Transaction, and that Transaction
 must in turn include that Split in the Transaction's list of Splits. A
 Split can belong to at most one Transaction. These relationships are
-forced by the engine. The engine user cannnot accidentally destroy this
-relationship as long as they stick to using the API and never access
-internal structures directly.
+enforced by the engine. The engine user cannnot accidentally destroy
+this relationship as long as they stick to using the API and never
+access internal structures directly.
 
 Splits are grouped into Accounts (@pxref{Accounts}) which are also known
-as "Ledgers" in accouting practice. Each Account consists of a list of
+as "Ledgers" in accounting practice. Each Account consists of a list of
 Splits that debit that Account. To ensure consistency, if a Split points
-at an Account, then the Account must point at the Split, and vice-versa.
+to an Account, then the Account must point to the Split, and vice-versa.
 A Split can belong to at most one Account. Besides merely containing a
 list of Splits, the Account structure also give the Account a name, a
 code number, description and notes fields, a key-value frame, a pointer
@@ -1138,14 +1137,13 @@ is linked to.
 This is the number of 'shares' which have been debited to the parent
 Account. This quantity may be negative, in which case the Split
 represents a 'credit'. Shares are given in units of the security of the
-Account, unless the security field is blank, in which case shares are
+Account, unless the security field is NULL, in which case shares are
 given in units of the Account currency. @xref{Accounts}.
 
-@item A 'price'
-This represents the price of the shares. The price is a ratio of the
-parent Account currency to the parent Account security. For most Accounts,
-the security is blank, and thus the price is @code{1.0}, since the currency
-effectively is the security. @xref{Accounts}.
+@item A 'value'
+This represents the value of the shares in units of the currency of
+the Account. If the currency and the security are the same, or the
+security field is NULL, the value and share quantity must be equal.
 
 @item A 'reconciled' flag
 This flag represents the reconciled status of the Split. Possible
@@ -1231,12 +1229,12 @@ Return the 'share quantity' of @var{split}.
 @end deftypefun
 
 @deftypefun gnc_numeric xaccSplitGetSharePrice (Split * @var{split})
-Return the 'share price' of @var{split}.
+Return the 'share price' of @var{split}, which is the value
+divided by the share quantity.
 @end deftypefun
 
 @deftypefun gnc_numeric xaccSplitGetValue (Split * @var{split})
-Return the value of @var{split}, which is equal to the share quantity
-multiplied by the share price.
+Return the value of @var{split}.
 @end deftypefun
 
 @deftypefun gnc_numeric xaccSplitGetBaseValue (Split * @var{split}, const char * @var{base_currency})
@@ -1617,7 +1615,7 @@ Set the description field of @var{trans} to @var{desc}.
 @tindex GNCBook
 
 The @dfn{GNCBook} interface encapsulate all the information about a
-gnucash dataset, including the methods used to read and write the
+GnuCash dataset, including the methods used to read and write the
 dataset to datastores.  This class provides several important services:
 
 @itemize
@@ -1663,7 +1661,7 @@ The book id must be a string in the form of a URI/URL.  In the current
 implementation, only one type of URI is supported, and that is the file
 URI: anything of the form @url{file:/home/somewhere/somedir/file.xac}
 The path part must be a valid path.  The file-part must be a valid
-gnucash data file. Paths may be relative or absolute. If the path is
+GnuCash data file. Paths may be relative or absolute. If the path is
 relative; that is, if the argument is @url{file:somefile.xac} then a
 sequence of search paths are checked for a file of this name.
 

src/doc/design/gnucash-design.texinfo

@@ -155,6 +155,10 @@ Cells
 
 * BasicCell::                   
 
+Reports
+
+* Creating a Report::
+
 User Preferences
 
 * Option Databases::            

src/doc/design/register.texinfo

@@ -4,7 +4,7 @@
 
 The register is an infrastructure for building a modular matrix of cells
 in which each cell may be specialized to perform a particular function,
-e.g., to read dates, numerical amounts, or text.  The register has been
+e.g., to read dates, numerical amounts, or text. The register has been
 designed to be easy to extend, modular, easy to maintain, and memory
 efficient. It is intended to be used for building financial apps and
 spread-sheets.
@@ -63,47 +63,27 @@ cells must implement. A BasicCell contains the following data members.
 @item char *value
 The 'value' of the cell stored as a character string.
 
-@item guint8 input_output
-This is a bit field used for storing flag values. The following flag
-values are defined.
+@item GdkWChar *w_value
+The 'value' of the cell stores as a wide character string.
 
-  @table @code
-
-  @item XACC_CELL_ALLOW_INPUT
-  If set, the cell will may accept keyboard and mouse input from the
-  user. Otherwise, the cell is for display only.
-
-  @item XACC_CELL_ALLOW_SHADOW
-  If set, the cell will 'shadow' the contents of the register which it
-  is contained in. In other words, as the cell is moved to new locations,
-  the value of the register at that location will be copied into the cell.
-
-  @item XACC_CELL_ALLOW_EXACT_ONLY
-  If set, the cell may only be entered by 'exact' indication of the
-  user. Currently, this means the user must click on the cell with the
-  mouse. This flag will prevent the cell from being tabbed into.
-
-  @end table
+@item gint value_len
+The length of w_value.
 
 @item guint32 changed
 This member is set to have all 1-bits (2^32 - 1) to indicate the
 cell contents have been changed from the register value.
 
+@item guint32 conditionally_changed
+This member is set to have all 1-bits (2^32 - 1) to indicate the
+cell contents have been changed from the register value, but that
+the register should not be considered to be changed unless other
+cells have been changed (not conditionally).
+
 @item char * blank_help
 This member is a text string which may be used by a GUI implementation
 to display an informative help string when the value of a cell is empty
 (perhaps prompting the user to enter a particular kind of value).
 
-@item guint32 bg_color
-@itemx guint32 fg_color
-An RGB value indicating the background (foreground) color to render the
-cell with.
-
-@item gboolean use_bg_color
-@itemx gboolean use_fg_color
-A boolean value indicating whether to use the @code{bg_color}
-(@code{fg_color}) member.
-
 @end table
 
 
@@ -112,9 +92,7 @@ A boolean value indicating whether to use the @code{bg_color}
 
 A @dfn{Cellblock} is an array of active cells. The cells are laid out in
 rows and columns. The cellblock serves as a convenient container for
-organizing active cells in an array. It provides several functions.
-First, it defines a tab-group (group of cells that can be traversed by
-hitting the tab-key). More importantly, through the mechanism of Cursors
+organizing active cells in an array. Through the mechanism of Cursors
 (defined below), it allows a group of cells to be treated as a single
 transactional entity. That is, the cursor/cellblock allows all edits to
 a groups of cells to be simultaneously committed or rejected by
@@ -126,16 +104,16 @@ transaction-processing applications with two-phase commit requirements.
 @section Table
 
 The @dfn{Table} is a displayed matrix. The table is a complex object;
-it is NOT merely a cellblock.  The table provides all of the GUI
+it is @emph{not} merely a cellblock. The table provides all of the GUI
 infrastructure for displaying a row-column matrix of strings.
 
 The table provides one very important function for minimizing memory
-usage for large matrixes. It defines the notion of a @dfn{Cursor}. The
-cursor is a cellblock (an array of active cells) that is moved to the
-location that the user is currently editing. The cursor "virtualizes"
-cell functions; that is, it makes it seem to the user as if all cells in
-the table are active, when in fact the only cell that actually needs to
-be active is the one that the user is currently editing.
+usage for large matrixes -- the notion of a @dfn{Cursor}. The cursor is
+a cellblock (an array of active cells) that is moved to the location
+that the user is currently editing. The cursor "virtualizes" cell
+functions; that is, it makes it seem to the user as if all cells in the
+table are active, when in fact the only cell that actually needs to be
+active is the one that the user is currently editing.
 
 The table design allows multiple cursors to be defined. When a user
 enters a cell, the appropriate cursor is positioned within the table.
@@ -148,13 +126,18 @@ financial example is a table which lists splits underneath their parent
 transaction. This is very different from a checkbook register, where all
 entries are uniform, and can be handled with a single repeated cursor.
 
+Users of the table must provide a TableView object which provides an API
+the table uses to obtain information about the data it is displaying
+such as strings, colors, etc. Thus, the table represents the non-GUI
+portion of the View object in the Model-View-Controller paradigm.
+
 
 @node Split Register,  , Table, Register
 @section Split Register
 
 The split register is a special-purpose object aimed at the display
 of financial transactions. It includes cells for the date, prices,
-balances, transfer accounts, etc.  The register is where the cells,
+balances, transfer accounts, etc. The register is where the cells,
 cursor and table get put together into a unified whole. The register
 defines specific, actual layouts and widths of the date, price, etc.
 cells in a table. It includes a table header, and defines more than
@@ -168,7 +151,7 @@ this implementation was created with the engine financial structures in
 mind.
 
 The second component (src/SplitLedger.[ch]) implements the full register
-behavior and makes full use of the Engine API. This component is
-responsible for loading transactions and splits into the register,
-modifying transactions and splits according to user input, and
-accomplishing tasks such as performing automatic completion.
+behavior (the Controller in MVC) and makes full use of the Engine
+API. This component is responsible for loading transactions and splits
+into the register, modifying transactions and splits according to user
+input, and accomplishing tasks such as performing automatic completion.

src/doc/design/reports.texinfo

@@ -1,5 +1,38 @@
 @node Reports, User Preferences, Register, Top
 @chapter Reports
+@cindex Reports
+
+The reporting infrastructure is designed facilitate the creation
+of sophisticated reports including tables, graphs, and hyperlinks.
+The infrastructure includes functionality to support the following:
+
+@itemize
+
+@item
+Creation of tables, with headings, subheadings, totals, and subtotals.
+
+@item
+Formatting of dates & numbers.
+
+@item
+Currency conversions.
+
+@item
+Create of graphs such as pie and bar charts.
+
+@item
+Creation of hyperlinks to other reports and to other GnuCash
+objects such as registers.
+
+@end itemize
+
+@menu
+* Creating a Report::           
+@end menu
+
+
+@node Creating a Report,  , Reports, Reports
+@section Creating a Report
 
 To define a report, your report must have 
 
@@ -11,9 +44,10 @@ and should have
 
 as well as
 
-@code{(gnc:depend "html-generator.scm")}
+@code{(gnc:depend "report-html.scm")}
  
-if you wish to use the html table generation facilities.
+if you wish to use the html generation facilities. You should
+avoid creating HTML directly wherever possible.
 
 To autoload your report, you should add the line @code{(gnc:depend
 <your_report_name>)} to the file @file{src/scm/report/report-list.scm}.
@@ -24,51 +58,33 @@ has lots of date-manipulation functions you'll almost certainly need.
 
 To define a report, you call @code{(gnc:define-report)}. This function
 can accept a variable number of arguments, but at the moment four
-distinct arguments are recognised, as in like the following from
+distinct arguments are recognised, as in the following from
 the transaction report:
 
 @example
   (gnc:define-report
    'version 1
-   'name (string-db 'lookup 'title)
+   'name (N_ "Transaction Report")
    'options-generator trep-options-generator
-   'renderer gnc:trep-renderer)
+   'renderer trep-renderer)
 @end example
 
 @table @code
 
-@item 'version
+@item version
 This is the version number of the report, which is currently ignored.
 
-@item 'name
-This is self-explanatory.
+@item name
+This is the name of the report. It should be marked as translatable,
+but the name should be given in untranslated form, hence the use of
+@code{(N_ )}.
 
-@item 'options-generator
+@item options-generator
 This should be a function that takes no arguments and returns an options
-structure with the options for the report.  The options interface is
+structure with the options for the report. The options interface is
 currently not fully documented, but should be.
 
-@item 'renderer
-This is a function that takes one argument - a set of options that use
-the options API. It returns a list, which either contains strings, or
-lists which only contain strings or lists of the same type.  When
-flattened and concatenated these strings should form the HTML of the
-report.
+@item renderer
+This is the function which renders the HTML.
 
 @end table
-
-To generate the HTML, you can write your own HTML generation code, or
-use the functions in html-generator.scm. These are already quite well
-documented in the source code itself. To use the HTML generation code,
-you build a structure containing a list of report columns, and for each
-column write functions that, given a report entry, generate the text for
-the cell, as well as column headers and column totals. This interface
-is quite likely to change.
-
-At the moment, the only tools for collecting summary information are
-@code{gnc:account-get-balance-interval} and
-@code{gnc:group-get-balance-interval}. As we start to calculate more
-sophisticated summary statistics (particularly for stock and investment
-tracking), we will add to these. Extracting data from accounts is also
-done directly ATM, but we shall soon use the Query API to do this. The
-Query API therefore needs some user-level documentation as well.

src/doc/design/top-level.texinfo

@@ -1,24 +1,24 @@
 @node Top Level, Engine, Introduction, Top
 @chapter Architectural Overview
 
-GnuCash is written primarily in two languages: C and Scheme.
-The engine/server is written in C primarily for speed,
-portability, stability and historical purposes.  Much of the
-day-to-day workhorse code is written in Scheme, primarily
-for its power, expressiveness and ease of development.
-The user interface is gtk/gnome, some of it done up in C,
-some in scheme, and some with the
-GUI designer tool glade @uref{glade.pn.org}.
+GnuCash is written primarily in two languages: C and Scheme. The
+engine/server is written in C primarily for speed, portability,
+stability and historical purposes. Much of the day-to-day workhorse code
+is written in Scheme, primarily for its power, expressiveness and ease
+of development.  The user interface is Gtk/Gnome, some of it written in
+C, some in scheme, and some with the GUI designer tool Glade
+@uref{glade.pn.org}.
 
 GnuCash is modular, thereby allowing separate individuals
 to maintain, develop and enhance certain modules without
-disturbing the overall development.  (Never mind that 
+disturbing the overall development. (Never mind that 
 modules help avoid spaghetti code and nasty, ugly hacks).
 The interfaces between modules are documented, and, for the
 most part, stable and unchanging.
 
 GnuCash currently consists of the following modules:
 
+
 @section The Engine
 
 The @dfn{Engine} (located under the @file{src/engine} directory in the
@@ -41,9 +41,21 @@ queries can be combined using standard boolean operators.
 
 The @dfn{File I/O} module (@file{src/engine/FileIO.*}) provides an
 interface for reading and writing a set of Accounts, Transactions, and
-Splits to a binary file. This module is being deprecated. A text-based
-format using scheme forms is being developed as a replacement. This new
-module will be separate from the Engine.
+Splits to a binary file. This module is deprecated.
+
+@subsection XML I/O
+
+The @dfn{XML I/O} module (@file{src/engine/*xml*.*} and
+@file{src/engine/*sixtp*.*}) provides an interface for reading and
+writing the engine information to an XML format.
+
+@subsection Backend
+
+The @dfn{Backend} module (@file{src/engine/Backend*.*}) provides
+hooks to allow different modules to be used for storing and retrieving
+Engine data. There are two backends currently under development, a
+Postgresql backend (@file{src/engine/sql/*}) and an RPC backend
+(@file{src/engine/rpc/*}).
 
 
 @section The Register
@@ -75,23 +87,23 @@ The @dfn{Reports} module (@file{src/scm/report.scm},
 balance sheets, profit & loss statements, etc. by using the engine
 API to fetch and display data formatted in HTML.
 
-This module is being redesigned to use the Query API to fetch the engine
-information instead of using the raw engine interface. The new reporting
-design will use Queries to extract the data and assemble it into a
-view-independent format. This data will then be converted to HTML
-reports and/or graphs such as bar and pie charts.
+For the most part, this module uses the Query API to fetch the engine
+information instead of using the raw engine interface. This design uses
+Queries to extract the data and assemble it into a view-independent
+format. This data is then be converted to HTML reports and/or graphs
+such as bar and pie charts.
 
 
 @section Graphs
 
-The @dfn{Graphs} module will be a future module implementing GUI graphs
-such as bar and pie charts. These graphs will be interactive in that the
-user can, for example, move pie wedges, and 'live' in that the user will
-be able to click on graph subsections to see a detail graph or report of
-that particular subsection.
+The @dfn{Graphs} module implements GUI graphs such as bar and pie
+charts. These graphs can be interactive in that the user can, for
+example, move pie wedges, and 'live' in that the user can click on graph
+subsections to see a detail graph or report of that particular
+subsection.
 
-This module will be implemented using the GUPPI library being developed
-by Jon Trowbridge (@url{http://www.gnome.org/guppi}).
+This module is implemented using the GUPPI library being developed by
+Jon Trowbridge (@url{http://www.gnome.org/guppi}).
 
 
 @section Price Quotes
@@ -146,5 +158,6 @@ be a personal-finance manager with enough power for the power user
 and the ease of use for the beginner.
 
 Currently, the Gnome interface is the only operational interface. There
-is an obsolete Motif interface which is not maintained. The Qt code
-won't compile, and most/all functions are missing.
+is an obsolete Motif interface which is not maintained and which is
+removed in current CVS. There is also old Qt code (removed in current
+CVS) which won't compile, and most/all functions are missing.

src/doc/design/user-preferences.texinfo

@@ -3,17 +3,17 @@
 @cindex User Preferences
 
 The options system is used to obtain user preferences, both globally,
-and when displaying a report.  A wide variety of option types are
+and when displaying a report. A wide variety of option types are
 supported, so it should be possible to create an option for just about
 any property the user might wish to specify.  New option types can be
 added if necessary, but as the process requires detailed knowledge of
-gnucash internals and GTK+/GNOME, it is not documented here.
+GnuCash internals and GTK+/GNOME, it is not documented here.
 
 At present, users are most likely to come across the options system when
 designing custom reports, and are consequently mostly going to use the
-Scheme interface.  There is also a C interface to much of the options
+Scheme interface. There is also a C interface to much of the options
 system which is used to access preferences for the UI, but it is not yet
-documented..
+documented.
 
 @menu
 * Option Databases::            
@@ -47,7 +47,7 @@ display.
 Sometimes, GnuCash requires the user to specify true/false properties.
 Others properties most easily specified by selections from a list,
 others from a number, others still by selecting dates, or one or more
-accounts in the account hierachy, or even colors.  Gnucash supports all
+accounts in the account hierachy, or even colors.  GnuCash supports all
 of these and more:
 
 @table @code
@@ -96,6 +96,14 @@ or more items from the group.
 For specifying a numeric quantity.  The programmer can bound the range
 and precision of the quantity.
 
+@item pixmap
+
+For selecting a pixmap located on the filesystem.
+
+@item color
+
+For selecting a color value.
+
 @item internal
 
 An option that isn't specified through an options dialog box.  For
@@ -256,7 +264,7 @@ for currency selection.
 Create an option that isn't controlled through the options GUI.  This is
 used mainly by the GUI to store state that should be preserved from 
 session to session but isn't really configurable from a dialog box, 
-such as the size of the gnucash main window.  
+such as the size of the GnuCash main window.  
 @end deffn
 
 @deffn Function gnc:make-number-range-option section name sort-tag documentation-string default-value lower-bound upper-bound num-decimals step-size
@@ -291,4 +299,3 @@ type as how the default values are specified (except the date option
 which needs to be fixed).
 
 @end deffn
-