Terminology Clarification requested

[Thomas Bullock]

Derek,

Thanks for your comments.  Sorry to be delayed in replying.  See my comments inserted  below.

Tom	

> -----Original Message-----
> From: Derek Atkins [mailto:warlord at MIT.EDU]
> Sent: Friday, December 10, 2010 9:11 AM
> To: Thomas Bullock
> Cc: John Ralls; gnucash-devel at gnucash.org
> Subject: Re: Terminology Clarification requested
> 
> 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.  

We are saying the same thing.  My intent was to indicate what I thought to be a transaction from an accountant's point of view (not that of the mechanics needed to make a multi-part/account transaction be recorded inside GC).
Comparing what I wrote above an what you listed below,  both are the same from a conceptual standpoint, but different within GC, because it can have only one date physically listed and the split parts of the transaction by association and inclusion in the transaction carry that date.  My using 3 dates was not expressing the idea from the perspective of how GC does do its work.  Sorry that misled you in understanding what I was saying.

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 your answer is telling me that the identification of the transaction object is strictly a function of which part of the multi-part real-world transaction is entered first by the GC user.  By default the other parts are identified within GC as splits.

> 
> >> 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).

We agree.  It is good to have the language you provide to understand the GC perspective.

> 
> > 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.

My use of the term 'prime element' was my way of getting at 'transaction object', since I did not have the language prior to this conversation to express myself in the language that you and other developers have become accustomed.

> 
> > 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.

I sent this question/issue to the developer's list because that is the source of everything official including the documentation.   By my raising the question you and John have provided the language that gives me insight into what you are doing and have created in GC.  My prime interest is in documentation and clear expression of ideas.  I cannot serve the project very well unless I have basic concepts clear, which is why I wrote the developer's list rather than the user's 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 totally agree.  The KVP is mentioned only because it was part of the email John sent that got me thinking about my understanding of a transaction.  That led to the email I sent originally.  KVP is not needed to understand from an accountant's viewpoint the concept of a transaction.

Tom

> 
> > 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