Resolving the stock split/merger issue.

[Rob Browning]

Right now you can't really enter a stock split/merger into gnucash
reasonably, and with Dave's help, I'd like to fix that.

He and I (and Bill) have talked about this for a bit, and I've thought
about it for a bit, and I've come up with this proposal.

stock splits/mergers:
=====================

Background and relevant considerations:
---------------------------------------

  * Rule#1: Dave gets as much or more say than anyone about
    implementation details that could go either way, if in fact, he's
    going to be the one having to integrate this into the register.

  * Is this a "transaction" or a split level event?

    * If a transaction level event, then what do you do about
      fractional remainders?  Carol has pointed out that in stock
      splits, you might end up with a fractional remainder that you're
      just reimbursed for in cash.  This argues that a stock split is
      a split-level event.  So for now, I'll presume that it's a
      split-level event.

    * If it's a split-level event, then we need a way to tag a split
      as a stock split/merge.  I see the following primary options:

      * Interpret certain numerical/destination combinations as
        indicating a split -- i.e. perhaps a zero valued split in a
        stock register that has shares actually bought or sold ==
        stock split/merger.  This requires very little modification,
        but may result in ambiguous interpretations if there are ever
        other situations where this pattern is also valid -- I can't
        think of any solid ones ATM, but, it's a concern -- stock
        gifts might be such a complication, but I suspect they'd need
        more representation than a zero valued split anyway, so they
        wouldn't be confusable with stock splits, but something else
        might be later.  Seems fragile to me.

      * Have a way of definitively tagging a split as a stock
        split/merger.  This could be either through a reserved kvp
        slot like (gnc:stock-split . #t) or via a new split "type
        field" (which could be implemented as either a kvp_slot or as
        an actual struct enum field...).  This could be used for stock
        splits, as well as other operations we need later, so you'd
        have (gnc:split-type . <type>) where type might be normal,
        stock-split, equity-transfer, etc.

        At first, I thought that this approach had the (dis?)advantage
        that unless we augment the UI to allow setting this tag in the
        register, creating one of these will have to be done via a
        separate dialog.  Dave pointed out a good solution -- see
        below.

Proposed solution:
------------------

  * ignore the aesthetics of the function names here, we'll pick
    better ones.

  * stock splits will be represented with a single Split.  You will
    initialize a Split to be a stock split via

      void xaccSplitMakeStockSplit(Split *s);
   
    You may ask a Split whether or not it's a stock split via

      gboolean xaccSplitStockSplit_p(Split* s);

    You can then set the split's date, quantity (i.e. damount), and
    other appropriate fields as desired with the normal mechanisms.

  * for a stock split Split, the value must always be 0, and the
    damount (or quantity) indicates the number of shares added to or
    subtracted from the account at the time of the split/merge.

  * Dave pointed out that since the value must always be zero, when
    the user tries to commit a split in a stock register with shares
    in/out, but no value, then a dialog can pop up and ask if they
    meant for this to be a stock split/merge.  This seems to solve the
    UI issue.

  * internally stock splits will be implemented as a Split with a
    reserved kvp_slot named gnc:split-type set to "stock-split".  This
    won't be exposed, so we can change it later if we need to, but
    this slot may also be used later to distingush other types of
    split (i.e. we may need one for closing the books, etc.)

-- 
Rob Browning <rlb@cs.utexas.edu> PGP=E80E0D04F521A094 532B97F5D64E3930