chiark / gitweb /
Some fixes already done
[ypp-sc-tools.db-test.git] / yarrg / README
index 82301b2..526d466 100644 (file)
@@ -4,7 +4,7 @@ YARRG - Yet Another Revenue Research Gatherer
 Overview
 --------
 
-This tool can:
+This tool will:
   - screenscrape the commodities trading screen
   - produce the results as a tab separated values file
   - upload the results to the YARRG and PCTB servers
@@ -13,19 +13,18 @@ To build, install the dependencies, cd to this directory and type `make'.
 
 To screenscrape and upload to both servers, select `trade
 commodities' from the hold of a vessel or building, and run:
-   ./ypp-commodities
-Currently we upload to the dedicated yarrg server yarrg.chiark.net,
-and also to pctb.ilk.org (the testing instance of the PCTB database,
-pending approval from the operators of the main server).
+   ./yarrg
+We upload to the dedicated yarrg server http://yarrg.chiark.net/,
+and also to the PCTB server http://pctb.crabdance.com/.
 
 Or, for example, for a tab-separated values dump:
-   ./ypp-commodities --tsv >commods.tsv
+   ./yarrg --tsv >commods.tsv
 
 While it is capturing the screenshots, do not move the mouse or use
-the keyboard.  Keyboard focus must stay in the YPP client window.
-If you use Gnome or KDE you must raise the YPP client window so that
-it is completely unobscured - the ypp-commodities program tries to do
-this but metacity and kwin do not honour the request.
+the keyboard.  Keyboard focus must stay in the YPP client window.  If
+you use Gnome or KDE you must raise the YPP client window so that it
+is completely unobscured - the yarrg program tries to do this but
+metacity and kwin do not honour the request.
 
 
 Command-line options
@@ -49,12 +48,14 @@ Options to vary the processing:
   --test-servers        Set default servers to be the test servers, not
                          the real live ones (doesn't affect explicit settings).
 
-Controlling what happens to the results - only one at a time:
-  --upload (default) Upload to the YARRG and PCTB servers
-  --tsv              Print data as clean tab-separated-values file
-  --raw-tsv          Dump the raw (not deduped, unsorted) OCR'd data
-  --best-prices      Print best buy and sell price for each commodity
-  --arbitrage        Print arbitrage opportunities
+Controlling what happens to the results - one or more:
+  --upload (default)    Upload to both the YARRG and PCTB servers
+  --upload-pctb         Upload to the PCTB servers
+  --upload-yarrg        Upload to the YARRG servers
+  --tsv                 Print data as clean tab-separated-values file
+  --raw-tsv             Dump the raw (not deduped, unsorted) OCR'd data
+  --best-prices         Print best buy and sell price for each commodity
+  --arbitrage           Print arbitrage opportunities
 
 Privacy options, which control conversations with the dictionary server:
   --dict-local-only  *  Do not talk to the server even to fetch new dictionary.
@@ -65,10 +66,11 @@ Please do not use options marked * with --upload.  See README.privacy.
 
 Options to override which servers we talk to:
   --yarrg-server HOST|URL When uploading to YARRG, use HOST or URL.
-  --pctb-server HOST|URL  Talk to the PCTB database at HOST or URL.
-  --dict-submit-url URL   Submit dictionary entries with HTTP POST under URL.
+  --pctb-server HOST|URL  When talking to PCTB, use HOST or URL.
+  --dict-submit-url URL   Submit dictionary updates here (default: use yarrg).
   --dict-update-from SRC  Fetch updated master dictionary with rsync from SRC.
-Or set the environment variables YPPSC_YARRG{_PCTB, _DICT_UPDATE, _DICT_SUBMIT}
+Or set the environment variables
+  YPPSC_YARRG{_YARRG, _PCTB, _DICT_UPDATE, _DICT_SUBMIT}
 
 
 Installation requirements
@@ -94,7 +96,7 @@ This program has quite a few dependencies:
 On other Linux distros the packages may have different names, but
 these should be roughly right for Debian and its derivatives.  You can
 install them with this rune:
-  sudo apt-get install build-essential libnetpbm10-dev netpbm libx11-dev libxtst-dev libpcre3-dev tk8.4 libxml-parser-perl libjson-perl
+  sudo apt-get install git-core build-essential libnetpbm10-dev netpbm libx11-dev libxtst-dev libpcre3-dev tk8.4 libxml-parser-perl libjson-perl
 
 
 The supplied helper programs
@@ -102,10 +104,10 @@ The supplied helper programs
   commod-results-processor
   database-info-fetch
 must (currently) also be in the current working directory when you run
-the main ypp-commodities program.
+the main yarrg program.
 
 The data files (see README.files) are also left in the current working
-directory.  There is notyet any feature to have the data files and
+directory.  There is not yet any feature to have the data files and
 helpers be somewhere else.
 
 
@@ -121,7 +123,7 @@ for me to download that will help.  At least keep a copy of it.
 
 If the problem is a failure to cope with some particular YPP client
 display and is reproducible, try running:
-   ./ypp-commodities --raw-tsv --single-page
+   ./yarrg --raw-tsv --single-page
 If this reproduces the problem, please email me the screenshot file
 _pages.ppm, which will consist only of the single screen, plus the
 error messasge.  I'll then be able to understand what's wrong,
@@ -147,8 +149,8 @@ GUI.
 See README.privacy for full details.
 
 
-Authorship and copyright
-------------------------
+Disclaimers, authorship and copyright
+-------------------------------------
 
 The PCTB server is a project of Joel Lord and various others.
 
@@ -156,32 +158,45 @@ The YARRG server was inspired by PCTB and is a project of the crew
 Special Circumstances (on the Midnight Ocean) and of the Sinister
 Greenend Organisation.
 
+PCTB and YARRG are both completely unofficial and Three Rings, the
+operators of Yohoho Puzzle Pirates, have nothing to do with either of
+them.  Please refer queries to us, not to Three Rings.  If you want to
+reuse the code here to do substantially novel things, you should ask
+Three Rings for permission (for example, by petitioning an Ocean
+Master).
+
 
 This yarrg screenscraper and upload client was written entirely from
-scratch by me, Ian Jackson, with assistance from Stephen Early.  It is
-part of ypp-sc-tools, a set of third-party tools for assisting players
-of Yohoho Puzzle Pirates.
+scratch by me, Ian Jackson, with assistance from Clare Boothby,
+Stephen Early, and Naath.  It is part of ypp-sc-tools, a set of
+third-party tools for assisting players of Yohoho Puzzle Pirates.
 
-ypp-sc-tools is
+ypp-sc-tools and YARRG are
 Copyright (C) 2009 Ian Jackson <ijackson@chiark.greenend.org.uk>
-Copyright (C) 2009 Stephen Early
+Copyright (C) 2009 Clare Boothby
+Copyright (C) 2009 Steve Early
+Copyright (C) 2009 Naath Cousins
 
 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 3 of the License, or
-(at your option) any later version.
+it under the terms of
+ (a) for the website code including the route searcher,
+      the GNU Affero General Public License and
+ (b) for the rest of the code, GNU General Public License
+as published by the Free Software Foundation, either version 3 of
+each applicable the License, or (at your option) any later version.
 
 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.
 
-You should have received a copy of the GNU General Public License
-along with this program.  If not, see <http://www.gnu.org/licenses/>.
+You should have received a copy of the GNU General Public License and
+GNU Affero General Public License along with this program.  If not,
+see <http://www.gnu.org/licenses/>.
 
 Yohoho and Puzzle Pirates are probably trademarks of Three Rings and
-are used without permission.  This program is not endorsed or
-sponsored by Three Rings.
+are used without permission.  Once again, this program is not endorsed
+or sponsored by Three Rings.
 
 
 The character and UI images copied from the YPP client, and submitted