-%# 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 documentation.
-%#
-<html><head><title>YARRG (Yet Another Revenue Research Gatherer)</title>
-</head><body>
-<h1>Introduction to YARRG</h1>
-YARRG is inspired by PCTB.
-
-<h1>Obtaining the client</h1>
-The current official version of YARRG for use as a client can browsed here:
- <a href="/~ijackson/ypp-sc-tools/master/">http://www.chiark.greenend.org.uk/~ijackson/ypp-sc-tools/master/</a>
-
-<p>
-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.
+<%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 documentation.
+
+
+</%doc>
+<& docshead &>
+<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. See the <a href="intro">Introduction</a> for more details.
+
+<p>
+
+The <a href="lookup">Market prices database</a> is the main output
+from YARRG. It offers a variety of enquiry options.
+
+<p>
+
+Hopefully you will be able to work it without too much help, but this
+documentation page contains information about the database website
+which you may not be able to divine from the online user interface.
+
+<p>
+
+If this page is all too complicated for you, you may prefer to read
+<a href="intro">the introduction</a> instead.
+
+<h2>Bookmarkable URLs</h2>
+
+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>
+
+(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><a name="arbitrage"></a>
+
+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>
+
+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.
+
+<h3><a name="capacity">Vessel capacity</a></h3>
+
+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).
+
+<p>
+
+So you should specify your vessel capacity. You can enter things
+like:
+<dl>
+<dt>sloop
+<dd>The capacity of a sloop, leaving no allowance for rum and shot
+<dt>wb - 1%
+<dd>The capacity of a war brig minus 1%
+<dt>13t 20kl
+<dd>13 tonnes (13,000kg), 20 kilolitres (20,000l)
+<dt>sloop - 10 small 40 rum
+<dd>The capacity of a sloop which remains after
+ 10 small shot and 40 rum are loaded
+<dt>2t plus 500kg minus 200kg
+<dd>2300kg, with no limit on volume
+</dl>
+Evaluation is strictly from left to right.