                 DOCUMENTATION FOR "STAR"

  STAR is a surprisingly sophisticated piece of financial software, allowing
  the management and accrual of personal expenses. It is written to be used
  by those who wish to take complete control of their personal expenses. In
  order to use STAR, you must be able to manage MS-DOS files and use a text
  editor. STAR is run in an MS-DOS window or full-screen.

  STAR allows you to manage future expenses through what are called
  "star accounts". These are user-named accounts (you choose how many and
  their names) that hold or accrue various subtotals of your bank account.
  These star accounts are like separate bank accounts, except the bank has no
  knowledge of their existence. They can have either positive or negative
  amounts in them. For instance, you may have a star account for your
  credit card, which is used to put money into until the actual bill
  arrives. When the bill arrives, the star account is emptied to pay the bill.
  This method allows you to keep track of how much freely spendable money you
  have in your bank account, versus money that is needed for expenses that will
  come due at a later date.

  STAR also allows you to keep track of your individual expenses through what
  are called "budget accounts". These are similiar to star accounts, but do not
  effect any balances. Each budget account has a projected spending quota, or
  budget (which may be zero or negative). As individual payments are applied
  to the associated budget account, a running total is kept and subtracted
  from the budget, allowing you to see what has been spent for that budget
  and what is remaining.

  Two sample STAR files are included (STAR.INP and STAR.OUT) which are fully
  explained below.

  This is shareware and may be freely distributed. If you find this program
  useful, send $25 to

           John David
           25 Brett Road
           Fairfield, CT 06430-1718

  Sending this payment entitles you to three email queries for help with
  questions, to the following address:

           star.support@snet.net

  To start, create a new directory ("\STAR") then copy everything there.
  STAR.EXE is the program, STAR.INP is a sample STAR-formatted input file
  and STAR.OUT is a sample STAR-formatted output file, the result of STAR
  having processed STAR.INP. PRINT.EXE is a program to print files.

  STAR is run in console mode of WIN95/98/2000/NT/ME. It will not run
  in Windows 3.x or DOS. To execute STAR, click on Start then Run,
  then type Command then hit <enter>. Then issue the commands "cd \star"
  and "dir". To simply this, you may wish to make a shortcut to
  \windows\command.com with the default directory (\STAR) pre-defined.
  It is recommended that MS-DOS be run with a full-screen with the number
  of lines set to 25. The memory should be maxed out in all categories with
  the "protected mode" box checked. To make a short-cut of the MS-DOS icon,
  right-click START, choose OPEN, click on PROGRAMS, then right-click MS-DOS
  and choose copy, then paste on the DESK-TOP.

  The full command to run STAR is:

          STAR  <input_file> [<output_file>] [/sort=[[+],-][0,1,2,3,[4]]]

  where <input_file> is a STAR-formatted input file and <output_file> is a
  STAR-formatted output file. Both files are meant to be edited with an
  ordinary text editor, such as EDIT (\windows\command\edit). An abbreviated
  command to run STAR is:

          STAR  <input_file>

  In this case, the output file will be the same as the input file,
  <input_file>. When the input file equals the output file, the input file
  is saved to <file_name>.bak.

  The briefest command to run STAR is:

          STAR  .<ext>

  In this case, the input file will be STAR.<ext> and the output file
  the same, STAR.<ext>, with STAR.BAK the saved input file.

  You can determine the order of the output in the archived section,
  (after the $END record), by entering the optional

                     /sort=[[+],-][0,1,2,3,[4]]

  where "+" indicates ascending (default) and "-" indicates descending.
  "1" indicates the first column (activity), "2" the value, "3" remarks
  and "4" the date. For instance,

           STAR star.act /sort=4

  is the (default) ascending sort on the date with input = output =
  "star.act", while

           STAR  star.act /sort=-4

  is the sort on the date in descending order.

  STAR processes the input file of format described below to produce an
  output file. If you choose different file names for input and output
  files, the output file should replace the input file after being reviewed
  for accuracy, using the MOVE command. However, you may wish to archive
  a copy of the input file before replacing it. If you chose the same file
  name as both input and output, be careful to save either the input file
  before processing or save the .BAK file afterwards if necessary, before
  processing a second time with the same input and output names.

  STAR-formatted files must abide by the following rules:

  The first part of a STAR file is the header section, which is a group of
  lines beginning with either "@", "*", "&" or "#". A "@" represents a
  "macro command" as explained later on, a "*" represents a "star" account,
  an "&" represents a "budget" account and a "#" represents the "main" balance,
  the actual account balance, less any star accounts. The main balance should
  only occur once, while the other types of accounts can occur multiple times,
  once for each account name.

  Following a leading "*" is the star account name which then is followed by a
  space and a value, the current balance for that star account. A star
  account balance may be positive, zero or negative. If it is positive,
  the main balance is decreased correspondingly. If it is negative, the
  main balance is increased correspondingly.

  Following a leading "&" is the budget account name which is then followed by
  a space and up to three values. The first value is the "budget" or quota
  for that account. This value is initially user-entered and the defines the
  budget and can appear multiple times. The sum of all definitions for a
  budget is the total for that budget. In the header section, the budget
  appears with its most current definition as this first value, with additional
  computer-generated values as follows. The second value is the amount spent or
  used by that account and the last value is the amount remaining or left in
  that account. None of the budget balances effect the star account balances or
  the main balance.

  Following a leading "#" (which should only occur once) is a space and up to
  five values. The first value is the main account balance, which is
  the actual account balance less the combined star account balances.
  This may be positive, zero or negative, as is also the case with star
  account balances. The second value is the total used across all budget
  accounts and the third value is the total remaining in all budget accounts.
  The fourth value is the sum of all the used amounts for budgets that are
  over their quotas (negative). The last value is the sum of all budgets.

  For example, if we wish to define the starting amounts for the following
  star and main accounts:

     *CREDITCARD  100.25
     *TAXI        -25.00
     &CLOTHES      50.00    10.00     40.00
     &FOOD         75.00    15.00     60.00
     #             35.01    25.00    100.00      0.00    125.00
!                           &used     &left     &over    &total

  In the above case, there is $100.25 in the star account CREDITCARD,
  negative $25 in TAXI and 35.01 in the main account. The account balance
  (shown below) is $110.26 (35.01-25+100.25)

  The star account CREDITCARD has a positive balance, which can be used
  to pay the credit card bill when it becomes due, assuming the balance
  is sufficient. Since negative balances are allowed by STAR, one star account
  may show sufficient funds, while other star accounts don't, the net result
  might be that there are insufficient funds to actually cover a positive
  star account.

  The star account TAXI has a negative balance indicating that
  the user has overspent his allocated amount for taxi's, which needs to be
  paid back at some time. Changing the value of a star account entails
  simply adding a line starting with the star account name and a value.
  If this value is positive, the star account is increased by the value
  and the main balance is decreased by the same value. If this value is
  is negative, the star account is decreased and the main balance
  increased. Thus the following would subtract $35 from the main balance
  and add $35 to TAXI, resulting in a surplus of $10:

  TAXI 35

  The following line, having been put in STAR processed this file, would
  look like:

!  star accounts=     75.25 balance=    110.26 audit=    105.26

  The balance is $110.26, the sum of all accounts. If the total
  balance becomes negative, then there may be insufficient funds
  at some time, as determined by the bank, unless an adequate deposit is made.
  Note that there are sufficient funds to pay the credit card in this case,
  as the main balance is positive. If the main balance becomes negative,
  there still may be sufficient funds to pay the credit card, depending
  on the other star account balances, or, more simply, the account
  balance.

  The audit balance should match the bank statement balance at the time of
  last audit. How to do an audit is explained below.

  There are two budget accounts, CLOTHES and FOOD. Both of this accounts
  are below budget, with $100 remaining. Note all budget accounts may be
  within budget, yet there may be insufficient funds to cover the star
  accounts and/or main balance. If this is not a transitory effect, but
  seemingly a permanent one, you may consider re-adjusting the budgets.

  The next section of a STAR file is the audited section. This is activity
  that the bank has acknowledged. This section ends with the line:

  $EOS

  for "end of statement". Activity entered here will be processed by STAR
  as part of the audit balance, which then should match the bank's statement
  balance.

  After the audit section comes the unaudited section, terminated by

  $END

  for "end of unaudited section". Activity entered after $END (archive section)
  will not be reflected in the audit balance, when processed by STAR. Perform
  regular maintance on the STAR files once a month or quarter, by deleting the
  oldest records after $END. Otherwise, STAR may run out of memory when
  processing the input file. STAR can handle 1000 archived records. From a
  budget point of view, the records older than the current monthly cycle
  should be removed.

  The rest of the file after $END should be used for previously processed
  activity, acknowledged by the bank, that is being kept in the file to be
  solely part of the budget computation. When such an item is no longer to
  be considered part of the budget computation, either delete the item or
  replace the "%" with an "!".

  The leading symbol "!" can be used for comments anywhere in the file.
  This is for freeform text, in contrast to leading '%" items that
  represent previously considered activity that must adhere to the required
  format and are still used to compute budget account balances.

  In addition, an activity line may have comments added to the end of that
  line. STAR will ignore any excess data on a line, after it has fulfilled
  its requirement for processing that line. In cases that are ambiguous,
  a comment string must start with a character other than a digit, "+",
  "-" or ".".

  The entry of activity in both the audited and unaudited sections
  is based on the leading (first) character and the number of words,
  comments not included, to wit:

  If there is only one word on the line, it is assumed to be an
  main account addition or subtraction. The allowable first characters
  are a number or a "+" or a "-". A leading "." has special meaning as
  explained below, and should not be used to enter additions or
  subtractions of less than a dollar. Use a leading "0.". Here are
  some examples:

  +100.00 - comment
  -50.00
  100.00
  0.34

  However, a better way to enter the above activity, is to use "named" main
  account notation (using 2 words) as described next.

  If there are two words on the line (the maximum allowed), then
  this activity is one of the following:

  If the first character is a "+" or a "-", then this is "named" main account
  activity, which is the perferred way to represent such activity
  in lieu of the preceeding single word entry described above.
  Some examples:

  -BANKFEE 10
  +INTEREST 2.34
  +DEPOSIT 25

  If the first character is a number, it is assumed to be a check
  number. This should be followed by a space and the amount. Here
  are some examples, for checks 405, 406 and 407:

  405 25.23
  406 100
  407 .1

  If the first character is a letter, it is assumed to be a star
  account. This should be followed by a space and the amount, either
  positive or negative. A positive amount represents an addition
  to the star account, while a negative one, a subtraction. You may
  enter star account activity at any time without effecting the balance.
  Some examples:

  CREDITCARD 10.23
  TAXI -3.25

  In the first case, $10.23 is to be subtracted from the main account
  and added to the star account CREDITCARD, while $3.25 is to be added
  to the main account, and subtracted from the star account TAXI.
  When it is time to pay off the credit card (suppose it is $10), enter
  the activity as a negative:

  CREDITCARD -10

  In this case, you will have $0.23 left in this star account (ready to
  be used for the next bill) and $10 more in your main account, to
  be used for writing a check to the credit card company.

  If the first character is a ".", then this represents an outstanding activity
  that has yet to appear on the bank statement, but reflected
  in the star accounts and main account and balance, but not in the audit
  balance.  Here are some examples:

  .+DEPOSIT       110
  .-ATM            75
  .401 30

  In the above case, the balance contains an extra $5 that is not reflected
  in the audit balance.

  If the first character is a "%", then this represents activity that is
  now included in the bank statement or audit balance. Generally, the "%"
  should be applied to activity that already has been processed and now
  is being acknowledged by the bank. Putting a leading '%' on unprocessed
  activity will result in an item failing to be processed for balance purposes,
  except for budget balances. If this is the case, the STAR formatting must
  be adhered to, with the second argument being the value followed by the
  third+ arguments possibly beginning with the budget designation "&".

  Budget accounts are entered on the same line as the activity that
  effects them. The leading character of a word referencing a budget
  account must start with a "&", with other comments also allowed. For
  instance:

  120 23.45 &FOOD - supermarket for dinner

  In the above case, check number 120 in the amount of $23.45 would be
  subtracted from the budget account FOOD. This is different from a star
  account, in that the main balance would not be effected.

  In order to split the activity amongst several budgets specify the
  amounts as follows, with the default budget (without "=xxx.xx")
  being given the remainder:

  406 100 &hotfood=25 &coldfood=35 &otherfood - shopping

  In this case, the remaining amount, $40, would be associated with
  the default budget "otherfood". It is not necessary to have a
  default budget. The sum of the budget associations can not exceed
  the total activity. Spaces are not allowed before or after the "=".

  Inorder to update a budget account without entering activity, use
  a leading "&" with the budget name followed by "=", such as

  &warmfood=23.50 - more shopping

  Note: A leading "&" without an "=" would represent the budget quota.
  Also comments and budget calculations must be placed in columns 34
  and higher on lines that begin with "%". If you process a line item,
  the result will adhere to this format.

  Star accounts can be manipulated the same manner, with the use of
  a leading "*" instead of "&". For instance,

  408 120 *savings

  would subtract 120 from savings, while

  408 120 *savings=-100

  would subtract 100 from savings. Note

  408 120 *savings=100

  would add 100 to savings, making the debit to the main account 220.
  This manner of manipulating star accounts is an alternate to entering
  the star transaction on a separate line.

  Any activity that contains either a budget reference or comment is
  automatically saved in the output file, either with a leading "."
  for activity not yet included in the audit balance or with a leading "%"
  for activity already included in the audit balance.

  The budget accounts are calculated using all activity items, regardless
  of whether or not they have already been included in the audit balance.
  Maintenance of the budget accounts is achieved by deleting the activity
  items or removing references to the budget account.

  Macros:

  Following a leading "@" is the macro name, which is used to match the first
  argument on an activity line. After the macro name comes the command to be
  executed, which can be any other activity line. For instance,

  @+deposit_paycheck      newcar    100   - put into savings for new car
  @+deposit_paycheck      computer   50   - put into savings for computer

  would add $100 automatically into the star account "newcar" and $50
  into "computer" whenever "+deposit_paycheck" was stipulated as an
  activity.

  How to do an audit:

  On a regular basis you should audit the STAR file with the bank
  statement. Here's how its done:

  1. Process the file if any new data has been added since the last time
  it was processed. Save a copy for your records, if desired.

  2. Either add a leading '%" to or delete outstanding activity that now
  appears on the bank statement.

  3. Add in any extra items such as fees and interest in the audit section
  (before $EOS).

  4. Process the file and then review the audit balance to make sure it
  matches the bank's statement balance.

  5. Replace the old file with the new one.

  After entering new activity, you must process the file before deleting
  any data. If you wish to see updated balances, you must also process
  the file. Note the included files STAR.INP and STAR.OUT. STAR.OUT is the result
  of processing STAR.INP. The bank thinks there is $22.60 left in the account,
  the actual balance being $2.27 with a negative main balance (due to the
  overspending of the TAXI star account). The ATM debit has now been
  acknowledged by the bank, so it has a leading '%'.

  Notes:

  To cancel an outstanding item (leading '.'), enter in the unaudited section
  +VOID <entry amount>, process the file then delete both the +VOID line and
  the original item. If you simply delete an outstanding item, that will only
  effect the audit balance, not the balance.

  You can use STAR to roll-up multiple charges to a single number,
  such as rolling credit card charges to a single star account in the main
  file. In fact, any common set of expenses can be aggregated in the following
  manner. Simply create a separate STAR-formatted file. Then enter each charge
  as a star account entry, depending on how you wish to classify it. You can
  use multiple star account names to further classify the charges, or just one
  name. The amount that is to be transferred from this file is the main
  account, which changes each time the file is processed. This main account
  must be also be entered before the $EOS line in the output file, so as to
  allow the main account to consist solely of the next set of entries to be
  processed. The sum of the star accounts in this file should match the single
  number in the main file.
