add documentation describing table layout

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

src/register/table-allgui.h

@@ -31,6 +31,47 @@
  * infrastructure.  Additional, GUI-dependent parts are implemented
  * in table-gtk.c and table-motif.c
  *
+ * CONCEPTS:
+ * The following apply to the rows in a table:
+ * -- a phys row can belong to only one virt row at a time.
+ * -- a cursor is always the same size as the virt row its on,
+ * -- there is only one cursor for a given virt row.
+ * -- there is no overlap; a phys row can only belong to one virt row.
+ *
+ * Lets say there are three cursors T(rans),S(plit), and B(lank).  
+ * Lets say that these are used to 'print' the following table layout:
+ * 
+ *       virt row 1   T
+ *       virt row 2   S
+ *       virt row 3   B
+ *       virt row 4   T
+ *       virt row 5   S
+ *       virt row 6   S
+ *       virt row 7   S
+ *       virt row 8   S
+ *       virt row 9   B
+ *
+ * You can see there is only one cursor per virt row.  There is no overlap
+ * between cursors and virt rows, the correspondence is one to one.  Note
+ * that the three cursors T,S and B may consist of one, or more phys rows,
+ * e.g. B and S may be one line each, but T may be two lines.  Thus, we 
+ * have the following physical layout:
+ *
+ *      phys row 1    virt row 1   T
+ *      phys row 2    virt row 1   T
+ *      phys row 3    virt row 2   S
+ *      phys row 4    virt row 3   B
+ *      phys row 5    virt row 4   T
+ *      phys row 6    virt row 4   T
+ *      phys row 7    virt row 5   S
+ *      phys row 8    virt row 6   S
+ *      phys row 9    virt row 7   S
+ *      phys row 10   virt row 8   S
+ *      phys row 11   virt row 9   B
+ *
+ * This layout remains static until the next time that the table is 
+ * re-'printed'.
+ *
  * HISTORY:
  * Copyright (c) 1998,1999 Linas Vepstas
  */