> On Jan 13, 2023, at 2:07 PM, flywire <flywi...@gmail.com> wrote:
>
> John, Can you explain why the PR is a dumb idea?
>
> Comments on customising reports normally say the process is not easy. Getting
> the relationships of some of the data right can be complex but well-presented
> documentation and code make it a lot easier.
>
> Report documentation is fairly well limited to the report wiki page and
> reports with source code comments. There is a simple hello-world.scm example
> report specifically written to show you the base layout of a GnuCash report.
>
> Firstly, a Hello World program is a convention as a minimalist program to
> generate hello world output. One of the features is, usually, changing the
> string changes the output.
>
> A couple of things make it confusing:
>
> 1. hello-world.scm is not a minimalist program so it fails user expectations,
> but tweeking the report name would avoid that expectation
>
> 2. It is not intuitively obvious in the Reports Examples menu which report is
> hello-world.scm, but Welcome to GnuCash would seem more obvious than Sample
> Report with Examples
>
> 3. Search 'Hello, World' has 22 hits:
>
> * 18 of those hits are 'Hello, World!' used as a section name? Why? It's a
> complicated name making the program harder to comprehend and distingush from
> output strings (let's ignore searching for the presence/absence of an
> exclamation mark). Just changing it to 'Hello' would be easier to read and
> make the program clearer.
>
> * 'Hello, World' string is used three times (and in a comment): as a string,
> report title, and report name. It is much easier to see what output unique
> strings are associated with without even understanding the structure of the
> report.
Had you written that instead of
"The code would be easier to follow if different strings other than Hello,
World! were used, making it clearer what they relate to. While this report
might have developed from a Hello World example, a minimal program to
generate output, it's much more than that now. Can it be renamed? Maybe
just hello.scm or move it to welcome-to-gnucash.scm with a related document
title."
and jumped to writing a PR changing the wrong things there would have been
scope for discussion at the outset.
It's amusing that you closed your email with "If there are no concerns I'll put
up a PR." Since the timestamps on your email and the PR are a whole minute
apart you clearly had great interest in discussing the matter.
To address point 1 one would change the file name.
To address point 2 that new file name would be something like
"sample-report-with-examples.scm".
To address point 3 one would change the names of the sections.
Instead of doing either of those you chose to change the default values of
three options and claimed that that somehow makes the code easier to understand.
>
> The PR changes points 2 and 3 with minimal change elsewhere.
That is obviously false. The PR does address
> * 'Hello, World' string is used three times (and in a comment): as a string,
> report title, and report name. It is much easier to see what output unique
> strings are associated with without even understanding the structure of the
> report.
But that claim is silly, because the user can (and should) open the options
dialog, change one of the options, click Apply, and observe what changes in the
report.
Regards,
John Ralls
_______________________________________________
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
