diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/DEVELOP.md | 81 | ||||
| -rw-r--r-- | doc/GLOSSARY.md | 154 | ||||
| -rw-r--r-- | doc/README | 64 |
3 files changed, 235 insertions, 64 deletions
diff --git a/doc/DEVELOP.md b/doc/DEVELOP.md new file mode 100644 index 00000000..e3a479d7 --- /dev/null +++ b/doc/DEVELOP.md @@ -0,0 +1,81 @@ +GLOSSARY +---- + +Developing the Ledger software uses a number different tools, not all of +which will be familiar to all developers. + +[**Boost**](http://www.boost.org): a standard set of C++ libraries. Most +Boost libraries consist of inline functions and templates in header files. + +[**Cheetah**](http://www.cheetahtemplate.org): a Python templating engine, +used by *./python/server.py*. + +[**CMake**](http://www.cmake.org): A cross platform system for building +from source code. It uses the *CMakeLists.txt* files. + +[**DOxygen**](http://doxygen.org): generates programming documentation from +source code files. Primarly used on C++ sources, but works on all. Uses +the *doc/Doxyfile.in* file. + +[**GCC**](http://gcc.gnu.org): Gnu Compiler Collection, which includes the +*gcc* compiler and *gcov* coverage/profiler tool. + +[**GMP**](https://gmplib.org): Gnu Multiple Precision Arithmetic Library +provides arbitrary precision math. + +[**Markdown**](https://daringfireball.net/projects/markdown/): A typesetter +format that produces *html* files from *.md* files. Note that GitHub +automatically renders *.md* files. + +[**sha1**](http://en.wikipedia.org/wiki/SHA-1): a marginally secure +cryptographic hash function, used only for signing the license file. + +[**Texinfo**](http://www.gnu.org/software/texinfo/): Gnu documentation +typesetter that produces *html* and *pdf* files from the *doc/\*.texi* +files. + +[**Travis CI**](https://travis-ci.org): a hosted continuous integration + service that builds and runs tests each commit posted to GitHub. Each + build creates a [log](https://travis-ci.org/ledger/ledger), updates a + [small graphic](https://travis-ci.org/ledger/ledger.png?branch=master) at + the top left of the main project's + [README.md](https://github.com/ledger/ledger/blob/master/README.md), and + emails the author of the commit if any tests fail. + +[**utfcpp**](http://utfcpp.sourceforge.net): a library for handling utf-8 +in a variety of C++ versions. + + +Orientation +--- + +The source tree can be confusing to a new developer. Here is a selective +orientation: + +**./acprep**: a custom thousand-line script to install dependencies, grab + updates, and build. It also creates *\*.cmake*, + *./CmakeFiles/* and other CMake temporary files. Use *./acprep --help* + for more information. + +**./README.md**: user readme file in markdown format, also used as the project + discription on GitHub. + +**./contrib/**: contributed scripts of random quality and completion. They + usually require editing to run. + +**./doc/**: documentation, licenses, and + tools for generating documents such as the *pdf* manual. + +**./lib/**: a couple libraries used in development. + +**./lisp/**: the [Emacs](http://www.gnu.org/software/emacs/) + [ledger-mode](http://ledger-cli.org/3.0/doc/ledger-mode.html) lisp code, + under the [GPLv2](http://www.gnu.org/licenses/gpl-2.0.html) license. + +**./python/**: samples using the Python ledger module. + +**./src/**: the C++ header and source files in a flat directory. + +**./test/**: a testing harness with subdirectories full of tests + +**./tools/**: an accretion of tools, mostly small scripts, to aid development diff --git a/doc/GLOSSARY.md b/doc/GLOSSARY.md new file mode 100644 index 00000000..5d3263d0 --- /dev/null +++ b/doc/GLOSSARY.md @@ -0,0 +1,154 @@ +ACCOUNTING GLOSSARY +--- + + Accounting and bookkeeping represent an entire field of human effort and + has evolved its own specialized vocabulary. Accounting hopes to + summarize and add understanding to where the money is going. + +**Account**: A category for grouping together amounts from similar + transactions. Each account has a name, which is usually capitalized, and + an account type. Accounts are often organized into a heirarchy when it + helps understanding. For example, a coffee shop might have Coffee, + Merchandise, and Equipment as accounts but arranged under an Inventory + account because different decisions are made on the total inventory + rather than just coffee. A heirarchy can be part of the account name in + Ledger, e.g., "Assets:Inventory:Coffee". Note that the Ledger software + usually creates the list of accounts on the fly: accounts are created + when transactions use them. + +**Account Type**: Each account has a type of Asset, Liability, Equity, + Income, or Expense. Assets represent something owned, e.g., Cash or + Inventory. Liabilities represent sometime owed, e.g., a Loan or + Mortgage. Equity, also called capital, is everything owned minus + everything owed (Assets - Liabilities). It is the financial measure of + how much you are ahead. Income is money earned somewhere, which puts you + more ahead. Expenses is money spent somewhere, which puts you less + ahead. The type of account determines if a debit represents an increase + or decrease in an account. For example, Inventory is an asset so a + transcation debiting Inventory would increase its value. Assets and + Expenses increase with debits and decrease with credits; Liabilities, + Equity, and Expenses increase with credits and decrease with debits. + +**Journal**: A record of all the financial transactions of a person or + firm. This data of where money goes can be collated into reports. This + used to be done with a physical book, called a ledger, where each account + was on one page. Each debit or credit in the journal was transfered to + the appropriate account page and the pages were totalled to produce + reports. This process is now done with the Ledger software which creates + reports from the journal. A journal is sometimes called a register. + +**Posting**: A single debit or credit line of a transaction. A posting +comprises an account and the debit or credit amount. It also inherits the +shared description and date from the transaction. In the Ledger software, +a posting may also have metadata and an account state. + + +**Report**: A summary made from a journal of transactions. Each + transaction affects accounts and those effects are collated and totaled. + The two most common reports are the balance sheet, which shows what is + owned and owed on a specific date, and the cash flow statement, which + shows how money was earned and spent over a period. The cash flow + statement is also called a profit and loss statement or an income + statement. + +**Transaction**: Our financial lives are recorded as a series of + transactions. Each transaction has a specific date, an equal total of + debits and credits affecting accounts, and some sort of description. For + example, "On January 1, pay $100 with check #243 from Checking to + Utilities for my Verizon phone bill" is a transaction. A credit of $100 + decreases my Checking asset, while a balancing debit of $100 increases my + Utility expense. A transaction needs at least two *postings*, meaning + account debits or credits, but can be as complicated as humans can make + finances. + +LEDGER GLOSSARY +--- + +The Ledger software also has its own terms. + +**Automated Transaction**: a command directive that modifies subsequent + transactions that match an expression. An automated transaction can add + additional postings to a transaction, add metadata, or change transaction + amounts. Reports can be filter postings modified or generated by an automated + transaction. + [§ Automated Transactions](http://www.ledger-cli.org/3.0/doc/ledger3.html#Automated-Transactions); + [§ Concrete Example of Automated Transactions](http://www.ledger-cli.org/3.0/doc/ledger3.html#Concrete-Example-of-Automated-Transactions) + +**Command Directive**: a command in a journal file to change how subsequent +lines and transactions in a journal file are processed. Command directives +control processing, set default values for subsequent accounts and +transactions, or override parts of subsequent transactions. A directive +line begins with name of the directive and may have addidtional arguments +or additional indented lines. The single letters *AbCDhIiNOoY* are aliased +to other command directives, providing compatiblity with the ancient past. +The characters **'='** and **'-'** are command directives for a automatic +transactions and periodic transactions, respectively. +[§ Command Directives](http://www.ledger-cli.org/3.0/doc/ledger3.html#Command-Directives) + +**Commodity**: any currency, stock, time or resource to be tracked + numerically. While many people only track money in Ledger, Ledger can + track different resources and manage rules to convert between them. The + system is flexible enough for the needs of very different users. Some + track billable time, converting minutes and hours into dollars. Others + track multiple currencies. Still others track the purchase and sale of + stocks. Each commodity is seperate unless a conversion rule is given. + [§ Commodities and Currencies](http://www.ledger-cli.org/3.0/doc/ledger3.html#Commodities-and-Currencies); + [§ Currencies and Commodities](http://www.ledger-cli.org/3.0/doc/ledger3.html#Currency-and-Commodities); + [§ Accounts and Inventories](http://www.ledger-cli.org/3.0/doc/ledger3.html#Accounts-and-Inventories); + [§ Posting Cost](http://www.ledger-cli.org/3.0/doc/ledger3.html#Posting-cost) + *(and next ten sections)*; + [§ Commodity Reporting](http://www.ledger-cli.org/3.0/doc/ledger3.html#Commodity-Reporting) + +**Effective Date**: an optional, second date information item in for a +posting or transaction. Some use the effective date for when work is +billed or when a check has cleared. The `--effective-date` option causes +the effective date to override the transaction's initial date for that +report. +[§ Effective Dates](http://www.ledger-cli.org/3.0/doc/ledger3.html#Effective-Dates); + +**Journal File**: the text input file for ledger, sometimes called a +register file. A journal file is a series of transactions, command +directives, and comments. Command directives start with the single word +name of the directive at the beginning of the line and include any +following indented lines. Transactions start with a date a the beginning +of the line and include any indented lines following. The journal file is +expected to be encoded as ASCII or utf-8 text. + +**Periodic Transaction**: the estimate of a transaction that would occur + periodically, e.g., a monthly expense. These estimates are only used in + budgeting and forecasting reports using the `--budget`, + `--forecast`, or `--unbudgeted` options. + [§ Budgeting and Forecasting](http://www.ledger-cli.org/3.0/doc/ledger3.html#Budgeting-and-Forecasting) + +**Transaction Code**: an optional item in a transaction or posting often + used to record a check number or bank code. Certain custom reports can + report this code. + [§ Codes](http://www.ledger-cli.org/3.0/doc/ledger3.html#Codes); + [§ Format Expressions](http://www.ledger-cli.org/3.0/doc/ledger3.html#Format-Expressions) + +**Transaction Metadata**: a term for comments and tags annotating a +transaction. Comments indented with a transaction will be stored with each +posting of a transaction. Tags are words in comments followed by colons. +Tags can be used as filters in reports and certain tags, "Payee" or +"Value", may affect fields of the transaction. +[§ Metadata](http://www.ledger-cli.org/3.0/doc/ledger3.html#Metadata), +[§ Applying Metadata to every matched posting](http://www.ledger-cli.org/3.0/doc/ledger3.html#Applying-metadata-to-every-matched-posting), +[§ Applying Metadata to the generated posting](http://www.ledger-cli.org/3.0/doc/ledger3.html#Applying-metadata-to-the-generated-posting) + +**Transaction State**: a state of *cleared*, *pending*, or *uncleared* on +each posting. The state is usually set for an entire transaction at once +with a mark after the date. The marks are ***** (cleared), **!** +(pending), or no mark (uncleared). The interpretation of this state is up +to the user, but is typically used in bank reconcilations or +differentiating time worked versus billed. Ledger supports reports and +filters based on state. +[§ Transaction State](http://www.ledger-cli.org/3.0/doc/ledger3.html#Transaction-state); +[§ Cleared Report]( +http://www.ledger-cli.org/3.0/doc/ledger3.html#Cleared-Report) + +**Virtual Posting**: an annotation posting in a transaction, similar in form as a regular posting but not required to balance debits and +credits. It is often used to support +[Fund Accounting](http://en.wikipedia.org/wiki/Fund_accounting) and various reports will collate and summarize virtual postings. Virtual postings should not be +confused with virtual posting costs. +[§ Virtual Postings](http://www.ledger-cli.org/3.0/doc/ledger3.html#Virtual-postings) +[§ Working with Multiple Funds and Accounts](http://www.ledger-cli.org/3.0/doc/ledger3.html#Working-with-multiple-funds-and-accounts) diff --git a/doc/README b/doc/README deleted file mode 100644 index 190436a2..00000000 --- a/doc/README +++ /dev/null @@ -1,64 +0,0 @@ - - Welcome to Ledger - - the command-line accounting program - -Introduction -============ - -Ledger is an accounting program which is invoked from the command-line using a -textual ledger file. To start using Ledger, you will need to create such a -file containing your financial postings. A sample has been provided in the -file "sample.dat". See the documentation (ledger.pdf, or ledger.info) for -full documentation on creating a ledger file and using Ledger to generate -reports. - -Once you have such a file -- you might call it "ledger.dat" -- you can start -looking at balances and account registers using commands like the following: - - ledger -f ledger.dat balance assets:checking - ledger -f ledger.dat register expenses:food - -This assumes, of course, that like the sample file you use account names such -as "Assets:Checking" and "Expenses:Food". If you use other account names, you -will need to vary the reporting commands you use accordingly. - - -Building -======== - -To build Ledger, you will need a fairly modern C++ compiler (gcc 2.95 will not -work), and at least these two libraries installed: - - gmp GNU multi-precision library - pcre Perl regular expression library - -(On some GNU/Linux systems, the packages you need to install are called -"gmp-dev" and "pcre-dev"). - -Once you have determined where the headers and libraries for the above -packages are installed, run the script "configure", passing those paths. If -you installed everything under /usr/local, you can probably just type -"./configure". Otherwise, do this: - - ./configure CPPFLAGS=-I<INCLUDE-PATH> LDFLAGS=-L<LIBRARY-PATH> - -If you need to specify multiple include or library paths, then do this: - - ./configure CPPFLAGS="-I<PATH1> -I<PATH2>" LDFLAGS="-L<PATH1> -L<PATH2>" - -Once configure is done running, just type: - - make install - - -Mailing List and IRC -==================== - -If you need help on how to use Ledger, or run into problems, you can join the -Ledger mailing list at the following Web address: - - http://groups.google.com/group/ledger-cli - -You can also find help at the #ledger channel on the IRC server -irc.freenode.net. |