From 71012f8848c91666441453bc210140cba4fe5d5e Mon Sep 17 00:00:00 2001
From: Simon Michael <simon@joyful.com>
Date: Thu, 20 Apr 2017 16:31:54 -0700
Subject: [PATCH] add "Don't Sink Your First Attempts at Plaintext Accounting"

By Robert Nielsen, 2017/4/20 version from the hledger mail list.
---
 index.html                       |  11 +--
 index.md                         |   6 +-
 plaintext-accounting-errors.html | 104 ++++++++++++++++++++++++++++
 plaintext-accounting-errors.md   | 113 +++++++++++++++++++++++++++++++
 4 files changed, 225 insertions(+), 9 deletions(-)
 create mode 100644 plaintext-accounting-errors.html
 create mode 100644 plaintext-accounting-errors.md
diff --git a/index.html b/index.html
index 60106dd..6ba1733 100644
--- a/index.html
+++ b/index.html
@@ -406,11 +406,12 @@ other console/curses tools
 <ul>
 <li><a href="http://ledger-cli.org/docs.html">Ledger manuals</a></li>
 <li><a href="https://github.com/ledger/ledger/wiki">Ledger wiki</a></li>
-<li><p><a href="http://ricostacruz.com/cheatsheets/ledger.html">The Great Cheatsheet for Ledger CLI</a></p></li>
-<li><p><a href="http://hledger.org/docs.html">hledger docs</a></p></li>
-<li><a href="http://furius.ca/beancount/doc/index">Beancount docs</a> (or <a href="http://aumayr.github.io/beancount-docs-static/">sphinx version with API docs</a>)</li>
-<li><p><a href="http://furius.ca/beancount/doc/cheatsheet">Beancount Syntax Cheatsheet</a></p></li>
-<li><p><a href="quickref/">Syntax Quick Reference for the Ledger-Likes</a></p></li>
+<li><a href="http://ricostacruz.com/cheatsheets/ledger.html">The Great Cheatsheet for Ledger CLI</a></li>
+<li><a href="http://hledger.org/docs.html">hledger docs</a></li>
+<li><a href="http://furius.ca/beancount/doc/index">Beancount docs</a> (or <a href="http://aumayr.github.io/beancount-docs-static/">sphinx version</a>)</li>
+<li><a href="http://furius.ca/beancount/doc/cheatsheet">Beancount Syntax Cheatsheet</a></li>
+<li><a href="plaintext-accounting-errors.html">Don’t Sink Your First Attempts at Plaintext Accounting</a></li>
+<li><a href="quickref/">Syntax Quick Reference for the Ledger-Likes</a></li>
 </ul>
 <h4 id="concepts">concepts</h4>
 <ul>
diff --git a/index.md b/index.md
index 4b1b4f9..54b04b7 100644
--- a/index.md
+++ b/index.md
@@ -444,12 +444,10 @@ other console/curses tools
 - [Ledger manuals](http://ledger-cli.org/docs.html)
 - [Ledger wiki](https://github.com/ledger/ledger/wiki)
 - [The Great Cheatsheet for Ledger CLI](http://ricostacruz.com/cheatsheets/ledger.html)
-
 - [hledger docs](http://hledger.org/docs.html)
-
-- [Beancount docs](http://furius.ca/beancount/doc/index) (or [sphinx version with API docs](http://aumayr.github.io/beancount-docs-static/))
+- [Beancount docs](http://furius.ca/beancount/doc/index) (or [sphinx version](http://aumayr.github.io/beancount-docs-static/))
 - [Beancount Syntax Cheatsheet](http://furius.ca/beancount/doc/cheatsheet)
-
+- [Don’t Sink Your First Attempts at Plaintext Accounting](plaintext-accounting-errors.html)
 - [Syntax Quick Reference for the Ledger-Likes](quickref/)
 
 #### concepts
diff --git a/plaintext-accounting-errors.html b/plaintext-accounting-errors.html
new file mode 100644
index 0000000..2c386e3
--- /dev/null
+++ b/plaintext-accounting-errors.html
@@ -0,0 +1,104 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+
+  <!-- Basic Page Needs
+  –––––––––––––––––––––––––––––––––––––––––––––––––– -->
+  <meta charset="utf-8">
+  <title>Plain Text Accounting, a guide to Ledger and friends</title>
+  <meta name="description" content="">
+  <meta name="author" content="">
+
+  <!-- Mobile Specific Metas
+  –––––––––––––––––––––––––––––––––––––––––––––––––– -->
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+
+  <!-- FONT
+  –––––––––––––––––––––––––––––––––––––––––––––––––– -->
+  <link href="//fonts.googleapis.com/css?family=Raleway:400,300,600" rel="stylesheet" type="text/css">
+
+  <!-- CSS
+  –––––––––––––––––––––––––––––––––––––––––––––––––– -->
+  <link rel="stylesheet" href="css/normalize.css">
+  <link rel="stylesheet" href="css/skeleton.css">
+  <link rel="stylesheet" href="css/site.css">
+
+  <!-- Favicon
+  –––––––––––––––––––––––––––––––––––––––––––––––––– -->
+  <link rel="icon" type="image/png" href="images/favicon.png">
+
+</head>
+<body>
+
+  <!-- Primary Page Layout
+  –––––––––––––––––––––––––––––––––––––––––––––––––– -->
+  <div class="container">
+
+<h2 id="dont-sink-your-first-attempts-at-plaintext-accounting">Don’t Sink Your First Attempts at Plaintext Accounting</h2>
+<p>Plain text accounting programs such as Ledger and HLedger are powerful, helpful tools, but your own user errors can take the wind out of your sails when you would rather be breezing through your accounting. Here, then, are several mistakes—ones that I have personally tested—that you will want to avoid in order to enjoy the benefits of plaintext accounting without unnecessary pain.</p>
+<h3 id="preliminary-assumptions">Preliminary assumptions:</h3>
+<ul>
+<li><p>You have Ledger or Hledger already installed and running on your PC, and you are ready, or have already begun, to start entering your data.</p></li>
+<li><p>You understand that there are normally three lines of text for each transaction, and you know basically what’s supposed to go in each line.</p></li>
+</ul>
+<h3 id="formatting-can-be-critical">Formatting Can Be Critical</h3>
+<p>The following two formatting errors will cause your work to come to a screeching halt. Here’s how to avoid them.</p>
+<p>First, as you enter transactions, make sure that the second and third (and any additional) lines in a transaction are indented by at least one space. In other words, do this:</p>
+<pre class="journal"><code>2017/01/15 Acme 
+  Expenses:Household   $20.00 ;roadrunner trap
+  Liabilities:CreditCard</code></pre>
+<p>Not this:</p>
+<pre class="journal"><code>2017/01/15 Acme
+Expenses:Household   $20.00 ;roadrunner trap
+Liabilities:CreditCard</code></pre>
+<p>The above two transactions look very similar to the human eye, but the second one doesn’t work.</p>
+<p>Another formatting issue that’s easy to miss, is that you need at least two spaces between the category ”Expenses:Household,” below) and the amount of the transaction (“$20.00”):</p>
+<pre class="journal"><code>2017/01/15 Acme
+  Expenses:Household  $20.00
+  Liabilities:CreditCard</code></pre>
+<p>Contrast this with the wrong way:</p>
+<pre class="journal"><code>2017/01/15 Acme
+  Expenses:Household $20.00
+  Liabilities:CreditCard</code></pre>
+<p>As it’s very hard to see the number of spaces in the critical parts, I have written them out in the two transactions below.</p>
+<p>Correct:</p>
+<pre class="journal"><code>2017/01/15 Acme
+  Expenses:Household[space][space]$20.00
+  Liabilities:CreditCard</code></pre>
+<p>Wrong:</p>
+<pre class="journal"><code>2017/01/15 Acme
+  Expenses:Household[space]$20.00
+  Liabilities:CreditCard</code></pre>
+<p>Again, it’s easy for us humans to miss the difference between one space and two, but your plaintext accounting program will notice.</p>
+<h3 id="use-currency-symbols-consistently">Use Currency Symbols Consistently</h3>
+<p>Here’s another error that’s easy to make and easy to overlook – omitting a currency symbol. For example:</p>
+<pre class="journal"><code>2017/01/15 Acme
+  Expenses:Household   20.00
+  Liabilities:CreditCard</code></pre>
+<p>If you have been working with US dollars, it’s very easy to think that the above 20.00 refers to $20.00, but Ledger and HLedger will process this amount as something other than US dollars.</p>
+<h3 id="using-a-comma-when-you-need-a-period">Using a Comma When You Need a Period</h3>
+<p>Another mistake to avoid is inadvertently typing a comma where a decimal in required. Let’s say, for example, that you are recording the purchase of a yacht for slightly more than $1.2 million. Here is the error:</p>
+<pre class="journal"><code>2017/01/16 Mega Yacht Company
+   Expenses:Leisure   $1,245,449,72
+   Assets:Bank:Checking</code></pre>
+<p>The correct way to write this is:</p>
+<pre class="journal"><code>2017/01/16 Mega Yacht Company
+   Expenses:Leisure   $1,245,449.72
+   Assets:Bank:Checking</code></pre>
+<p>If you are using Emacs, erroneously using a comma instead of a decimal point as shown above can manifest itself as a confusing error message about no transactions that need to be cleared.</p>
+<p>Finally, the above examples assume you are using a numbering system that separates thousands with commas and integers from fractions with periods. There are systems that separate thousands with periods and that use commas to separate integers and fractions. From my reading of the documentation, both Ledger and Hledger can work with either system, but the point remains not to use a comma when you mean to use a period and vice versa.</p>
+<h3 id="summary">Summary</h3>
+<ul>
+<li><p>Indent the second and following lines of each transaction. The first line of the transaction needs to be flush left.</p></li>
+<li><p>Use two spaces after the transaction category and before the currency symbol (assuming that you are working with currency).</p></li>
+<li><p>Use the currency symbol before every amount that’s currency.</p></li>
+<li><p>Don’t use a comma when you need to write a decimal point.</p></li>
+</ul>
+<p>So, avoid the above mistakes and enjoy some clear sailing with plaintext accounting.</p>
+
+  </div>
+
+<!-- End Document
+  –––––––––––––––––––––––––––––––––––––––––––––––––– -->
+</body>
+</html>
diff --git a/plaintext-accounting-errors.md b/plaintext-accounting-errors.md
new file mode 100644
index 0000000..fe8ea71
--- /dev/null
+++ b/plaintext-accounting-errors.md
@@ -0,0 +1,113 @@
+## Don’t Sink Your First Attempts at Plaintext Accounting
+
+Plain text accounting programs such as Ledger and HLedger are powerful, helpful tools, but your own user errors can take the wind out of your sails when you would rather be breezing through your accounting. Here, then, are several mistakes—ones that I have personally tested—that you will want to avoid in order to enjoy the benefits of plaintext accounting without unnecessary pain. 
+
+### Preliminary assumptions:
+
+- You have Ledger or Hledger already installed and running on your PC, and you are ready, or have already begun, to start entering your data. 
+
+- You understand that there are normally three lines of text for each transaction, and you know basically what’s supposed to go in each line.
+
+### Formatting Can Be Critical
+
+The following two formatting errors will cause your work to come to a screeching halt. Here’s how to avoid them.
+
+First, as you enter transactions, make sure that the second and third (and any additional) lines in a transaction are indented by at least one space. In other words, do this:
+
+```journal
+2017/01/15 Acme 
+  Expenses:Household   $20.00 ;roadrunner trap
+  Liabilities:CreditCard
+```
+
+Not this:
+
+```journal
+2017/01/15 Acme
+Expenses:Household   $20.00 ;roadrunner trap
+Liabilities:CreditCard
+```
+
+The above two transactions look very similar to the human eye, but the second one doesn’t work.
+
+Another formatting issue that’s easy to miss, is that you need at least two spaces between the category ”Expenses:Household,” below) and the amount of the transaction (“$20.00”):
+
+```journal
+2017/01/15 Acme
+  Expenses:Household  $20.00
+  Liabilities:CreditCard
+```
+
+Contrast this with the wrong way:
+
+```journal
+2017/01/15 Acme
+  Expenses:Household $20.00
+  Liabilities:CreditCard
+```
+
+As it’s very hard to see the number of spaces in the critical parts, I have written them out in the two transactions below.
+
+Correct:
+
+```journal
+2017/01/15 Acme
+  Expenses:Household[space][space]$20.00
+  Liabilities:CreditCard
+```
+
+Wrong:
+
+```journal
+2017/01/15 Acme
+  Expenses:Household[space]$20.00
+  Liabilities:CreditCard
+```
+
+Again, it’s easy for us humans to miss the difference between one space and two, but your plaintext accounting program will notice.
+
+### Use Currency Symbols Consistently
+
+Here’s another error that’s easy to make and easy to overlook – omitting a currency symbol. For example:
+
+```journal
+2017/01/15 Acme
+  Expenses:Household   20.00
+  Liabilities:CreditCard
+```
+
+If you have been working with US dollars, it’s very easy to think that the above 20.00 refers to $20.00, but Ledger and HLedger will process this amount as something other than US dollars. 
+
+### Using a Comma When You Need a Period
+
+Another mistake to avoid is inadvertently typing a comma where a decimal in required. Let’s say, for example, that you are recording the purchase of a yacht for slightly more than $1.2 million. Here is the error:
+
+```journal
+2017/01/16 Mega Yacht Company
+   Expenses:Leisure   $1,245,449,72
+   Assets:Bank:Checking
+```
+
+The correct way to write this is:
+
+```journal
+2017/01/16 Mega Yacht Company
+   Expenses:Leisure   $1,245,449.72
+   Assets:Bank:Checking
+```
+
+If you are using Emacs, erroneously using a comma instead of a decimal point as shown above can manifest itself as a confusing error message about no transactions that need to be cleared.
+
+Finally, the above examples assume you are using a numbering system that separates thousands with commas and integers from fractions with periods. There are systems that separate thousands with periods and that use commas to separate integers and fractions. From my reading of the documentation, both Ledger and Hledger can work with either system, but the point remains not to use a comma when you mean to use a period and vice versa.
+
+### Summary
+
+- Indent the second and following lines of each transaction. The first line of the transaction needs to be flush left.
+
+- Use two spaces after the transaction category and before the currency symbol (assuming that you are working with currency).
+
+- Use the currency symbol before every amount that’s currency.
+
+- Don’t use a comma when you need to write a decimal point.
+
+So, avoid the above mistakes and enjoy some clear sailing with plaintext accounting.
