Terminology Clarification requested

[Derek Atkins]

Thomas Bullock <tbullock at nd.edu> writes:

>> > My formation long ago as a young accountant contained this
>> understanding of a transaction: it was the accounting expression of an
>> activity that happened in the physical world, which the accounting
>> ledgers were tracking in their own notation.  For example, suppose the
>> activity is buying a car using cash and debt on 11/10/2010.  The
>> accounting transaction is that act of purchase.  The accounting
>> notation was the language of debits and credits with accompanying
>> names describing the purpose of the monetary "buckets" or value
>> holders.

Yes, and GnuCash (and indeed any other financial program) should model
real-world transactions.

>> > Thus, in a journal, the transaction would be recorded similarly to
>> this:
>> > 								    Debit
>> Credit
>> > 	11/10/2010		New car                     15,000
>> > 	11/10/2010		New car loan
>> 	10,000
>> > 	11/10/2010		Cash in bank
>> 5,000

This example is not only contrived, but you're confusing yourself.
You're writing this as three transactions, where really it's a single
transaction with multiple Splits.  So more accuratately:

   11/10/2010    New Car
                 Asset                15,000
                 Loan                                 10,000
                 Cash                                  5,000

If you really want to know how GnuCash encodes this, simplisitically the
first line is the "Transaction" object, and the three lines below that
are the "Split" objects.

>> So we have a data structure called a "transaction" that includes a
>> variable number (but at least 2) of subordinate data structures called
>> "split", along with some date fields, and some "key-value" or KVP
>> data. 
>
> I infer then that it does not matter which element of the transaction
> gets labeled 'transaction' with all the parts that it has in the code.
> You are saying that whichever piece of the 'transaction' (as an
> accountant understands it) becomes the 'transaction' (as a programmer
> understands it) it is treated as the prime element of the activity
> being recorded.  It is prime because it has different coding treatment
> compared to the subordinate parts which have a programming
> status/treatment that identifies them as subordinate.

The transaction, as the accountant understands it, is a combination of a
Transaction object and its associated Split objects.  A balanced
transaction has at least two Splits.  A basic balanced transaction has
exactly two Splits (one debit, one credit, of the same value).

> If this description is basically correct, then is there anything that
> GC coding uses to identify the 'prime element' and by default relegate
> the remaining elements to subordinate status as 'split' elements for
> split programming treatment?  What makes one element standout that it
> is or should be the element that is accorded 'transaction' programming
> treatment?  Is it strictly an accident of user perception, that is,
> whatever the GC user types in first?

I'm not sure what you mean by "prime element" here.  Could you explain
what you mean?  Within the application both Transaction and Split
objects are first-class objects, but in reality you cannot have a Split
without a Transaction.  Basically, a Split encodes a single debit or
credit into/outof an Account.  A Transaction is a binding of a set of
Splits into a single, umm, transaction.  In a balanced transaction, the
Splits sum to zero.

> I do understand this has programming consequences inside GC code and
> in the broader context of what happens in the case of the 'close
> books' function.  The details of the process are outside the
> accounting area of concern.  Accounting just expects all the parts of
> the transaction to be present and in balance, no matter how that
> occurs to make the 'in balance' condition a fact.

Exactly, which is why we don't really need to document how it all works
internally in user documentation.  Remember, this is the devel list, not
the user list.

>> 
>> Regards,
>> John Ralls
>
> If my inferences above are correct, they are important to a proper
> conceptual understanding in the documentation to help a new GC user.
> There has to be some awareness in the documentation that the
> accounting and programming uses of 'transaction' are different and
> where the difference lies.

Well, this SHOULD all be in the concepts guide, at least basically.  The
question of where to store a KVP, however, is absolutely outside the
scope of any such documentation.

> I hope you won't mind correcting me if I have made incomplete or
> incorrect inferences.
>
> Thanks.
>
> Tom	

-derek

-- 
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       warlord at MIT.EDU                        PGP key available