X-Git-Url: https://git.dogcows.com/gitweb?p=chaz%2Fhomebank2ledger;a=blobdiff_plain;f=README;h=9a40d413453d06f00ac239afaae136a39bccd094;hp=edf80f67b68867f093deecf76776401eb0fd5934;hb=e325852aa9ca67592ca857dd4f38cb3f13a97715;hpb=71591e40fa4a522e41ed7283cce39780f4ef8cb5

diff --git a/README b/README
index edf80f6..9a40d41 100644
--- a/README
+++ b/README
@@ -1,52 +1,281 @@
 NAME
 
-    App::HomeBank2Ledger - A tool to convert HomeBank files to Ledger
-    format
+    homebank2ledger - A tool to convert HomeBank files to Ledger format
 
 VERSION
 
-    version 0.001
+    version 0.008
 
 SYNOPSIS
 
-        App::HomeBank2Ledger->main(@args);
+        homebank2ledger --input FILEPATH [--output FILEPATH] [--format FORMAT]
+                        [--version|--help|--manual] [--account-width NUM]
+                        [--accounts|--no-accounts] [--payees|--no-payees]
+                        [--tags|--no-tags] [--commodities|--no-commodities]
+                        [--opening-date DATE]
+                        [--rename-account STR]... [--exclude-account STR]...
 
 DESCRIPTION
 
-    This module is part of the homebank2ledger script.
+    homebank2ledger converts HomeBank <http://homebank.free.fr/> files to a
+    format usable by Ledger <https://www.ledger-cli.org/>. It can also
+    convert directly to the similar Beancount <http://furius.ca/beancount/>
+    format.
 
-METHODS
+    This software is EXPERIMENTAL, in early development. Its interface may
+    change without notice.
 
- main
+    I wrote homebank2ledger because I have been maintaining my own personal
+    finances using HomeBank (which is awesome) and I wanted to investigate
+    using plain text accounting programs. It works well enough for my data,
+    but you may be using HomeBank features that I don't so there may be
+    cases this doesn't handle well or at all. Feel free to file a bug
+    report. This script does NOT try to modify the original HomeBank files
+    it converts from, so there won't be any crazy data loss bugs... but no
+    warranty.
 
-        App::HomeBank2Ledger->main(@args);
+ Features
 
-    Run the script and exit; does not return.
+      * Converts HomeBank accounts and categories into a typical set of
+      double-entry accounts.
 
- formatter
+      * Retains HomeBank metadata, including payees and tags.
 
-        $formatter = $app->formatter($homebank, $opts);
+      * Offers some customization of the output ledger, like account
+      renaming.
 
-    Generate a App::HomeBank2Ledger::Formatter.
+    This program is feature-complete in my opinion (well, almost -- see
+    "CAVEATS"), but if there is anything you think it could do to be even
+    better, feedback is welcome; just file a bug report. Or fork the code
+    and have fun!
 
- convert_homebank_to_ledger
+ Use cases
 
-        my $ledger = $app->convert_homebank_to_ledger($homebank, $opts);
+    You can migrate the data you have in HomeBank so you can start
+    maintaining your accounts in Ledger (or Beancount).
 
-    Converts a File::HomeBank to a App::HomeBank2Ledger::Ledger.
+    Or if you don't plan to switch completely off of HomeBank, you can
+    continue to maintain your accounts in HomeBank and use this script to
+    also take advantage of the reports Ledger offers.
 
- print_to_file
+INSTALL
 
-        $app->print_to_file($str);
-        $app->print_to_file($str, $filepath);
+    There are several ways to install homebank2ledger to your system.
 
-    Print a string to a file (or STDOUT).
+ using cpanm
 
- parse_args
+    You can install homebank2ledger using cpanm. If you have a local perl
+    (plenv, perlbrew, etc.), you can just do:
 
-        $opts = $app->parse_args(@args);
+        cpanm App::Homebank2Ledger
 
-    Parse command-line arguments.
+    to install the homebank2ledger executable and its dependencies. The
+    executable will be installed to your perl's bin path, like
+    ~/perl5/perlbrew/bin/homebank2ledger.
+
+    If you're installing to your system perl, you can do:
+
+        cpanm --sudo App::Homebank2Ledger
+
+    to install the homebank2ledger executable to a system directory, like
+    /usr/local/bin/homebank2ledger (depending on your perl).
+
+ Downloading just the executable
+
+    You may also choose to download homebank2ledger as a single executable,
+    like this:
+
+        curl -OL https://raw.githubusercontent.com/chazmcgarvey/homebank2ledger/solo/homebank2ledger
+        chmod +x homebank2ledger
+
+ For developers
+
+    If you're a developer and want to hack on the source, clone the
+    repository and pull the dependencies:
+
+        git clone https://github.com/chazmcgarvey/homebank2ledger.git
+        cd homebank2ledger
+        make bootstrap      # installs dependencies; requires cpanm
+
+OPTIONS
+
+ --version
+
+    Print the version and exit.
+
+    Alias: -V
+
+ --help
+
+    Print help/usage info and exit.
+
+    Alias: -h, -?
+
+ --manual
+
+    Print the full manual and exit.
+
+    Alias: --man
+
+ --input FILEPATH
+
+    Specify the path to the HomeBank file to read (must already exist).
+
+    Alias: --file, -i
+
+ --output FILEPATH
+
+    Specify the path to the Ledger file to write (may not exist yet). If
+    not provided, the formatted ledger will be printed on STDOUT.
+
+    Alias: -o
+
+ --format STR
+
+    Specify the output file format. If provided, must be one of:
+
+      * ledger
+
+      * beancount
+
+ --account-width NUM
+
+    Specify the number of characters to reserve for the account column in
+    transactions. Adjusting this can provide prettier formatting of the
+    output.
+
+    Defaults to 40.
+
+ --accounts
+
+    Enables account declarations.
+
+    Defaults to enabled; use --no-accounts to disable.
+
+ --payees
+
+    Enables payee declarations.
+
+    Defaults to enabled; use --no-payees to disable.
+
+ --tags
+
+    Enables tag declarations.
+
+    Defaults to enabled; use --no-tags to disable.
+
+ --commodities
+
+    Enables commodity declarations.
+
+    Defaults to enabled; use --no-commodities to disable.
+
+ --budget
+
+    Enables budget transactions.
+
+    Budget transactions are only supported by the Ledger format (for now).
+    This option is silently ignored otherwise.
+
+    Defaults to enabled; use --no-budget to disable.
+
+ --opening-date DATE
+
+    Specify the opening date for the "opening balances" transaction. This
+    transaction is created (if needed) to support HomeBank's ability to
+    configure accounts with opening balances.
+
+    Date must be in the form "YYYY-MM-DD". Defaults to the date of the
+    first transaction.
+
+ --rename-account STR
+
+    Specifies a mapping for renaming accounts in the output. By default
+    homebank2ledger tries to come up with sensible account names (based on
+    your HomeBank accounts and categories) that fit into five root
+    accounts:
+
+      * Assets
+
+      * Liabilities
+
+      * Equity
+
+      * Income
+
+      * Expenses
+
+    The value of the argument must be of the form "REGEXP=REPLACEMENT". See
+    "EXAMPLES".
+
+    Can be repeated to rename multiple accounts.
+
+ --exclude-account STR
+
+    Specifies an account that will not be included in the output. All
+    transactions related to this account will be skipped.
+
+    Can be repeated to exclude multiple accounts.
+
+EXAMPLES
+
+ Basic usage
+
+        # Convert homebank.xhb to a Ledger-compatible file:
+        homebank2ledger path/to/homebank.xhb -o ledger.dat
+    
+        # Run the Ledger balance report:
+        ledger -f ledger.dat balance
+
+    You can also combine this into one command:
+
+        homebank2ledger path/to/homebank.xhb | ledger -f - balance
+
+ Account renaming
+
+    With the "--rename-account STR" argument, you have some control over
+    the resulting account structure. This may be useful in cases where the
+    organization imposed (or encouraged) by HomeBank doesn't necessarily
+    line up with an ideal double-entry structure.
+
+        homebank2ledger path/to/homebank.xhb -o ledger.dat \
+            --rename-account '^Assets:Credit Union Savings$=Assets:Bank:Credit Union:Savings' \
+            --rename-account '^Assets:Credit Union Checking$=Assets:Bank:Credit Union:Checking'
+
+    Multiple accounts can be renamed at the same time because the first
+    part of the mapping is a regular expression. The above example could be
+    written like this:
+
+        homebank2ledger path/to/homebank.xhb -o ledger.dat \
+            --rename-account '^Assets:Credit Union =Assets:Bank:Credit Union:'
+
+    You can also merge accounts by simple renaming multiple accounts to the
+    same name:
+
+        homebank2ledger path/to/homebank.xhb -o ledger.dat \
+            --rename-account '^Liabilities:Chase VISA$=Liabilities:All Credit Cards' \
+            --rename-account '^Liabilities:Amex$=Liabilities:All Credit Cards'
+
+    If you need to do anything more complicated, of course you can edit the
+    output after converting; it's just plain text.
+
+ Beancount
+
+        # Convert homebank.xhb to a Beancount-compatible file:
+        homebank2ledger path/to/homebank.xhb -f beancount -o ledger.beancount
+    
+        # Run the balances report:
+        bean-report ledger.beancount balances
+
+CAVEATS
+
+      * I didn't intend to make this a releasable robust product, so it's
+      lacking tests.
+
+      * Scheduled transactions are not (yet) converted.
+
+      * There are some minor formatting tweaks I will make (e.g.
+      consolidate transaction tags and payees)
 
 BUGS