Restructured customization groups. Completed initial draft of ledger-mode documentation

This commit is contained in:
Craig Earls 2013-02-27 17:27:52 -07:00
parent 3db3d23765
commit 42911df9f5
10 changed files with 232 additions and 68 deletions

View file

@ -72,7 +72,9 @@ reports and much more...
* The Ledger Buffer::
* The Reconcile Buffer::
* The Report Buffer::
* Installing and Customizing Ledger-mode::
* Customizing Ledger-mode::
* Generating Ledger Regression Tests::
* Embedding Example results in Ledger Documentation::
* Hacking Ledger-mode::
@end menu
@ -83,12 +85,12 @@ reports and much more...
@node Introduction to Ledger Mode, The Ledger Buffer, Copying, Top
@chapter Introduction to Ledger Mode
@menu
* Quick installation::
* Quick Installation::
* Menus::
* Quick Demo::
@end menu
@node Quick installation, Menus, Introduction to Ledger Mode, Introduction to Ledger Mode
@node Quick Installation, Menus, Introduction to Ledger Mode, Introduction to Ledger Mode
@section Quick Installation
The emacs lisp source for Ledger-mode is included with the source
@ -107,7 +109,7 @@ This sets up Emacs to automatically recognize files that end with
@file{.ledger} and start Ledger mode. Nothing else should be required
as long as the ledger command line utility is properly installed.
@node Menus, Quick Demo, Quick installation, Introduction to Ledger Mode
@node Menus, Quick Demo, Quick Installation, Introduction to Ledger Mode
@section Menus
The vast majority of Ledger-mode functionality is available from the
@ -225,6 +227,12 @@ payees and accounts. Included files are not currently included in the
completion scan. Repeatedly hitting @code{TAB} will cycle through the
possible completions.
Ledger mode can also help you keep your amounts in alignment. Setting
@code{ledger-post-auto-adjust-amounts} to true tells Ledger-mode to
automatically place any amounts such that their last digit is aligned to
the column specified by @code{ledger-post-amount-alignment-column},
which defautls to 52. @xref{Ledger Post Customization Group}
@node Editing Amounts, Marking Transactions, Adding Transactions, The Ledger Buffer
@section Editing Amounts
GNU Calc is a very powerful Reverse Polish Notation calculator built
@ -439,7 +447,7 @@ If for some reason during reconciliation your target amount changes,
type @code{t} and enter the new target value.
@node The Report Buffer, Installing and Customizing Ledger-mode, The Reconcile Buffer, Top
@node The Report Buffer, Customizing Ledger-mode, The Reconcile Buffer, Top
@chapter The Report Buffer
@menu
* Running Basic Reports::
@ -552,36 +560,177 @@ it will reverse the order of the transactions and maintain the proper
mathematical sense.
@node Installing and Customizing Ledger-mode, Hacking Ledger-mode, The Report Buffer, Top
@chapter Installing and Customizing Ledger-mode
@node Customizing Ledger-mode, Generating Ledger Regression Tests, The Report Buffer, Top
@chapter Customizing Ledger-mode
@menu
* Emacs Initialization File::
* Ledger-mode Customization::
* Customization Variables::
* Ledger-mode Faces::
@end menu
@node Emacs Initialization File, Ledger-mode Customization, Installing and Customizing Ledger-mode, Installing and Customizing Ledger-mode
@section Emacs Initialization File
@node Ledger-mode Customization, Ledger-mode Faces, Emacs Initialization File, Installing and Customizing Ledger-mode
@node Ledger-mode Customization, Customization Variables, Customizing Ledger-mode, Customizing Ledger-mode
@section Ledger-mode Customization
@node Customization Variables, , Ledger-mode Customization, Installing and Customizing Ledger-mode
Ledger-mode has several options available for configuration. All
options can be configure through the Emacs customization menus, or
specified in your Emacs initialization file. The complete list of
options is show below. To change the option using the Emacs
customization menu, simply choe customize in the Options menu and look
for Ledger under the data options. Alternately you can choose
``Customize Specific Group'' and enger ``Ledger'' as the group.
@node Customization Variables, , Ledger-mode Customization, Customizing Ledger-mode
@section Customization Variables
@node Ledger-mode Faces, , Customization Variables, Installing and Customizing Ledger-mode
@section Ledger-mode Faces
@menu
* Using EMACS customization menus::
* Complete list of customization variables::
* Ledger Customization Group::
* Ledger Reconcile Customization Group::
* Ledger Report Customization Group::
* Ledger Faces Customization Group::
* Ledger Post Customization Group::
* Ledger Exec Customization Group::
* Ledger Test Customization Group::
* Ledger Texi Customization Group::
@end menu
@node Using EMACS customization menus, Complete list of customization variables, Ledger-mode Faces, Ledger-mode Faces
@subsection Using EMACS customization menus
@node Ledger Customization Group, Ledger Reconcile Customization Group, Customization Variables, Customization Variables
@subsection Ledger Customization Group
@table @code
@item ledger-default-acct-transaction-indent
Default indentation for account transactions in an entry.
@item ledger-occur-use-face-unfolded
If non-nil use a custom face for xacts shown in `ledger-occur' mode using @code{ledger-occur-xact-face}.
@item ledger-clear-whole-transactions
If non-nil, clear whole transactions, not individual postings.
@item ledger-highlight-xact-under-point
If non-nil highlight xact under point using @code{ledger-font-highlight-face}.
@end table
@node Complete list of customization variables, , Using EMACS customization menus, Ledger-mode Faces
@subsection Complete list of customization variables
@node Ledger Reconcile Customization Group, Ledger Report Customization Group, Ledger Customization Group, Customization Variables
@subsection Ledger Reconcile Customization Group
@node Hacking Ledger-mode, , Installing and Customizing Ledger-mode, Top
@table @code
@item ledger-reconcile-default-commodity
The default commodity for use in target calculations in ledger
reconcile. Defaults to $ (USD)
@item ledger-recon-buffer-name
Name to use for reconciliation window.
@item ledger-fold-on-reconcile
If non-nil, limit transactions shown in main buffer to those matching the
reconcile regex.
@item ledger-buffer-tracks-reconcile-buffer
If non-nil, then when the cursor is moved to a new xact in the recon
window.
@item ledger-reconcile-force-window-bottom
If non-nil, make the reconcile window appear along the bottom of the
register window and resize.
@item ledger-reconcile-toggle-to-pending
If non-nil, then toggle between uncleared and pending (@code{!}). If false
toggle between unlceared and cleared (@code{*})
@end table
@node Ledger Report Customization Group, Ledger Faces Customization Group, Ledger Reconcile Customization Group, Customization Variables
@subsection Ledger Report Customization Group
@table @code
@item ledger-reports
Definition of reports to run.
@item ledger-report-format-specifiers
An alist mapping ledger report format specifiers to implementing functions.
@end table
@node Ledger Faces Customization Group, Ledger Post Customization Group, Ledger Report Customization Group, Customization Variables
@subsection Ledger Faces Customization Group
Ledger Faces : Ledger mode highlighting
@table @code
@item ledger-font-uncleared-face
Default face for Ledger
@item ledger-font-cleared-face
Default face for cleared (*) transactions
@item ledger-font-highlight-face
Default face for transaction under point
@item ledger-font-pending-face
Default face for pending (!) transactions
@item ledger-font-other-face
Default face for other transactions
@item ledger-font-posting-account-face
Face for Ledger accounts
@item ledger-font-posting-amount-face
Face for Ledger amounts
@item ledger-occur-folded-face
Default face for Ledger occur mode hidden transactions
@item ledger-occur-xact-face
Default face for Ledger occur mode shown transactions
@item ledger-font-comment-face
Face for Ledger comments
@item ledger-font-reconciler-uncleared-face
Default face for uncleared transactions in the reconcile window
@item ledger-font-reconciler-cleared-face
Default face for cleared (*) transactions in the reconcile window
@item ledger-font-reconciler-pending-face
Default face for pending (!) transactions in the reconcile window
@item ledger-font-report-clickable-face
Default face for pending (!) transactions in the reconcile window
@end table
@node Ledger Post Customization Group, Ledger Exec Customization Group, Ledger Faces Customization Group, Customization Variables
@subsection Ledger Post Customization Group
Ledger Post :
@table @code
@item ledger-post-auto-adjust-amounts
If non-nil, then automatically align amounts to column specified in
@code{ledger-post-amount-alignment-column}
@item ledger-post-amount-alignment-column
The column Ledger-mode uses to align amounts
@item ledger-post-use-completion-engine
Which completion engine to use, iswitchb, ido, or built-in
@item ledger-post-use-ido
@end table
@node Ledger Exec Customization Group, Ledger Test Customization Group, Ledger Post Customization Group, Customization Variables
@subsection Ledger Exec Customization Group
Ledger Exec : Interface to the Ledger command-line accounting program.
@table @code
@item ledger-binary-path
Path to the ledger executable.
@item ledger-init-file-name
Location of the ledger initialization file. nil if you don't have one
@end table
@node Ledger Test Customization Group, Ledger Texi Customization Group, Ledger Exec Customization Group, Customization Variables
@subsection Ledger Test Customization Group
@table @code
@item ledger-source-directory
Directory where the Ledger sources are located.
@item ledger-test-binary
Directory where the debug binary.
@end table
@node Ledger Texi Customization Group, , Ledger Test Customization Group, Customization Variables
@subsection Ledger Texi Customization Group
@table @code
@item ledger-texi-sample-doc-path
Location for sample data to be used in texi tests, defaults to @file{~/ledger/doc/sample.dat}
@item ledger-texi-normalization-args
texi normalization for producing ledger output, defaults to ``@code{--args-only --columns 80}''
@end table
@node Generating Ledger Regression Tests, Embedding Example results in Ledger Documentation, Customizing Ledger-mode, Top
@chapter Generating Ledger Regression Tests
Work in Progress.
@node Embedding Example results in Ledger Documentation, Hacking Ledger-mode, Generating Ledger Regression Tests, Top
@chapter Embedding Example results in Ledger Documentation
Work in Progress.
@node Hacking Ledger-mode, , Embedding Example results in Ledger Documentation, Top
@chapter Hacking Ledger-mode
Work in Progress.
@bye

View file

@ -29,13 +29,7 @@
(defcustom ledger-reconcile-default-commodity "$"
"The default commodity for use in target calculations in ledger reconcile."
:type 'string
:group 'ledger)
(defcustom ledger-use-decimal-comma nil
"If non-nil the use commas as decimal separator.
This only has effect interfacing to calc mode in edit amount"
:type 'boolean
:group 'ledger)
:group 'ledger-reconcile)
(defun ledger-split-commodity-string (str)
"Split a commoditized amount into two parts"

View file

@ -38,7 +38,7 @@
(defcustom ledger-binary-path "ledger"
"Path to the ledger executable."
:type 'file
:group 'ledger)
:group 'ledger-exec)
(defun ledger-exec-ledger (input-buffer &optional output-buffer &rest args)
"Run Ledger using INPUT-BUFFER and optionally capturing output in OUTPUT-BUFFER with ARGS."

View file

@ -24,7 +24,7 @@
(defcustom ledger-init-file-name "~/.ledgerrc"
"Location of the ledger initialization file. nil if you don't have one"
:group 'ledger)
:group 'ledger-exec)
(defvar ledger-environment-alist nil)

View file

@ -35,7 +35,7 @@
(defconst ledger-occur-overlay-property-name 'ledger-occur-custom-buffer-grep)
(defcustom ledger-occur-use-face-unfolded t
"If non-nil use a custom face for xacts shown in `ledger-occur' mode."
"If non-nil, use a custom face for xacts shown in `ledger-occur' mode using ledger-occur-xact-face."
:type 'boolean
:group 'ledger)
(make-variable-buffer-local 'ledger-occur-use-face-unfolded)

View file

@ -28,7 +28,7 @@
;;; Code:
(defgroup ledger-post nil
""
"Options for controlling how Ledger-mode deals with postings and completion"
:group 'ledger)
(defcustom ledger-post-auto-adjust-amounts nil
@ -37,19 +37,17 @@
:group 'ledger-post)
(defcustom ledger-post-amount-alignment-column 52
"If non-nil, ."
"The column Ledger-mode attempts to align amounts to."
:type 'integer
:group 'ledger-post)
(defcustom ledger-post-use-iswitchb nil
"If non-nil, ."
:type 'boolean
:group 'ledger-post)
(defcustom ledger-post-use-ido nil
"If non-nil, ."
:type 'boolean
:group 'ledger-post)
(defcustom ledger-post-use-completion-engine :built-in
"Which completion engine to use, :iswitchb or :ido chose those engines,
:built-in uses built-in Ledger-mode completion"
:type '(radio (const :tag "built in completion" :built-in)
(const :tag "ido completion" :ido)
(const :tag "iswitchb completion" :iswitchb) )
:group 'ledger-post)
(defun ledger-post-all-accounts ()
"Return a list of all accounts in the buffer."
@ -73,13 +71,13 @@
PROMPT is a string to prompt with. CHOICES is a list of
strings to choose from."
(cond
(ledger-post-use-iswitchb
((eq ledger-post-use-completion-engine :iswitchb)
(let* ((iswitchb-use-virtual-buffers nil)
(iswitchb-make-buflist-hook
(lambda ()
(setq iswitchb-temp-buflist choices))))
(iswitchb-read-buffer prompt)))
(ledger-post-use-ido
((eq ledger-post-use-completion-engine :ido)
(ido-completing-read prompt choices))
(t
(completing-read prompt choices))))
@ -114,7 +112,7 @@ PROMPT is a string to prompt with. CHOICES is a list of
(defun ledger-next-amount (&optional end)
"Move point to the next amount, as long as it is not past END."
(when (re-search-forward "\\( \\|\t\\| \t\\)[ \t]*-?\\([A-Z$€£]+ *\\)?\\(-?[0-9,]+?\\)\\(.[0-9]+\\)?\\( *[A-Z$€£]+\\)?\\([ \t]*@@?[^\n;]+?\\)?\\([ \t]+;.+?\\)?$" (marker-position end) t)
(when (re-search-forward "\\( \\|\t\\| \t\\)[ \t]*-?\\([A-Z$€£]+ *\\)?\\(-?[0-9,]+?\\)\\(.[0-9]+\\)?\\( *[A-Z$€£]+\\)?\\([ \t]*@@?[^\n;]+?\\)?\\([ \t]+;.+?\\|[ \t]*\\)?$" (marker-position end) t)
(goto-char (match-beginning 0))
(skip-syntax-forward " ")
(- (or (match-end 4)

View file

@ -23,7 +23,7 @@
;;; Commentary:
;;
;; Code to handle reconciling Ledger files wiht outside sources
;;; Code:
@ -32,31 +32,35 @@
(defvar ledger-acct nil)
(defvar ledger-target nil)
(defgroup ledger-reconcile nil
"Options for Ledger-mode reconciliation"
:group 'ledger)
(defcustom ledger-recon-buffer-name "*Reconcile*"
"Name to use for reconciliation window."
:group 'ledger)
:group 'ledger-reconcile)
(defcustom ledger-fold-on-reconcile t
"If t, limit transactions shown in main buffer to those matching the reconcile regex."
:type 'boolean
:group 'ledger)
:group 'ledger-reconcile)
(defcustom ledger-buffer-tracks-reconcile-buffer t
"If t, then when the cursor is moved to a new xact in the recon window.
Then that transaction will be shown in its source buffer."
:type 'boolean
:group 'ledger)
:group 'ledger-reconcile)
(defcustom ledger-reconcile-force-window-bottom nil
"If t make the reconcile window appear along the bottom of the register window and resize."
:type 'boolean
:group 'ledger)
:group 'ledger-reconcile)
(defcustom ledger-reconcile-toggle-to-pending t
"If true then toggle between uncleared and pending.
reconcile-finish will mark all pending posting cleared."
:type 'boolean
:group 'ledger)
:group 'ledger-reconcile)
(defun ledger-reconcile-get-balances ()

View file

@ -28,6 +28,11 @@
(eval-when-compile
(require 'cl))
(defgroup ledger-report nil
"Customization option for the Report buffer"
:group 'ledger
)
(defcustom ledger-reports
'(("bal" "ledger -f %(ledger-file) bal")
("reg" "ledger -f %(ledger-file) reg")
@ -46,7 +51,7 @@ in that variable for more information on the behavior of each
specifier."
:type '(repeat (list (string :tag "Report Name")
(string :tag "Command Line")))
:group 'ledger)
:group 'ledger-report)
(defcustom ledger-report-format-specifiers
'(("ledger-file" . ledger-report-ledger-file-format-specifier)
@ -58,7 +63,7 @@ specifier."
The function is called with no parameters and expected to return the
text that should replace the format specifier."
:type 'alist
:group 'ledger)
:group 'ledger-report)
(defvar ledger-report-buffer-name "*Ledger Report*")

View file

@ -19,15 +19,19 @@
;; Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
;; MA 02111-1307, USA.
(defcustom ledger-source-directory "~/src/ledger"
"Directory where the Ledger sources are located."
:type 'directory
(defgroup ledger-test nil
"Definitions for the Ledger testing framework"
:group 'ledger)
(defcustom ledger-test-binary "~/Products/ledger/debug/ledger"
(defcustom ledger-source-directory "~/ledger/"
"Directory where the Ledger sources are located."
:type 'directory
:group 'ledger-test)
(defcustom ledger-test-binary "/Products/ledger/debug/ledger"
"Directory where the Ledger debug binary is located."
:type 'file
:group 'ledger)
:group 'ledger-test)
(defun ledger-test-org-narrow-to-entry ()
(outline-back-to-heading)

View file

@ -19,9 +19,19 @@
;; Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
;; MA 02111-1307, USA.
(defvar ledger-path "/Users/johnw/bin/ledger")
(defvar ledger-sample-doc-path "/Users/johnw/src/ledger/doc/sample.dat")
(defvar ledger-normalization-args "--args-only --columns 80")
(defgroup ledger-texi nil
"Options for working on Ledger texi documentation"
:group 'ledger)
(defcustom ledger-texi-sample-doc-path "~/ledger/doc/sample.dat"
"Location for sample data to be used in texi tests"
:type 'file
:group 'ledger-texi)
(defcustom ledger-texi-normalization-args "--args-only --columns 80"
"texi normalization for producing ledger output"
:type 'string
:group 'ledger-texi)
(defun ledger-update-test ()
(interactive)
@ -92,10 +102,10 @@
(defun ledger-texi-expand-command (command data-file)
(if (string-match "\\$LEDGER" command)
(replace-match (format "%s -f \"%s\" %s" ledger-path
data-file ledger-normalization-args) t t command)
(concat (format "%s -f \"%s\" %s " ledger-path
data-file ledger-normalization-args) command)))
(replace-match (format "%s -f \"%s\" %s" ledger-binary-path
data-file ledger-texi-normalization-args) t t command)
(concat (format "%s -f \"%s\" %s " ledger-binary-path
data-file ledger-texi-normalization-args) command)))
(defun ledger-texi-invoke-command (command)
(with-temp-buffer (shell-command command t (current-buffer))
@ -122,7 +132,7 @@
(let ((section (match-string 1))
(example-name (match-string 2))
(command (match-string 3)) expanded-command
(data-file ledger-sample-doc-path)
(data-file ledger-texi-sample-doc-path)
input output)
(goto-char (match-end 0))
(forward-line)