From 19009b594635d31414f858691d4ceffd78093220 Mon Sep 17 00:00:00 2001 From: Christian Wehling Date: Sun, 23 Jul 2023 18:06:19 +0200 Subject: [PATCH] Manual (C,de), F::Q: Add a note that 'gnc-fq-*' has been replaced by 'gnucash-cli --quotes' and describe the purpose of the 'info' and 'dump' functions. --- C/manual/ch_Finance-Quote.xml | 243 ++++++++++++++++++++++----------- C/manual/tips-appendix.xml | 20 +-- de/manual/ch_Finance-Quote.xml | 241 +++++++++++++++++++++----------- de/manual/tips-appendix.xml | 21 +-- 4 files changed, 327 insertions(+), 198 deletions(-) diff --git a/C/manual/ch_Finance-Quote.xml b/C/manual/ch_Finance-Quote.xml index eb01f020..9c7ee830 100644 --- a/C/manual/ch_Finance-Quote.xml +++ b/C/manual/ch_Finance-Quote.xml @@ -105,17 +105,6 @@ This is perl 5, version 30, subversion 0 (v5.30.0) built for x86_64-linux-gnu-th Under &win; run the program &gmi.winOS.inst-fq; to run. This will install Strawberry Perl. - - &app; Version 2.2.6 and before require ActivePerl. in - version 5.8. - - - - - &app; Version 2.4 and before require ActivePerl Version - 5.16.3 and later. - - @@ -148,7 +137,7 @@ This is perl 5, version 30, subversion 0 (v5.30.0) built for x86_64-linux-gnu-th To determine if the &app-perl; module &app-fq; is already installed on your system, type perldoc Finance::Quote in a terminal window and check to see if there - is any documentation + is any documentation available. @@ -160,7 +149,7 @@ SYNOPSIS [...] - available. If you are now shown documentation, then &app-fq; is already installed and you can + If you are now shown documentation, then &app-fq; is already installed and you can configure periodical quotes update as described in . If no documentation is displayed, you will have to continue with this chapter. @@ -177,30 +166,28 @@ SYNOPSIS + + Next, update &app-fq; with sudo gnc-fq-update. + + + Run the gnucash-cli --quotes info command to verify that the program is already in a directory that is entered in the PATH environment variable. - If you’ve installed &app; packages provided by your distribution, - &app-cli; must be on your PATH. The currentness - of your distribution can be checked under - &app-fq;- - versions. + If you’ve installed &app; packages provided by your distribution, &app-cli; will be on your + PATH. The &app-fq; version provided by your package manager can be checked + at + &app-fq;-versions or by using your package manager's info command. - Next, update &app-fq; with sudo gnc-fq-update. - - - - - Run gnucash-cli --quotes info to check &app-fq; works properly. This command - returns the version number of &app-fq; module currently installed as well as a list of - sources available via the &app-fq; module. It will also inform you if there is a problem - with your installation or if it is missing, and may suggest a fix. + If &app-fq; works properly, the command returns the version number of &app-fq; module currently + installed as well as a list of sources available via the &app-fq; module. It will also inform + you if there is a problem with your installation or if it is missing, and may suggest a fix. @@ -278,17 +265,44 @@ SYNOPSIS Using &app-cli; for Testing and Automation. - &app; provides a commandline facility &app-cli; that one can use in a terminal session to check the + &app; provides a commandline facility &app-cli; that one can use with the + --quotes option in a terminal session to check the version and supported source modules, to display the quotes or exchange rates for selected securities or currencies, or to update all of the prices in a book without launching the GUI. + + In &app; version 4.x and earlier one used separate perl programs gnc-fq-check + instead of gnucash-cli --quote info and gnc-fq-dump + instead of gnucash-cli --quote dump. + + + Displaying the Finance::Quote Version and Supported Sources - gnucash-cli --quotes info produces the following output: + + The --quotes info option returns the version number of the currently + installed &app-fq; module and a list of available sources. It informs you also if there is + a problem with your installation and gives the reasons. + + + + The latest &app-fq; version is &app-fq-vers;. The list of sources that follows depends on the &app-fq; version. + + + The input of + + gnucash-cli + + -Q + --quotes + + info + + in the terminal produces the following output: @@ -316,10 +330,6 @@ yahoo_json yahooweb za - The latest &app-fq; version is &app-fq-vers;. Depending on the actuality of your installation - the list of source modules made here may differ. - - If there's a problem with your installation it will tell you about it. For example in this case we're missing the Perl modules Finance::Quote and JSON::Parse: @@ -332,8 +342,8 @@ Failed to initialize Finance::Quote: missing_modules Finance::Quote JSON::Parse - In this case, &app-fq; is not installed correctly and therefore cannot be used for course retrieval with &app;. - Please install &app-fq; according to the instructions at + In this case, &app-fq; is not installed correctly and therefore cannot be used for quote retrieval + with &app;. Please install &app-fq; according to the instructions at . @@ -341,16 +351,58 @@ Failed to initialize Finance::Quote: missing_modules Finance::Quote JSON::Parse Displaying Quotes in a Terminal Window + + The --quotes dump option provides quotes for a source and a list of of + symbols in a format that is easy for humans to read. This is useful to verify that a + particular online quote source is accessible and provides data. + + + You can also check to see if the symbol you want to use for your online + price retrieval is available at the desired quote source. + + + + + You may use gnucash-cli --quotes dump to test quote sources and symbols + individually should &app; report an error during quote retrieval. The command will show + the fields required by &app;; use gnucash-cli --verbose --quotes dump + to see all of the information returned by &app-fq;. + + + To display a quote for one or more stocks or the exchange rate for one or more currencies you can - use gnucash-cli --quotes dump as follows. It offers two output forms - for non-currency securities and one for currency exchange rates. + use gnucash-cli --quotes dump as follows: + + gnucash-cli + + -Q + --quotes + + dump + + -V + --verbose + + Source + Symbol + + + + It offers two output forms for non-currency securities and one for currency exchange rates. Currencies - Currencies use the source currency and require at least two ISO-4217 currency - codes; the exchange rates are denominated in the first code. For example: + Currencies use the source currency and require at least two + ISO 4217 currency codes; the exchange + rates are denominated in the first code. + + Since &app-fq; 1.41 the default source for currencies is Alpha Vantage. See also the + notes on . + + + For example: @@ -368,12 +420,13 @@ $ gnucash-cli --quotes dump currency USD GBP EUR Stocks - - - A short form displaying only the fields that &app; uses along with comments indicating whether the - fields are optional or required; you can use this to determine if &app; will be - able to use the quote to update your book's price database. - + To retrieve quotes of your securities, please enter the quote source and the desired symbol. + + + A short form displaying only the fields that &app; uses along with comments indicating whether the + fields are optional or required; you can use this to determine if &app; will + be able to use the quote to update your book's price database. + $ gnucash-cli --quotes dump yahooweb AAPL @@ -385,18 +438,18 @@ Finance::Quote fields GnuCash uses: nav: <=== one of these price: <=/ - - - - - - With the -V option a possibly longer output showing all of the fields - &app-fq; returned. This can be useful to troubleshoot problems with a &app-fq; - source module. - + + + + + + With the --verbose option a possibly longer output showing all of the fields + &app-fq; returned. This can be useful to troubleshoot problems with a &app-fq; + source module. + -$ ALPHAVANTAGE_API_KEY=123456789 bin/gnucash-cli -V --quotes dump alphavantage INTC +$ ALPHAVANTAGE_API_KEY=123456789 gnucash-cli --verbose --quotes dump alphavantage INTC INTC: open => 34.8200 isodate => 2023-07-27 @@ -414,48 +467,80 @@ currency_set_by_fq => 1 p_change => 0.5530 method => alphavantage - - - - Notice that in this case we used alphavantage and provided the - ALPHAVANTAGE_API_KEY on the command line. That's not - necessary if the key is already stored in the shell environment or in &app; - preferences. - - - - - + + + + Notice that in this case we used alphavantage and provided the + ALPHAVANTAGE_API_KEY on the command line. That's + not necessary if the key is already stored in &mc.ed.pref; + . + + + + + + + + + To test if &app-fq; works for currencies inside &app;, do the following: + + + + create a transaction with the desired commodity in the book currency, + + + + + make a right click on it, + + + + + select &gmi.ac.ed-ex; in the context menu. + + + + + In the window click the Get exchange rate button. + + + + + If the exchange rate source and the symbol are set, the current + rate will be entered in the exchange rate field. + - Updating Prices Automatically with &app-cli; + Updating Quotes Automatically with &app-cli; With the command gnucash-cli --quotes get &user-datafile; - The old command gnucash --add-price-quotes &user-datafile; is obsolete as of &app; 5.0. + This replaces the command &app; --add-price-quotes &user-datafile; in &app; + version 4.x and earlier. - you can receive the current prices of your foreign exchange and securities and write them directly into your - &app;-file without starting the user interface. This enables an automatic, regular updating of the prices. + you can receive the current prices of your foreign exchange and securities and write them + directly into your &app;-file without starting the user interface. This enables an + automatic, regular updating of the prices. - The command fails if exclusive access to the data file is not possible, for example, - the data file is opened in another &app; instance, or the last session for the file crashed. + The command fails if exclusive access to the data file is not possible, for example, the data file + is opened in another &app; instance, or the last session for the file crashed. - The specified file &user-datafile; depends on the name and location of your - data file. This can be determined from the name displayed in the top frame of the &app; - window before the -. + The specified file &user-datafile; depends on the name and location of your data file. This can be + determined from the name displayed in the top frame of the &app; window before the + -. - The file name can also be found in the list of recently opened files in the &gm.file;menu. - If you hover the mouse pointer on the menu item numbered 1 in the list of recently opened files, - the full file name is displayed in the statusbar. + The file name can also be found in the list of recently opened files in the &gm.file; menu. If you + hover the mouse pointer on the menu item numbered 1 in the list of recently opened + files, the full file name is displayed in the statusbar. diff --git a/C/manual/tips-appendix.xml b/C/manual/tips-appendix.xml index 1a2602c8..a225c2af 100644 --- a/C/manual/tips-appendix.xml +++ b/C/manual/tips-appendix.xml @@ -144,25 +144,7 @@ - store the key which you got there in - - Edit - Preferences Online - Quotes - - . - - - - - To use him also with gnucash-cli --quotes dump commands you should set - an environment variable - ALPHAVANTAGE_API_KEY. Please consult the manual of your OS or - command shell. - - Environment variable in <filename>.bashrc</filename> -export ALPHAVANTAGE_API_KEY=############## - + store the key which you got there in &mc.ed.pref; . diff --git a/de/manual/ch_Finance-Quote.xml b/de/manual/ch_Finance-Quote.xml index aac5d115..bd85cb23 100644 --- a/de/manual/ch_Finance-Quote.xml +++ b/de/manual/ch_Finance-Quote.xml @@ -107,17 +107,6 @@ This is perl 5, version 30, subversion 0 (v5.30.0) built for x86_64-linux-gnu-th Unter &win; führen Sie das Programm &mc.winOS.inst-fq; aus. Dies wird Strawberry Perl installieren. - - &app; Version 2.2.6 und früher benötigen ActivePerl in - Version 5.8. - - - - - &app; Version 2.4 und früher benötigen ActivePerl ab - Version 5.16.3. - - @@ -181,31 +170,29 @@ SYNOPSIS - Führen Sie den Befehl gnucash-cli --quotes info aus, um zu - überprüfen, ob das Programm bereits in einem Verzeichnis liegt, welches in der - Umgebungsvariable PATH eingetragen ist. - - Wenn Sie die von Ihrer Distribution bereitgestellten &app; Pakete installiert haben, sollte - &app-cli; bereits in Ihrem PATH sein. Die - Aktualität ihrer Distribution können Sie unter - &app-fq;- - Versionen nachlesen. - - + Aktualisieren Sie &app-fq; mit sudo gnc-fq-update. Der Befehl + kann auch für eine Neuinstallation verwendet werden. Die richtige Syntax ist von der + jeweiligen Distribution abhängig. - Als nächstes aktualisieren Sie &app-fq; mit sudo gnc-fq-update. Die richtige - Syntax ist von der jeweiligen Distribution abhängig. + Führen Sie den Befehl gnucash-cli --quotes info aus, um zu überprüfen, ob + das Programm bereits in einem Verzeichnis liegt, welches in der Umgebungsvariable + PATH eingetragen ist. + + Wenn Sie die von Ihrer Distribution bereitgestellten &app; Pakete installiert haben, sollte + &app-cli; bereits in Ihrem PATH sein. Die &app-fq; Version, die von Ihrem Paketmanager + bereitgestellt wird, kann unter + &app-fq;-versions nachgelesen werden oder mit dem info-Befehl + der Softwareverwaltung überprüft werden. + + - - - Führen Sie gnucash-cli --quotes info aus, um zu prüfen, ob &app-fq; richtig - installiert ist. Wenn dies so ist, dann werden die Versionsnummer sowie die von &app-fq; + Ist &app-fq; richtig installiert ist, dann werden die Versionsnummer sowie die von &app-fq; verwendbaren Quellen für eine Kursabfrage aufgelistet. Bei Problemen mit der Installation - von &app-fq; wird eventuell eine Lösung vorgeschlagen. + wird eventuell eine Lösung vorgeschlagen. @@ -228,8 +215,8 @@ SYNOPSIS Installieren Sie &app-xcode; Sie können &app-xcode; aus dem App Store installieren oder Sie installieren die viel kleineren - Xcode-Befehlszeilentools, indem Sie sudo xcode-select - --install in einer Terminal.app Eingabeaufforderung ausführen. + Xcode-Befehlszeilentools, indem Sie sudo xcode-select --install + in einer Terminal.app Eingabeaufforderung ausführen. , falls noch nicht geschehen. Es enthält Entwicklungswerkzeuge, die von CPAN benötigt @@ -286,17 +273,45 @@ SYNOPSIS Verwendung von &app-cli; für Tests und Automatisierung - &app; enthält die Befehlszeilenanwendung &app-cli;, die in einer Terminalsitzung verwendet werden - kann, um die Version und die unterstützten Quellmodule zu prüfen, Kurse oder Wechselkurse + &app; enthält die Befehlszeilenanwendung &app-cli;, welche mit der Option + --quotes in einer Terminalsitzung verwendet werden kann, um die + Version und die unterstützten Quellmodule von &app-fq; zu prüfen, Kurse oder Wechselkurse für ausgewählte Wertpapiere oder Währungen anzuzeigen und alle Kurse in einem Buch zu - aktualisieren, ohne die grafische Benutzeroberfläche zu starten. + aktualisieren, ohne hierfür die grafische Benutzeroberfläche zu starten. + + In &app; Version 4.x und früher wurden die separaten Perl-Programme gnc-fq-check + an Stelle von gnucash-cli --quote info und gnc-fq-dump + anstatt gnucash-cli --quote dump verwendet. + + + Anzeige der &app-fq; Version und der unterstützten Quellen - gnucash-cli --quotes info erzeugt die folgende Ausgabe: + + Die Nutzung der Option --quotes info liefert die Versionsnummer des derzeit + installierten &app-fq; Moduls sowie eine Liste der verfügbaren Quellen. Es informiert Sie + auch, wenn es ein Problem mit Ihrer Installation gibt und nennt die Gründe dafür. + + + + Die neueste &app-fq; Version ist &app-fq-vers;. Entsprechend der Aktualität Ihrer Installation kann + sich die nachfolgende Auflistung der Quellenmodule unterscheiden. + + + Die Eingabe von + + gnucash-cli + + -Q + --quotes + + info + + im Terminal erzeugt die folgende Ausgabe: @@ -324,12 +339,9 @@ yahoo_json yahooweb za - Die neueste &app-fq; Version ist &app-fq-vers;. Entsprechend der Aktualität Ihrer Installation - kann sich die hier gemachte Auflistung der Quellenmodule unterscheiden. - - Wenn es ein Problem mit Ihrer Installation gibt, werden Sie darauf hingeweisen. In dem nachfolgend - aufgeführtem Fall fehlen zum Beispiel die &app-perl;-Module Finance::Quote und JSON::Parse: + aufgeführtem Beispiel wird auf Probleme mit den &app-perl;-Modulen Finance::Quote und JSON::Parse + hingewiesen: @@ -347,23 +359,59 @@ Failed to initialize Finance::Quote: missing_modules Finance::Quote JSON::Parse - Anzeige von Kursen in einem Terminalfenster + Abfrage von Kursen in einem Terminalfenster + + + Die Option --quotes dump liefert Kursdaten für eine Kursquelle und eine Liste + von Symbolen in einem Format, das für Menschen leicht zu lesen ist. Dies ist nützlich, + um zu überprüfen, ob eine bestimmte Online-Kursquelle erreichbar ist und Daten liefert. + + + Weiterhin können Sie überprüfen, ob das , welches Sie für Ihr + Wertpapier zum Online-Kursabruf verwenden möchten, bei der gewünschten + bekannt ist. + + + + + Sie können gnucash-cli --quotes dump verwenden, um Kursquellen und Symbole + einzeln zu testen, wenn &app; einen Fehler beim Abrufen von Kursen meldet. Der Befehl + zeigt die Felder an, die von &app; genutzt werden. Verwenden Sie die Optionen + gnucash-cli --verbose --quotes dump, um alle Informationen zu sehen, die + &app-fq; von der Kursquelle erhält. + + Um einen Kurs für eine oder mehrere Aktien oder den Wechselkurs für eine oder mehrere Währungen - anzuzeigen, können Sie gnucash-cli --quotes dump wie folgt - verwenden. Es bietet eine Ausgabeform für Devisenkurse und zwei für Aktien und - Wertpapiere. + anzuzeigen, verwenden Sie den Befehl wie folgt: + + gnucash-cli + + -Q + --quotes + + dump + + -V + --verbose + + Quelle + Symbol + + + + Es bietet eine Ausgabeform für Devisenkurse und zwei für Aktien und Wertpapiere. Währungen Für den Abruf von Devisenkursen wird die Quelle currency verwendet, welche - mindestens zwei ISO-4217-Währungscodes erfordern; die Wechselkurse werden in der - ersten Währung angegeben. + mindestens zwei ISO 4217 Währungscodes erfordern; + die Wechselkurse werden in der ersten Währung angegeben. Seit &app-fq; 1.41 ist die Standardquelle für Währungen Alpha Vantage. Lesen Sie - auch die Hinweise zu . + auch die Hinweise dazu in . Zum Beispiel: @@ -384,13 +432,15 @@ $ gnucash-cli --quotes dump currency USD GBP EUR Wertpapiere - - - Eine Kurzform, die nur die Felder anzeigt, die &app; benötigt, ergänzt mit Kommentaren, die - angeben, ob die Felder empfohlen oder erforderlich sind; damit können Sie - herausfinden, ob &app; in der Lage sein wird die Kursangaben zu verwenden, um - die Kursdatenbank Ihres Buches zu aktualisieren. - + Zum Abruf von Kursen Ihrer Wertpapiere ist die abzufragende Kursquelle sowie das gewünschte Symbol + anzugeben. + + + Eine Kurzform, die nur die Felder anzeigt, die &app; benötigt, ergänzt mit Kommentaren, die + angeben, ob die Felder empfohlen oder erforderlich sind; damit können Sie + herausfinden, ob &app; in der Lage sein wird die Kursangaben zu verwenden, um + die Kursdatenbank Ihres Buches zu aktualisieren. + $ gnucash-cli --quotes dump yahooweb AAPL @@ -401,18 +451,18 @@ $ gnucash-cli --quotes dump yahooweb AAPL NAV: <=== Eins von diesen Preis: <=/ - - - - - - Mit der Option -V wird eine möglicherweise längere Ausgabe mit allen - Datenfeldern von &app-fq; zurückgegeben. Dies kann nützlich sein, um Probleme - mit einem &app-fq; Quellmodul zu beheben. - + + + + + + Mit der Option --verbose wird eine längere Ausgabe mit allen Datenfeldern von + &app-fq; zurückgegeben. Dies kann nützlich sein, um Probleme mit einem + &app-fq; Quellmodul zu beheben. + -$ ALPHAVANTAGE_API_KEY=123456789 bin/gnucash-cli -V --quotes dump alphavantage INTC +$ ALPHAVANTAGE_API_KEY=123456789 gnucash-cli --verbose --quotes dump alphavantage INTC INTC: date => 07/27/2023 close => 34.3600 @@ -430,31 +480,60 @@ currency_set_by_fq => 1 net => 0.1900 method => alphavantage - - - - Beachten Sie, dass wir in diesem Fall als Quelle alphavantage verwendet und den - ALPHAVANTAGE_API_KEY in der Befehlszeile angegeben - haben. Das ist nicht notwendig, wenn der Schlüssel bereits in der - Umgebungsvariable der Shell oder in den &app;-Einstellungen gespeichert ist. - - - - - + + + + Beachten Sie, dass wir in diesem Fall als Quelle alphavantage verwendet und den + ALPHAVANTAGE_API_KEY in der Befehlszeile angegeben + haben. Das ist nicht notwendig, wenn der Schlüssel bereits in &mc.ed.pref; + gespeichert ist. + + + + + + + + + Um zu testen, ob &app-fq; für Währungen innerhalb von &app; funktioniert, gehen Sie wie folgt vor: + + + + erstellen Sie eine Buchung mit dem gewünschtem Handelsgut in der Buchwährung, + + + + + machen einen Rechtsklick darauf, + + + + + wählen Sie im Kontextmenü die Option &gmi.ac.ed-ex;. + + + + + Klicken Sie auf die Schaltfläche Wechselkurs abrufen im . + + + + + Sind die Kursquelle sowie das Symbol richtig eingestellt, wird der aktuelle Kurs in das Feld für den Wechselkurs eingetragen. + - Automatisierte Abfrage von Kursen mit &app-cli; + Automatisierte Aktualisierung von Kursen mit &app-cli; Mit dem Kommando gnucash-cli --quotes get &user-datafile; - Der alte Befehl gnucash --add-price-quotes &user-datafile; ist seit &app; 5.0 - nicht mehr verfügbar! + Dies ersetzt den Befehl &app; --add-price-quotes &user-datafile; in &app; + Version 4.x und früher. können Sie die aktuellen Kurse Ihrer Devisen und Wertpapiere abrufen und direkt in ihre @@ -519,8 +598,8 @@ currency_set_by_fq => 1 gnucash-cli --quotes get &user-datafile; > /dev/null 2>&1 - (Den Zeilenumbruch nicht in die crontab übernehmen, der wurde hier nur zum - Zwecke der Lesbarkeit eingefügt.) + (Den Zeilenumbruch nicht in die crontab übernehmen, der wurde hier nur zum Zwecke + der Lesbarkeit eingefügt.) diff --git a/de/manual/tips-appendix.xml b/de/manual/tips-appendix.xml index 127a69c3..9b53e467 100644 --- a/de/manual/tips-appendix.xml +++ b/de/manual/tips-appendix.xml @@ -37,7 +37,7 @@ - Die Datenquellen in Finance::Quote + Datenquellen in Finance::Quote Es gibt drei Arten von Quellen. Dabei ist die erste - Währung - fest implementiert und dafür zuständig, die Wechselkurse der von der ISO registrierten Währungen abzurufen. Die beiden @@ -144,24 +144,7 @@ - Ihren dort erhaltenen Schlüssel in - - &mc.ed.pref; Online Kurse - - eingeben. - - - - - Um ihn auch mit dem gnucash-cli --quotes dump Befehl zu verwenden, - müssen Sie ihn auch in einer Umgebungsvariable - ALPHAVANTAGE_API_KEY setzen. Ziehen Sie dazu die - Dokumentation Ihres Betriebssystems oder Befehlszeileninterpreters zu Rate, - wie Sie das dauerhaft erreichen. - - Umgebungsvariable in <filename>.bashrc</filename> -export ALPHAVANTAGE_API_KEY=############## - + Ihren dort erhaltenen Schlüssel in &mc.ed.pref; eintragen.