+<%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 &>
+<%perl>
+my $url_base_base= 'http://yarrg.chiark.net/download/jpctb';
+my $download_version= '0.9.1';
+my $url_base= "$url_base_base/$download_version";
+</%perl>
<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>
You will need to upload data yourself if there is no data for your
ocean or island, or the data that is there is too old. You should
-also upload when preparing trade run, as market conditions change and
+also upload when preparing a trade run, as market conditions change and
you want a plan based on recent data.
-<h2>Uploading from Linux</h2>
+<p>
+
+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>
-The YARRG upload client uploads both to YARRG and
-<a href="http://pctb.crabdance.com/">PCTB</a>.
+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 integrates it with JPCTB to provides a YARRG/PCTB
+Upload facility.
<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). You should see both the Puzzle Pirates window and the JPCTB
+window appear. Log in normally, and visit a commodity trading screen
+(at a market, shoppe or vessel hold). Select "All Commodities" in the
+YPP client. Then press "Upload" in the JPCTB window.
<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 should not disturb the normal running of Puzzle
+Pirates. However, please make sure that if your YPP client misbehaves
+at all, you try starting it in the vanilla way (without JPCTB
+integration) before asking for help. In particular, if the JPCTB
+startup does not work, but the ordinary Puzzle Pirates startup does,
+report the problem to us, not to Three Rings.
+
+<h3>Installing and running on Linux</h3>
+
+Download
+<a href="<% $url_base %>/jpctb.tar.gz"><% $url_base %>/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="<% $url_base %>/jpctb-setup.exe"><% $url_base %>/jpctb-setup.exe</a>
+and double-click on it. It will either:
+<ol>
+<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!)
+</ol>
+
+<h3>Installing on Macs</h3>
+
+We believe that it should be straightforward for a MacOS 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>
+
+Essentially, JPCTB is a specialised "screen reader" which instead of
+reading information out loud, uploads it to the YARRG and PCTB
+databases.
<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>.)
+YARRG JPCTB uses the Java Accessibility API, which is a part of the
+Java platform. It's a facility in Java, available for all Java
+programs, intended to help make applications available to users with
+disabilities: for example, it permits hooking in screen readers. The
+use of the Java Accessibility API 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>
-<h2>Uploading from Windows</h2>
+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.
-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.
+<p>
+
+JPCTB works by running an 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>Authorship, source code and other versions</h2>
+
+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, updated the build system,
+and wrote a Windows installer.
<p>
-See our <a href="devel">Developers' information</a> page.
+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 download directory contains some historical versions, which you
+can see here:
+<a href="<% $url_base_base %>/"><% $url_base_base %>/</a> .
+
+<p>
-<h2>Uploading from Macs</h2>
+The source code for the downloadable released binaries is in the
+<a href="<% $url_base %>/jpctb.tar.gz">Linux
+tarball</a>. We maintain YARRG JPCTB in git, and you can get
+source code for recent and perhaps unreleased versions from
+<code>git://git.yarrg.chiark.net/jpctb.git</code> and/or
+<code>git://git.chiark.greenend.org.uk/~ijackson/jpctb.git</code> .
-There is not currently a publicly available upload client for Macs for
-either YARRG or PCTB.
</div>
<& footer &>