===================================================================
RCS file: /cvs/pta/pta_import.1,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -p -r1.4 -r1.5
--- pta/pta_import.1	2020/11/12 14:26:51	1.4
+++ pta/pta_import.1	2020/11/14 22:15:56	1.5
@@ -1,4 +1,4 @@
-.\" $Id: pta_import.1,v 1.4 2020/11/12 14:26:51 schwarze Exp $
+.\" $Id: pta_import.1,v 1.5 2020/11/14 22:15:56 schwarze Exp $
 .\"
 .\" Copyright (c) 2020 Freda Bundchen
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: November 12 2020 $
+.Dd $Mdocdate: November 14 2020 $
 .Dt PTA_IMPORT 1
 .Os
 .Sh NAME
@@ -22,7 +22,7 @@
 .Nd print pta journal entries from bank CSV file input
 .Sh SYNOPSIS
 .Nm pta_import
-.Fl I Ar bankFormat
+.Fl I Ar accountname
 .Op Ar file
 .Sh DESCRIPTION
 The
@@ -37,7 +37,7 @@ If the
 .Ar file
 argument is omitted, standard input is read instead.
 .Pp
-.Ar bankFormat
+.Ar accountname
 is exactly one of
 .Pp
 .Bl -bullet -offset indent -compact
@@ -50,8 +50,48 @@ is exactly one of
 .El
 .Pp
 and corresponds to an existing
-.Pa import_ Ns Ar bankFormat Ns Pa .txt
-file in the current directory.
+.Pa import_ Ns Ar accountname Ns Pa .txt
+configuration file in the current directory.
+.Ss Configuration file format
+Each file of the form
+.Pa import_ Ns Ar accountname Ns Pa .txt
+in the current directory is a configuration file used to
+import transactions from a financial institution.
+Like all
+.Xr pta 1
+input files, it is an
+.Xr ascii 7
+text file using strings of one or more space characters
+as the field delimiter and using the hash character
+.Pq Sq #
+in the first column to mark lines as ignored.
+.Pp
+Each file contains one line beginning with
+.Qq ACCOUNT
+and is followed by whitespace and then an account number.
+.Pp
+Each file contains lines of the form
+.Pp
+.Ar selector account_number booking_identifier
+.Pp
+The
+.Ar selector
+is a string consisting of regular expressions
+separated by commas.
+Its fields correspond to header fields in the financial
+institution's CSV file and is used to classify transactions
+that match the search pattern.
+The first selector that
+matches a transaction wins.
+.Pp
+The
+.Ar account_number
+corresponds to an account number in
+.Pa ./accounts.txt .
+The
+.Ar booking_identifier
+is defined by the user to classify
+the transaction.
 .Sh FILES
 .Bl -tag -width Ds -compact
 .It Pa ./import_capital_one_credit.txt
@@ -64,17 +104,6 @@ account number from
 .Pa ./accounts.txt
 used by this account, as well as patterns used to map transactions to
 the correct account and booking identifier.
-.Ss Defining the account number
-Each file must contain one line beginning with
-.Qq ACCOUNT
-and is followed by whitespace and then an account number.
-The account number corresponds to the account in
-.Pa ./accounts.txt
-for the imported account.
-.Ss Patterns in the import_bankFormat.txt files
-Each file contains lines of the form
-.Pp
-.Ar selector account_number booking_identifier
 .Sh EXIT STATUS
 .Ex -std
 .Sh EXAMPLES
@@ -82,87 +111,26 @@ Add journal entries to a journal file using a CSV file
 a financial institution:
 .Pp
 .Dl "$ pta_import -I chase_credit chasedownload.csv >> journal.txt"
-.Ss A sample credit card purchase
-Suppose a line in the
-.Pa chasedownload.csv
-file looks like
+.Ss Account numbers in the configuration file
+The line
 .Pp
-.Dl "10/26/2020,10/26/2020,example.com*asldfkj,Shopping,Sale,-17.07"
+.Dl ACCOUNT 3235
 .Pp
-If the line matching the
-.Qq Shopping
-category in the user's
-.Pa ./import_chase_credit.txt
-file is
+in the configuration file corresponds to a line such as
 .Pp
-.Dl ,,,Shopping,,, 9996 SHOP
+.Dl 3235 L Capital One credit card
 .Pp
-then the
-.Qq Shopping
-category defined by Chase is mapped to the user's
-.Qq SHOP
-booking identifier, and the user's account for shopping
-expenses is defined as
-.Qq 9996
-in their
+in
 .Pa ./accounts.txt .
 .Pp
-We further assume in this example that the user has edited
-.Pa ./import_chase_credit.txt
-so that the line beginning with
-.Qq ACCOUNT
-contains the liability account they have defined for their Chase card
-in
-.Pa ./accounts.txt
-.Pp
-In this example,
-.Pa ./import_chase_credit.txt
-contains
-.Dl ACCOUNT 3234
-.Pp
-Then
-.Nm
-prints
-.Pp
-.Dl "20201026 SHOP 9996 3234 17.07 example.com*asldfkj"
-.Ss A sample credit card payment
-.Dl "10/27/2020,10/27/2020,Payment Thank You - Web,,Payment,1653.42"
-.Pp
-Suppose the user's
-.Pa ./import_chase_credit.txt
-file contains
-.Pp
-.Dl ,,,,Payment,, 1700 PAY
-.Pp
-which matches Chase's payment category to the user's asset account
-.Qq 1700
-used to pay off the credit card.
-Then
-.Nm
-prints
-.Pp
-.Dl "20201027 PAY 3234 1700 1653.2 Payment Thank You - Web"
-.Ss Account numbers in the import_bankFormat.txt files
-For example, if
-.Pa ./import_capital_one_credit.txt
-contains
-.Pp
-.Dl ACCOUNT 1293
-.Pp
-then there must be a corresponding entry in
-.Pa ./accounts.txt
-such as
-.Pp
-.Dl 1293 L Capital One credit card
-.Pp
 The description
 .Qq Capital One credit card
 may vary, but in this example, the account numbers
-.Qq 1293
+.Qq 3235
 match, and the account type is
 .Qq L
 to indicate that it is a liability account.
-.Ss Patterns in the import_bankFormat.txt files
+.Ss Patterns in the configuration file
 Suppose
 .Pp
 .Dl ,,,Automotive,,, 1111 AUTO
@@ -185,6 +153,45 @@ defined in
 with the
 .Qq Auto
 booking identifier.
+.Ss A sample credit card purchase
+If
+.Pa chasedownload.csv
+file contains
+.Pp
+.Dl "10/26/2020,10/26/2020,example.com*asldfkj,Shopping,Sale,-17.07"
+.Pp
+and
+.Pa ./import_chase_credit.txt
+contains
+.Bd -literal -offset Ds
+ACCOUNT 3234
+,,,Shopping,,, 9996 SHOP
+.Ed
+.Pp
+and
+.Pa ./accounts.txt
+contains
+.Bd -literal -offset Ds
+3234 L Chase credit card
+9996 X shopping
+.Ed
+.Pp
+then the
+.Qq Shopping
+category defined by Chase is mapped to the user's
+.Qq SHOP
+booking identifier, the user's account for shopping
+expenses is defined as
+.Qq 9996
+in their
+.Pa ./accounts.txt ,
+the user's account for the credit card is 3234 in their
+.Pa ./accounts.txt ,
+and
+.Nm
+prints
+.Pp
+.Dl "20201026 SHOP 9996 3234 17.07 example.com*asldfkj"
 .Ss A complete example
 Suppose
 .Pa ./accounts.txt
@@ -246,6 +253,14 @@ outputs
 20201108 SHOP 5203 3234 53.83 example.com
 20201104 PAY 3234 1700 75.43 Payment Thank You - Web
 .Ed
+.Pp
+Note that the selector for Dr\&. Sally Sue
+in the example configuration file comes before the
+Health & Wellness selector.
+Since the first match wins, transactions for Dr\&. Sally Sue
+can be classified with the DENTAL booking identifier,
+even though the bank's CSV file classifies
+these transactions as Health & Wellness.
 .Sh SEE ALSO
 .Xr pta-accounts 5 ,
 .Xr pta-journal 5 ,
@@ -257,21 +272,9 @@ has the following limitations:
 .Bl -dash
 .It
 Pattern recognition in the
-.Pa import_bankFormat.txt
+.Pa import_accountname.txt
 files is under continued development.
 .It
 The only defined import formats are for Chase credit cards,
 Capital One credit cards, and Optum Health Savings Accounts.
-.It
-Note that the first pattern match wins in
-.Pa ./import_bankFormat.txt .
-In the complete example above, we put the line containing
-.Qq Dr. Sally Sue
-before the line matching the
-.Qq Health & Wellness
-category because we wanted to override the
-.Qq Health & Wellness
-category, and use the
-.Qq Dental expenses
-account instead.
 .El