</%doc>
-<html><head><title>YARRG (Yet Another Revenue Research Gatherer)</title>
+<html><head><title>Website documentation - YARRG</title>
</head><body>
-<h1>Introduction to YARRG</h1>
+<a href="lookup">YARRG</a> -
+ Yet Another Revenue Research Gatherer
+|
+<a href="intro">introduction</a>
+|
+<b>documentation</b>
+
+<h1>Looking up data in YARRG</h1>
YARRG (Yet Another Revenue Research Gatherer) is a third-party tool
for helping find profitable trades and trade routes in Yohoho Puzzle
-Pirates. It was inspired by
-<a href="http://pctb.crabdance.com/">PCTB</a>.
+Pirates. See the <a href="intro">Introduction</a> for more details.
<p>
-The 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.
+The <a href="lookup">Market prices database</a> is the main output
+from YARRG. It offers a variety of enquiry options.
-<h2><a href="lookup">Market prices database</a></h2>
+<p>
-The <a href="lookup">lookup page</a> gives access to the uploaded data.
+This website documentation page contains information about the
+database website which you may not be able to divine from the online
+user interface.
-<h2>Uploading from Linux</h2>
+<h2>Bookmarkable URLs</h2>
-The YARRG upload client uploads both to YARRG and to the
-<a href="pctb.ilk.org">PCTB testing server</a>.
+Mostly, you can bookmark the specific pages and queries. Select the
+ocean, query page, and other combinations of options, as you wish, and
+perhaps fill in the actual data fields too, and bookmark the resulting
+URL.
<p>
-The current official version of YARRG for use as an upload
-client can browsed here:
- <a href="/~ijackson/ypp-sc-tools/master/">http://www.chiark.greenend.org.uk/~ijackson/ypp-sc-tools/master/</a>
-See particularly the
-<a href="/~ijackson/ypp-sc-tools/master/yarrg/README">YARRG README</a>.
+(An exception to this is if you select the `Update' option from the
+`Trades for route' lookup; the list of (de)selected stalls is too long
+to fit in a URL.)
+
+<h2>Dynamic confirmation of meaning of text entry boxes</h2>
+
+If you have Javascript enabled, the various text entry boxes will be
+annotated with a brief explanation of the system's interpretation of
+your current entry string. To get the actual results updated, you
+must still hit `Go' or `Update'.
+
+<h2>Trades for route</h2>
+
+Given a list of islands (or archipelagoes), provides a list of
+potentially profitable trades. If the route is suitable for the trade
+route optimiser, it will generate a complete voyage plan, telling you
+which goods to buy and sell where at which stalls and prices.
<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 you specify only one island or one archipelago, the site shows only
+arbitrage trades. If you want single-hop trades within an
+archipelago, you must enter the archipelago name twice.
<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.
+After getting the results, you can untick various trades individually,
+and select `Update' to get a new plan. The unticked trades will be
+excluded from the voyage plan (if any) and also from the totals.
-<h2>Uploading from Windows</h2>
+<h3>Vessel capacity</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. The
-mechanism and format for uploading is documented in
-<a href="/~ijackson/ypp-sc-tools/master/yarrg/README.devel">README.devel</a>.
+If you don't specify a vessel or a vessel capacity, the trading plan
+will not take into account the fact that your voyage will be on a ship
+with a limited size. This will probably result in a plan
+which trades excessively cumbersome goods (eg. hemp, wood, iron).
-<h1>YARRG development, contribution and troubleshooting</h1>
+<p>
-<h2>Free Software (aka Open Source)</h2>
+So you should specify your vessel capacity. Currently you must
+specify the actual mass and volume, as two numbers each with units.
+The system understands the units t (tonnes), kg, l and kl
+(kilolitres). There should be a space between the two limits, and no
+space before the unit.
-YARRG is Free Software - you may share and modify it. See the
-licences for details.
+<h3>Estimated loss per league</h3>
+
+In theory if you were guaranteed to have a trouble-free voyage it
+would be worth trading goods at very low margins. However, in
+practice problems can arise: you may be attacked and lose your stock,
+or market conditions may change between your collection and delivery
+of the goods.
<p>
-Not only the client but also the webserver code is Free. The website
-code can be found in the same tree as above, in the <code>web</code>
-directory.
+We model this by pretending that you expect to lose a fixed proportion
+of your stock each league you sail. This expected loss does not
+appear in the trade tables (although the distance does), but it does
+affect the way the voyage trading plan optimiser chooses which trades
+to do.
<p>
-But in case we have made changes but not yet pushed them
-(perhaps because we haven't done a release), and to make it easy for
-anyone else who runs a copy of the website to provide everyone with
-the source for their version, the website code itself lets you download
-an up-to-date <a href="source.tar.gz">tarball</a> of its
-actually-running source code.
+Trades whose margin is less than the expected loss are never selected.
+For example, if you select 1% loss per league, and plan a voyage of 5
+leagues, then any trade with a margin of less than 5.15% would be
+completely excluded (5.15% not 5% because the loss works like compound
+interest). Theoretically very profitable trades which are close to
+the expected break-even point because of the distance can also be
+rejected by the optimiser in favour of shorter distance trades with
+theoretically smaller margins.
<p>
-If you would like to run a (perhaps modified) copy of the YARRG
-website it would be very easy for us to make our system send you
-copies of updates submitted by users of the official YARRG client, in
-the format expected by the code you'll be running. Please just ask
-us.
+As a guide: you may expect to lose between 0.1% and 1% per league.
+0.1% would correspond, for example, to losing one fight to brigands
+every ten 10-league voyages.
-<h2>Contacting the YARRG developers</h2>
+<p>
-Email Ian Jackson ijackson (at) chiark.greenend.org.uk. Or talk to
-any Fleet Officer or above of the crew Special Circumstances on the
-Midnight Ocean.
+You can enter the value in the box either as a percentage, or as a
+fraction 1/<em>divisor</em>, eg 1/200 is the same as 0.5%.
-<& footer, isdocs => 1 &>
+<& footer &>
--- /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 the introduction.
+
+
+</%doc>
+<html><head><title>YARRG (Yet Another Revenue Research Gatherer)</title>
+</head><body>
+
+<a href="lookup">YARRG</a> -
+ Yet Another Revenue Research Gatherer
+|
+<b>introduction</b>
+|
+<a href="docs">documentation</a>
+
+<h1>Introduction to YARRG</h1>
+
+YARRG (Yet Another Revenue Research Gatherer) is a third-party tool
+for helping find profitable trades and trade routes in Yohoho Puzzle
+Pirates. It was inspired by
+<a href="http://pctb.crabdance.com/">PCTB</a>.
+
+<p>
+
+The 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.
+
+<h2><a href="lookup">Market prices database</a></h2>
+
+The <a href="lookup">lookup page</a> gives access to the uploaded data;
+there is also <a href="docs">documentation</a> to help with using that
+website.
+
+<h2>Uploading from Linux</h2>
+
+The YARRG upload client uploads both to YARRG and to the
+<a href="pctb.ilk.org">PCTB testing server</a>.
+
+<p>
+
+The current official version of YARRG for use as an upload
+client can browsed here:
+ <a href="/~ijackson/ypp-sc-tools/master/">http://www.chiark.greenend.org.uk/~ijackson/ypp-sc-tools/master/</a>
+See particularly the
+<a href="/~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.
+
+<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.
+
+<h2>Uploading from Windows</h2>
+
+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. The
+mechanism and format for uploading is documented in
+<a href="/~ijackson/ypp-sc-tools/master/yarrg/README.devel">README.devel</a>.
+
+<h1>YARRG development, contribution and troubleshooting</h1>
+
+<h2>Free Software (aka Open Source)</h2>
+
+YARRG is Free Software - you may share and modify it. See the
+licences for details.
+
+<p>
+
+Not only the client but also the webserver code is Free. The website
+code can be found in the same tree as above, in the <code>web</code>
+directory.
+
+<p>
+
+But in case we have made changes but not yet pushed them
+(perhaps because we haven't done a release), and to make it easy for
+anyone else who runs a copy of the website to provide everyone with
+the source for their version, the website code itself lets you download
+an up-to-date <a href="source.tar.gz">tarball</a> of its
+actually-running source code.
+
+<p>
+
+If you would like to run a (perhaps modified) copy of the YARRG
+website it would be very easy for us to make our system send you
+copies of updates submitted by users of the official YARRG client, in
+the format expected by the code you'll be running. Please just ask
+us.
+
+<h2>Contacting the YARRG developers</h2>
+
+Email Ian Jackson ijackson (at) chiark.greenend.org.uk. Or talk to
+any Fleet Officer or above of the crew Special Circumstances on the
+Midnight Ocean.
+
+<& footer, isdocs => 1 &>
~yarrgweb / ypp-sc-tools.db-test.git / commitdiff