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>
_______________________________________________
gnucash-user mailing list
gnucash-user@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.
