Skip to content

Commit

Permalink
updated documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
blais committed May 26, 2008
1 parent 37bc766 commit f5e3874
Show file tree
Hide file tree
Showing 8 changed files with 714 additions and 391 deletions.
14 changes: 4 additions & 10 deletions doc/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -3,18 +3,12 @@
MODELS = \
beancount.sql

HTML = \
accounting.html \
beancount.html \
capgains.html \
differences.html \
pyledger.html

.SUFFIXES: .txt .sql .db .create .test .clean .html

all: docs sql
all: sql

docs: $(HTML)
docs:
projects docs beancount

.txt.html:
rst2html.py $< > $(<:.txt=.html)
Expand Down Expand Up @@ -42,4 +36,4 @@ examples:
rst-literals -s accounting.txt >/dev/null

clean:
rm -f $(MODELS) $(HTML)
rm -f $(MODELS)
40 changes: 23 additions & 17 deletions doc/accounting.html
Original file line number Diff line number Diff line change
Expand Up @@ -22,31 +22,31 @@ <h1 class="title">Issues Around Double-Entry Accounting</h1>
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Martin Blais &lt;<a class="reference external" href="mailto:blais&#64;furius.ca">blais&#64;furius.ca</a>&gt;</td></tr>
<td>Martin Blais &lt;<a class="reference" href="mailto:blais&#64;furius.ca">blais&#64;furius.ca</a>&gt;</td></tr>
</tbody>
</table>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#issues" id="id1">Issues</a></li>
<li><a class="reference internal" href="#the-problems-does-accounting-solve-for-me" id="id2">The Problems does Accounting Solve for Me</a></li>
<li><a class="reference internal" href="#accounting-basics-notes" id="id3">Accounting Basics (Notes)</a></li>
<li><a class="reference internal" href="#questions-about-accounting" id="id4">Questions about Accounting</a><ul>
<li><a class="reference internal" href="#q-storing-the-units-of-the-value" id="id5">Q: Storing the units of the value?</a></li>
<li><a class="reference internal" href="#q-how-do-i-reevaluate-my-home" id="id6">Q: How do I reevaluate my home?</a></li>
<li><a class="reference internal" href="#q-should-the-amortizable-assets-be-taken-into-assets-or-expenses" id="id7">Q: Should the amortizable assets be taken into Assets or Expenses?</a></li>
<li><a class="reference internal" href="#q-paying-government-taxes" id="id8">Q: Paying government taxes</a></li>
<li><a class="reference internal" href="#q-how-do-we-account-for-existing-positions-in-an-investment-account" id="id9">Q: How do we account for existing positions in an investment account?</a><ul>
<li><a class="reference internal" href="#closing-the-books" id="id10">Closing the books</a></li>
<li><a class="reference internal" href="#tracking-lots" id="id11">Tracking Lots</a></li>
<li><a class="reference" href="#issues" id="id1">Issues</a></li>
<li><a class="reference" href="#the-problems-does-accounting-solve-for-me" id="id2">The Problems does Accounting Solve for Me</a></li>
<li><a class="reference" href="#accounting-basics-notes" id="id3">Accounting Basics (Notes)</a></li>
<li><a class="reference" href="#questions-about-accounting" id="id4">Questions about Accounting</a><ul>
<li><a class="reference" href="#q-storing-the-units-of-the-value" id="id5">Q: Storing the units of the value?</a></li>
<li><a class="reference" href="#q-how-do-i-reevaluate-my-home" id="id6">Q: How do I reevaluate my home?</a></li>
<li><a class="reference" href="#q-should-the-amortizable-assets-be-taken-into-assets-or-expenses" id="id7">Q: Should the amortizable assets be taken into Assets or Expenses?</a></li>
<li><a class="reference" href="#q-paying-government-taxes" id="id8">Q: Paying government taxes</a></li>
<li><a class="reference" href="#q-how-do-we-account-for-existing-positions-in-an-investment-account" id="id9">Q: How do we account for existing positions in an investment account?</a><ul>
<li><a class="reference" href="#closing-the-books" id="id10">Closing the books</a></li>
<li><a class="reference" href="#tracking-lots" id="id11">Tracking Lots</a></li>
</ul>
</li>
<li><a class="reference internal" href="#q-yves-do-you-use-the-settlement-date-or-the-trade-date" id="id12">Q: (Yves) Do you use the settlement date or the trade date?</a></li>
<li><a class="reference internal" href="#q-how-do-we-balance-when-i-have-a-currency-basis" id="id13">Q: How do we balance when I have a currency basis?</a></li>
<li><a class="reference" href="#q-yves-do-you-use-the-settlement-date-or-the-trade-date" id="id12">Q: (Yves) Do you use the settlement date or the trade date?</a></li>
<li><a class="reference" href="#q-how-do-we-balance-when-i-have-a-currency-basis" id="id13">Q: How do we balance when I have a currency basis?</a></li>
</ul>
</li>
<li><a class="reference internal" href="#questions-answered" id="id14">Questions Answered</a><ul>
<li><a class="reference internal" href="#q-how-to-track-company-expenses" id="id15">Q: How to Track Company Expenses</a></li>
<li><a class="reference" href="#questions-answered" id="id14">Questions Answered</a><ul>
<li><a class="reference" href="#q-how-to-track-company-expenses" id="id15">Q: How to Track Company Expenses</a></li>
</ul>
</li>
</ul>
Expand Down Expand Up @@ -171,6 +171,12 @@ <h1><a class="toc-backref" href="#id2">The Problems does Accounting Solve for Me
simply use my accounting file, and reconcile it later when the
statements arrive!</p>
</li>
<li><p class="first">I'm selling books online. I used to find it error-prone and
annoying at the end of every year to figure out how many sales I'd
done. Now I can simply download the data from PayPal and have it
converted automatically, and the balance check insures that I
haven't made any mistakes.</p>
</li>
</ol>
<p>In addition, a double-entry accounting system would allow me to do
things I never could do easily before:</p>
Expand Down Expand Up @@ -199,7 +205,7 @@ <h1><a class="toc-backref" href="#id2">The Problems does Accounting Solve for Me
tried to use GnuCash, and quickly gave up: it was buggy and difficult
to use. I did searches on the internet, which turned up a number of
large bloated systems, until I found &quot;Ledger&quot;, a simple program
written by John Wietley, which was using simple text files to solve
written by John Wiegley, which was using simple text files to solve
the problem elegantly. I learned a lot by just playing with Ledger (I
could not sleep for a few days, was so excited with the elegance of
the solution).</p>
Expand Down
36 changes: 18 additions & 18 deletions doc/beancount.html
Original file line number Diff line number Diff line change
Expand Up @@ -35,29 +35,29 @@ <h1 class="title">Bean Counter: A Simpler Double-Entry Accounting System via SQL
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
<li><a class="reference internal" href="#description-of-objects" id="id2">Description of Objects</a><ul>
<li><a class="reference internal" href="#securities" id="id3">Securities</a></li>
<li><a class="reference internal" href="#accounts" id="id4">Accounts</a></li>
<li><a class="reference internal" href="#transactions" id="id5">Transactions</a></li>
<li><a class="reference internal" href="#posting" id="id6">Posting</a></li>
<li><a class="reference" href="#introduction" id="id1">Introduction</a></li>
<li><a class="reference" href="#description-of-objects" id="id2">Description of Objects</a><ul>
<li><a class="reference" href="#securities" id="id3">Securities</a></li>
<li><a class="reference" href="#accounts" id="id4">Accounts</a></li>
<li><a class="reference" href="#transactions" id="id5">Transactions</a></li>
<li><a class="reference" href="#posting" id="id6">Posting</a></li>
</ul>
</li>
<li><a class="reference internal" href="#inconsistencies" id="id7">Inconsistencies</a></li>
<li><a class="reference internal" href="#operations" id="id8">Operations</a><ul>
<li><a class="reference internal" href="#importing-postings" id="id9">Importing Postings</a></li>
<li><a class="reference internal" href="#categorizing-postings" id="id10">Categorizing Postings</a></li>
<li><a class="reference internal" href="#graph-of-account-relationships" id="id11">Graph of Account Relationships</a></li>
<li><a class="reference" href="#inconsistencies" id="id7">Inconsistencies</a></li>
<li><a class="reference" href="#operations" id="id8">Operations</a><ul>
<li><a class="reference" href="#importing-postings" id="id9">Importing Postings</a></li>
<li><a class="reference" href="#categorizing-postings" id="id10">Categorizing Postings</a></li>
<li><a class="reference" href="#graph-of-account-relationships" id="id11">Graph of Account Relationships</a></li>
</ul>
</li>
<li><a class="reference internal" href="#tags" id="id12">Tags</a></li>
<li><a class="reference internal" href="#initialization" id="id13">Initialization</a></li>
<li><a class="reference internal" href="#other-issues" id="id14">Other Issues</a><ul>
<li><a class="reference internal" href="#issues-with-multiple-currencies" id="id15">Issues with Multiple Currencies</a></li>
<li><a class="reference internal" href="#import-batches" id="id16">Import Batches</a></li>
<li><a class="reference" href="#tags" id="id12">Tags</a></li>
<li><a class="reference" href="#initialization" id="id13">Initialization</a></li>
<li><a class="reference" href="#other-issues" id="id14">Other Issues</a><ul>
<li><a class="reference" href="#issues-with-multiple-currencies" id="id15">Issues with Multiple Currencies</a></li>
<li><a class="reference" href="#import-batches" id="id16">Import Batches</a></li>
</ul>
</li>
<li><a class="reference internal" href="#ideas-for-automation" id="id17">Ideas for Automation</a></li>
<li><a class="reference" href="#ideas-for-automation" id="id17">Ideas for Automation</a></li>
</ul>
</div>
<!-- 1 Introduction
Expand Down Expand Up @@ -318,7 +318,7 @@ <h1><a class="toc-backref" href="#id13">Initialization</a></h1>
<h1><a class="toc-backref" href="#id14">Other Issues</a></h1>
<div class="section" id="issues-with-multiple-currencies">
<h2><a class="toc-backref" href="#id15">Issues with Multiple Currencies</a></h2>
<p>At <a class="reference external" href="http://homepages.tcp.co.uk/~m-wigley/gc_wp_ded.html">http://homepages.tcp.co.uk/~m-wigley/gc_wp_ded.html</a>, a transaction
<p>At <a class="reference" href="http://homepages.tcp.co.uk/~m-wigley/gc_wp_ded.html">http://homepages.tcp.co.uk/~m-wigley/gc_wp_ded.html</a>, a transaction
between multiple currencies is expressed as four entries, going
through a special &quot;cash book&quot; account. Is this useful?</p>
</div>
Expand Down
138 changes: 138 additions & 0 deletions doc/capgains.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,138 @@
<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>Notes on Capital Gains</title>
<link rel="stylesheet" href="../style.css" type="text/css" />
</head>
<body>

<div id="project-header">
<a href="/"><img src="/home/furius-logo-w.png" id="logo"></a>
<div id="project-home"><a href="..">Project Home</a></div>
</div>

<div class="document" id="notes-on-capital-gains">
<h1 class="title">Notes on Capital Gains</h1>

<blockquote>
<p>From &quot;Filippo Tampieri&quot; &lt;<a class="reference" href="mailto:filippo.tampieri&#64;gmail.com">filippo.tampieri&#64;gmail.com</a>&gt;
To &quot;Martin Blais&quot; &lt;<a class="reference" href="mailto:blais&#64;furius.ca">blais&#64;furius.ca</a>&gt;
Cc &quot;John Wiegley&quot; &lt;<a class="reference" href="mailto:johnw&#64;newartisans.com">johnw&#64;newartisans.com</a>&gt; [Add]
Subject Re: Here is one valid way to book capital gains Show full header
Use #1.
Also, you have to use the &quot;average&quot; purchased price for the asset. In other words, if you bought 100 AAPL at USD40/share, then bought another 100 AAPL at USD60/share, and finally sold 50 AAPL at USD70/share, you do not get to choose which lot you are selling from; instead, you have to think of having 200 AAPL at USD50/share; that's your cost basis; so when you sell the 50 AAPL at USD70/share, you are making USD20 a share (and are left with 150 AAPL at USD50/share).
I actually prefer to think in terms of total costs. It is easier to understand, easier to program, and easier to account for commission costs.
So, the example becomes: you bought 100 AAPL at USD4,000, then you bought another 100 AAPL at USD6,000, and finally sold 50 AAPL at USD3,500. Just before the sale, you had 200 AAPL at USD10,000; after the sale, you are left with 150 AAPL at USD6,500.
Super-simple.
Splits and stock exchanges are also very simple. Say, AAPL now splits 2:1, then I will have 300 AAPL at USD6,500; finally, something happens and they are exchanged for EEPL at 3:2 and I am left with 450 EEPL at USD6,500. See the cost basis never changes.
For tax reporting in a different currency, say CAD, you simply have to replace all USD figures with CAD figures using the exchange rate at the date of the transaction where the USD currency is used (when you buy and when you sell), then you run all the transactions from scratch to update your holdings and realized gains (and you will have your report in the new currency).
My software does all this, but it is extremely simple.</p>
<p>On Fri, Apr 25, 2008 at 1:36 PM, Martin Blais &lt;<a class="reference" href="mailto:blais&#64;furius.ca">blais&#64;furius.ca</a>&gt; wrote:</p>
<blockquote>
<p>Thanks for the clarification.</p>
<p>For calculating the gain, do you</p>
<p>1) convert the cost to CAD, convert the proceeds to CAD, then take the
difference?
(removing the commissions before converting each time)</p>
<p>or</p>
<p>2) calculate the capital gains in foreign currency (e.g. USD), minus the
commission costs, and then convert at the rate when you closed your
position?</p>
<p>On Fri, 25 Apr 2008 13:21:50 -0400, &quot;Filippo Tampieri&quot;
&lt;<a class="reference" href="mailto:filippo.tampieri&#64;gmail.com">filippo.tampieri&#64;gmail.com</a>&gt; said:
&gt; I'll try to be more clear.
&gt; For us living in Canada, the tax reporting currency is CAD.
&gt; The currency of the stock account is the currency used to buy the stock.
&gt; You
&gt; probably have a USD investment account and a CAD investment account.
&gt; So, if you buy AAPL in USD in your USD investment account, you will have
&gt; to
&gt; report realized gains to Canada Revenue in CAD.
&gt;
&gt;
&gt; On Fri, Apr 25, 2008 at 11:50 AM, Martin Blais &lt;<a class="reference" href="mailto:blais&#64;furius.ca">blais&#64;furius.ca</a>&gt; wrote:
&gt;
&gt; &gt; Your description makes it sound like I'll have to take care of all this
&gt; &gt; manually...
&gt; &gt;
&gt; &gt; Which is the reporting currency, and which is the account currency? I'm
&gt; &gt; not sure which is which, the words aren't clear to me. If you buy a
&gt; &gt; foreign stock, do you declare the gains in the stock's native currency,
&gt; &gt; or in converted amount in CAD?
&gt; &gt;
&gt; &gt;
&gt; &gt;
&gt; &gt;
&gt; &gt; On Fri, 25 Apr 2008 11:16:23 -0400, &quot;Filippo Tampieri&quot;
&gt; &gt; &lt;<a class="reference" href="mailto:filippo.tampieri&#64;gmail.com">filippo.tampieri&#64;gmail.com</a>&gt; said:
&gt; &gt; &gt; The compute capital gains from US investments that are taxed in Canada,
&gt; &gt; &gt; you
&gt; &gt; &gt; will need to keep track of the date of each purchase so that you can
&gt; &gt; &gt; correctly compute your releazed gains/losses in the reporting currency
&gt; &gt; &gt; rather than the currency of the account (or transaction). Also, you will
&gt; &gt; &gt; have to provide for the possibility of stock exchanges (i.e. you bought
&gt; &gt; &gt; XXX,
&gt; &gt; &gt; but later that was exchange for YYY - due to a merger, for example - and
&gt; &gt; &gt; finally you sold YYY); this has happened a few times to my investments
&gt; &gt; &gt; over
&gt; &gt; &gt; the last few years. Finally, how do you account for splits? You may have
&gt; &gt; &gt; the
&gt; &gt; &gt; split ratio, but many brokers report splits by simply showing some amount
&gt; &gt; &gt; of
&gt; &gt; &gt; shares going into your accout at no cost (e.g. you have 100 shares of
&gt; &gt; &gt; AAPL;
&gt; &gt; &gt; they split 3:2; your account statement may show 50 shares of AAPL &#64; $0.00
&gt; &gt; &gt; going into your account).
&gt; &gt; &gt;
&gt; &gt; &gt;
&gt; &gt; &gt; On Fri, Apr 25, 2008 at 12:17 AM, Martin Blais &lt;<a class="reference" href="mailto:blais&#64;furius.ca">blais&#64;furius.ca</a>&gt; wrote:
&gt; &gt; &gt;
&gt; &gt; &gt; &gt; ... in the absence of &quot;true&quot; tracking of positions and trades.
&gt; &gt; &gt; &gt; This is not tooo bad, all I have to do is find the amounts of the
&gt; &gt; &gt; &gt; commissions at both ends of the trade.
&gt; &gt; &gt; &gt;
&gt; &gt; &gt; &gt;
&gt; &gt; &gt; &gt;
&gt; &gt; &gt; &gt; def test_with_commissions(self):
&gt; &gt; &gt; &gt;
&gt; &gt; &gt; &gt; # Booked capital gains.
&gt; &gt; &gt; &gt; lgr = ledger_str(self.def_accounts + &quot;&quot;&quot;
&gt; &gt; &gt; &gt;
&gt; &gt; &gt; &gt; 2008-01-10 * Bought some shares.
&gt; &gt; &gt; &gt; Assets:Broker 10 AAPL &#64; 120.00 USD
&gt; &gt; &gt; &gt; Expenses:Commissions 9.95 USD
&gt; &gt; &gt; &gt; Assets:Bank -1209.95 USD
&gt; &gt; &gt; &gt;
&gt; &gt; &gt; &gt; 2008-01-11 * Sold some shares.
&gt; &gt; &gt; &gt; Assets:Broker -10 AAPL {120.00 USD} &#64; 125.00 USD
&gt; &gt; &gt; &gt; Assets:Bank 1240.05 USD ;; actual amount deposited
&gt; &gt; &gt; &gt; (easy to find on statement)
&gt; &gt; &gt; &gt; Expenses:Commissions 9.95 USD ;; actual commission for
&gt; &gt; &gt; &gt; closing the trade
&gt; &gt; &gt; &gt; Income:CapitalGains ;; automatically computed gain
&gt; &gt; &gt; &gt; (from share cost above)
&gt; &gt; &gt; &gt; [Income:CapitalGains] 19.90 USD ;; offset for commissions to
&gt; &gt; &gt; &gt; open and close this trade, manually entered
&gt; &gt; &gt; &gt; [Expenses:Deductible-Costs] ;; an account that track costs
&gt; &gt; &gt; &gt; for closed trades
&gt; &gt; &gt; &gt;
&gt; &gt; &gt; &gt; &quot;&quot;&quot;, 'booked-gains')
&gt; &gt; &gt; &gt; assert len(lgr.transactions) == 2
&gt; &gt; &gt; &gt;
&gt; &gt; &gt; &gt; commisions = 2*Decimal('9.95')
&gt; &gt; &gt; &gt; for accname, amount in (
&gt; &gt; &gt; &gt; ('Assets:Bank', Decimal('50')-commisions),
&gt; &gt; &gt; &gt; ('Expenses:Commissions', commisions),
&gt; &gt; &gt; &gt; ('Income:CapitalGains', -(Decimal('50')-commisions)),
&gt; &gt; &gt; &gt; ):
&gt; &gt; &gt; &gt; assert (lgr.get_account(accname).total == Wallet('USD',
&gt; &gt; &gt; &gt; amount))
&gt; &gt; &gt; &gt;</p>
</blockquote>
</blockquote>
</div>
</body>
</html>
Loading

0 comments on commit f5e3874

Please sign in to comment.