beancount.el commands/usage

[Jonathan Goldman]

Hi all,

Apologies for this newbie question but I'm not sure of the commands/usage when you have beancount.el installed. I'm not familiar with how to read the code for it and haven't found much documentation and I'm not familiar with what org mode could do.

I have found auto-completion for accounts when typing tab for transactions which is very useful. I also found this summary by Alex Johnstone. 

My understanding from reading was the beacount.el is now a major mode that incorporates some of org mode functionality. Is that right? 

Can I collapse sections (e.g. all of 2018 entries)? 

For entering current date is there a quick command?

What functionality/capabilities to people use from beacount.el? 

How do you typically use the capabilities of emacs and beacount.el to enter data and do most people organize chronologically? I was thinking of having the following organization for transactions

*YEAR

**MONTH

***ACCOUNT1

***ACCOUNT2

thanks,

Jonathan

[TRS-80]

On 2019-12-30 23:42, Jonathan Goldman wrote:
> Hi all,
>
> Apologies for this newbie question but I'm not sure of the

> commands/usage when you have beancount.el [1] installed. I'm not

> familiar with how to read the code for it and haven't found much
> documentation and I'm not familiar with what org mode could do.

Orgmode is an excellent tool for note taking, capturing code
snippets, and many other jobs. I have been using it for years to
document projects, keep TODOs, and keep a personal wiki.

IMO, it is well worth spending a few minutes learning some of its
functionality. And Orgmode itself is actually quite
straightforward, really.

I often refer to it as "the gateway drug to Emacs" :) but you
didn't really say if you are familiar with Emacs itself or
not (Emacs I would say is a little more learning curve than
Orgmode).

> My understanding from reading was the beacount.el is now a major mode
> that incorporates some of org mode functionality. Is that right?

My information very likely may be out of date, but last I knew
beancount.el was a minor mode, with Orgmode being the major
mode. There was some discussion a while back on mailing list
about changing this, but I don't know if that ever happened or
not.

> Can I collapse sections (e.g. all of 2018 entries)?

Yes. Just put point (cursor) on the heading row (the one with
*(s)) and press <TAB>. You can cycle folding by pressing <TAB> 3
times. If you hold <Shift> + <TAB>, you can cycle the whole document.
Otherwise without <Shift> you will cycle only the branch that point is
on.

> For entering current date is there a quick command?

In Orgmode, there is C-c ! but that will give you something that
looks like [2020-02-24 Mon] which is Org (not beancount) date format.

The great thing about Emacs though is that it would be pretty
easy to write your own Emacs lisp function to do something like
this. Which is sort of the whole point of Emacs (i.e., "the
/extensible/ text editor"). ;)

If you are interested in doing that, just have a look at the
introduction to Emacs Lisp that is included in Emacs help.

It occurred to me to write such function, then I realized the reason
it's not already included is that most of the time we are probably
entering back dated transactions. So this would only be useful if you
keep up with entering stuff daily. And if you can manage that, you
likely have even more time than I do to write such function. ;)

> What functionality/capabilities to people use from beacount.el?

Neat formatting (alignment of transactions), completion (as you
found out), syntax highlighting mainly. There may be others and
things may have been added in the meantime that I am not aware of
as well.

> How do you typically use the capabilities of emacs and beacount.el to
> enter data and do most people organize chronologically? I was thinking
> of having the following organization for transactions
> *YEAR
> **MONTH
> ***ACCOUNT1
> ***ACCOUNT2

Personally, my work flow is to import transactions in groups from
CSV files and convert them into Beancount format with the generic
CSV Importer. I also slightly customized it to do very simple
pattern matching on the vendor / description and assign an
Expense account from that. Then I go through and double check /
tweak / verify each entry, add notes, etc. Finally I manually
copy the transactions into the appropriate place(s) in my
.beancount file using beancount.el mode in Emacs for features
mentioned above.

Having said that, many people have many different work flows. Martin
(used to anyway) advocate for entering all stuff manually in order to
keep up with doing it frequently and there is some value to that,
too. Other people use more advanced importers with heuristics that
lern over time and do suggestions (there are a couple different ones I
think), etc.

Organization is subject to debate, preferences, and personal
circumstances; however generally I follow Martin advice for
organizing Chart of Accounts like:

Type:Institution:Account

for example:

Assets:Self:Cash
Assets:BankName:Checking
Liabilities:BankName:CreditCard

etc...

And then my Org structure sort of follows this, so at top level I
have:

* Options
* Chart of Accounts
(I use for opening directives and to keep track in one place)
* Assets (Cash/Bank) Account Registers
* Liability (Credit Card) Account Registers
* Pay Records
* Empty Account Trees (for copying)
etc...

...which is debatable and really doesn't matter (suit yourself what
you like). It will also depend largely on your circumstances. I think
some people add another level in there for country, if they have
accounts spread out like that...etc...

Anyway, if we mimic the account naming scheme in our Org structure
then we get (moving deeper):

** BankName
*** Checking Account
**** Year
***** Month

With careful formatting of the year and month which somewhat follows
Orgmode's built in datetree functionality, i.e.:

** BankName
*** Checking Account
**** 2020
***** 2020-01 JAN

I say "somewhat" because I have changed the full month ex. "January"
to "JAN" just because that's how I have my physical indexes of
receipts also set up in my file boxes.

Doing it this way also opens up to even more automated parsing of the
file (especially importing transactions). I already began work along
the lines of inserting something like:

##### Account BlaBla automated import here ###

at the point where new transactions would need to be imported. So far
I implemented a couple loops that automatically split the transactions
at the months and years and insert those parts of the date tree. But
haven't gotten around to finishing that yet.

Circling back to Emacs itself, I did not want to presume anything, but
for anyone reading this that is new to Emacs or afraid of it's
somewhat infamous learning curve, I can highly reccommend the built in
Tutorial (C-h t). There is also Spacemacs for those who have years of
muscle memory already trained in vim.

Cheers!

TRS-80