From 6cc86c4b4db1302d06c6c9571d199ba2ae06c354 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Sun, 23 May 2010 17:37:56 +0100 Subject: [PATCH] Web page documenting YARRG JPCTB --- yarrg/web/scraper | 85 ++++++++++++++++++++++ yarrg/web/upload | 180 ++++++++++++++++++++++++++++++++++++---------- 2 files changed, 226 insertions(+), 39 deletions(-) create mode 100755 yarrg/web/scraper diff --git a/yarrg/web/scraper b/yarrg/web/scraper new file mode 100755 index 0000000..91edcc6 --- /dev/null +++ b/yarrg/web/scraper @@ -0,0 +1,85 @@ +<%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 + 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 . + + 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. + + + +<& docshead &> +

"yarrg" screenscraper for YARRG and PCTB

+ +There is an obsolete screenscraper for Linux, known as "yarrg". It is +much slower and less reliable than JPCTB. We recommend you use +YARRG JPCTB instead. + +

Instructions for using obsolete "yarrg"

+ +

+ +The current official version of the yarrg screenscraper can browsed here: + http://www.chiark.greenend.org.uk/~ijackson/ypp-sc-tools/master/ . +See particularly the +YARRG README. + +

+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: +

+git-clone http://www.chiark.greenend.org.uk/~ijackson/ypp-sc-tools/master/.git ypp-sc-tools
+cd ypp-sc-tools
+cd yarrg
+make
+
+this will download the code into the directory ypp-sc-tools, +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 git-core. +In that case, use git core, with a space, instead.) + +

+ +When new versions of the upload client are released, you can: +

+cd .../ypp-sc-tools
+git-pull
+cd yarrg
+make
+
+to fetch the new version. (Again, you may need git pull +instead of git-pull.) + +

Windows and MacOS

+

+The yarrg scraper would be almost impossible to port to Windows. In +any case it is obsolete. + + +<& footer &> diff --git a/yarrg/web/upload b/yarrg/web/upload index 59556b2..c0d15ef 100755 --- a/yarrg/web/upload +++ b/yarrg/web/upload @@ -1,11 +1,46 @@ +<%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 + 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 . + + 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. + + + <& docshead &>

Uploading to YARRG

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.

@@ -14,62 +49,129 @@ 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 you want a plan based on recent data. -

Uploading from Linux

+

-The YARRG upload client uploads both to YARRG and -PCTB. +The YARRG JPCTB upload client uploads both to YARRG and +PCTB. It is intended to +replace both the "yarrg" and "PPAOCR" screenscrapers. + +

Instructions

+ +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.

-The current official version of YARRG for use as an upload -client can browsed here: - http://www.chiark.greenend.org.uk/~ijackson/ypp-sc-tools/master/ -See particularly the -YARRG README. +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".

-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. + +

Installing and running on Linux

+ +Download +http://www.greenend.org.uk/owen/free/jpctb.tar.gz +and unpack it. You run it from the command line. Change +to the directory where you unpacked the tarball above, and then run 
-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
-this will download the code into the directory ypp-sc-tools, -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 git-core. -In that case, use git core, with a space, instead.) +where /path/to/yohoho/yohoho is the location of the +ordinary Puzzle Pirates startup script, which is normally +yohoho/yohoho in your home directory. + +

Installing on Windows

+ +Download +http://www.greenend.org.uk/owen/free/jpctb-linkfarmer/jpctp-setup.exe +and double-click on it. It will either: + +
  • Just work, in which case you'll have a new icon on your desktop which + runs Puzzle Pirates with JPCTB integrated. +
  • 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!) + + +

    Installing on Macs

    + +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. + +

    How does it work? Is it a violation of the Terms of Service?

    + +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).

    -When new versions of the upload client are released, you can: -

    -cd .../ypp-sc-tools
-git-pull
-cd yarrg
-make
-
    -to fetch the new version. (Again, you may need git pull -instead of git-pull.) +Essentially, JPCTB is a specialised "screen reader" which instead of +reading information out loud, uploads it to the YARRG and PCTB +databases. -

    Uploading from Windows

    +

    -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.

    -See our Developers' information 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 without JPCTB +(for example, in case the JPCTB client should cause any kind of +problem). -

    Uploading from Macs

    +

    Authorship and source code

    -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.

    +YARRG JPCTB is +Copyright 2006-2009 Burninator, +Copyright 2009-2010 Owen Dunn and +Copyright 2009-2010 Ian Jackson. +It is Free Software with NO WARRANTY, released under +the MIT-style two-clause licence. + +

    + +The source code for the downloadable released binaries is in the +Linux +tarball. We maintain YARRG JPCTB in git, and you can get +recent and perhaps unreleased versions from +git://git.yarrg.chiark.net/jpctb.git. + + <& footer &> -- 2.30.2