Provided by: smtm_1.6.10_all bug

NAME

       smtm - Display and update a configurable ticker of global stock quotes

SYNOPSYS

        smtm [options] [stock_symbol ...]

OPTIONS

        --time min      minutes to wait before update
        --file smtmrc   to store/retrieve stocks selected
        --proxy pr      network address and port of firewall proxy
        --fwall [id:pw] account and password for firewall
        --chart len     select length of data interval shown in chart
                        (must be one of b, w, 3, 6, 1, 2, 5, m or t)
        --timeout len   timeout in seconds for libwww-perl UserAgent
        --wide          also display value changes and holdings
        --percent       show relative performance in percent instead of bps
        --sort style    sort display by specified style
                        (must be one r, a, p, v, n, v, V or h)
        --columns set   choose the columns to display (can be any combination
                        of s, n, l, a, r, v, p, V, R, h)
        --nookbutton    close other windows via left mouseclick, suppress button
        --help          print a short help message

DESCRIPTION

       smtm, which is a not overly clever acronym for Show Me The Money, is a financial ticker
       and portfolio application for quotes from exchanges around the world (provided they are
       carried on Yahoo!). It creates and automatically updates a window with quotes from Yahoo!
       Finance. It can also display the entire variety of charts available at Yahoo! Finance.
       When called with one or several symbols, it displays these selected stocks. When smtm is
       called without arguments, it reads the symbols tickers from a file, by default ~/.smtmrc.
       This file can be created explicitly by calling the Save option from the File menu. Beyond
       stocks, smtm can also display currencies (from the Philadephia exchange), US mutual funds,
       options on US stocks, several precious metals and quite possibly more; see the Yahoo!
       Finance website for full information.

       smtm can also aggregate the change in value for both individual positions and the the
       entire portfolio.  For this, the number of shares is needed, as well as the cross-currency
       expression pair. The standard ISO notation is used. As an example, GBPUSD translates from
       Pounds into US Dollars. To compute annualised returns, the purchase date and purchase
       price can also be entered.

       smtm displays the full name of the company, the absolute price change and the relative
       percentage change in basispoints (i.e., hundreds of a percent) or in percentages if the
       corresponding option has been selected.  Other information that can be displayed are the
       traded volume, the profit/loss, the aggregate positon value, the holding period length,
       the annualised return, the drawdown, the earnings per share, the price/earnings ratio, the
       dividend yield, and the market capitalization. Note that the return calculation ignores
       such fine points as dividends, and foreign exchange appreciation or depreciation for
       foreigns stocks.  All display columns can be selected, or deselected, individually.

       Losers are flagged in red.  smtm can be used for stocks from the USA, Canada, various
       European exchanges, various Asian exchanges (Singapore, Taiwan, HongKong, Kuala Lumpur,
       ...) Australia and New Zealand. It should work for other markets supported by Yahoo. US
       mutual funds are also available, but less relevant as their net asset value is only
       computed after the market close. Some fields might be empty if Yahoo! does not supply the
       full set of fields; the number of supported fields varies even among US exchanges. The
       sorting order can be chosen among eight different options.

       The quotes and charts are delayed, typically 15 minutes for NASDAQ and 20 minutes
       otherwise, see http://finance.yahoo.com for details. New Zealand is rumoured to be
       somewhat slower with a delay of one hour. However, it is worth pointing out that (at least
       some) US) indices are updated in real time at Yahoo!, and therefore available in real time
       to smtm.  Intra-day and five-day charts are updated during market hours by Yahoo!, other
       charts with longer timeframes are updated only once a week by Yahoo!.

       smtm supports both simple proxy firewalls (via the --proxy option) and full-blown
       firewalls with account and password authorization (via the --fwall option). Firewall
       account name and password can be specified as command line arguments after --fwall, or
       else in a pop-up window. This setup has been in a few different environments.

       smtm can display two more views of a share position. Clicking mouse button 1 launches a
       detailed view with price, date, change, volume, bid, ask, high, low, year range,
       price/earnings, dividend, dividend yield, market capital information, number of shares
       held and annualised return. However, not all of that information is available at all
       exchanges.  Clicking the right mouse button display a chart of the corresponding stock;
       this only works for US and Canadian stocks.  The type of chart can be specified either on
       the command-line, or via the Chart menu. Choices are intraday, five day, three months, six
       months, one year, two years, five years or max years. The default chart is a five day
       chart. The middle mouse button opens an edit window to modify and augment the information
       stored per stock.

       See http://help.yahoo.com/help/us/fin/chart/ for help on Yahoo!  Finance charts.

       smtm has been written and tested under Linux. It should run under any standard Unix,
       success with Solaris, HP-UX and FreeBSD is confirmed (but problems are reported under
       Solaris when a threaded version of Perl is used). It also runs under that other OS from
       Seattle using the ActivePerl implementation from http://www.activestate.com.  In either
       case, it requires the Perl/Tk module for windowing, and the LWP module (also known as
       libwww-perl) for data retrieval over the web. The excellent Date::Manip modules is also
       required for the date parsing and calculations. With recent versions of ActivePerl, only
       Date::Manip needs to be installed on top of the already provided modules.

EXAMPLES

         smtm CSCO NT

       creates a window following the Cisco and Nortel stocks.

         smtm MSFT:Bill SUNW:Scott ORCL:Larry

       follows three other tech companies and uses the override feature for the displayed name. [
       Historical note: We once needed that for European stocks as Yahoo! did not supply the
       company name way back in 1999 or so. This example just documents a now ancient feature. ]

         smtm  BT.A.L::10:GBPCAD   T::10:USDCAD \
               BCE.TO::10   13330.PA::10:EURCAD \
               "555750.F:DT TELECOM:10:EURCAD"

       creates a window with prices for a handful of telecom companies on stock exchanges in
       London, New York, Toronto, Paris and Frankfurt. Note how a names is specified to override
       the verbose default for the German telco.  Also determined are the number of shares, here
       10 for each of the companies. Lastly, this example assumes a Canadian perspective: returns
       are converted from British pounds, US dollars and Euros into Canadian dollars. Quotation
       marks have to be used to prevent the shell from splitting the argument containing spaces.
       [ Historical note: The Deutsche Telecom stock can now also be referenced as DTEGn.DE;
       similarly other stock previously available only under their share number are now
       accessible using an acronym reflecting their company name.]

MENUS

       Four menus are supported: File, Edit, Chart and Help.  The File menu offers to load or
       save to the default file, or to 'save as' a new file.  Exit is also available.

       The Edit menu can launch windows to either add a new stock or delete one or several from a
       list box. Submenus for column selection based on various criteria are available.
       Similarly, the Sort menu allows to select one of eight different sort options.  Further,
       one can modify the delay time between updates and choose between the default title display
       or the wide display with changes in the position and total position value.

       The Charts menu allows to select the default chart among the eight choices intraday, five
       day, three months, six months, one year, two years, five years or 'max' years. Chart sizes
       can be selected among three choices. Plot types can be selected among line chart, bar
       chart and the so-called candlestick display. For both moving averages and exponential
       moving averages, six choices are avilable (5, 10, 20, 50, 100 and 200 days, respectively)
       which can all be selected (or deselected) individually. Similarly, any one of seven
       popular technical analysis charts can be added. Logarithmic scale can be turned on/off.
       Volume bar charts as also be selected or deselected. Similarly, Bollinger bands and the
       parabolic SAR can be selected. A selection box can be loaded to enter another symbol (or
       several of these, separated by comma) for performance comparison. Lastly, the gallery
       command can launch the display of a chart for each and every stock symbol currenly loaded
       in the smtm display.  Note that intra-day and intra-week charts do not offer all the
       various charting options longer-dated charts have available.  Once charts are shown, they
       are also updated regularly at the same interval the main displayed is updated at.

       Lastly, the Help menu can display either the text from the manual page, or the copyright
       information in a new window.

DISPLAY

       The main window is very straightforward. For each of the stocks, up to eleven items can be
       displayed: its symbol, its name, its most recent price, the change from the previous close
       in absolute terms, the change in relative terms, the volume, the profit or loss, the total
       position value, the holding period, the annualised return (bar F/X effects or dividends)
       and the drawdown relative to the 52-week high.  The relative change is either expressed in
       basispoints (bps), which are 1/100s of a percent, or in percent; this can be controlled
       via a checkbutton as well as an command-line option.  Further display options are earnings
       per share, price/earnings ratio, dividend yield and market capitalization.  This display
       window is updated in regular intervals; the update interval can be specified via a menu or
       a command-line option.

       The window title displays the relative portfolio profit or loss for the current day in
       basispoints, i.e., hundreds of a percent, or in percent if the corresponding option is
       chosen, as well as the date of the most recent update. If the --wide options is used, the
       net change and ney value of the portfolio (both in local currency) are also displayed.

       Clicking on any of the stocks with the left mouse button opens a new window with all
       available details for a stock. Unfortunately, the amount of available information varies.
       Non-North American stocks only have a limited subset of information made available via the
       csv interface of Yahoo!. For North American stocks, not all fields all provided by all
       exchanges. Clicking on the details display window itself closes this window. Clicking on
       any of the stocks with the right mouse button opens a new window with a chart of the given
       stock in the default chart format. This option was initially available only for North
       American stocks but now works across most if not all markets, thanks to expanded support
       by Yahoo!.  Clicking on the chart window itself closes this window. Finally, the middle
       mouse button opens an edit window.

CHART DISPLAY (AKA 'GALLERY' MODE)

       In 'gallery' mode, chart windows are opened for all active securities.  These charts are
       automatically updated whenever the display is updated.  This mean that only the intra-
       daily and intra-weekly chart timeframe selection are meaningful -- all others are updated
       at the source, i.e. Yahoo!, daily or weekly, and there is no little point in downloading
       the same chart over and over again.

       However, for intra-daily and intra-weekly charts, this is a very useful feature. It should
       be noted that not all chart size, chart timeframe and chart option permutations actually
       lead to existing charts. For example, logarithmic scale does seem to exist for shorter-
       dated time frames. Neither does the 'small' chart size.

BUGS

       Closing the stock addition or deletion windows have been reported to cause random
       segmentation violation under Linux. This appears to be a bug in Perl/Tk which will
       hopefully be solved, or circumvented, soon.  This bug does not bite under Solaris, FreeBSD
       or NT or other Linux distributions. Update: This problem appears to have disappeared with
       Perl 5.6.*.

       Problems with undefined symbols have been reported under Solaris 2.6 when Perl has been
       compiled with thread support. Using an unthreaded Perl binary under Solaris works. How
       this problem can be circumvented is presently unclear.

       It is not clear whether the market capitalization information is comparable across
       exchange. Some differences could be attributable to 'total float' versus 'free float'
       calculations.

SEE ALSO

       Finance::YahooQuote.3pm, Finance::YahooChart.3pm, LWP.3pm, lwpcook.1, Tk::UserGuide.3pm

       See http://help.yahoo.com/help/us/fin/chart/ for help on Yahoo!  Finance charts.

COPYRIGHT

       smtm is (c) 1999 - 2008 by Dirk Eddelbuettel <edd@debian.org>

       Updates to this program might appear at http://dirk.eddelbuettel.com/code/smtm.html. If
       you enjoy this program, you might also want to look at my beancounter program
       http://dirk.eddelbuettel.com/code/beancounter.html, as well as the Finance::YahooQuote
       module at http://dirk.eddelbuettel.com/code/yahooquote.html which was originally written
       by Dj Padzensky, and that is used by both smtm and beancounter.

       This program is free software; you can redistribute it and/or modify it under the terms of
       the GNU General Public License as published by the Free Software Foundation; either
       version 2 of the License, or (at your option) any later version.  There is NO warranty
       whatsoever.

       The information that you obtain with this program may be copyrighted by Yahoo! Inc., and
       is governed by their usage license.  See
       http://www.yahoo.com/docs/info/gen_disclaimer.html for more information.

ACKNOWLEDGEMENTS

       The Perl code by Dj Padzensky, in particular his Finance::YahooQuote module (originally on
       the web at http://www.padz.net/~djpadz/YahooQuote/ and now maintained by me at
       http://dirk.eddelbuettel.com/code/yahooquote.html/) and his Finance::YahooChart module (on
       the web at http://www.padz.net/~djpadz/YahooChart/) were most helpful. They provided the
       initial routines for downloading stock data and determining the Yahoo! Chart url. Earlier
       version of smtm use a somewhat rewrittem variant (which still reflected their heritage),
       newer version rely directly on Finance::YahooQuote now that Yahoo!  uses a similar backend
       across the globe. Dj's code contribution is most gratefully acknowledged.

CPAN

       The remaining sections pertain to the CPAN registration of smtm. The script category is a
       little mismatched but as there is no Finance section, Networking was as good as the other
       choices.

SCRIPT CATEGORIES

       Networking

PREREQUISITES

       On Windows, smtm can use the Perl distribution from http://www.activestate.com.  On both
       Unix and Windows, smtm requires the "Tk" module for windowing, the "LWP" module for data
       retrieval over the web, and the excellent "Date::Manip" module for the date parsing and
       calculations. Finance::YahooQuote is used for actual data access. Tk::PNG is used to
       display the png charts since Yahoo! switched from gif to png around May 2005.

COREQUISITES

       None.

OSNAMES

       smtm is not OS dependent. It is known to run under Linux, several commercial Unix variants
       and Windows

README

       smtm, which is a not overly clever acronym for Show Me The Money, is a financial ticker
       and portfolio application for quotes from exchanges around the world (provided they are
       carried on Yahoo!). It creates and automatically updates a window with quotes from Yahoo!
       Finance. It can also display the entire variety of charts available at Yahoo! Finance.
       Fairly extensive documentation for smtm is available at
       http://dirk.eddelbuettel.com/code/smtm.html.