Thanks for doing that. I have been working on learning scheme and
understanding report code better so will have a look.
As for the changes in version 5.0, they don't really impact the ability to
create custom reports. If anything it cuts down on the amount of code
needed and (I imagine) provides a much cleaner framework in the background.
As I understand it, the part that was rewritten in C is the option engine
and database, that is the part of the code that provide the utilities to
create specific types of options (a checkbox, a dropdown list, a text box,
etc) and then the part of the code that stores the values selected by users
and let you retrieve them later to prepare your report. A lot of that used
to be done in scheme, in a huge file called options.scm. This was in scheme
but hardly something any end-user would go into (just looking at it would
give me a panic attack). What has not changed is that the code to create
the actual list of options for each specific report is still in scheme, in
each report scm file, but instead of calling utility functions written in
scheme, you now call utility functions written in C.
If there is a difference, it's a good one. As said in the release text, in
the old code it took more lines of code to create options in your report
scm file.
This is what the 2-step old code looked like just to get started in
creating an option database and making it available
;; create your option database
(define options (gnc:new-options))
;; define a function you will call later in your report to add a new option
to your option database
(define (gnc:register-trep-option new-option)
(gnc:register-option options new-option))
In version 5.0, it's much simpler -- you just create your option database
like this:
;; initialize your option database
let ((options (gnc-new-optiondb)))
Then in the old code to create an actual option, it was also 2 nested
steps, for instance here to create a simple checkbox:
(gnc:register-trep-option
(gnc:make-simple-boolean-option
pagename-currency optname-orig-currency
"b" (G_ "Also show original currency amounts") #f))
As you can see you had to use the function created earlier to register your
options, and within that you had to call a utility function to create your
option.
In version 5, it's much simpler, you only have to call one function that
both creates the option and puts it in your option database:
(gnc-register-simple-boolean-option options
pagename-currency optname-orig-currency
"b" (G_ "Also show original currency amounts") #f)
Bottom line version 5.0 is actually easier to work with for creating
options. But yes more documentation would be nice. For now the best way to
discover v4 vs v5 is to pick 2 report files from each version and compare
them so see the changes.
And to be clear, rewriting the whole option engine code in C must have been
a LOT of work, so big thanks to John Ralls and co for doing it.
Sincerely,
Vincent Dawans
On Wed, Apr 12, 2023 at 3:57 PM flywire <flywire0 at gmail.com> wrote:
> I've updated https://wiki.gnucash.org/wiki/Custom_Reports to GnuCash V5.
> I'd appreciate those interested in custom reports testing it and providing
> feedback because there are still parts left over from historical versions
> and other parts that do/don't work in Linux with no Windows equivalents.
>
> Breaking changes in https://github.com/Gnucash/gnucash/releases/tag/5.0
>
> Report and Book Options
> >
> > - This major change will affect everyone who has written custom
> > reports in Guile Scheme.
> > - The report and book options code has been completely rewritten in
> > C++ with SWIG providing Guile Scheme access for reports. The new
> design
> > requires directly registering options with for example
> > gnc-optiondb-register-string-option instead of calling
> > gnc:make-string-option to create an option followed by
> gnc:register-option
> > to insert it in the report's options.
> > - Value access is also changed: Instead of retrieving an option and
> > then querying or setting its value with gnc:option-value one will
> query the
> > optiondb with gnc-option-value, the arguments to which are the
> optiondb,
> > the section, and the option name.
> > - Supporting the new options backend the options dialog code in
> > gnc-dialog-options, gnc-business-options, and the new
> gnc-option-gtk-ui
> > have also been rewritten in C++.
> >
> >
> The wiki shows what works but there is no explanation of why it works
> (insight on the process). The community has a very limited knowledge base
> for writing GnuCash reports. John Ralls made these changes seemingly with
> support from two other developers.
>
> I've asked for a bit of insight but nothing has been given. As I understand
> it, reports, normally incorporating parts of library report modules,
> include options. The option value list was directly accessible in scheme
> report code but it has been moved to compiled C++ code where it is not
> accessible once GnuCash is installed.
>
> "Custom reports can be fairly challenging and while the information
> > presented [in the wiki] is brief it should be enough to get you started."
>
>
>
> Regardless, I highlight the following:
>
> 1. There are little glitches here and there like typos, bad paths, and
> broken links
> 2. https://wiki.gnucash.org/wiki/Custom_Reports#Debugging_your_report
> needs work for Windows
> 3.
>
> https://wiki.gnucash.org/wiki/Custom_Reports#Technique_to_reload_reports_without_restarting_GnuCash
> is totally broken
> 4. https://wiki.gnucash.org/wiki/Custom_Reports#Designing_new_Reports -
> disheartening bug, the report name, a default option and key
> feature but not returned
> 5. https://wiki.gnucash.org/wiki/Custom_Reports#The_Report-Renderer
> seems outdated, and needs replacing with style sheet content
> 6. https://wiki.gnucash.org/wiki/Custom_Reports#The_GnuCash_API is a
> fairly useless table. Better to list the items in the table and
> demonstrate
> how to search the API to find and use them, using the report name from
> the prototype report.
> 7.
>
> https://wiki.gnucash.org/wiki/Custom_Reports#Command_line_access_to_the_API
> - don't know if it works, seemingly not in Windows
> 8. https://wiki.gnucash.org/wiki/Custom_Reports#Adding_Menu_Items -
> don't know if it works, seemingly not in Windows
>
> A new section is needed to address moving the option lists into C++ lists.
> It seems those options, say start/end-of-year, could be overwritten in
> scheme so they are customised before being used in reports, restoring
> previous functionality.
>
> Regards
> _______________________________________________
> gnucash-user mailing list
> gnucash-user at gnucash.org
> To update your subscription preferences or to unsubscribe:
> https://lists.gnucash.org/mailman/listinfo/gnucash-user
> -----
> Please remember to CC this list on all your replies.
> You can do this by using Reply-To-List or Reply-All.
>