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

10 files changed, 232 insertions, 68 deletions

diff --git a/doc/ledger-mode.texi b/doc/ledger-mode.texi
index 0dc487a2..9b2c1262 100644
--- a/doc/ledger-mode.texi
+++ b/doc/ledger-mode.texi
@@ -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 Ledger Reconcile Customization Group, Ledger Report Customization Group, Ledger Customization Group, Customization Variables
+@subsection Ledger Reconcile Customization Group
+
+@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
 
-@node Complete list of customization variables,  , Using EMACS customization menus, Ledger-mode Faces
-@subsection Complete list of customization variables
+Work in Progress.
 
-@node Hacking Ledger-mode,  , Installing and Customizing Ledger-mode, Top
+@node Hacking Ledger-mode,  , Embedding Example results in Ledger Documentation, Top
 @chapter Hacking Ledger-mode
 
+Work in Progress.
 @bye
diff --git a/lisp/ldg-commodities.el b/lisp/ldg-commodities.el
index 6f835221..c5500785 100644
--- a/lisp/ldg-commodities.el
+++ b/lisp/ldg-commodities.el
@@ -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"
diff --git a/lisp/ldg-exec.el b/lisp/ldg-exec.el
index af5dd3a8..d62fd419 100644
--- a/lisp/ldg-exec.el
+++ b/lisp/ldg-exec.el
@@ -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."
diff --git a/lisp/ldg-init.el b/lisp/ldg-init.el
index fbb4b838..72317088 100644
--- a/lisp/ldg-init.el
+++ b/lisp/ldg-init.el
@@ -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)
 
diff --git a/lisp/ldg-occur.el b/lisp/ldg-occur.el
index c3f04c5d..1561d6f8 100644
--- a/lisp/ldg-occur.el
+++ b/lisp/ldg-occur.el
@@ -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)
diff --git a/lisp/ldg-post.el b/lisp/ldg-post.el
index 14c3c55f..de28a8a9 100644
--- a/lisp/ldg-post.el
+++ b/lisp/ldg-post.el
@@ -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)
diff --git a/lisp/ldg-reconcile.el b/lisp/ldg-reconcile.el
index 6a9d05fd..6093f9df 100644
--- a/lisp/ldg-reconcile.el
+++ b/lisp/ldg-reconcile.el
@@ -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 ()
diff --git a/lisp/ldg-report.el b/lisp/ldg-report.el
index 4db58494..0aa91ac0 100644
--- a/lisp/ldg-report.el
+++ b/lisp/ldg-report.el
@@ -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*")
 
diff --git a/lisp/ldg-test.el b/lisp/ldg-test.el
index 7667a05e..dbba9546 100644
--- a/lisp/ldg-test.el
+++ b/lisp/ldg-test.el
@@ -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)
diff --git a/lisp/ldg-texi.el b/lisp/ldg-texi.el
index 53e050ce..84ba34c2 100644
--- a/lisp/ldg-texi.el
+++ b/lisp/ldg-texi.el
@@ -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)