[GNC-dev] Sample Report with Examples

[john]

Geert,

Roger. The problem with that argument is that someone with that little programming experience isn't going to be able to write a custom report anyway. Even someone with enough programming experience to agree that default option values aren't significant to the structure of the code isn't going to be able to write a custom report unless at least some of that experience is in one of  the Lispish languages. The Lispish paradigms of car, cdr, lambda, map, and so on are utterly foreign to most procedural language programmers, but required for writing GnuCash reports.

Yes, the use of Hello, World is a bit flippant, and yes, hello-world.scm isn't a minimal Scheme program. It's also not a sample report because it doesn't demonstrate querying the GnuCash data performing analysis, or presenting results. So if someone feels motivated to make it less flippant and better described then I suggest:

* Change the filename to options-example.scm, and the menu-name to "Options Example".
* Add a report title option. Most of the real reports have one. Set its default to "Example Title".
* Fix the comment describing the value of `name from "This will be used, among other things for making its menu item in the main menu.". It doesn't do that, it sets the name on the options dialog's title bar and the default value for the General section's Report Name option. "menu-name", which is part of the report-registration block at the bottom, sets the menu name. The comment should also explain that changing the report name option will change the value of the report's window or tab title but not its options dialog title.
* Change the name value to "Options Example Report".
* Change the two Hello… section names to something like Tab A and Tab B to make clear that "Sections" in the option block map to tabs on the dialog box.
* Change the string option default to "String Option Default".
* Speaking of the General section, there should be a comment explaining that a skeleton General section gets added by gnc:report-template-new-options that provides the name (but not the title, reports must add that themselves) and stylesheet options.

Regards,
John Ralls


> On Jan 14, 2023, at 2:02 AM, Geert Janssens <geert.gnucash at kobaltwit.be> wrote:
> 
> Ok, I tend to agree partially with flywire on this one.
> 
> John, you and I have years of programming experience and to us the default value of an option is a minor detail.
> 
> However I can imagine someone with hardly any development experience at all will have a much harder time to map the same string used multiple times in the report code to the output visible on screen. And I sympathize with those that try to create their own custom reports. So yes, using different sample strings in code (even for default values) makes it easier to relate output on the report with what's written in the code - before - any option is changed.
> 
> To us this may look like bikeshedding, I think for someone trying to wrap their head around the gnucash code this may actually help.
> 
> And while bikeshedding was mentioned, I'd rather use values like
> "Sample string", "Sample Document Title" and "Sample Report" than the half-baked "Hello String" and "Hello Example".
> 
> As with these changes "Hello, World" is never used, the file name is probably better changed as well.
> 
> Regards,
> 
> Geert
> 
> Op zaterdag 14 januari 2023 05:47:29 CET schreef john:
> > > On Jan 13, 2023, at 6:46 PM, flywire <flywire0 at gmail.com> wrote:
> > >
> > > The point is not about the changes options make to reports, it's about how
> > > the report source code changes the report and report options. Why
> > > wouldn't unique string values help people unfamiliar with reports see the
> > > relationship more clearly?
> > While it's possible in Scheme to take that quoted option value and convert
> > it to code I don't know of any report code in GnuCash that does so. That's
> > a very good thing, we have enough Scheme-induced vulnerabilities without
> > that.
> >
> > With that in mind, no, the quoted-string default values do not in any way
> > have anything to do with illustrating how the report source code changes
> > the report and report options. Nor, for that matter, does hello-world.scm
> > illustrate anything of the sort. hello-world.scm simply provides examples
> > of the different types of options and very simply displays the values in
> > the report. There's not a single line of code that changes the behavior of
> > the report based on an option value--unlike many of the real options in
> > most of the real reports.
> >
> > Regards,
> > John Ralls
> >
> > _______________________________________________
> > gnucash-devel mailing list
> > gnucash-devel at gnucash.org
> > https://lists.gnucash.org/mailman/listinfo/gnucash-devel
> 
>