home *** CD-ROM | disk | FTP | other *** search
/ PC World 2000 February / PCWorld_2000-02_cd.bin / live / usr / X11R6 / lib / X11 / cbb / docs / cbb-man.txt
INI File  |  1998-10-07  |  58KB  |  1,322 lines
  1. [next] [up] [previous]
  2.  
  3.                                     CBB
  4.                            A Check Book Balancer
  5.                                 for Unix/X11
  6.  
  7.                          Written by Curtis L. Olson
  8.                              curt@infoplane.com
  9.                     with many contributions from others.
  10.                  Copyright ⌐ 1994 - 1997 by Curtis L. Olson.
  11.  
  12. This program is free software; you can redistribute it and/or modify it
  13. under the terms of the GNU General Public License as published by the Free
  14. Software Foundation; either version 2 of the License, or (at your option)
  15. any later version.
  16.  
  17. This program is distributed in the hope that it will be useful, but WITHOUT
  18. ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  19. FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
  20. more details.
  21.  
  22. You should have received a copy of the GNU General Public License along with
  23. this program; if not, write to the Free Software Foundation, Inc., 675 Mass
  24. Ave, Cambridge, MA 02139, USA.
  25.  
  26. Contents
  27.  
  28.  
  29.    * 1 Introduction
  30.    * 2 Important Information
  31.         o 2.1 Contacting the Author
  32.         o 2.2 The CBB Mailing List
  33.         o 2.3 Availability
  34.         o 2.4 Prerequisites
  35.         o 2.5 Installation
  36.              + 2.5.1 Normal Installation
  37.              + 2.5.2 Upgrading CBB
  38.         o 2.6 Advanced Installation Issues
  39.              + 2.6.1 Avoiding Older Perl Versions
  40.              + 2.6.2 Automating the Install Script
  41.              + 2.6.3 Package Maintainer Install Options
  42.         o 2.7 Migrating Data Files to Version 0.60 or Later
  43.              + 2.7.1 Data File Format
  44.              + BEST Pre-Version-0.60 to Current-Version Migration Procedure
  45.              + OLD Pre-Version-0.60 to Current-Version Migration Procedure
  46.    * 3 CBB Tutorial
  47.         o 3.1 Quick Overview
  48.         o 3.2 Create a demo Account
  49.         o 3.3 Import Some Data
  50.         o 3.4 Edit Transactions
  51.         o 3.5 Balance the Account
  52.         o 3.6 Reports and Graphs
  53.         o 3.7 Saving and Exiting CBB
  54.    * 4 CBB Reference Manual
  55.         o 4.1 Making New Accounts
  56.              + 4.1.1 Creating From Scratch
  57.              + 4.1.2 Importing Quicken Data
  58.              + 4.1.3 Setting an Initial Balance
  59.         o 4.2 Editing Transactions
  60.              + 4.2.1 Overview
  61.              + 4.2.2 General Key Bindings
  62.              + 4.2.3 Specific Key Bindings for the Check Number field
  63.              + 4.2.4 Specific Key Bindings for the Date field
  64.              + 4.2.5 Splits
  65.              + 4.2.6 Memorized Transactions
  66.         o 4.3 Categories
  67.              + 4.3.1 Viewing Categories
  68.              + 4.3.2 Creating Categories
  69.              + 4.3.3 Deleting Categories
  70.         o 4.4 Transfers Between Accounts
  71.         o 4.5 Balancing
  72.         o 4.6 Reporting
  73.              + 4.6.1 Transaction List
  74.              + 4.6.2 Transaction List By Category
  75.              + 4.6.3 Short List By Category
  76.              + 4.6.4 Missing Checks
  77.              + 4.6.5 Average Monthly Expenses by Category
  78.         o 4.7 Graphing
  79.              + 4.7.1 Graph of Running Balance
  80.         o 4.8 Preferences
  81.         o 4.9 Saving your work
  82.         o 4.10 Importing and Exporting
  83.              + 4.10.1 Importing from Quicken
  84.              + 4.10.2 Exporting to Quicken
  85.         o 4.11 Security Issues
  86.              + 4.11.1 Umasks and Default Permissions
  87.              + 4.11.2 Data Encryption
  88.                   + Enabling Encryption:
  89.                   + Compatible Encryption Software:
  90.                   + Configuring the Key:
  91.                   + Saving the Preferences:
  92.                   + Other Items to Note:
  93.                   + Possible Bugs:
  94.    * 5 Contributed scripts
  95.         o 5.1 Fetching and Installing the Latest Greatest CBB
  96.         o 5.2 Investment Accounts
  97.         o 5.3 Migrating from Previous Data File Formats
  98.         o 5.4 Managing Recurring Transactions
  99.              + 5.4.1 Overview of the recur.pl script
  100.              + 5.4.2 Config file format
  101.         o 5.5 Keeping a Manageable Data File Size
  102.         o 5.6 Alternative Interfaces to CBB
  103.              + 5.6.1 Txn
  104.              + 5.6.2 Emacs Forms Mode
  105.              + 5.6.3 Your Favorite Editor
  106.              + 5.6.4 Other Options
  107.    * 6 CBB Internals
  108.         o 6.1 The ``.cbbrc.tcl'' File
  109.         o 6.2 The External Menu
  110.         o 6.3 Creating and Installing New Reports
  111.         o 6.4 Creating and Installing New Graphs
  112.         o 6.5 The Devel Menu
  113.         o 6.6 Logging
  114.    * 7 Frequently Asked Questions
  115.    * About this document ...
  116.  
  117. 1 Introduction
  118.  
  119. CBB is a personal finance management utility for Unix/X11. It is written
  120. entirely in Perl and Tcl/Tk so it is very portable and very extendable. It
  121. is a program for anyone who would like to balance their checkbook and manage
  122. their money using free software under Unix and X11.
  123.  
  124. CBB is intended to be an open, extensible program. It utilizes a simple,
  125. tab-delimited data file format and, because it is written entirely in Perl
  126. and Tcl/Tk, it is very modifiable. In addition, it provides a simple
  127. interface for users to add their own reports, graphs, and external modules
  128. without modifying any of the CBB source.
  129.  
  130. The name, CBB, stands for the Check Book Balancer. It is intended to fit
  131. well in the Unix naming scheme where commands should be short and easy to
  132. type. Every once in a while I try to think of something a little more
  133. creating, but as of yet, nothing has come to mind.
  134.  
  135. CBB has now existed for more than two and a half years. Version 0.60
  136. represented a fairly substantial reworking/reorganization of version
  137. 0.53--although this may not always be immediately visible on the surface.
  138. Version 0.62 represented a substantial amount of rework to better support
  139. tk4.0. Now, versions 0.70 and later look much spiffier and sport completely
  140. reworked internals, plus many new features, tweaks, and fixes.
  141.  
  142. I sincerely hope you can find CBB useful in your day to day and year to year
  143. money management. I am always working to improve this program so please send
  144. in your comments, suggestions, and complaints.
  145.  
  146. 2 Important Information
  147.  
  148. 2.1 Contacting the Author
  149.  
  150. If you would like to contact me, you may send email to curt@infoplane.com.
  151. Although sometimes the business of life gets the best of me, I will do my
  152. best to respond in a timely manner and address your issue or concern.
  153.  
  154. 2.2 The CBB Mailing List
  155.  
  156. The address for the CBB mailing list is cbbers@infoplane.com. To subscribe,
  157. send a message to cbbers-request@infoplane.com with a message body of
  158. subscribe. To unsubscribe, send a message to cbbers-request@infoplane.com
  159. with a message body of unsubscribe. Recent messages to this list are
  160. archived at:
  161.  
  162.     http://www.menet.umn.edu/~curt/cbb/mail.archive/
  163.  
  164. 2.3 Availability
  165.  
  166. The current version of CBB is always available via anonymous ftp from one of
  167. the following sites:
  168.  
  169.     ftp://ftp.me.umn.edu/pub/finance/cbb-latest.tar.gz
  170.     ftp://ftp.fifi.org/pub/cbb/cbb-latest.tar.gz
  171.  
  172. 2.4 Prerequisites
  173.  
  174. CBB is written in Perl and Tcl/Tk. These need to be installed on your system
  175. before you can can continue. Note, CBB now requires tk4.0 or higher and
  176. perl5.002 or higher. If you notice any problems or incompatibilities please
  177. let me know.
  178.  
  179. Tcl and Tk are available via anonymous ftp from:
  180.  
  181.    ftp://ftp.smli.com/pub/tcl/
  182.  
  183. Note, the Tcl FAQ has a list of mirror sites. You can read the FAQ online
  184. at:
  185.  
  186.    http://www.cis.ohio-state.edu/hypertext/faq/usenet/tcl-faq/top.html
  187.  
  188. Perl is available via anonymous ftp from:
  189.  
  190.     prep.ai.mit.edu:/pub/gnu/perl-5.***.tar.gz
  191.     ftp.cs.umn.edu:/pub/gnu/perl-5.***.tar.gz
  192.  
  193. 2.5 Installation
  194.  
  195. For most systems and environments, installing CBB will be very
  196. straightforward. Simply follow the instructions in section 2.5.1.
  197.  
  198. 2.5.1 Normal Installation
  199.  
  200.  
  201.  
  202. Gunzip and untar the distribution file and cd to the newly created directory
  203. and run:
  204.  
  205.     make install
  206.  
  207. Specify the location of perl5 and wish4.x and specify where you would like
  208. the executables and associated files installed.
  209.  
  210. 2.5.2 Upgrading CBB
  211.  
  212. Periodically, new version of CBB are released. Most of the general laws of
  213. computer upgrades apply to CBB. Although I go to great efforts to ensure new
  214. versions work better than the previous version, occasionally problems creep
  215. in. Use a good measure of caution (such as backing up your data files, and
  216. keeping a copy of the previous version of CBB) when upgrading this or any
  217. other component of your system.
  218.  
  219. Once you have CBB installed and running, and if you are ``net'' connected,
  220. upgrading to the latest version is trivial. Just follow the simple
  221. instructions in section 5.1.
  222.  
  223. You can manually upgrade CBB by simply installing the new version over the
  224. top of the old. Be aware that I occassionally add, remove, or change the
  225. names of files in the distribution. Over time, old, outdated, useless files
  226. could accumulate in the CBB lib directory.
  227.  
  228. 2.6 Advanced Installation Issues
  229.  
  230. The environments and needs of users are often widely varied. The CBB install
  231. script supports several additional options. If you are having trouble
  232. installing CBB, you may want to read through this section for ideas.
  233.  
  234. 2.6.1 Avoiding Older Perl Versions
  235.  
  236. If the copy of perl that comes first in your path is an older version (such
  237. as perl4) and you have perl5 located someplace else on your system, you can
  238. use the following command to install CBB:
  239.  
  240.     make PERL=/path/to/newer/copy/of/perl install
  241.  
  242. 2.6.2 Automating the Install Script
  243.  
  244. The CBB install script by default is interactive and askes several
  245. questions. Running make install simply runs the install script, and nothing
  246. else. If you run the install script by hand, ./install.pl you can pass it
  247. several command line options. The following options are available:
  248.  
  249.     --help:             Display the usage message.
  250.     --perlpath <path>:  Full pathname to perl interpreter.
  251.     --wishpath <path>:  Full pathname to wish interpreter.
  252.     --bindir <dir>:     Directory to install executables.
  253.     --libdir <dir>:     Directory to install support files.
  254.  
  255. If you specify any one of the above paths from the command line, the install
  256. script will not prompt for it.
  257.  
  258. 2.6.3 Package Maintainer Install Options
  259.  
  260. The CBB install script has two addtional options to assist package
  261. maintainers. Most Unix operating systems have a ``package'' format for
  262. installing packages. Packages are convenient because they can be quickly and
  263. easily installed, upgraded, and deinstalled. The software come preconfigured
  264. in the package. Unfortunately most versions of Unix have their own
  265. incompatible package format.
  266.  
  267. However, if you are a package maintainer for some brand of Unix, the
  268. following options will interest you:
  269.  
  270.     --prefix <dir>:   Root directory where CBB will eventually be
  271.                       installed and run from ... this is where CBB
  272.                       thinks it lives.
  273.     --destdir <dir>:  Root directory where CBB will actually be
  274.                       installed right now for package building
  275.                       purposes.  It is assumed that once the package
  276.                       is installed, CBB will reside in the --prefix
  277.                       directory.
  278.  
  279. These options allow you to install CBB in a one directory, but modify the
  280. internal variables and pointers to make CBB think it has been installed in a
  281. completely different directory tree.
  282.  
  283. 2.7 Migrating Data Files to Version 0.60 or Later
  284.  
  285.  
  286.  
  287. If you are upgrading from a pre-0.60 version, you will need to upgrade your
  288. data files as well.
  289.  
  290. If you are not upgrading from a pre 0.60 version, you can safely skip this
  291. section. This section describes the procedure to migrate your data files
  292. from the pre-0.60 format to the current format.
  293.  
  294. The initial versions of CBB saved its data in an ASCII text file with the
  295. fields delimited by the `:' character. However, not too far into this CBB
  296. project (at version 0.50a I believe) I switched my thinking and decided to
  297. take advantage of perl's dbm support. This has one primary advantage. Any
  298. changes made to the data file are immediately saved. This also has some
  299. disadvantages. It tends to close off the data file so it can only be
  300. manipulated from within CBB. This is good from a ``data encapsulation''
  301. perspective, but it suddenly becomes a problem if the data file needs to be
  302. manipulated in a way which CBB doesn't support. Another point to note is
  303. that because perl is so good at slurping in text files, and because of
  304. certain constraints imposed by the Tk front end, using the dbm format did
  305. not provide any speed advantage. In fact, for certain operations I noted a
  306. speed decrease.
  307.  
  308. With the above observations in mind, I decided to come full circle and
  309. return to saving CBB data files in an open ASCII format by default. The
  310. astute among you may observe that ASCII files have one major disadvantage.
  311. They are only saved at the user's request. So, one hapless user working all
  312. day without saving + one unexpected power outage, one press of the reset
  313. button, or one of any other creative ways people invent to destroy their
  314. data = trouble. To counter this problem, I created an auto save feature. At
  315. regular intervals, if the current data file has been modified, it is saved
  316. to a temporary file. This greatly reduces the risk of data loss stupidity or
  317. acts of God--or acts of God in response to our stupidity.
  318.  
  319. 2.7.1 Data File Format
  320.  
  321. The ASCII data file format is defined to be one record per line with the
  322. fields delimited by the <tab> character. CBB saves the following fields in
  323. this order: date, check number, description, debit amount, credit amount,
  324. category, comment, and the cleared flag. Please feel free (in fact, I
  325. encourage you) to view a CBB data file with any text viewer (more or less.)
  326. The format is mostly self explanitory.
  327.  
  328. BEST Pre-Version-0.60 to Current-Version Migration Procedure
  329.  
  330. REMEMBER to always backup up your data before doing anything radical to it.
  331.  
  332. The easiest and simplest way convert your data files is to export them to
  333. the ``CBB'' format using your pre-0.60 version of CBB. This is a slightly
  334. different format than current versions of CBB use, but current versions of
  335. CBB will be able to detect this slightly different format and load the files
  336. correctly. When you save the file from the new version of CBB is will be
  337. save in the new format.
  338.  
  339. OLD Pre-Version-0.60 to Current-Version Migration Procedure
  340.  
  341. This section describes a perl script which automates the conversion of data
  342. file formats. However it is rumored to only work with perl4 and not perl5.
  343. All other parts of CBB require perl5.002 or greater. Please be careful with
  344. this script and always back up your data before you do anything radical.
  345. ``Your millage may vary.''
  346.  
  347. I have provided a perl script to automate the data file migration,
  348. migrate-to-0.60a.pl. It is located in the contrib subdirectory of the
  349. distribution-dir directory.
  350.  
  351.   1. Backup your data file directory. Do it now!!!
  352.   2. cd $CBB_LIB_DIR/contrib
  353.   3. migrate-to-0.60a.pl <data-dir>
  354.   4. Choose whether you want to migrain (oops I mean migrate) to ASCII or
  355.      dbm format. Type ascii or dbm. I personally recommend using the ASCII
  356.      format, unless you have strong convictions otherwise.
  357.  
  358. The migrate script will perform the following tasks:
  359.  
  360.   1. Convert categories file from `:' delimited to <tab> delimited, and save
  361.      it in an ASCII format.
  362.   2. Remove any *.bal.dir and *.bal.pag. These have always been redundant
  363.      from CBB's perspective.
  364.   3. Rename all $file.txn.dir to $file.dir, and all $file.txn.pag to
  365.      $file.pag. This makes for a slightly more pleasant naming scheme.
  366.   4. Open each $file.dir and convert all transactions from `:' delimited to
  367.      <tab> delimited.
  368.   5. If migrating to ASCII, save file to ASCII CBB format and delete dbm
  369.      file.
  370.  
  371. When the script has finished, your data files should be all set for your new
  372. version of CBB. Start up CBB and poke around your files a bit. If you notice
  373. any problems, let me know immediately--and be glad you backed up all your
  374. data like I suggested earlier.
  375.  
  376. 3 CBB Tutorial
  377.  
  378. So, you want to go for a little test drive? Want to see how or if this thing
  379. works? Want to send me a 21 inch monitor? Just checking. :-) Well, read on
  380. ...
  381.  
  382. The following procedure will lead you through the process of creating a new
  383. account, importing some data, editing transactions, and balancing your
  384. account.
  385.  
  386. 3.1 Quick Overview
  387.  
  388. First, here is the ``one-paragraph'' version of this manual. To use CBB,
  389. first make a directory where you would like to keep your group of accounts.
  390. Then, go to this directory, run cbb, and make your account(s). Optionally
  391. you could choose to import the default categories, but this can be done at
  392. any time. Next, load the desired account (if it is not already loaded) and
  393. create, delete, and edit transactions to your hearts content. When your
  394. statement arrives in the mail, balance your account. Meanwhile, you have
  395. been printing some reports, viewing some graphs, maybe setting up some
  396. recurring transactions, and hopefully managing your money better than before
  397. you started using CBB!
  398.  
  399. 3.2 Create a demo Account
  400.  
  401. Ok, so you've just installed CBB. What now? Well, if you are like me, you
  402. will have already run it a few times before you cracked open the manual and
  403. read all the way down to here. So go ahead and lauch CBB again. The first
  404. thing you need to do is create an account.
  405.  
  406.   1. Run CBB by typing cbb.
  407.   2. Select Make New Account ... from the File menu.
  408.   3. Enter an account name (i.e. my-demo.cbb) and an account description
  409.      (i.e. My Demo Account).
  410.   4. Click on the Create Account button. Your new account will be created,
  411.      and added to the master account list at the bottom of the main window.
  412.      The name of the account will also be added to the category list (i.e.
  413.      [my-demo]). This category is used to specify transfers between
  414.      accounts.
  415.   5. You will be warned about not having a categories file. This is
  416.      perfectly normal at this point. An empty categories file will be
  417.      created for you.
  418.   6. If you like, pull down the Functions menu and select Categories -> Add
  419.      Default Categories to create a bunch of default categories.
  420.  
  421. 3.3 Import Some Data
  422.  
  423. Now that you have created an account it is time to enter a few transactions.
  424. If you like, you can import some sample data to save your fingers from the
  425. brutalities of typing. Otherwise, feel free to skip this section and enter
  426. your own transactions. The CBB distribution comes with some sample data just
  427. for this tutorial.
  428.  
  429.   1. Select Import QIF File ... from the File menu.
  430.   2. You will be presented with a file selection dialog box. Navigate your
  431.      way to the CBB distribution directory. Beneath the distribution
  432.      directory is a demo directory. Go to the demo directory and find the
  433.      file named demo.qif. Double click on this file to select it and import
  434.      it.
  435.  
  436. 3.4 Edit Transactions
  437.  
  438.  
  439.  
  440. Now, that you have some data to play with, try editing a transaction. Click
  441. the ``!'' box or hit enter to commit the transaction. Click the ``X'' box or
  442. type <Meta-N> to clear the entry boxes and start over.
  443.  
  444. Now try creating new transactions.
  445.  
  446. Try playing around with ``splits'' to specify more than one category for a
  447. transaction. Feel free to explore the menus and buttons until you get the
  448. hang of things. You can refer to Section 4.2 for a more detailed description
  449. of transaction editing.
  450.  
  451. 3.5 Balance the Account
  452.  
  453. Now, lets pretend you just received your bank statement in the mail and you
  454. want to reconcile your new account. Lets also pretend that you didn't mess
  455. thing up too bad back in Section 3.4.
  456.  
  457.   1. Find the Balance button towards the bottom right hand corner of the
  458.      window and click on it. This will bring up a list of all ``uncleared''
  459.      transactions.
  460.   2. Enter a statement ending balance of 1740.00. (Leave the statement
  461.      beginning balance as 0.00.)
  462.   3. Select the first four transactions as well as the sixth transaction.
  463.      (Just pretend these were the ones that showed up on your statement.)
  464.      Note, as you select transactions, watch the Debits = n, Credits = n,
  465.      Difference = n line.
  466.   4. When the starting balance - withdrawals + deposits = ending balance,
  467.      click on the Update button to mark all the selected transactions as
  468.      cleared.
  469.   5. Congratulations: your account is (hopefully) balanced.
  470.  
  471. When your next statement arrives and you run the balance routine again, you
  472. will only be presented with ``uncleared'' transactions to select. This is a
  473. good way to spot old checks that never were cashed ...such as your mortgage
  474. payment that got ``lost in the mail.'' Note: by balancing your checkbook in
  475. this manner, two good things happen. The first is, when your brother finally
  476. cashes that check for $100.00 - many months after you wrote it - your bank
  477. balance doesn't suddenly drop -$100.00 from where you think it should be.
  478. That transaction had always been entered and subtracted out of your bank
  479. balance. The second good thing is that it is easy to spot these sorts of
  480. situations so that you can call up your brother and pester him to cash the
  481. check.
  482.  
  483. 3.6 Reports and Graphs
  484.  
  485. Now that you have entered a bit of data, you may want to ``understand'' your
  486. data at a deeper level. CBB comes with several reports and graphs which can
  487. help you get a better idea of where and how your money is being spent. Feel
  488. free to look at a few reports and graphs at this point.
  489.  
  490. 3.7 Saving and Exiting CBB
  491.  
  492. Wow! You've been slaving away for the last 10 minutes perfecting your demo
  493. account. Great job! That is about all there is to it. CBB isn't rocket
  494. science. It just boils down ``plus and minus''. Since this is not real data,
  495. you probably don't care to save it. However, if this had been an actual
  496. account, you most definitely would want to save your hard work. CBB stores
  497. all your changes in memory, so you must save the account before you quit. If
  498. your forget to save your work before you quit, CBB will remind you to do
  499. this. If you do something awful, like reboot your machine or log out without
  500. saving, you are not completely out of luck. CBB periodically saves a backup
  501. copy of your account with a file name of #account.cbb#. When you reload your
  502. account, CBB will notice the autosave file and ask if you want to load it
  503. instead. Under normal circumstances you will want to answer yes. If you
  504. aren't sure, don't do anything. Exit CBB, go to your data directory and look
  505. at the files manually to make sure which version is the one you want.
  506.  
  507. 4 CBB Reference Manual
  508.  
  509. 4.1 Making New Accounts
  510.  
  511. 4.1.1 Creating From Scratch
  512.  
  513. To create a new account from scratch, choose Make New Account ... from the
  514. File menu. Enter the account name without any extension. (CBB will
  515. automatically add a .cbb to the name you provide.) This account name will
  516. become a category of the form [acct-name] description for use in transfers
  517. between accounts. Section 4.4 explains how transfers work. Next enter a
  518. description for this account. When you satisfied with your name and
  519. description, click on the Create Account button and your new empty account
  520. will be created and loaded.
  521.  
  522. 4.1.2 Importing Quicken Data
  523.  
  524. To create a new account based on exported Quicken data, create a new account
  525. from scratch as described in the previous subsection. Once the account has
  526. been created, Quicken data can be imported into it. Importing data from
  527. Quicken is explained in Section 4.10.1.
  528.  
  529. 4.1.3 Setting an Initial Balance
  530.  
  531. Setting an initial balance for an account is as simple as creating a first
  532. transaction with a credit amount equal to the initial balance.
  533.  
  534. 4.2 Editing Transactions
  535.  
  536.  
  537.  
  538. 4.2.1 Overview
  539.  
  540. At all times in CBB (except for those times when you are doing other things)
  541. you are either creating new transactions, or editing existing transactions.
  542. Other operations such as balancing may temporarily suspend the entry, but
  543. when the chosen function is completed, you are returned to your current edit
  544. or insert operation.
  545.  
  546. At any time you can abort the current edit or insert operation by initiating
  547. a new edit or insert or by clicking the ``X'' button to the right of the
  548. entry area.
  549.  
  550. When you are satisfied with the current contents of the edit area, hit
  551. Return or click the ``!'' button to the right of the entry area and the
  552. transaction will be updated. If you are creating a new transaction, it will
  553. be inserted. If if you are editing an existing transaction, it will be
  554. updated.
  555.  
  556. 4.2.2 General Key Bindings
  557.  
  558. Tk4.x provides several standard key bindings to facilitate data entry. These
  559. tend to mimic emacs key bindings. Figure 1 shows a list of some of the more
  560. useful of these key bindings. For those hackers among us: look in
  561. $(TK_LIB_DIR)/entry.tcl for a complete list of key/mouse bindings.
  562.  
  563.    [figure117]
  564. Figure 1: General Key Bindings.
  565.  
  566. 4.2.3 Specific Key Bindings for the Check Number field
  567.  
  568. When the focus is in the check number field you can use the + and - keys to
  569. increment and decrement the number. CBB remembers the last check number you
  570. used, so when you are creating a new transaction, pressing + will insert the
  571. next check number. Figure 2 shows a list of these key bindings.
  572.  
  573.    [figure142]
  574. Figure 2: Check Number Field Bindings.
  575.  
  576. 4.2.4 Specific Key Bindings for the Date field
  577.  
  578. The + and - keys work as you expect when the focus is in the date field.
  579. They will increment or decrement the date. CBB tries to keep track of things
  580. like leap year or even the number of days in a specific month. So, if CBB
  581. generates an illegal date such as 2/30/97 please report this as a bug.
  582. Figure 3 shows a list of these key bindings.
  583.  
  584.    [figure164]
  585. Figure 3: Date Field Bindings.
  586.  
  587. 4.2.5 Splits
  588.  
  589. The Splits function allows you to ``split'' the value of a transaction among
  590. several different categories. Caution: Even though you may click Dismiss in
  591. the Splits window, the transaction will not be updated. You need to hit
  592. Return or click the ``!'' button again once the splits window is closed.
  593. Note: If the splits window does not provide enough lines, you can increase
  594. the maximum number of splits in your .cbbrc.tcl file.
  595.  
  596. 4.2.6 Memorized Transactions
  597.  
  598. CBB keeps a list of transactions sorted and indexed by the description. When
  599. entering a typical transaction you would normally first specify the check
  600. number, then specify the date, then specify the description. If you have
  601. entered a similar transaction in the past, then you only need to type the
  602. first few characters of the description, hit Tab and the rest of the
  603. transaction is filled in for you. At this point you should make any
  604. necessary changes. Finally, you can update the transaction by hitting
  605. Return.
  606.  
  607. If you don't want your transaction completed (i.e. your transaction is being
  608. completed in an undesired fashion) you can type Control-Tab in the
  609. description field to avoid the completion feature.
  610.  
  611. The transaction is auto-completed only once per transaction. In other words,
  612. your changes won't keep getting overwritten each time you tab through the
  613. description field. Also, this feature is only activated by Tabbing from the
  614. description field. Shift-Tabbing or pressing Return have the same effect as
  615. they do in any other field.
  616.  
  617. Note: You can turn this feature on and off from the File -> Preferences
  618. menu.
  619.  
  620. 4.3 Categories
  621.  
  622. Categories are used to give each transaction a ``type.'' This is useful for
  623. reporting, since the report can be organized by category.
  624.  
  625. 4.3.1 Viewing Categories
  626.  
  627.  
  628.  
  629. Categories can be viewed by typeing <Meta-C> or selecting Categories ->
  630. Category List ... from the Functions menu. This brings up a list of
  631. categories. When the category list is open, double clicking on an category
  632. will paste it into the current entry. Alternatively, you can select a
  633. category and click on the Paste button.
  634.  
  635. 4.3.2 Creating Categories
  636.  
  637. Adding a category is as easy as using it in a transaction. When the
  638. transaction is updated, and the category is unknown, you will be asked if
  639. you wish to add the new category. Simply fill in the category description
  640. and check the Tax Related box (if it is tax related.) Once you are
  641. satisfied, click on the Add button.
  642.  
  643. Alternatively, you can bring up the category list and click on the Add
  644. button.
  645.  
  646. As a last resort, you can manually edit the categories file. CBB stores the
  647. category file in the same subdirectory as the associated account file. Note,
  648. the fields are delimited by tabs. Have fun and be careful if you try this!
  649.  
  650. 4.3.3 Deleting Categories
  651.  
  652. Once the category list window has been opened (see Section 4.3.1) simply
  653. select a category and click on the Delete button and the category will be
  654. deleted.
  655.  
  656. 4.4 Transfers Between Accounts
  657.  
  658.  
  659.  
  660. When an account is created, a category of the form [acct-name] is also
  661. created. To create a transfer to another account, use the destination
  662. account name (enclosed in [ and ]) to specify the account being transfered
  663. to. When the transaction is inserted into the current account a
  664. corresponding transaction will be inserted in destination account.
  665.  
  666. WARNING: currently when a transfer transaction is edited or deleted, its
  667. corresponding transaction in the other account should be automatically
  668. changed as well. This code is not well tested at this time, so keep your
  669. eyes open if you edit transfer transactions and make sure the corresponding
  670. changes get made on the other end. CBB will warn you whenever you edit or
  671. delete a transfer transaction.
  672.  
  673. 4.5 Balancing
  674.  
  675. Clicking on the Balance button will bring up a list of all ``uncleared''
  676. transactions in a window. CBB already knows your statement beginning
  677. balance. It is simply the sum of all the cleared transactions. Verify your
  678. statement's beginning balance then enter your ending balance. Then go
  679. through all your ``uncleared'' transactions and check off all that are
  680. listed on your statement. CBB will keep a running total of the beginning
  681. balance + the transactions. When you are all done, this should equal the
  682. ending balance. If it doesn't, there is a discrepancy someplace ...which
  683. will hopefully be not too hard to track down. When everything matches, click
  684. on the Update button. This will ``clear'' all the selected transactions.
  685. When you balance your checkbook next month, only the ``uncleared''
  686. transactions will be presented to you.
  687.  
  688. This technique makes it easy to spot and handle situations when some
  689. ``individual'' doesn't cash your check for 3 months ...it is still in the
  690. system and easy to spot. This way your idea of your balance stays in sync
  691. with the bank's idea of your balance. And since it is entered into CBB and
  692. subtracted from your running balance, you won't get burned when they finally
  693. do cash it.
  694.  
  695. If you notice a discrepancy that needs to be fixed while balancing, you can
  696. bring the main CBB window forward and make your changes. Then, bring the
  697. balance window forward and click the Refresh button. This will bring the
  698. balance window back in sync with the main window. Alternatively you could
  699. close and reopen the balance window.
  700.  
  701. 4.6 Reporting
  702.  
  703. As of version 0.60 of CBB, I have completely reworked the reporting
  704. mechanism. Each report is actually a stand-alone, self-sufficient,
  705. executable perl script (although there is nothing magical about the use of
  706. perl, they could be written in any language.)
  707.  
  708. When you select a Reports ... you are presented with a dialog box. In this
  709. dialog box you can select the report you would like to print, the files you
  710. would like to include in the report, a date range, and report destination.
  711. If you wish to include all transactions up to a certain date, leave the
  712. Starting Date field blank. If you wish to include all transactions from a
  713. certain date on, leave the Ending Date field blank. To include all
  714. transactions leave both fields blank. Dates should be in the following
  715. format: mm/dd/[[yy]yy]. Valid dates are 5/19, 5/19/95, and 5/19/2095.
  716.  
  717. Reports can be printed to a variety of destinations. If you select Send to
  718. Screen the report will be displayed in a window. If you select Save to File
  719. or Pipe, enter a file name in the appropriate field and the report will
  720. saved to that file. If you specify a file name of the form | command, CBB
  721. will pipe the output of the report through the specified command. For
  722. instance, if you wanted to send the report to a printer, you could enter
  723. something like:
  724.  
  725.     | nenscript -2Gr | lpr -d hp4L
  726.  
  727. 4.6.1 Transaction List
  728.  
  729. The first report is simply a list of all transactions. It looks remarkably
  730. like the contents of the transaction list box.
  731.  
  732. 4.6.2 Transaction List By Category
  733.  
  734. The next report displays all transactions sorted and subtotaled by category.
  735. It properly handles splits.
  736.  
  737. 4.6.3 Short List By Category
  738.  
  739. This report is similar to the Transaction List By Category report except it
  740. omits the individual transactions and only displays the sum of the
  741. transactions for each category. It also properly handles splits.
  742.  
  743. 4.6.4 Missing Checks
  744.  
  745. This report will scan through all the transactions of the selected accounts
  746. and find any breaks in the sequence. It will also flag any duplicate check
  747. numbers.
  748.  
  749. 4.6.5 Average Monthly Expenses by Category
  750.  
  751. This report is a nice tool to assist in budgeting. It will show your average
  752. monthly expenses for each category.
  753.  
  754. 4.7 Graphing
  755.  
  756. Graphing is very similar to reporting. Each graph is actually a stand-alone,
  757. self-sufficient, executable perl script which process the input data and
  758. calls a second Tk script to display the result.
  759.  
  760. When you select a graph you are presented with a dialog box similar to the
  761. one presented for report printing. You can select a graph, group of input
  762. files, and a date range. If you wish to include all transactions up to a
  763. certain date, leave the Starting Date field blank. If you wish to include
  764. all transactions from a certain date on, leave the Ending Date field blank.
  765. To include all transactions leave both fields blank. Dates should be in the
  766. following format: mm/dd/[[yy]yy]. Valid dates are 5/19, 5/19/95, and
  767. 5/19/2095.
  768.  
  769. 4.7.1 Graph of Running Balance
  770.  
  771. This graph is analogous to the ``Transaction List'' report. It simply plots
  772. a graph of your running balance over the specified date range.
  773.  
  774. 4.8 Preferences
  775.  
  776. Currently, preferences need much work ...However, you can set a few things
  777. including fonts in your .cbbrc.tcl file.
  778.  
  779. If you have your own custom Tcl code you would like to include (such as
  780. setting your favorite key bindings) you can created a file called .wishrc in
  781. your home directory and place the code there. CBB will source this file if
  782. it exists after it sources your .cbbrc.tcl file.
  783.  
  784. 4.9 Saving your work
  785.  
  786. All changes must be saved--or how could they be called changes.
  787.  
  788. CBB is similar to vi or emacs in that all your changes are made in RAM. So,
  789. just like you must save your work in vi or emacs, you must save your work in
  790. CBB. To do this, click on the Save button or select Save Account or Save
  791. Account As ... from the File menu.
  792.  
  793. CBB has an ``auto save'' feature. Your proposed changes are saved to a
  794. temporary file at regular intervals. (This interval defaults to 3 minutes
  795. and can be set in your .cbbrc.tcl file.) If CBB is killed or crashes, the
  796. autosave file will be left intact. When you startup CBB and load the
  797. account, CBB will notice the autosave file and ask you if you would like to
  798. use it instead.
  799.  
  800. And, as my great grandfather always said, ``save early and save often!''
  801.  
  802. 4.10 Importing and Exporting
  803.  
  804. 4.10.1 Importing from Quicken
  805.  
  806.  
  807.  
  808. CBB is capable of importing Quicken export files. These files are of the
  809. form <name>.qif. The transfer process is relatively simple.
  810.  
  811.   1. Boot dos/windows. (dosemu?!?, wine?!? - anyone?) Run Quicken and open
  812.      up the desired account.
  813.   2. From the File menu, choose Export->Export QIF and specify the export
  814.      file name. This should be <name>.qif
  815.   3. Once the file is created, copy this file to someplace where you can
  816.      access it from Linux.
  817.   4. Now, quickly exit from dos/windows before it begins to corrupt your
  818.      mind or your machine--you stinkin' Bill Gates lover.
  819.   5. Boot Linux! Whew ...much better!
  820.   6. Run cbb.
  821.   7. Make a new account. (Or load an existing account if you wish to import
  822.      the transaction into it.)
  823.   8. Select Import QIF File ... from the File menu and select the file you
  824.      wish to import. Click on the Import button and the file will be
  825.      imported into a New account.
  826.  
  827. 4.10.2 Exporting to Quicken
  828.  
  829. CBB is also capable of generating Quicken export files. These files can be
  830. imported into Quicken. This process is also relatively simple.
  831.  
  832.   1. Run cbb.
  833.   2. Load the account you would like to export.
  834.   3. Select Export QIF File from the File menu. A file called
  835.      <acct-name>.qif will be created.
  836.   4. Move this file to dos/windows side of the world. (Use your favorite
  837.      method.)
  838.   5. Boot dos/windows, run Quicken. (At this point things begin to get hazy
  839.      since I've never done this ...use your noggin ...it can't be that
  840.      hard.)
  841.   6. From the File menu, choose Import and specify the Import file name.
  842.      This should be <acct-name>.qif
  843.   7. You are on your own. Enjoy your stay in dos/windows land. Say ``Hi!''
  844.      to our buddy, Bill G. for me while you are there. And while you are at
  845.      it, please let me know what I can do to win back your business. :-)
  846.  
  847. 4.11 Security Issues
  848.  
  849. Computer security is a lot like other types of security. There is no such
  850. thing as a perfect secure computer system or network. For every protection
  851. you put in place, some clever person will be able to devise a way to
  852. circumvent it. Usually when a cracker is discovered, whatever hole they
  853. leveraged to gain their illegal access can be closed. The cracker then
  854. proceeds to find a new hole. It is a never ending cycle.
  855.  
  856. Having said that, there are steps you can take to protect your personal
  857. privacy and make sure that any violation is intentional and nonaccidental.
  858.  
  859. If you are the only user of a non-networked machine, this section will
  860. probably not be your biggest concern, however, if you use CBB on a shared
  861. machine, please read on. You may wish to protect your personal financial
  862. data from being potentially viewed by others.
  863.  
  864. 4.11.1 Umasks and Default Permissions
  865.  
  866. Starting with version 0.73, CBB sets it's umask to 0066. For those of you
  867. who aren't brushed up on bitmasks and octal numbers, this means that your
  868. data files are made to be read/write by only you. This is equivalent to
  869. executing chmod 600 file.cbb from the Unix command line. This means that
  870. only you or the ``super-user'' are allowed to read or modify your data.
  871.  
  872. 4.11.2 Data Encryption
  873.  
  874. Making your data non-readable to everyone but yourself is usually sufficient
  875. in most normal circumstances. However, the most vigilant (or paranoid) users
  876. might like the additional security of keeping their data encrypted. CBB is
  877. now capable of calling an external encryption program such as ``crypt'' or
  878. ``pgp'' to encrypt and decrypt your data as needed.
  879.  
  880. WARNING: The first rule of encryption says that using cryptography programs
  881. without a proper level of understanding of what is going on is usually worse
  882. than not using any encryption at all!!!
  883.  
  884. There are many pitfalls here, so proceed only if understand what encryption
  885. can and cannot do for you, and only if you know what you are doing (in
  886. general), and make sure to keep good backups of your data (in a secure
  887. location, otherwise what good is encryption.)
  888.  
  889. Enabling Encryption:
  890.  
  891. In order to use the encryption features, you have to check the button Use
  892. Cryptography in the Preferences menu.
  893.  
  894. If there are no cryptography programs already defined, you will then be
  895. asked to enter your encryption and decryption program and options.
  896.  
  897. Compatible Encryption Software:
  898.  
  899. Basically you can use any program that follows the following criteria:
  900.  
  901.    * Accepts input from stdin (the data to be encrypted/decrypted).
  902.    * Writes output to stdout (the data to be encrypted/decrypted).
  903.    * Accepts the passing of the key (cryptcode) as the last argument in the
  904.      commandline.
  905.    * It should be able to identify unencrypted data and pass it along when
  906.      decrypting (if you want to be able to load unencrypted when in
  907.      encryption mode - this is very convenient for converting data.)
  908.  
  909. PGP fulfills these requirements if you use the following options:
  910.  
  911. Encryption:
  912.      ``pgp -fc -z''
  913. Decryption:
  914.      ``pgp -f -z''
  915.  
  916. If you specify the encryption code of ``secret,'' CBB will then invoke pgp
  917. with pgp -fc -z secret to encrypt and pgp -f -z secret to decrypt the data.
  918.  
  919. Note that this does not use public key cryptography, but simply uses the
  920. IDEA algorithm to encrypt the data.
  921.  
  922. This way of passing the code is also a possible security leak on some
  923. systems, because other users might be able to snoop the command line
  924. arguments to pgp (Linux allows pgp to blank out this particular argument, so
  925. you cannot see it with ps -e).
  926.  
  927. There might be other security risks in this way of handling encryption, so
  928. please check the pgp manual.
  929.  
  930. Configuring the Key:
  931.  
  932. After having entered the encryption and decryption progam, you will be asked
  933. for the ``cryptcode'' (the key). You have to enter it twice (you don't want
  934. to lose data because you encrypted it with a mistyped key), and instead of
  935. letters, there should appear only "*" in the entry box.
  936.  
  937. Saving the Preferences:
  938.  
  939. If you now save an account, it will be encrypted. Also the preferences will
  940. be saved (they get saved each time you save an account - and only then, so
  941. save an account after changing them.) This does save the ``encrypted mode''
  942. flag, and the encryption and decryption commands. It does not save the
  943. cryptcode (you don't want to read it in your preferences file, do you).
  944.  
  945. Other Items to Note:
  946.  
  947. When ``encrypted mode'' is entered, logging is turned off (no sense in
  948. having encrypted data files, if your transaction log is unencrypted). It is
  949. turned back on, if you leave ``encrypted mode.''
  950.  
  951. If you are in ``non-encrypted mode,'' you will notice that your encrypted
  952. accounts don't show any balances in the account-list anymore.
  953.  
  954. If cbb gets started in ``encrypted mode'' it will ask you automatically for
  955. your ``cryptcode'' before starting.
  956.  
  957. Possible Bugs:
  958.  
  959.    * Pressing cancel in the different crypto-windows might not reset
  960.      non-encrypted mode.
  961.    * Add-ons (or external scripts) that rely on being able to read the files
  962.      directly will not work anymore.
  963.    * No error is reported when opening an account with a bad cryptcode (it
  964.      just does not show you any entries, and allows you to overwrite the
  965.      account with a blank account. This is not really a security risk, since
  966.      someone who can overwrite an account from within cbb can do the same
  967.      from the command line. But it is a data loss risk.
  968.  
  969. 5 Contributed scripts
  970.  
  971. This section describes several scripts that are beyond the original scope of
  972. CBB, yet may be useful in managing your money. These scripts are installed
  973. in: $CBB_LIB_DIR/contrib
  974.  
  975. 5.1 Fetching and Installing the Latest Greatest CBB
  976.  
  977.  
  978.  
  979. The script fetch-latest.pl will automatically fetch the latest version of
  980. CBB from ftp.me.umn.edu. It will then untar and gunzip it. Finally it will
  981. run the standard install procedure to install it.
  982.  
  983. You can run this script from within CBB by selecting Fetch & Install Latest
  984. CBB from the External menu. Then, answer the standard install questions when
  985. prompted. Don't forget to quit and restart CBB once the install has
  986. completed successfully.
  987.  
  988. 5.2 Investment Accounts
  989.  
  990. The script invest.pl is a simple hack to help keep track of your
  991. investments. An alternative would be to use a real application like
  992. ``Xinvest''. A pointer to Xinvest can be found on the CBB web page.
  993.  
  994. The invest.pl accepts a simply formatted text file from stdin and writes a
  995. simple report to stdout. A sample input file could look like the following.
  996. Note: each field is separated by one or more tabs.
  997.  
  998. # Date          Description             Shares  Unit Price
  999. #-----          -----------             ------  ----------
  1000. 19960101        Beginning of 1996       10.000  25.00
  1001. 19960201        Updated value           0.000   26.56
  1002. 19960301        Purchase more shares    10.00   25.87
  1003. 19960401        Updated value           0.000   26.04
  1004. 19961216        St Cap Gain Reinvest    1.157   26.43
  1005. 19961216        Lt Cap Gain Reinvest    1.220   26.43
  1006. 19961216        Service Fee             -0.568  26.43
  1007.  
  1008. Executing the command: cat sample.inv | invest.pl would produce the
  1009. following output:
  1010.  
  1011.                                         Price   Total
  1012.                                 New     per     Shares  Total   Total
  1013. Date     Description            Shares  Share   Owned   Invstd  Value
  1014. -------- ---------------------- ------  ------  ------  ------  ------
  1015. 19960101 Beginning of 1996      10.000  25.00   10.000  250.00  250.00
  1016. 19960201 Updated value          0.000   26.56   10.000  250.00  265.60
  1017. 19960301 Purchase more shares   10.000  25.87   20.000  508.70  517.40
  1018. 19960401 Updated value          0.000   26.04   20.000  508.70  520.80
  1019. 19961216 St Cap Gain Reinvest   1.157   26.43   21.157  539.28  559.18
  1020. 19961216 Lt Cap Gain Reinvest   1.220   26.43   22.377  571.52  591.42
  1021. 19961216 Service Fee            -0.568  26.43   21.809  556.51  576.41
  1022.  
  1023. 5.3 Migrating from Previous Data File Formats
  1024.  
  1025. Please see section 2.7, page [gif]  for an explanation of this script and
  1026.  
  1027. its use.
  1028.  
  1029. 5.4 Managing Recurring Transactions
  1030.  
  1031. Wouldn't you like your mortgage payment to entered automatically every
  1032. month? Would you like to have some idea of how much money you will have in a
  1033. month, six months, or a year? Then read on. This might be just what you
  1034. need.
  1035.  
  1036. Recurring transactions which have been automatically inserted are denoted by
  1037. placing a ``?'' in the ``cleared'' field. This is changed to a ``!'' when
  1038. the transaction date has passed. (Note: this code is changed to a ``x'' when
  1039. the transaction is cleared.)
  1040.  
  1041. 5.4.1 Overview of the recur.pl script
  1042.  
  1043. The recur.pl script has two main sections.
  1044.  
  1045.   1. The first thing the script does is traverse the account looking for any
  1046.      transactions with a ``?'' in the cleared field. Of these transactions,
  1047.      those which have a date older than today's date will have their cleared
  1048.      field changed to a `` !''. Those transactions with a future date will
  1049.      be deleted. (They will be reinserted in the next step.)
  1050.   2. The last thing thing the script does is to traverse the .rcr file for
  1051.      the account and reinsert all future entries up until the cutoff date.
  1052.      At this time the cutoff date is set for a year in advance, but this can
  1053.      be changed by editing a variable at the beginning of the recur.pl
  1054.      script.
  1055.  
  1056. 5.4.2 Config file format
  1057.  
  1058. The config (<account>.rcr) file is reminiscent of a crontab file. The format
  1059. is slightly different, but the idea is generally the same. Specify the days,
  1060. months, and years that the transaction will take place, then specify the
  1061. transaction. One thing to note is that all fields must be separated by one
  1062. <Tab> character. The script will then insert that transaction on those days.
  1063.  
  1064. For instance, the following entry will cause an auto loan payment to be
  1065. inserted on the fifth of every month. Once the transaction has been entered,
  1066. you can make any changes you like to it, such as adding
  1067.  
  1068. # Days  Months  Years   Description     Debit   Credit  Comment Category
  1069. # ----  ------  -----   -----------     -----   ------  ------- --------
  1070. 5       *       *       Loan's R Us     100.00  0.00            Auto-Loan
  1071.  
  1072. Another variation would be the following entry which will insert a
  1073. transaction every fourth of July.
  1074.  
  1075. 4       7       *       Fireworks       35.00   0.00   Bang     Entertainment
  1076.  
  1077. The next entry will insert a transaction on the 15th and last day of every
  1078. month.
  1079.  
  1080. 15,last *       *       Salary          0.00    3.14   Peanuts  Salary Income
  1081.  
  1082. This entry will insert a transaction on the 1st day of January, April, July,
  1083. and October.
  1084.  
  1085. *       1,4,7,10  *     Auto Insurance  200.00  0.00   Approx.  Insurance
  1086.  
  1087. REMEMBER, separate each field by a <Tab> character and not spaces.
  1088.  
  1089. Finally, a slightly different entry format will allow you to enter
  1090. transactions based on a regular interval such as every other week. The first
  1091. field specifies the start date of the interval. This can be any date, but
  1092. recur.pl will never enter past recurring transactions. The transactions will
  1093. kick in after the current date. Then next field is the interval in days. So
  1094. 14 would specify an interval of every other week. The third field is ignored
  1095. and not used. The last five fields are identical to the previous types of
  1096. entries.
  1097.  
  1098. # Start Date  Intrvl Not Used  Description  Debit  Credit  Comment  Category
  1099. # ----------  ------ --------  -----------  -----  ------  -------  --------
  1100. 19960119      14     *         Salary       0.00   2.78    Peanuts  Salary
  1101.  
  1102. 5.5 Keeping a Manageable Data File Size
  1103.  
  1104. The script yearend.pl simply moves all uncleared transactions from the
  1105. specified account to a new account. This helps keep file sizes smaller.
  1106. Usage: yearend.pl <account>.cbb <new-account>.cbb
  1107.  
  1108. 5.6 Alternative Interfaces to CBB
  1109.  
  1110. A number of people have enquired about text interfaces to CBB. Currently
  1111. there is no complete solution, but there are a few options. Note, rumor has
  1112. it that someone is working on a dialog interface to CBB, I look forward to
  1113. seeing this when it is ready.
  1114.  
  1115. 5.6.1 Txn
  1116.  
  1117. Christopher B. Browne (cbbrowne@unicomp.net) has provided a perl script
  1118. called txn. It will append records to .cbb files, and do so from the command
  1119. line. For instance:
  1120.  
  1121. [25%] txn checking -t '75' 'The Mansion in Dallas' Lunch 75.00 'Gratuitously
  1122. expensive luncheon'
  1123.  
  1124. Added to /home/cbbrowne/kwiken/checking.cbb
  1125. 19970422 75 The Mansion in Dallas 75.00 0 Lunch Gratuitously expensive
  1126. luncheon
  1127.  
  1128. This script does have certain limitations:
  1129.  
  1130.    * It appears that ``splits'' have been changed somewhat; I haven't
  1131.      checked yet to see if they are handled correctly.
  1132.    * Writing to a .cbb file whilst the TCL version is open and using the
  1133.      file in question will have obviously questionable results. If Curt
  1134.      implements his file locking idea (which probably ought to put the PID
  1135.      of the main CBB process in either /var/lock/LCK..cbb or do individual
  1136.      file locks like /var/lock/LCK..checking.cbb), I could have txn look for
  1137.      and/or lock these...
  1138.    * You'll have to modify the paths at the start of the script to locate
  1139.      your favorite CBB directory.
  1140.    * This script assumes that if the category is not available that you can
  1141.      look at a list of similar category names and pick one. If you plan to
  1142.      write scripts that will create transactions as ``batch jobs,'' then
  1143.      you'll have to ensure that the category is correct. I'm not sure how to
  1144.      best deal with the error condition of not having a correct category.
  1145.      Create ``ntxn'' (non-interactive txn) that reports an error and dies
  1146.      upon receiving a bad category, perhaps? An additional command line
  1147.      switch? Ideas anyone?
  1148.    * I have no further intentions to maintain the code that allowed
  1149.      deletion/reconciliation from the command line. The cbbsh of 1994 did
  1150.      provide this functionality, at the cost of a fairly painful user
  1151.      interface. It just makes too much sense to do transaction editing with
  1152.      a somewhat ``GUIed'' interface to bring most of the remainder of CBBSH
  1153.      up to date.
  1154.  
  1155. 5.6.2 Emacs Forms Mode
  1156.  
  1157. Ravinder Bhumbla (rbhumbla@atol.ucsd.edu) has contributed an Emacs
  1158. forms-mode for browsing/editing .cbb files from within Emacs. Emacs version
  1159. 19 has a forms mode which can be used to browse regularly ordered data. It
  1160. is a convenient tool when you are not at an X terminal.
  1161.  
  1162. Just read the file .../contrib/emacs-forms into an Emacs buffer. Edit the
  1163. path to your .cbb file where it says ``EDIT HERE'' and then type M-x
  1164. forms-mode. Emacs will ask if you want to evaluate the current buffer
  1165. contents. Type ``yes''. (Ravi)
  1166.  
  1167. 5.6.3 Your Favorite Editor
  1168.  
  1169. CBB stores it's data file in a simple tab-delimited format. If you are
  1170. careful about maintaining the correct tab-delimited format, it is quite
  1171. possible to edit your files with just about any text editor. You will
  1172. definitely want to make a backup copy of your .cbb file before attempting
  1173. this. It is very easy to make a mistake and corrupt a transaction record.
  1174. However, this can be a useful technique for many tasks.
  1175.  
  1176. For instance, lets say my wife just informed me that comestibles are spelled
  1177. ``Food'' not ``Fude''. I could use a text editor to do a global substition
  1178. through my entire .cbb file to fix this mistake. Another use could be for
  1179. deleting or duplicating blocks of transactions.
  1180.  
  1181. This simple format gives you last-resort options when you need to do
  1182. something that the graphical interface was not designed to do.
  1183.  
  1184. 5.6.4 Other Options
  1185.  
  1186. Most spreadsheets and database applications can load tab-delimited files.
  1187. This is another alternative for manipulating or viewing .cbb files in ways
  1188. that the graphical front end cannot.
  1189.  
  1190. 6 CBB Internals
  1191.  
  1192. 6.1 The ``.cbbrc.tcl'' File
  1193.  
  1194. CBB stores the values of a few standard variables in the .cbbrc.tcl file.
  1195. Whenever CBB starts, it first sources this file. This file is regenerated
  1196. based on the current value of the relevant variables whenever an account is
  1197. created, loaded, or saved. Any additions/deletions will be lost. However,
  1198. changes to the values of the variables will be maintained. Some of the
  1199. preferences that can be set in your .cbbrc.tcl file are: debugging on or
  1200. off, balloon help on or off, USA or international date format, autosave
  1201. interval, main list box dimensions, account list box height, maximum number
  1202. of splits, font selection, color selection, and your favorite web browser.
  1203. Please look in your .cbbrc.tcl for a complete and current list of
  1204. preferences that can be set.
  1205.  
  1206. 6.2 The External Menu
  1207.  
  1208. CBB has a user configurable menu entitled External. The file extern.conf
  1209. controls the contents of this menu. An example of an extern.conf file is:
  1210.  
  1211.     Calculator <Tab> xcalc
  1212.     Calendar   <Tab> ical
  1213.  
  1214.     -
  1215.  
  1216.     Install the Latest CBB   <Tab> xterm -sb -e \
  1217.         \$lib_path/contrib/fetch-latest.pl
  1218.  
  1219. The first field (everything before the <tab>) is the name to appear on the
  1220. External menu. The second field (everything after the <tab> is the command
  1221. line of the program to execute. Before launching the external program, CBB
  1222. will save the current contents of the buffer to a temporary file. This
  1223. allows the external program to have access to any changes that have been
  1224. made, but not yet saved. The %t is replaced with the full path name of this
  1225. temporary file. The %a is replaced with the full name of the current account
  1226. file.
  1227.  
  1228. 6.3 Creating and Installing New Reports
  1229.  
  1230. CBB has a ``simple'' well defined interface for installing new reports. Each
  1231. report is a stand alone ``program'' which understands a predefined set of
  1232. command line options and displays its output to stdout.
  1233.  
  1234. When the Configure Reports program is launched, it looks for the file,
  1235. .../lib/cbb/reports/reports.conf. This file consists of entries like the
  1236. following:
  1237.  
  1238.   Transaction List        rep-txn-list.pl
  1239.   Txn List by Category    rep-by-cat.pl
  1240.   Short List by Category  rep-by-cat-shrt.pl
  1241.  
  1242. Each line contains two fields. The report name which will appear in the
  1243. dialog box, and the executable name of the report. CBB scans this file when
  1244. it starts up in order to create the Reports menu.
  1245.  
  1246. CBB assumes that all report executables will also be located in the
  1247. .../lib/cbb/reports/ directory. Each report must accept the following
  1248. options where date if of the form mm/dd/[yy[yy]] and account-list is a list
  1249. of a CBB (ASCII) format account files:
  1250.  
  1251.   Usage:  report [ -from date ] [ -to date] account-list
  1252.  
  1253. The report executable will read the entries in the specified account files,
  1254. ignore any entries outside the specified date range, and print its output to
  1255. stdout. The last thing the report should print is a single line containing
  1256. the text none.
  1257.  
  1258. When a report is selected from the Reports menu, CBB displays the Report
  1259. Configuration dialog box. When the user clicks on Generate Report, CBB saves
  1260. the current contents of its ``buffer'' to a temporary file. It then looks up
  1261. the corresponding report executable, and launches it with the above options.
  1262. CBB reads the output of the executable (stopping when it receives a line
  1263. containing only the text none) and routes it according what the user
  1264. specified in the Report Configuration dialog box.
  1265.  
  1266. 6.4 Creating and Installing New Graphs
  1267.  
  1268. The procedure for creating and installing new graphs is analogous to the
  1269. reports procedure. One thing to note, the graph executable should wait for a
  1270. carriage return from stdin before exiting. This is CBB's way of letting the
  1271. graph executable know that the user is done looking at the graph.
  1272.  
  1273. 6.5 The Devel Menu
  1274.  
  1275. When CBB is invoked with the -devel option, a Devel menu is added to the
  1276. menu bar. This menu will allow you to re-``source'' the various Tk pieces of
  1277. CBB. With this option enabled you can reload various pieces of the code
  1278. after modifying them without quiting and restarting CBB. This can greatly
  1279. speed up the development process in some situtations.
  1280.  
  1281. This works by executing the Tk source command on the selected file. To use
  1282. this feature effectively, you need to be aware of the contents of a
  1283. particular Tk file. Effectively, you are re-running that code at the time
  1284. you are sourcing it. Therefore, old procedure definitions will be replaced
  1285. if they were changed. The thing to watch out for is code that is executed
  1286. outside of procedure calls. This code will be executed when you re-source
  1287. the file. This may or may not cause a problem if this code is intended to be
  1288. run only once on startup.
  1289.  
  1290. Activating and using this menu is something you only need to be concerned
  1291. about if you are actively developing code.
  1292.  
  1293. 6.6 Logging
  1294.  
  1295. 7 Frequently Asked Questions
  1296.  
  1297. The FAQ tends to resist emacs TeX mode. This is most annoying. Because of
  1298. this I have placed the FAQ in its own separate file called ...Ta da!!!
  1299. ...``FAQ''. The FAQ is also available on the CBB web page at:
  1300. http://www.menet.umn.edu/~clolson/cbb/
  1301.  
  1302. About this document ...
  1303.  
  1304. CBB
  1305. A Check Book Balancer
  1306. for Unix/X11
  1307.  
  1308. This document was generated using the LaTeX2HTML translator Version 96.1-h
  1309. (September 30, 1996) Copyright ⌐ 1993, 1994, 1995, 1996, Nikos Drakos,
  1310. Computer Based Learning Unit, University of Leeds.
  1311.  
  1312. The command line arguments were:
  1313. latex2html -split 0 -show_section_numbers cbb-man.tex.
  1314.  
  1315. The translation was initiated by Curtis L. Olson on Tue May 6 20:38:52 CDT
  1316. 1997
  1317. ----------------------------------------------------------------------------
  1318. [next] [up] [previous]
  1319.  
  1320. Curtis L. Olson
  1321. Tue May 6 20:38:52 CDT 1997
  1322.