chiark / gitweb /
website: jarrg is released
[ypp-sc-tools.main.git] / yarrg / web / upload
index 59556b2..6de28be 100755 (executable)
+<%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 &>
+<%shared>
+my $url_base_base= 'http://yarrg.chiark.net/download/jarrg';
+</%shared>
+<%def downloadurl><%args>
+$leaf
+$test => 0
+#        ^ change this to change the default version
+</%args><%perl>
+my $download_version= $test ? '/test' : '';
+my $url_base= "$url_base_base$download_version";
+my $url= $url_base.'/'.$leaf;
+</%perl><a href="<% $url %>"><%
+    $m->has_content ? $m->content : $url
+%></a></%def>
 <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 JARRG), 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 trade run, as market conditions change and
 you want a plan based on recent data.
 
-<h2>Uploading from Linux</h2>
+<p>
+
+The JARRG 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.
 
-The YARRG upload client uploads both to YARRG and
-<a href="http://pctb.crabdance.com/">PCTB</a>.
+<h2>Instructions</h2>
+
+First you must install JARRG, 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 JARRG 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 JARRG (as detailed
+below).  You should see both the Puzzle Pirates window and the JARRG
+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 Market Data" in the JARRG 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:
-<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.)
+
+It is OK to switch away from the commodity list in Puzzle Pirates as
+soon as the Jarrg progress bar appears.  The uploader has taken a copy
+of the data, so you can do something else while the upload takes
+place.
 
 <p>
 
-When new versions of the upload client are released, you can:
+The JARRG 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 JARRG
+integration) before asking for help.  In particular, if the JARRG
+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
+<& downloadurl, leaf => 'jarrg-linux.tar.gz' &>
+and unpack it.  You run jarrg from the command line.  Change
+(<code>cd</code>) to the top level <code>jarrg</code> directory
+which was created when you unpacked the tarball, and then run
 <pre>
-cd .../ypp-sc-tools
-git-pull
-cd yarrg
-make
+./jarrg /path/to/yohoho/yohoho
 </pre>
-to fetch the new version.  (Again, you may need <kbd>git pull</kbd>
-instead of <kbd>git-pull</kbd>.)
+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
+<& downloadurl, leaf => 'jarrg-setup.exe' &>
+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 JARRG 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>
 
-<h2>Uploading from Windows</h2>
+<h3>Installing on Macs</h3>
 
-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.
+We believe that it should be straightforward for a MacOS expert to get
+JARRG 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, JARRG is a specialised "screen reader" which instead of
+reading information out loud, uploads it to the YARRG and PCTB
+databases.
+
+<p>
+
+JARRG 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>
+
+Installing JARRG 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>
+
+JARRG runs the unmodified Puzzle Pirates game, but with a separate
+copy of your system's JVM (Java Virtual Machine); that copy of the JVM
+is configured to use the JARRG accessibility plugin.  We do this
+(rather than configuring the computer's main JVM to use the
+accessibility plugin) to avoid interfering with other uses of Java on
+your computer - in particular, so that it is always possible to launch
+Puzzle Pirates <em>without</em> JARRG (for example, in case the plugin
+should cause any kind of problem).
+
+<h2><a name="source">Authorship, source code and other versions</a></h2>
+
+Thanks to Burninator for writing the core of the JARRG client.  Ian
+Jackson and Owen Dunn adapted it to improve the installation setup (in
+particular, to avoid modifying any of the YPP client's startup files).
+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.
+JARRG 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.
 
-<h2>Uploading from Macs</h2>
+<p>
 
-There is not currently a publicly available upload client for Macs for
-either YARRG or PCTB.
+The code for the downloadable binaries is in
+in <& downloadurl, leaf=>'jarrg-source.tar.gz' &>.
+The download directory also sometimes contains other versions
+(eg unreleased test versions), which you can see here:
+ <& downloadurl, leaf => '', test => 0 &>
 
 <p>
 
+We maintain JARRG in git, and you can get
+source code for recent and perhaps unreleased versions from one of:
+<pre>
+git://git.yarrg.chiark.net/jarrg-ian.git</code> <a href="http://www.chiark.greenend.org.uk/ucgi/~yarrgweb/git?p=jarrg-ian.git;a=summary">(gitweb)</a>
+git://git.yarrg.chiark.net/jarrg-owen.git</code>&nbsp;<a href="http://www.chiark.greenend.org.uk/ucgi/~yarrgweb/git?p=jarrg-owen.git;a=summary">(gitweb)</a>
+</pre>
+
+
 </div>
 <& footer &>