document directive

[Chary Ev2geny]

Dear all,

i never really had a use for the document directive, but as I now logged an issue  with it I am kind of trying to dig in it, hence questions.

The documentation says:

A Document directive can be used to attach an external file to the journal of an account:

2013-11-03 document Liabilities:CreditCard "/home/joe/stmts/apr-2014.pdf"

The filename gets rendered as a browser link in the journals of the web interface for the corresponding account and you should be able to click on it to view the contents of the file itself. This is useful to integrate account statements and other downloads into the flow of accounts, so that they’re easily accessible from a few clicks. Scripts could also be written to obtain this list of documents from an account name and do something with them.

Q1: for the beancount v3, is there any application which actually uses this now?

Q2: why does this directive need a date, what is the logic of assigning a date information?

Q3: for me a document, assigned to an account sounds more like a meta information. So, why invert a special directive? Why this design decision was done? Why not just write something like this:

2020-01-01 open Assets:Bank:Checking

  document: "/path/to/file.txt"

[Martin Blais]

On Sat, Nov 23, 2024 at 8:20 AM Chary Ev2geny <char...@gmail.com> wrote:

Dear all,

i never really had a use for the document directive, but as I now logged an issue  with it I am kind of trying to dig in it, hence questions.

The documentation says:

A Document directive can be used to attach an external file to the journal of an account:

2013-11-03 document Liabilities:CreditCard "/home/joe/stmts/apr-2014.pdf"

The filename gets rendered as a browser link in the journals of the web interface for the corresponding account and you should be able to click on it to view the contents of the file itself. This is useful to integrate account statements and other downloads into the flow of accounts, so that they’re easily accessible from a few clicks. Scripts could also be written to obtain this list of documents from an account name and do something with them.

Q1: for the beancount v3, is there any application which actually uses this now?

I'm not aware of one, but I suspect Fava probably does something.

This was used somewhere in bean-web a long time ago.

Q2: why does this directive need a date, what is the logic of assigning a date information?

Documents invariably are issued on some particular date.

 

Q3: for me a document, assigned to an account sounds more like a meta information. So, why invert a special directive? Why this design decision was done? Why not just write something like this:

2020-01-01 open Assets:Bank:Checking

  document: "/path/to/file.txt"

Documents are issued at all sorts of later dates, i.e., statements; those aren't transactions so what would you associated it with? A Note directive? I suppose you could. I felt that documents deserved to have a place in the schema, but I guess it's debatable.

 

--
You received this message because you are subscribed to the Google Groups "Beancount" group.
To unsubscribe from this group and stop receiving emails from it, send an email to beancount+...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/beancount/d76fe5ac-708e-46b5-ab6b-e678a8c1b132n%40googlegroups.com.

[Chary Ev2geny]

Martin,

ok, thanks. 

So, just trying to determine the expected behavior in application to the issue 874 . 

I think the whole beancount loader to printer path, no code shall be trying to be clever and convert the document path to the OS planform specific path (which is what seems to be happening)

So, if on Windows it has got "/home/joe/stmts/apr-2014.pdf", it shall print the same "/home/joe/stmts/apr-2014.pdf".

  
Correct?

[Martin Blais]

I haven't been following too closely but last I checked the problem was that escape rules for the document string is the same as for all the other strings, so you can't really use backslash (\). You have to double up (escape) the backslashes on Windows, i.e., use \\ instead of \.

(The alternative would be to make special interpretation of that string and that's... ugly. If this really matters I'd rather we create another type of string literal, e.g. r"" which doesn't escape, a bit like in Python.)

To view this discussion visit https://groups.google.com/d/msgid/beancount/2d994c51-3936-4b83-9d78-b2d971854eb6n%40googlegroups.com.

[Daniele Nicolodi]

On 23/11/24 14:20, Chary Ev2geny wrote:
> Dear all,
>

> i never really had a use for the *document *directive, but as I now
> logged an issue  with it https://github.com/beancount/beancount/
> issues/874 I am kind of trying to dig in it, hence questions.

There is no issue in how the document directive work. Everything works
as intended. The issue is with the test. I prepared an PR that fixes
this (and a couple of other) tests when ran on Windows. See
https://github.com/beancount/beancount/pull/876 The commits there have
all the details.

It can be debated that how things are intended to work is the best or
most obvious, but any change would be an incompatible change to how the
entries printing code works. For example it would break some of mine
that programmatically adds document directives. I am not aware of any
issue issue filed about the behavior of this part of the code, thus I
don't really see reason to change it.

Cheers,
Dan

[Chary Ev2geny]

I confirm, that the new test works on Windows

thanks for fixing!

[marvhen]

I personally would like to associate a document with multiple accounts, not just 1 account.  The use case is bank statements where multiple accounts are held and a single document referencing all accounts is issued.  Another case is end of year/quarter/etc reports and tax documents to easily verify totals match what was reported.