dklrt/dklrt.texi

\input texinfo @c -*-texinfo-*-

@c %**start of header
@setfilename dklrt.info
@settitle Ledger Recurring Transactions 1.0
@c %**end of header

@syncodeindex fn cp
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex vr cp

@c Before release, run C-u C-c C-u C-a
@c (texinfo-all-menus-update with a prefix arg). This
@c updates the node pointers, which texinfmt.el needs.

@copying
This manual is for emacs package dklrt version 1.0.

Copyright @copyright{} 2010–2013 David Keegan.

May be redistributed under the terms of the Free Software
Foundation GNU Free Documentation Licence.
@end copying

@dircategory Emacs misc features
@direntry
* Ledger Recurring Transactions: (dklrt).
@end direntry

@documentencoding UTF-8

@iftex
@finalout
@end iftex

@macro dkcmditem{key, key2, command}
@item @kbd{\key\}@tie{} (@kbd{\key2\}) (@code{\command\})
@end macro

@macro dkcmd{key, key2, command}
@kbd{\key\}@tie{} (@kbd{\key2\}) (@code{\command\})
@end macro

@macro dkcmdidx{key, key2, command}
@kindex \key\
@kindex \key2\
@findex \command\
@kbd{\key\}@tie{} (@kbd{\key2\}) (@code{\command\})
@end macro

@macro dktag{text}
@samp{\text\}
@end macro

@titlepage
@title Ledger Recurring Transactions 1.0
@author David Keegan
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents

@ifnottex
@node Top
@top Ledger Recurring Transactions
@end ifnottex

An add-on to ledger-mode which appends recurring
transactions to the current ledger file, usually on entry to
ledger-mode. Recurring transactions are configured in a
separate file which conforms to ledger file format and
resides in the same directory as the ledger file.

@menu
* Introduction::
* Configuration File::
* Operations::
* Index::
@end menu

@node Introduction
@chapter Introduction

@menu
* Overview::
* Getting Started::
* Known Issues::
* History::
@end menu

@node Overview
@section Overview

@cindex recurring transactions
@cindex transactions, recurring
@pindex ledger
Recurring transactions are accounting transactions that
repeat at regular intervals such as paychecks, standing
orders, and pension contributions. This emacs package
appends recurring transactions to a ledger file, the input
file for John Wiegley's ledger program. @xref{Top,,
Overview, ledger3, Ledger: Command-Line Accounting}.

@findex @code{ledger-mode}
An add-on to emacs ledger-mode, the package appends
recurring transactions to the current ledger file, usually
on entry to @code{ledger-mode}. @xref{Top,,Overview,
ledger-mode, Ledger Mode}.

@cindex configuration file
Recurring transactions are configured in a separate file
which conforms to ledger file format, and resides in the
same directory as the ledger file. @xref{Configuration File}.

@node Getting Started
@section Getting Started

@findex @code{dklrt-AppendRecurringMaybe}
To append recurring transactions automatically on entry to
@code{ledger-mode}, add this line to your emacs profile:

@lisp
 (add-hook 'ledger-mode-hook 'dklrt-AppendRecurringMaybe)
@end lisp

To bind @kbd{\C-cr} to @code{dklrt-AppendRecurringMaybe} while in
@code{ledger-mode} only, add this line to your emacs profile
(optional):

@findex @code{dklrt-SetCcKeys}
@lisp
(add-hook 'ledger-mode-hook 'dklrt-SetCcKeys)
@end lisp

@vindex @code{dklrt-SortAfterAppend}
If you want to have recurring transactions positioned by date in
the ledger file, add this line to your emacs profile (optional):

(setq dklrt-SortAfterAppend t)

Note that as this causes the whole ledger buffer to be
sorted after transactions are appended, it affects the
positions of all transactions.

@node Known Issues
@section Known Issues

@cindex issues
@cindex limitations
@enumerate
@item
In the configuration file, a transaction date must be
expressed in ISO format, eg ``YYYY-MM-DD'' or
``YYYY/MM/DD''. This format is preserved when the
transaction is appended to the ledger file. It is compatible
with ledger's default date format, and should work with
@code{ledger-mode}.

Problems can be expected if --input-date-format has been
configured with a non-ISO format in the ledger init file
(.ledgerrc) or on the ledger command line.
@xref{Configuration File}.

@vindex @code{dklrt-PythonProgram}
@item
Depends on some python code which is included in the package
(and requires that python is installed on the system). The
python program is customisable via variable
@code{dklrt-PythonProgram}.
@end enumerate

@node History
@section History

This package was developed between 2011-06-08 and 2011-08-17.

@node Configuration File
@chapter Configuration File

@cindex configuration file
@cindex file, configuration
@vindex @code{dklrt-RecurringConfigFileSuffix}
Recurring transactions for a particular ledger file are
configured in a separate file. The configuration file is in
the same directory as the ledger file, and its filename is
the same as that of the ledger file except that the ledger
file suffix is replaced by @file{.rec}. The suffix is
customisable via variable
@code{dklrt-RecurringConfigFileSuffix}.

@menu
* Format::
* Date and Period::
* Restrictions::
@end menu

@node Format
@section Format

The configuration file contains one or more transactions in
ledger file format. For example:

@smallformat
@verbatim

2013-11-10 (1m) Payee Details
    ; Transaction Note.
    Asset:Bank:Current                       €-10.00  ; [=2013-11-08]
    Expense:Phone                             €10.00  ; Payee: Eircom.
    (Asset:OwedBy:Partner)                    €10.00
    ; Posting Note2.

2013-12-01 (1w) Payee8
    Asset:Bank:Savings                       €200.00
    Expense:SavingPlan

@end verbatim
@end smallformat

Each transaction date is followed by a repetition period
in the position normally occupied by a ledger transaction
code.

A transaction is considered to begin with a transaction date
at the beginning of a line, and includes the remainder of
the line and all subsequent lines up to but excluding the
next transaction date. The transaction date in the
configuration file controls when the transaction becomes due
for appending to the ledger file, and is the actual
transaction date once appended.

@node Date and Period
@section Date and Period

@cindex transaction date
@cindex date, transaction
The transaction date must be in ISO format: ``YYYY-MM-DD''
or ``YYYY/MM/DD''. It occurs at the beginning of a line and
marks the start of a transaction (and the end of the
previous transaction, if any).

@cindex repetition period
@cindex repetition interval
@cindex period, repetition
@cindex interval, repetition
A parenthesised transaction repetition period must follow
the date in the position where a ledger transaction ``code''
would normally occur. It is surrounded by whitespace and is
in the following format:

@verbatim
(<Count><Unit>)
@end verbatim

Where:

@table @code
@item Count
An unsigned decimal integer.

@item Unit
A single character from the following: y (year), m (month) w
(week), d (day), specifying the period unit and following
immediately after the Count integer without intervening
space.
@end table

@node Restrictions
@section Restrictions

@cindex restrictions, configuration file
The recurring transactions configuration file must not
contain any of the following ledger constructs:

@enumerate
@item
Stand-alone comment (ie not part of a transaction).

@item
Historical commodity price (starts with ``P'').

@item
Automated transaction (starts with ``='').

@item
Period transaction (starts with ``~'').

@item
Command directive.
@end enumerate

@cindex restrictions, transaction date/payee line
In addition the following restrictions apply to the the
initial (date/payee) line of each transaction:

@enumerate
@item
The transaction date must @emph{not} have an effective/auxiliary
date suffix (of the form ``=YYYY-MM-DD'').

@item
A transaction state/clear flag (immediately after the date)
is @emph{not} permitted.
@end enumerate

@node Operations
@chapter Operations

@findex @code{dklrt-AppendRecurringMaybe}
The main entry point is function
@code{dklrt-AppendRecurringMaybe}. This is normally
configured to run automatically on entry to
@code{ledger-mode}. It can also be bound to a key
(@kbd{\C-cr} is suggested).

@cindex append pre-conditions
@cindex pre-conditions, append
Function @code{dklrt-AppendRecurringMaybe} does nothing
unless all the following conditions are met:

@enumerate

@item
The current buffer is in @code{ledger-mode}.

@item
The current buffer is unmodified.

@item
The file associated with the current buffer exists.

@item
The current file is @emph{not} a recurring transaction config file
(ie does not have suffix @file{.rec}).

@item
A recurring transaction config file exists for the current
ledger file (same directory and basename, but with suffix
@file{.rec}).

@end enumerate

If all the conditions are met, recurring transactions are
read from the config file and their dates are compared with
the current date.

@cindex appended transaction
@cindex transaction, appended
If a transaction is considered ``due'', it is appended to
the ledger file. The append includes the full transaction
text as it appears in the configuration file, except that
the repetition period (including enclosing parentheses) is
removed.

Once a recurring transaction has been appended to the ledger
file, the transaction date is shifted forward by the
repetition period to the date of the next append and written
back to the configuration file. @xref{Configuration File}.

@cindex append due time
@cindex due time, append
@vindex @code{dklrt-AppendBefore}
By default, a recurring transaction becomes due up to one
day before its current transaction date. This is
customisable via variable @code{dklrt-AppendBefore}.

@cindex sort transactions
@vindex @code{dklrt-SortAfterAppend}
After recurring transactions have been appended, the ledger
file can optionally be sorted to keep transactions ordered
by date. This behaviour is customisable via variable
@code{dklrt-SortAfterAppend}.

@node Index
@chapter Index
@printindex cp

@bye