Skip to content

Commit

Permalink
Improve documentation for gnucash-cli
Browse files Browse the repository at this point in the history 
insert
- entities for MAC
- new lines
- variablelist
  • Loading branch information
@CWehli
CWehli committed May 4, 2023
1 parent 95cf269 commit ad2693f
Showing 1 changed file with 160 additions and 90 deletions.
250 changes: 160 additions & 90 deletions C/manual/ch_Finance-Quote.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -61,11 +61,12 @@ Translators:
<para>To check if &app-perl; is already installed on your system, call the command
<userinput>perl -v</userinput> in the terminal.
<!-- Fixme: https://bugs.gnucash.org/show_bug.cgi?id=798618 -->
<informalexample><?dbfo pgwide="1"?>
<informalexample><?dbfo pgwide="1"?>
<screen language="console">$ perl -v
This is perl 5, version 30, subversion 0 (v5.30.0) built for x86_64-linux-gnu-thread-multi
This is perl 5, version 30, subversion 0 (v5.30.0) built for x86_64-linux-gnu-
thread-multi
</screen>
</informalexample>
</informalexample>
If you are shown the version number of the &app-perl; interpreter, skip the next details
and continue instead with <xref linkend="finance-quote-install" />.
</para>
Expand Down Expand Up @@ -144,17 +145,16 @@ This is perl 5, version 30, subversion 0 (v5.30.0) built for x86_64-linux-gnu-th
<para>To determine if the &app-perl; module &app-fq; is already installed on your system, type
<userinput>perldoc Finance::Quote</userinput> in a terminal window and check to see if there is
any documentation
<!-- Fixme: https://bugs.gnucash.org/show_bug.cgi?id=798618 -->
<informalexample><?dbfo pgwide="1"?>
<informalexample><?dbfo pgwide="1"?>
<screen language="console">
$ perldoc Finance::Quote
NAME
Finance::Quote - Get stock and mutual fund quotes from various exchanges
$ perldoc Finance::Quote
NAME
Finance::Quote - Get stock and mutual fund quotes from various exchanges

SYNOPSIS
[...]
SYNOPSIS
[...]
</screen>
</informalexample>
</informalexample>
available. If you are now shown documentation, then &app-fq; is already installed and you can
configure periodical quotes update as described in <xref linkend="fq-auto-quote" />.
If no documentation is displayed, you will have to continue with this chapter.
Expand All @@ -173,12 +173,13 @@ SYNOPSIS
</step>

<step>
<simpara>Run the <userinput>gnucash-cli --quotes info</userinput> command to verify that the program is already in a directory
<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,
<filename>gnucash-cli</filename> must be on your <envar>PATH</envar>. The currentness of your
distribution can be checked under
<filename>gnucash-cli</filename> 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 @@ -222,14 +223,23 @@ SYNOPSIS
</step>

<step>
<simpara>Open a Finder window, select <guimenu>Applications</guimenu> from the sidebar, double-click <guimenu>Utilities</guimenu> in the file area, then double-click on <guimenu>Terminal</guimenu> to open <application>Terminal</application></simpara>
<simpara>Open a <application>Finder</application> window, select &gm.macOS.appl; from the sidebar,
double-click &gmi.macOS.appl.util; in the file area, then double-click
on <guimenu>Terminal</guimenu> to open <application>Terminal</application>
</simpara>
</step>

<step>
<simpara>In the Terminal window enter <userinput>sudo /Applications/Gnucash.app/Contents/Resources/bin/gnc-fq-update</userinput>. That script asks lots of questions. Accept the default for each.
<simpara>In the Terminal window enter
<userinput>sudo /Applications/Gnucash.app/Contents/Resources/bin/gnc-fq-update</userinput>.
That script asks lots of questions. Accept the default for each.
</simpara>
</step>

<step>
<simpara>Type <userinput>exit</userinput> or <keycombo action='simul'><keycap>Control</keycap><keycap>D</keycap></keycombo> to terminate the shell followed by <keycombo action='simul'><keycap>Command</keycap><keycap>Q</keycap></keycombo> to quit <application>Terminal</application>.
<simpara>Type <userinput>exit</userinput> or <keycombo>&kc.ctrl;<keycap>D</keycap></keycombo>
to terminate the shell followed by <keycombo>&kc.cmd;<keycap>Q</keycap></keycombo>
to quit <application>Terminal</application>.
</simpara>
</step>
</procedure>
Expand All @@ -253,15 +263,21 @@ 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 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.
<para>&app; provides a commandline facility &app-cli; 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.
</para>
</abstract>

<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:</para>
<!-- Fixme: https://bugs.gnucash.org/show_bug.cgi?id=798618 -->

<para><command>gnucash-cli --quotes info</command> produces the following output:
</para>

<informalexample><?dbfo pgwide="1"?>
<screen language="console">
<screen language="console">
$ gnucash-cli --quotes info
Found Finance::Quote version 1.52.
Finance::Quote sources:
Expand All @@ -279,73 +295,128 @@ SYNOPSIS
tiaacref tmx tradeville troweprice troweprice_direct
tsp ukfunds unionfunds usa usfedbonds yahoo_json
za
</screen></informalexample>
<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>
</screen>
</informalexample>

<para>The latest &app-fq; version is &app-fq-vers;.
</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>

<informalexample><?dbfo pgwide="1"?>
<screen language="console">
<screen language="console">
$ gnucash-cli --quotes info
Failed to initialize Finance::Quote: missing_modules Finance::Quote JSON::Parse
</screen></informalexample>
</screen>
</informalexample>
</sect2>

<sect2 id="fq-print-quotes">
<title>Displaying Quotes in a Terminal Window</title>
<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.
<itemizedlist>
<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:
<informalexample><?dbfo pgwide="1"?>
<screen language="console">
$ gnucash-cli --quotes dump currency USD GBP EUR
1 GBP = 1.11917349089527 USD

1 EUR = 0.9717 USD
</screen></informalexample></para></listitem>
<listitem><para>Stocks</para><itemizedlist>
<listitem><para>A short form displaying only the fields that GnuCash uses along with comments indicating whether the fields are optional or required; you can use this to determine if GnuCash 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
Finance::Quote fields GnuCash uses:
symbol: AAPL &lt;=== required
date: 10/14/2022 &lt;=== recommended
currency: USD &lt;=== required
last: 138.38 &lt;=\
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><?dbfo pgwide="1"?>
<screen language="console">
$ ALPHAVANTAGE_API_KEY=123456789 bin/gnucash-cli -V --quotes dump alphavantage INTC
INTC:
method =&gt; alphavantage
p_change =&gt; -1.9304
high =&gt; 26.6300
date =&gt; 10/14/2022
currency_set_by_fq =&gt; 1
close =&gt; 26.4200
currency =&gt; USD
isodate =&gt; 2022-10-14
low =&gt; 25.7600
success =&gt; 1
net =&gt; -0.5100
open =&gt; 26.4600
symbol =&gt; INTC
volume =&gt; 48118005
last =&gt; 25.9100
</screen></informalexample>
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 GnuCash preferences.</para>
</listitem></itemizedlist></listitem>
</itemizedlist>
</para></sect2>

<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.
<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:
<informalexample><?dbfo pgwide="1"?>
<screen language="console">
$ gnucash-cli --quotes dump currency USD GBP EUR
1 GBP = 1.11917349089527 USD

1 EUR = 0.9717 USD
</screen>
</informalexample>
</para>
</listitem>
</varlistentry>

<varlistentry>
<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><?dbfo pgwide="1"?>
<screen language="console">
$ gnucash-cli --quotes dump yahoo_json AAPL
Finance::Quote fields GnuCash uses:
symbol: AAPL &lt;=== required
date: 10/14/2022 &lt;=== recommended
currency: USD &lt;=== required
last: 138.38 &lt;=\
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><?dbfo pgwide="1"?>
<screen language="console">
$ ALPHAVANTAGE_API_KEY=123456789 bin/gnucash-cli -V --quotes dump alphavantage INTC
INTC:
method =&gt; alphavantage
p_change =&gt; -1.9304
high =&gt; 26.6300
date =&gt; 10/14/2022
currency_set_by_fq =&gt; 1
close =&gt; 26.4200
currency =&gt; USD
isodate =&gt; 2022-10-14
low =&gt; 25.7600
success =&gt; 1
net =&gt; -0.5100
open =&gt; 26.4600
symbol =&gt; 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>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>

<sect2 id="fq-auto-quote">
<title>Updating Prices Automatically with &app-cli;</title>
<para>You have to register the &app-cli; with a scheduler in order to get Online
Quotes automatically and periodically. The method depends on your OS.
</para>
<para>You have to register the &app-cli; with a scheduler in order to get Online
Quotes automatically and periodically. The method depends on your OS.
</para>

<example>
<title>Automated quote retrieval every Friday at 4:00 p.m.</title>
<example>
<title>Automated quote retrieval every Friday at 4:00 p.m.</title>

<procedure>
<title>On &lin; and &mac;</title>
Expand All @@ -360,16 +431,20 @@ SYNOPSIS

<step>
<para>Add the following line to your crontab:
<informalexample>
<screen>0 16 * * 5 gnucash-cli --quotes get &user-datafile; &gt; /dev/null 2&gt;&amp;1</screen>
<informalexample><?dbfo pgwide="1"?>
<screen>
0 16 * * 5 gnucash-cli --quotes get &user-datafile; &gt; /dev/null 2&gt;&amp;1
</screen>
</informalexample>

<important>
<para>On &lin; if there is no graphic session that has already started the dbus, running on your computer at the
time of the quote request, you must do the entry as follows instead:
<informalexample>
<screen>0 16 * * 5 env `dbus-launch` sh -c 'trap "kill $DBUS_SESSION_BUS_PID" EXIT;
gnucash-cli --quotes get &user-datafile; &gt; /dev/null 2&gt;&amp;1</screen>
<informalexample><?dbfo pgwide="1"?>
<screen>
0 16 * * 5 env `dbus-launch` sh -c 'trap "kill $DBUS_SESSION_BUS_PID" EXIT;
gnucash-cli --quotes get &user-datafile; &gt; /dev/null 2&gt;&amp;1
</screen>
</informalexample>
(Do not copy the line breaks into the crontab, they were inserted here only for the
purpose of readability).
Expand All @@ -386,17 +461,12 @@ gnucash-cli --quotes get &user-datafile; &gt; /dev/null 2&gt;&amp;1</screen>
</para>

<step>
<simpara>Select
<menuchoice>
<guimenu>Start</guimenu><guisubmenu>Windows Administrative
Tools</guisubmenu><guimenuitem>Task Scheduler</guimenuitem>
</menuchoice>
.
<simpara>Select &mc.winOS.sys.tasks;
</simpara>
</step>

<step>
<simpara>Select <guimenuitem>Create Task</guimenuitem>.
<simpara>Select &gmi.winOS.sys.task;.
</simpara>
</step>

Expand Down

0 comments on commit ad2693f

Please sign in to comment.