From a4a10fc7b0acd0e2af37f92e9bbacefa5e39b480 Mon Sep 17 00:00:00 2001
From: "Bradley M. Kuhn" <bkuhn@ebb.org>
Date: Mon, 29 Apr 2013 19:55:07 -0400
Subject: [PATCH] Initial documentation of the Program: tag. Includes
introduction of the section about making use of these tags.
---
accounts/config/config-accounts.ledger | 2 +-
accounts/config/config-tags.ledger | 8 +++++++
accounts/org/main-org.ledger | 4 ++++
npo-ledger-cli-tutorial.md | 32 ++++++++++++++++++++++++++
4 files changed, 45 insertions(+), 1 deletion(-)
diff --git a/accounts/config/config-accounts.ledger b/accounts/config/config-accounts.ledger
index 34b269f..c51cf3a 100644
--- a/accounts/config/config-accounts.ledger
+++ b/accounts/config/config-accounts.ledger
@@ -41,7 +41,7 @@ account Accrued:Accounts Receivable:Main Org
; to the assert in ever Expense account because of the following bug:
; http://bugs.ledger-cli.org/show_bug.cgi?id=953
-define expenseChecker() = (tag("Receipt") !~ /^\s*$/ or tag("Invoice") !~ /^\s*$/ or tag("Statement") !~ /^\s*$/)
+define expenseChecker() = (tag("Receipt") !~ /^\s*$/ or tag("Invoice") !~ /^\s*$/ or tag("Statement") !~ /^\s*$/) and tag("Program") !~ /^\s*$/
; or payee =~ /NEVER CHARGED/
account Expense:Main Org:Office Supplies
diff --git a/accounts/config/config-tags.ledger b/accounts/config/config-tags.ledger
index d222b78..f017131 100644
--- a/accounts/config/config-tags.ledger
+++ b/accounts/config/config-tags.ledger
@@ -39,3 +39,11 @@ tag Invoice
tag IncomeType
assert value =~ /^(Donations|RBI|UBTI)$/
+
+; Program tag must match the general format of a ledger account as an
+; assertion, but we at least check known names of programs, so that warnings
+; are produced if a new program never seen before is encountered.
+
+tag Program
+ assert value =~ /[ A-z0-9\-]+(:[ A-z0-9\-]+)*/
+ check value =~ /^(Main Org:(Overhead|Direct Fundraising))$/
diff --git a/accounts/org/main-org.ledger b/accounts/org/main-org.ledger
index 18e22a4..94d4ac6 100644
--- a/accounts/org/main-org.ledger
+++ b/accounts/org/main-org.ledger
@@ -6,15 +6,18 @@
2012-02-05 Office Supply Galore - Online Order
;Receipt: accounts/documentation/org/receipts/2012-02-05_office-supply-galore.txt
Expense:Main Org:Office Supplies $35.00
+ ;Program: Main Org:Overhead
Liabilities:Credit Card:Visa -$35.00
2011/05/28 My Bad Billing Hosting - NEVER CHARGED
Liabilities:Credit Card:Visa $-100.00
Expense:Main Org:Hosting $100.00
+ ;Program: Main Org:Overhead
2012/01/01 My Bad Billing Hosting - REVERSAL - NEVER CHARGED
Liabilities:Credit Card:Visa $100.00
Expense:Main Org:Hosting $-100.00
+ ;Program: Main Org:Overhead
2012-05-03 Sir Moneybags
;Entity: Sir-Moneybags
@@ -22,3 +25,4 @@
Accrued:Accounts Receivable:Main Org $100,000.00
Income:Main Org:Donations $-100,000.00
;IncomeType: Donations
+ ;Program: Main Org:Direct Fundraising
diff --git a/npo-ledger-cli-tutorial.md b/npo-ledger-cli-tutorial.md
index 35ea4f5..d808d0e 100644
--- a/npo-ledger-cli-tutorial.md
+++ b/npo-ledger-cli-tutorial.md
@@ -261,6 +261,18 @@ relatively simple change to `config-tags.ledger`, though, to support other
income types, or to change it entirely to handle use-cases other than USA
Form 990 filing.
+#### Program Tag
+
+The `Program` tag is used primarily to track program activity for `Income:`
+and `Expense:` accounts. This allows for knowing what particular initiative
+initiated the income (e.g., a specific fundraising campaign) and/or what
+particular program activity an expense is toward (e.g., funding travel to
+some specific conference).
+
+The Program tag is always a string with the same format as a Ledger CLI
+account (primarily for use with Ledger CLI's `--pivot` and `--group-by`,
+[as described later](#testing-program-success).
+
### Expense Account Documentation
Each Expense account entries need to be tagged with an
@@ -312,6 +324,26 @@ However, going forward, you'd likely never enter anything the ledger
the Expense did/should occur. This use of `NEVER CHARGED` in the payee is
thus deprecated.
+Analysis of the Data
+--------------------
+
+If this methodology is followed, Ledger can be used to analyze the financial
+data for the organization.
+
+### Testing Program Success
+
+If you use the [`Program`](#program-tag) tag effectively, you can easily test
+the successes of various fundraising programs with a command like this:
+
+ $ ledger -f accounts/books.ledger --pivot Program bal '/^Income/'
+
+Meanwhile, using the [`Program`](#program-tag) tag for Expenses can help
+track what programs are costing with commands like hese:
+
+ $ ledger -f accounts/books.ledger --group-by 'tag("Program")' reg '/^Expense/'
+
+FIXME: example output
+
Copyright and License of This File
----------------------------------