Skip to content

Commit

Permalink
Manual (C,de), F::Q: Add a note that 'gnc-fq-*' has been replaced
Browse files Browse the repository at this point in the history 
by 'gnucash-cli --quotes' and describe the purpose of the 'info' and
'dump' functions.
  • Loading branch information
@CWehli
CWehli committed Jul 27, 2023
1 parent 3e21995 commit dc11850
Show file tree
Hide file tree
Showing 2 changed files with 292 additions and 128 deletions.
213 changes: 149 additions & 64 deletions C/manual/ch_Finance-Quote.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -105,17 +105,6 @@ This is perl 5, version 30, subversion 0 (v5.30.0) built for x86_64-linux-gnu-th
<step>
<para>Under &win; run the program &gmi.winOS.inst-fq; to run. This will install
<ulink url="&url-wp-en;Strawberry_Perl">Strawberry Perl</ulink>.
<footnote>
<para>&app; Version 2.2.6 and before require <ulink url="&url-wp-en;ActivePerl">ActivePerl</ulink>. in
version 5.8.
</para>
</footnote>

<footnote>
<para>&app; Version 2.4 and before require <ulink url="&url-wp-en;ActivePerl">ActivePerl</ulink> Version
5.16.3 and later.
</para>
</footnote>
</para>
</step>

Expand Down Expand Up @@ -165,6 +154,13 @@ SYNOPSIS
documentation is displayed, you will have to continue with this chapter.
</para>

<note>
<para>In &app; version 5.0 the old commands <userinput>gnc-fq-check</userinput>,
<userinput>gnc-fq-dump</userinput> and <userinput>gnc-fq-helper</userinput> have been
removed and replaced with similar functions in &app-cli;.
</para>
</note>

<para>The process of installing &app-fq; depends on the system. For the different supported systems, you
can follow the instructions below:
</para>
Expand All @@ -181,9 +177,8 @@ SYNOPSIS
<simpara>Run the <userinput>gnucash-cli --quotes info</userinput> command to verify that the program is
already in a directory that is entered in the <envar>PATH</envar> environment variable.
<footnote>
<simpara>If you&rsquo;ve installed &app; packages provided by your distribution,
&app-cli; must be on your <envar>PATH</envar>. The currentness
of your distribution can be checked under
<simpara>If you&rsquo;ve installed &app; packages provided by your distribution, &app-cli; must be on your
<envar>PATH</envar>. The currentness of your distribution can be checked under
<ulink url="&url-repo;perl:finance-quote/versions"><citetitle>&app-fq;-
versions</citetitle></ulink>.
</simpara>
Expand Down Expand Up @@ -278,7 +273,8 @@ SYNOPSIS
<title>Using &app-cli; for Testing and Automation.</title>

<abstract>
<para>&app; provides a commandline facility &app-cli; that one can use in a terminal session to check the
<para>&app; provides a commandline facility &app-cli;, which can be used in mode
<replaceable>--quotes</replaceable> that one can use 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.
Expand All @@ -288,7 +284,30 @@ SYNOPSIS
<sect2 id="fq-check-version">
<title>Displaying the Finance::Quote Version and Supported Sources</title>

<para><command>gnucash-cli --quotes info</command> produces the following output:
<abstract>
<para>The <replaceable>--quotes info</replaceable> mode 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.
</para>
</abstract>

<para>The latest &app-fq; version is &app-fq-vers;. According to the actuality of your installation the
following the following listing of source modules may differ.
</para>

<para>The input of
<cmdsynopsis>
<command>gnucash-cli</command>
<arg choice="req">--quotes</arg>
<arg choice="req">info</arg>
</cmdsynopsis>
in the terminal produces the following output:
<footnote id="fn_gnc-fq-old">
<para>In &app; version 5.0 the commands <userinput>gnc-fq-check</userinput>, +
<userinput>gnc-fq-dump</userinput> and <userinput>gnc-fq-helper</userinput> have been +
removed and replaced with similar functions in &app-cli;.
</para>
</footnote>
</para>

<informalexample>
Expand All @@ -314,10 +333,6 @@ za
</screen>
</informalexample>

<para>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.
</para>

<para>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:
</para>
Expand All @@ -330,25 +345,62 @@ Failed to initialize Finance::Quote: missing_modules Finance::Quote JSON::Parse
</screen>
</informalexample>

<para>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
<para>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
<xref linkend="fq-install" />.
</para>
</sect2>

<sect2 id="fq-print-quotes">
<title>Displaying Quotes in a Terminal Window</title>

<abstract>
<para>The <replaceable>--quotes dump</replaceable> mode 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 course source is accessible and provides data.
</para>

<para>You can also check to see if the symbol you want to use for your online
price retrieval is available at the desired price source is
known.
</para>
</abstract>

<tip>
<para>With the use of <userinput>gnucash-cli --quotes dump</userinput>.
<footnoteref linkend="fn_gnc-fq-old" /> you can test symbols faster than from within
&app;, in case an error occurs during the retrieval with &app;. The output of the script
is better suited for analysis, because not all working symbols will be are retrieved as
well, if <guibutton>Get Quotes</guibutton> in the <xref linkend="tool-price" />.
</para>
</tip>

<para>To display a quote for one or more stocks or the exchange rate for one or more currencies you can
use <userinput>gnucash-cli --quotes dump</userinput> as follows. It offers two output forms
for non-currency securities and one for currency exchange rates.
use <userinput>gnucash-cli --quotes dump</userinput> as follows:
<cmdsynopsis>
<command>gnucash-cli</command>
<arg choice="opt">-V</arg>
<arg choice="req">--quotes</arg>
<arg choice="req">dump</arg>
<arg choice="plain"><replaceable>Quelle</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>Symbol</replaceable></arg>
</cmdsynopsis>
</para>

<para>It offers two output forms for non-currency securities and one for currency exchange rates.
<variablelist>
<varlistentry>
<term>Currencies</term>

<listitem>
<para>Currencies use the source <userinput>currency</userinput> and require at least two ISO-4217 currency
codes; the exchange rates are denominated in the first code. For example:
codes; the exchange rates are denominated in the first code.
<footnote>
<para>Since &app-fq; 1.41 the default source for currencies is <quote>Alpha Vantage</quote>. Read also the
notes on <xref linkend="gnc-tbl-fq-currency-source" />.
</para>
</footnote>
For example:
<informalexample>
<?dbfo pgwide="1"?>
<screen language="console">
Expand All @@ -366,12 +418,13 @@ $ gnucash-cli --quotes dump currency USD GBP EUR
<term>Stocks</term>

<listitem>
<itemizedlist>
<listitem>
<para>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.
<informalexample>
<para>To retrieve quotes of your securities, please enter the quote source and the desired symbol.
<itemizedlist>
<listitem>
<para>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.
<informalexample>
<?dbfo pgwide="1"?>
<screen language="console">
$ gnucash-cli --quotes dump yahoo_json AAPL
Expand All @@ -383,18 +436,18 @@ Finance::Quote fields GnuCash uses:
nav: &lt;=== one of these
price: &lt;=/
</screen>
</informalexample>
</para>
</listitem>

<listitem>
<para>With the <userinput>-V</userinput> 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.
<informalexample>
</informalexample>
</para>
</listitem>

<listitem>
<para>With the <userinput>-V</userinput> 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.
<informalexample>
<?dbfo pgwide="1"?>
<screen language="console">
$ ALPHAVANTAGE_API_KEY=123456789 bin/gnucash-cli -V --quotes dump alphavantage INTC
$ ALPHAVANTAGE_API_KEY=123456789 gnucash-cli -V --quotes dump alphavantage INTC
INTC:
method =&gt; alphavantage
p_change =&gt; -1.9304
Expand All @@ -412,48 +465,80 @@ INTC:
volume =&gt; 48118005
last =&gt; 25.9100
</screen>
</informalexample>

<note>
<para>Notice that in this case we used alphavantage and provided the
<userinput>ALPHAVANTAGE_API_KEY</userinput> on the command line. That's not
necessary if the key is already stored in the shell environment or in &app;
preferences.
</para>
</note>
</para>
</listitem>
</itemizedlist>
</informalexample>

<note>
<para>Notice that in this case we used alphavantage and provided the
<userinput>ALPHAVANTAGE_API_KEY</userinput> on the command line. That's
not necessary if the key is already stored in the shell environment or in
&app; preferences.
</para>
</note>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>

<procedure>
<para>To test if &app-fq; works for currencies inside &app;, do the following:
</para>

<step>
<para>create a transaction with the desired commodity in the book currency,
</para>
</step>

<step>
<para>make a right click on it,
</para>
</step>

<step>
<para>select &gmi.ac.ed-ex; in the context menu.
</para>
</step>

<step>
<para>In the <xref linkend="trans-win-enter" /> window click the <guilabel>Get exchange rate</guilabel> button.
</para>
</step>
</procedure>

<para>If the exchange rate source and the symbol are set, the current
rate will be entered in the exchange rate field.
</para>
</sect2>

<sect2 id="fq-auto-quote">
<title>Updating Prices Automatically with &app-cli;</title>

<para>With the command <command>gnucash-cli --quotes get &user-datafile;</command>
<footnote>
<simpara>The old command <command>gnucash --add-price-quotes &user-datafile;</command> is obsolete as of &app; 5.0.
<simpara>The command <command>gnucash --add-price-quotes &user-datafile;</command> is obsolete as of
&app; 5.0.
</simpara>
</footnote>
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.
<note>
<para>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.
<para>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.
</para>
</note>
</para>

<para>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 <quote>-</quote>.
<para>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
<quote>-</quote>.
<tip>
<para>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 <guilabel>statusbar</guilabel>.
<para>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 <guilabel>statusbar</guilabel>.
</para>
</tip>
</para>
Expand Down
Loading

0 comments on commit dc11850

Please sign in to comment.