[GNC] Thoughts on Online Quotes documentation

[Frank H. Ellenberger]

Hi Jim,

I am sorry for the delay. I inserted my view inline.

Am 25.12.23 um 01:14 schrieb Jim DeLaHunt:
> I recently had a problem[1] with getting online quotes from GnuCash 5.5 
> on macOS. It caused me to reflect on some shortcomings[2] of the GnuCash 
> wiki page on Online Quotes[3]. This message is an attempt to capture 
> some thoughts on how that the Online Quotes documentation might be 
> improved. Actually doing the improvement is a big job. I don't promise 
> to do it myself right now.
> 
> A general observation: the top of Online Quotes is big and sprawling, 
> with many facets:
> 
> 1. The task: how to install, how to update, how to configure stock
>     entries, how to get quotes, how to get historical prices
> 2. The components of the online quotes machinery:
>      1. the Perl interpreter
>      2. Finance::Quote and the Perl modules on which it depends
>      3. GnuCash's tools for installing Finance::Quote
>      4. System installs vs package manager installs of Perl & modules
>         (I'm looking at you, Homebrew and MacPorts)
> 3. The different platforms — Unix, macOS, Apple Silicon vs x86_64 on
>     macOS, Windows, different versions of Windows. There are variants of
>     many of the sections for the various platforms.
> 4. The different data sources and symbols quirks for each
> 5. Troubleshooting
> 6. Versions of GnuCash: the facilities for online quotes have changed
>     from major version to major version of GnuCash, and that content is
>     folded together into one wiki page.
> 7. The documentation locations: the Online Quotes wiki page[3], and two
>     places in the GnuCash manual[4][5], aspire to be well coordinated
>     but have evolved away from that.
> 
> The current Online Quotes wiki page is 108,503 bytes mixing together 
> #1-#6 above. That is so big and confusing to be hard to navigate.
> 
> One short term action could be to agree how to refactor. Then various 
> people can take incremental refactoring steps.
> 
> In particular, I suggest we consider splitting Online Quotes by GnuCash 
> version groups, then by platform. Version groups are ranges of GnuCash 
> versions, and change where the Online Quotes behaviour in GnuCash 
> changed: current is GnuCash 5.x, previous is 4.x, before that is 3.11 
> and earlier. Platform is probably: macOS (inc Homebrew, Gnucash), 
> Windows, Unix, cross-platform.

While at the beginning of a change most users still have the older 
version. So both versions are on the same level of the Wiki. In the 
manual older versions should only survive in a footnote to inform an 
updating user about the change and have still the infos for users who 
can or want not update the program.

> Imagine the article <wiki.gnucash.org/wiki/Online_Quotes> refers to 
> sub-articles like 
> <wiki.gnucash.org/wiki/Online_Quotes/current/macOS/Installation>, 
> <wiki.gnucash.org/wiki/Online_Quotes/4.x/Unix/Troubleshooting>, 
> <wiki.gnucash.org/wiki/Online_Quotes/current/all/Retrieving>. (Those 
> names are for illustration only. Getting good names will probably take 
> some work.)

ISTR that wikipedia discourages the use of subpages.

> Another short-term action is to move content out of the wiki article and 
> into the GnuCash Manual, especially for Installation. The article says, 
> "Before you continue read the Official Documentation... We try to reduce 
> redundancy." Let's take that seriously.

This is the important part. So feel free to remove or replace parts 
covered by the manual with links to the respective section.
That is often forgotten because there are up to 3 month between the 
change in the docs visible as
https://code.gnucash.org/docs/C/gnucash-manual/index.html
and their release published as
https://www.gnucash.org/docs/v5/C/gnucash-manual/index.html.

There is only one small issue: wikimedia's syntax-highlight covers more 
languages than docbook's. So some examples look nicer in the wiki than 
in docbook.

> Hopefully these notes contribute to whatever improvement project gets done.
> Best regards,
>     —Jim DeLaHunt
> 
> [1] [GNC] GnuCash 5.5 (macOS) can't get quotes, because it doesn't see 
> JSON::Parse,  Sat, 23 Dec 2023 12:30:43 -0800 
> <https://www.mail-archive.com/gnucash-user@gnucash.org/msg38877.html>
> 
> [2] ibid thread,  Sun, 24 Dec 2023 11:31:44 -0800 
> <https://www.mail-archive.com/gnucash-user@gnucash.org/msg38883.html>
> 
> [3] <https://wiki.gnucash.org/wiki/Online_Quotes>
> 
> [4] GnuCash Manual, 5.4.2. "Steps to enable Online Quotes updating" 
> <https://www.gnucash.org/docs/v5/C/gnucash-manual//acct-create.html#accts-online-quotes>
> 
> [5] GnuCash Manual, Chapter 11. "Setting Up the Quote Retrieval" 
> <https://www.gnucash.org/docs/v5/C/gnucash-manual/finance-quote.html>