<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter SYSTEM "gnc-docbookx.dtd">
<!-- (Do not remove this comment block.)
Version: 1.0.0
Last modified: August 08th 2021

Maintainers:
  xxx
Author:
  TANIGUCHI Yasuaki <yasuakit@gmail.com>
  Christian Wehling <christian.wehling@web.de>
Translators:
  (translators put your name and email here)
-->
<chapter id="finance-quote"
         xmlns:xi="http://www.w3.org/2001/XInclude">
  <title>Setting up the Online Quote update</title>

  <para>If you have more than a couple of commodities, you will tire of having to update their quotes
    constantly. &app; has the ability to automatically download the most recent quote for your
    commodities using the Internet. This is accomplished through the &app-perl; module &app-fq;,
    which must be installed in order to activate this feature.
  </para>

  <sect1 id="finance-quote-install">
    <title>Installing &app-fq;</title>

    <para>To determine if the &app-perl; module &app-fq; is already installed on your system, type
      <command>perldoc Finance::Quote</command> in a terminal window and check to see if there is
      any documentation
<screen>NAME
    Finance::Quote - Get stock and mutual fund quotes from various exchanges

SYNOPSIS
       [...]
</screen>
      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="finance-quote-scheduler" />.
      If no documentation is displayed, you will have to continue with this chapter.
    </para>

    <itemizedlist>
      <title>Prerequisites for an Online Quote update with &app-fq;</title>

      <listitem>
        <para>the &app-perl; language interpreter,
        </para>
      </listitem>

      <listitem>
        <para>the &app-perl;-module &app-fq; and
        </para>
      </listitem>

      <listitem>
        <para>any dependencies required by the &app-fq; module.
        </para>
      </listitem>
    </itemizedlist>

    <note>
      <para>If you feel uncomfortable about performing any of these steps, please either email the &app;-user
        mailing list (<email>gnucash-user@gnucash.org</email>) for help or come to the
        <ulink url="&url-irc;">#&appname; IRC channel</ulink>.
        You can also find more information in the &app; wiki at
        <ulink url="&url-wiki-OQ;">Online Quotes</ulink>. You can also leave out this step and
        manually update your stock quotes.
      </para>
    </note>

    <para>The installation of &app-perl; is not the focus of this manual. A detailed description can be found
      in the &app; Wiki at <ulink url="&url-wiki-OQ;#Perl">Perl</ulink>.
    </para>

    <para>The process of installing &app-fq; depends on the system. For the different supported systems, you
      can follow the instructions below:
    </para>

    <procedure>
      <title>Installing &app-fq; on &lin;</title>

      <step>
        <simpara>Close &app;.
        </simpara>
      </step>

      <step>
        <simpara>Run the <command>gnc-fq-check</command> command to verify that the program is already in a directory
          that is entered in the PATH environment variable.
          <footnote>
            <simpara>If you&rsquo;ve installed &app; packages provided by your distribution,
              <filename>gnc-fq-check</filename> must be on your PATH. The currentness of your
              distribution can be checked under
              <ulink url="&url-repo;perl:finance-quote/versions"><citetitle>&app-fq;-
              versions</citetitle></ulink>.
            </simpara>
          </footnote>
        </simpara>

        <tip>
          <simpara>If <filename>gnc-fq-check</filename> is not in your PATH, perhaps because you built the application
            yourself using unusual paths, search the folder where &app; is installed, e.g. with the
            command <command>which gnc-fq-check</command>, and change to that directory. It is a
            good idea to include the current directory in the PATH environment variable. Please
            refer to the documentation for your distribution for more information.
          </simpara>
        </tip>
      </step>

      <step>
        <simpara>Next, update with <command>sudo gnc-fq-update</command> or <command>su -c gnc-fq-update</command>
          with root privileges &app-fq; It depends on your distribution.
        </simpara>

        <para>This will launch a &app-perl; <acronym><ulink url="&url-cpan;">CPAN</ulink></acronym>
          <footnote>
            <simpara>See <ulink url="&url-cpan;misc/cpan-faq.html">CPAN Frequently Asked Questions</ulink> for details.
            </simpara>
          </footnote>
          module internally. When you launch the CPAN module for the first time, you must setup and
          configure it. However, on the most systems if you accept the default settings or answer
          the first question <computeroutput>Are you ready for manual configuration?
          [yes]</computeroutput> with <userinput>no</userinput>, you will be able to install
          &app-fq; successfully.
        </para>
      </step>

      <step>
        <simpara>Run <command>gnc-fq-dump</command> to check &app-fq; works properly. This program 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.
        </simpara>
      </step>
    </procedure>

    <procedure>
      <title>Installing &app-fq; on &mac;</title>

      <step>
        <simpara>Close &app;.
        </simpara>
      </step>

      <step>
        <simpara>Install Xcode if it is not installed.
        </simpara>

        <simpara>XCode is an optional item from your &mac; distribution DVD.
        </simpara>
      </step>

      <step>
        <simpara>Run the <emphasis>Update Finance Quote</emphasis> app in the &app; dmg.
        </simpara>

        <para>You can run it from the dmg or copy it to the same folder to which you copied &app;. It will open a
          Terminal window and run a script for you which will ask lots of questions. Accept the
          default for each unless you know what you&rsquo;re doing.
        </para>
      </step>
    </procedure>

    <procedure>
      <title>Installing &app-fq; on &win;</title>

      <step>
        <simpara>Close &app;.
        </simpara>
      </step>

      <step>
        <simpara>Run
          <menuchoice>
            <guimenu>Start</guimenu> <guisubmenu>&app;</guisubmenu> <guimenuitem>Install Online
            Price Retrieval</guimenuitem>
          </menuchoice>
          . This is a small utility that installs &app-fq; for you.
        </simpara>
      </step>
    </procedure>
  </sect1>

  <sect1 id="finance-quote-scheduler">
    <title>Configuring for Getting Online Quotes Periodically</title>

    <para>The command <command>gnucash-cli --quotes get &user-datafile;</command>
      <footnote>
        <simpara>The Online Quotes Retrieval command has been changed from &app; 4.0. The old command
          <command>gnucash --add-price-quotes &user-datafile;</command> is still available, but it
          is deprecated and will be removed in the future release. If you've upgraded from &app;
          3.11 or previous version, it is recommended to use the new command
          <command>gnucash-cli</command>.
        </simpara>
      </footnote>
      can be used to fetch the current quotes of your stocks and write them directly into your
      &app;-data file without starting the GUI. Thus an automatic, regular updating of the
      price database is possible.
      <warning>
        <para>Please note that the data file should not be open in another instance of &app; at the same time!
        </para>
      </warning>
    </para>

    <para>The file specified &user-datafile; will depend on the name and location of your data file. This can
      be determined by the name displayed in the top frame of the &app; window, before the
      <quote>-</quote>.
      <tip>
        <para>The file name can also be found under <guimenu>File</guimenu> in the recently opened file list. If
          you place the mouse over the menu item with the number 1 in the list of recently opened
          files, the complete file name is displayed in the <guilabel>status bar</guilabel>.
        </para>
      </tip>
    </para>

    <para>You have to register the <command>gnucash-cli</command> 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>

      <procedure>
        <title>On &lin; and &mac;</title>

        <para>Register <command>gnucash-cli</command> with <application>cron</application>.
        </para>

        <step>
          <simpara>Run <command>crontab -e</command>.
          </simpara>
        </step>

        <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>

            <warning>
              <para>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>
                (Do not copy the line breaks into the crontab, they were inserted here only for the
                purpose of readability).
              </para>
            </warning>
          </para>
        </step>
      </procedure>

      <procedure>
        <title>On &win;</title>

        <para>Register <command>gnucash-cli</command> with Task Scheduler.
        </para>

        <step>
          <simpara>Select
            <menuchoice>
              <guimenu>Start</guimenu><guisubmenu>Windows Administrative
              Tools</guisubmenu><guimenuitem>Task Scheduler</guimenuitem>
            </menuchoice>
            .
          </simpara>
        </step>

        <step>
          <simpara>Select <guimenuitem>Create Task</guimenuitem>.
          </simpara>
        </step>

        <step>
          <simpara>Enter the appropirate items on <guilabel>Create Task</guilabel> Window.
          </simpara>
        </step>
      </procedure>

      <para>Adjust the time to the close of the stock exchange and consider <emphasis>fund quotes</emphasis>,
        that the net asset value (NAV) is determined well after the markets closed. The types have
        their description in <xref linkend="tool-price" />.
<!-- FIXME: aadjust the link to a proper ID -->
      </para>
    </example>

    <para>Some users have made additions to the wiki and shared their experiences on the
      <ulink url="&url-wiki-OQ;#Updating_enabled_Quotes_from_outside_GnuCash">Online Quotes Page on
      GnuCash Wiki</ulink>.
    </para>
  </sect1>
</chapter>
