--- /dev/null
+<%doc>
+
+ This is part of the YARRG website. YARRG is a tool and website
+ for assisting players of Yohoho Puzzle Pirates.
+
+ Copyright (C) 2009 Ian Jackson <ijackson@chiark.greenend.org.uk>
+ Copyright (C) 2009 Clare Boothby
+
+ YARRG's client code etc. is covered by the ordinary GNU GPL (v3 or later).
+ The YARRG website is covered by the GNU Affero GPL v3 or later, which
+ basically means that every installation of the website will let you
+ download the source.
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as
+ published by the Free Software Foundation, either version 3 of 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 Affero General Public License for more details.
+
+ You should have received a copy of the 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.
+
+
+ This Mason component generates information about the old yarrg client.
+
+
+</%doc>
+<& docshead &>
+<h1>"yarrg" screenscraper for YARRG and PCTB</h1>
+
+There is an obsolete screenscraper for Linux, known as "yarrg". It is
+much slower and less reliable than JPCTB. We recommend you use
+<a href="upload">YARRG JPCTB</a> instead.
+
+<h2>Instructions for using obsolete "yarrg"</h2>
+
+<p>
+
+The current official version of the yarrg screenscraper can browsed here:
+ <a href="http://www.chiark.greenend.org.uk/~ijackson/ypp-sc-tools/master/">http://www.chiark.greenend.org.uk/~ijackson/ypp-sc-tools/master/</a> .
+See particularly the
+<a href="http://www.chiark.greenend.org.uk/~ijackson/ypp-sc-tools/master/yarrg/README">YARRG README</a>.
+
+<p>
+To install the client, install the "git" version control system
+and the other dependencies listed in the "Installation requirements"
+section of the README and then run:
+<pre>
+git-clone http://www.chiark.greenend.org.uk/~ijackson/ypp-sc-tools/master/.git ypp-sc-tools
+cd ypp-sc-tools
+cd yarrg
+make
+</pre>
+this will download the code into the directory <code>ypp-sc-tools</code>,
+and build the software. (If your Linux is very up to date you may
+find that it complains that it doesn't know the command <kbd>git-core</kbd>.
+In that case, use <kbd>git core</kbd>, with a space, instead.)
+
+<p>
+
+When new versions of the upload client are released, you can:
+<pre>
+cd .../ypp-sc-tools
+git-pull
+cd yarrg
+make
+</pre>
+to fetch the new version. (Again, you may need <kbd>git pull</kbd>
+instead of <kbd>git-pull</kbd>.)
+
+<h2>Windows and MacOS</h2>
+<p>
+The yarrg scraper would be almost impossible to port to Windows. In
+any case it is obsolete.
+
+</div>
+<& footer &>
+<%doc>
+
+ This is part of the YARRG website. YARRG is a tool and website
+ for assisting players of Yohoho Puzzle Pirates.
+
+ Copyright (C) 2009 Ian Jackson <ijackson@chiark.greenend.org.uk>
+ Copyright (C) 2009 Clare Boothby
+
+ YARRG's client code etc. is covered by the ordinary GNU GPL (v3 or later).
+ The YARRG website is covered by the GNU Affero GPL v3 or later, which
+ basically means that every installation of the website will let you
+ download the source.
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as
+ published by the Free Software Foundation, either version 3 of 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 Affero General Public License for more details.
+
+ You should have received a copy of the 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.
+
+
+ This Mason component generates information about the uploader.
+
+
+</%doc>
<& docshead &>
<h1>Uploading to YARRG</h1>
<p>
The YARRG system has two main parts: this website which maintains a
-searchable database of commodity prices, and an upload client, which
-screenscrapes the commodity data from the Puzzle Pirates game client
-and uploads it to the database.
+searchable database of commodity prices, and an upload client (known
+as YARRG JPCTB), which screenscrapes the commodity data from the
+Puzzle Pirates game client and uploads it to the database.
<p>
also upload when preparing trade run, as market conditions change and
you want a plan based on recent data.
-<h2>Uploading from Linux</h2>
+<p>
-The YARRG upload client uploads both to YARRG and
-<a href="http://pctb.crabdance.com/">PCTB</a>.
+The YARRG JPCTB upload client uploads both to YARRG and
+<a href="http://pctb.crabdance.com/">PCTB</a>. It is intended to
+replace both the <a href="scraper">"yarrg"</a> and "PPAOCR" screenscrapers.
+
+<h2>Instructions</h2>
+
+First you must install YARRG JPCTB, following the instructions for
+your operating system, below. This will not modify your Puzzle
+Pirates installation. Instead, it provides you with a new way to run
+Puzzle Pirates which has an additional YARRG/PCTB Upload function.
<p>
-The current official version of YARRG for use as an upload
-client can browsed here:
- <a href="http://www.chiark.greenend.org.uk/~ijackson/ypp-sc-tools/master/">http://www.chiark.greenend.org.uk/~ijackson/ypp-sc-tools/master/</a>
-See particularly the
-<a href="http://www.chiark.greenend.org.uk/~ijackson/ypp-sc-tools/master/yarrg/README">YARRG README</a>.
+To upload data, run the Puzzle Pirates client with JPCTB (as detailed
+below), log in normally, and visit a commodity trading screen (at a
+market, shoppe or vessel hold). Select "All Commodities", and hit
+"Upload".
<p>
-To install the client, install the "git" version control system
-and the other dependencies listed in the "Installation requirements"
-section of the README and then run:
+
+The JPCTB integration is done via fully supported Java Accessibility
+interfaces and without modifying the Puzzle Pirates client, and should
+not disturb the normal running of Puzzle Pirates. However, please
+make sure that if your YPP client misbehaves in any way, you try
+running it in the vanilla way without JPCTB integration before asking
+for help. In particular, if the JPCTB startup method does not work,
+but the vanilla client startup method does, report the problem to us,
+not to Three Rings.
+
+<h3>Installing and running on Linux</h3>
+
+Download
+<a href="http://www.greenend.org.uk/owen/free/jpctb.tar.gz">http://www.greenend.org.uk/owen/free/jpctb.tar.gz</a>
+and unpack it. You run it from the command line. Change
+to the directory where you unpacked the tarball above, and then run
<pre>
-git-clone http://www.chiark.greenend.org.uk/~ijackson/ypp-sc-tools/master/.git ypp-sc-tools
-cd ypp-sc-tools
-cd yarrg
-make
+./jpctb /path/to/yohoho/yohoho
</pre>
-this will download the code into the directory <code>ypp-sc-tools</code>,
-and build the software. (If your Linux is very up to date you may
-find that it complains that it doesn't know the command <kbd>git-core</kbd>.
-In that case, use <kbd>git core</kbd>, with a space, instead.)
+where <code>/path/to/yohoho/yohoho</code> is the location of the
+ordinary Puzzle Pirates startup script, which is normally
+<code>yohoho/yohoho</code> in your home directory.
+
+<h3>Installing on Windows</h3>
+
+Download
+<a href="http://www.greenend.org.uk/owen/free/jpctb-linkfarmer/jpctp-setup.exe">http://www.greenend.org.uk/owen/free/jpctb-linkfarmer/jpctp-setup.exe</a>
+and double-click on it. It will either:
+<nl>
+<li>Just work, in which case you'll have a new icon on your desktop which
+ runs Puzzle Pirates with JPCTB integrated.
+<li>Fail, and tell you what to do next. Usually this means installing a
+ Java Runtime Environment (or JVM) and then uninstalling and re-
+ installing Puzzle Pirates. (Don't worry about reinstalling; you
+ won't lose any of your pirates or pieces of eight!)
+</nl>
+
+<h3>Installing on Macs</h3>
+
+We believe that it should be straightforward for a MacOS developer or
+expert to get YARRG JPCTB working properly on MacOS but we have not
+been able to test this ourselves. The Linux installation method is
+probably the best starting point.
+
+<h2>How does it work? Is it a violation of the Terms of Service?</h2>
+
+YARRG JPCTB uses the Java Accessibility API, which is a part of the
+Java platform. It's an interface provided for making applications
+available to users with disabilities, for example for hooking in
+screen readers. This approach was helpfully suggested by a Ringer in
+the forums (to another developer of a third-party tool, wanting help
+getting information out of Duty Reports).
<p>
-When new versions of the upload client are released, you can:
-<pre>
-cd .../ypp-sc-tools
-git-pull
-cd yarrg
-make
-</pre>
-to fetch the new version. (Again, you may need <kbd>git pull</kbd>
-instead of <kbd>git-pull</kbd>.)
+Essentially, JPCTB is a specialised "screen reader" which instead of
+reading information out loud, uploads it to the YARRG and PCTB
+databases.
-<h2>Uploading from Windows</h2>
+<p>
-There is not currently an upload client for Windows which feeds data
-into YARRG. It would probably be straightforward to modify the
-Windows PCTB v5 upload client to upload to YARRG as well.
+Installing YARRG JPCTB does not modify any game files, and does not
+hook into the game itself. It makes no permanent or global changes to
+your overall computer, operating system or Java configuration. And it
+does not access (indeed, we don't think it could access) any of the
+core game functionality which would make cheating possible.
<p>
-See our <a href="devel">Developers' information</a> page.
+JPCTB works by running any unmodified copy of the YPP client but with
+a separate JVM (Java Virtual Machine) configured to use the
+appropriate accessibility plugin. We do this (rather than configuring
+the computer's main JVM to use the JPCTB accessibility plugin) so that
+it is still possible to launch Puzzle Pirates <em>without</em> JPCTB
+(for example, in case the JPCTB client should cause any kind of
+problem).
-<h2>Uploading from Macs</h2>
+<h2>Authorship and source code</h2>
-There is not currently a publicly available upload client for Macs for
-either YARRG or PCTB.
+Thanks to Burninator for writing the core of the JPCTB client. Ian
+Jackson and Owen Dunn adapted it to improve the installation setup (in
+particular, to more completely avoid modifying the YPP client's
+startup files, which Three Rings unsurprisingly objected to). Owen
+Dunn added support for uploading to YARRG and a Windows installer.
<p>
+YARRG JPCTB is
+Copyright 2006-2009 Burninator,
+Copyright 2009-2010 Owen Dunn and
+Copyright 2009-2010 Ian Jackson.
+It is Free Software with <strong>NO WARRANTY</strong>, released under
+the MIT-style two-clause licence.
+
+<p>
+
+The source code for the downloadable released binaries is in the
+<a href="http://www.greenend.org.uk/owen/free/jpctb.tar.gz">Linux
+tarball</a>. We maintain YARRG JPCTB in git, and you can get
+recent and perhaps unreleased versions from
+<code>git://git.yarrg.chiark.net/jpctb.git</code>.
+
+
</div>
<& footer &>
~yarrgweb / ypp-sc-tools.db-test.git / commitdiff