Saving customized reports (reloaded)

[Christian Stimming]

-----BEGIN PGP SIGNED MESSAGE-----

The procedure from yesterday about manually saving a report was not at all 
tested, because I didn't have any access to gnucash at the time of writing. 
Now that I'm back at my home machine, I took some time to play around with 
the idea, and these instructions are what I came up with.

Summary: It *is* possible to save customized reports. For the desperate user, 
it is already possible as a workaround with some scheme editing. In order to 
offer this from inside gnucash, we only have to export the report's renderer 
function from their scheme file and then we can put the code outlined below 
either in ~/.gnucash/books/<bookname> (per-book per-user), or in ~/.gnucash/
config.auto (per-user), or in some to-be-created site-wide file.

Detailed instructions for any interested developer or advanced user: If you 
want to save a report with specific option settings, you need to perform the 
following steps, assuming you have installed gnucash-1.8 from source and have 
the source directory still available. As always, make sure you have backup 
files of the source directory and of your data available.

1. In gnucash, open the original report. Change the options so that it shows 
what you want. Close gnucash while leaving that report window opened.

2. Open the file ~/.gnucash/books/<path_to_your_book_name> with your favorite 
text editor.

3. Find the section entitled ";; options for report <your_report_name>", 
probably at the end of the file. For each of your still-opened reports, there 
is one such section. If you have multiple reports based on the same template, 
you need to figure out which one you want by looking closely at each report's 
options.

4. Copy the section with the report options into a new text file, e.g. 
"my-report.scm", and write it into gnucash's source directory src/report/
standard-reports/my-report.scm . The section starts with the command "(let 
((options 
..." and it ends with the closing parentheses that closes the opening 
parentheses before the "let" command, after the gnc:restore-report command.

5. In the new file my-report.scm, insert the following commands in front of 
your pasted section:

(define-module (gnucash report my-report))
(use-modules (gnucash main))
(use-modules (gnucash gnc-module))
(gnc:module-load "gnucash/report/report-system" 0)

6. Figure out the filename of the source code for the original report. For a 
transaction report, that would be transaction.scm. For an account summary, 
that would be account-summary.scm. Open that file and look for the command 
(define-module ...) in the very beginning. Copy this line into your 
my-report.scm right after the gnc:module-load that we just inserted, but 
change the command name from "define-module" into "use-modules". The 
resulting line might look like

(use-modules (gnucash report account-summary))

7. Now, embrace the pasted section in my-report.scm by a function definition. 
That is, in front of the "(let ((options ..." insert the line

(define (my-options-gen)

[yes, there's one closing parentheses missing]. At the end of the pasted 
section, you need to remove the line with the "gnc:restore-report" command. 
Instead, you insert a line saying 

  options))

[yes, that's two closing parentheses]. This should close the "(define 
(my-options-gen)" block.

8. Additionally, below the pasted section outside of the function we just 
created, insert the lines 

(gnc:define-report
 'version 1
 'name "My New Report"
 'options-generator my-options-gen
 'renderer accsum-renderer)

The name "My New Report" can be chosen arbitrarily.

9. The very last argument after the 'renderer literal, "accsum-renderer" in 
the example, might need to be different in your case if your original report 
was something different from an account summary report. You need to look up 
the gnc:define-report function call in the source code file for the original 
report (step 6.), usually at the very end of that file. Copy the same 
argument that you find in the original report's source to my-report.scm. 
(However, for some reports like account-piechart.scm and 
categories-barchart.scm things are a bit more complicated unless you happen 
to know some scheme. In that case, ask on IRC...)

10. This function name that we used in step 9 usually is not accessible 
outside of the original report's source file. In order to fix this for your 
needs, you need to edit the original report's source file and, e.g. in 
account-summary.scm, append the line

(export accsum-renderer)

to the very end of the file (unless this command happens to exist already 
somewhere in this file, which might very well be the case in future versions 
of gnucash). If you are editing some other file, exchange the function name 
"accsum-renderer" by the appropriate name that you found out in step 10.

11. In that directory, in the file standard-reports.scm, add the line 
  (use-modules (gnucash report my-report))
to the list of use-modules commands so that your new report is loaded.

12. In that source directory, in the file Makefile.am, add the file name 
my-report.scm to the list of report file names in the variable gncscmmod_DATA 
so that your new report is installed.

13. Call "make install" so that your newly created report file as well as the 
two other edited files are installed. It is sufficient if you call "make 
install" *only* in this directory src/report/standard-reports/ (this will 
save you a *lot* of time).

14. Start gnucash again. If something went wrong, you can always go back to 
your original copy of the gnucash source, call "make install" in the 
directory src/report/standard-reports , your changes will be reverted and 
gnucash should start up fine again.

That's it.

Developers: The point here is that it is possible to re-use the 
gnc:report-restore code directly for defining a new report, once the renderer 
functions are available outside of their definition file. I suggest we should 
do this once and for all report (of course together with some name 
normalization). 

Christian
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.4 (GNU/Linux)

iQCVAwUBQMraQWXAi+BfhivFAQE7RAQAlDKw+JDQVS7Bn228J3/KDayukQqk0gH0
BOtcKv1ivTVTn5N9tfyjYhffYf89RjiMXSd3yVUAP3kDVWzrpBryA9L/a9p5IbjV
nwmx1VLcb3k8e6AKdLpFCzTL0pKwV7tKfguXCVyqSHsbcofJLwSf6e5tko+8t/6K
UxbSaIn5SDE=
=5pjS
-----END PGP SIGNATURE-----