chiark / gitweb /
where-vessels: subclass smasher works; need to reorg to be a grid like Show
[ypp-sc-tools.db-live.git] / yarrg / web / docs
index 48a0062..10caaee 100755 (executable)
 
 
 </%doc>
-<html><head><title>Website documentation - YARRG</title>
-</head><body>
-
-<a href="lookup">YARRG</a> -
- Yet Another Revenue Research Gatherer
-|
-<a href="devel">development</a>
-|
-<a href="intro">introduction</a>
-|
-<b>documentation</b>
-
+<& docshead &>
 <h1>Looking up data in YARRG</h1>
 
 YARRG (Yet Another Revenue Research Gatherer) is a third-party tool
@@ -62,6 +51,11 @@ 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
@@ -71,8 +65,8 @@ 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
+(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>
@@ -80,7 +74,7 @@ to fit in a URL.)
 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'.
+must still hit "Go" or "Update".
 
 <h2>Trades for route</h2>
 
@@ -89,7 +83,7 @@ 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>
+<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
@@ -98,10 +92,10 @@ 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
+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>Vessel capacity</h3>
+<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
@@ -115,12 +109,13 @@ like:
 <dl>
 <dt>sloop
 <dd>The capacity of a sloop, leaving no allowance for rum and shot
-<dt>sloop - 1%
-<dd>The capacity of a sloop minus 1%
-<dt>20t 13kl
+<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 - 100l 100kg
-<dd>The capacity of a sloop minus 100l, minus 100kg
+<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>
@@ -128,18 +123,22 @@ Evaluation is strictly from left to right.
 
 <p>
 
-Formally, the capacity is a list of terms, all but the first preceded
-by one of <kbd>-</kbd>, <kbd>minus</kbd>, <kbd>+</kbd>,
-<kbd>plus</kbd>.  Each term may specify a mass and/or a volume
-(separated by a space), as a number followed (without an intervening
-space) by a unit (<kbd>t</kbd>, <kbd>kg</kbd>, <kbd>kl</kbd> or
-<kbd>l</kbd>).  Alternatively each term except the first may specify a
-percentage, which is applied as a percentage change to the answer from
-all the preceding terms.  The first term may be a ship name or
-abbrevation instead.  If the first term specifies only one of mass or
-volume, all the subsequent terms may only adjust that same value.
+More formally:
+<pre>
+ capacity-string := [ first-term term* ]
+ term := ('+' | '-' | 'plus' | 'minus') (value+ | number'%')
+ value := mass | volume
+        | integer commodity-name-or-abbreviation
+ mass := number ('t' | 'kg')
+ volume := number ('kl' | 'l')
+ first-term := mass | volume | mass volume | volume mass
+             | ship-name-or-abbreviation
+</pre>
 
-<h3>Expected losses</h3>
+If the first term specifies only one of mass or volume, all the
+subsequent terms may only adjust that same value.
+
+<h3><a name="losses">Expected losses</a></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
@@ -157,25 +156,140 @@ to do.
 
 <p>
 
-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.
+Trades whose margin is less than the expected loss are never included
+in the suggested plan.  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, if it's not
+possible to do both.
 
 <p>
 
-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.
+As a guide: you may expect to lose between 0.01% and 1% per league.
+For example 0.1% would correspond to losing one fight to brigands (who
+take 10% if they win) for every 100 leagues sailed.
 
 <p>
 
 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%; in each
+fraction 1/<em>divisor</em>, eg 1/2000 is the same as 0.05%; in each
 case it is taken as the loss for each league of the voyage.
 
+<h3><a name="minprofit">Minimum trade value</a></h3>
+
+Often there are many low-volume, low-value trades.  It can be rather
+labour-intensive to buy and sell a dozen different commodities, half
+of which are only making a few poe each.
+
+<p>
+
+The "minimum trade value" specifies a minimum profit that you would
+like to get from each (commodity, collect island, deliver island)
+triplet.  Trades which don't meet this minimum will start out unticked in
+the "Relevant trades" table and will not be included in the voyage
+trading plan.
+
+<p>
+
+If you want to change your threshold, you have to select "Apply",
+which will automatically tick and untick all of the tickboxes for in
+"Relevant trades", as appropriate.  This will undo any customisation
+of the set of trades you have already done by manually ticking and
+unticking individual trades.
+
+<p>
+
+The value is an absolute poe amount, typically 5 or 10, representing
+the minimum profit to make it worthwhile (from a time and effort point
+of view) clicking in the YPP client to collect and deliver a
+commodity.  Setting a higher threshold will make each island visit
+faster, by excluding trivial transactions, and so reduce the chance
+that market conditions change adversely during your voyage.
+
+<h3><a name="poelimit">Caution about stalls' poe reserves</a></h3>
+
+If you select <b>Also be cautious about stalls' poe reserves</b>,
+YARRG will calculate a minimum amount of poe that each stall has on
+hand (by looking at all the offers that stall is making), and never
+plan for you to sell goods at that stall for more than the available
+poe.
+
+<p>
+
+Goods planned to be bought at the stall (which might boost the stall's
+poe reserves) are not considered, to avoid having to calculate the
+stall's cash reserves at various different times.
+
+<h3><a name="capital">Available capital</a></h3>
+
+If you don't specify the amount of capital you have available to
+invest in the voyage, the trading plan will assume that your capital
+is unlimited.  If you specify an amount in PoE here, the trading plan
+will never require you to spend more than that amount on commodities.
+
+<p>
+
+The trading plan does not take into account accumulated profits from
+each leg of the journey when applying the available capital
+constraint.  For example, if you specify a journey from A to B to C
+and a capital limit of 10000 PoE, the trading plan will not tell you
+to buy 1000 peas at A for 10 PoE each, sail them to B and sell all of
+them for 20 PoE each, and then buy 2000 beans at B for 10 PoE each and
+sail them to C to sell for 20 PoE each even if such a trade would in
+fact be possible.  In practice this is unlikely to be a problem!
+
+<h3><a name="posinclass">Locating commodities in the YPP client UI</a></h3>
+
+In the Voyage Trading Plan, YARRG indicates after the commodity name
+where in the YPP commodity UI each commodity can be found.  First
+comes the initial letter of the category:
+%     my $dbh= dbw_connect('Midnight');
+%     my $getclasses= $dbh->prepare(
+%        "SELECT commodclass FROM commodclasses ORDER BY commodclass");
+%     $getclasses->execute();
+<%
+    join '; ', map { $_->[0] =~ m/^./ or die; "<strong>$&</strong>$'" }
+        @{ $getclasses->fetchall_arrayref() }
+%>.
+<p>
+
+Then, if applicable, follows a number from <strong>0</strong> to
+<strong>9</strong> indicating roughly where the commodity is in the
+list of commodities of the same class.  The number indicates which
+tenth of the list is: <strong>0</strong> for the first (top) tenth,
+<strong>1</strong> for the 2nd, and so on, up to <strong>9</strong>
+for the final tenth.
+
+<p>
+For example,
+<blockquote>
+<table><tr>
+<td>Fine pink cloth&nbsp;&nbsp;
+<td><div class=mouseover
+ title="Fine pink cloth is under Cloth, commodity 14 of 55">C 2</div>
+</table>
+</blockquote>
+indicates that Fine pink cloth can be found under Cloth,
+between 20% and 30% of the way down through the types of Cloth.
+If you mouseover that in a suitably equipped browser you should see the
+text:
+<blockquote>
+Fine pink cloth is under Cloth, commodity 14 of 55
+</blockquote>
+<p>
+
+The position indicator digit isn't shown for very small
+categories.
+
+The exact location of the commodity in the actual game
+client may vary because YARRG only considers the list of all possible
+commodities, not the list of actual offers at the island in question.
+
+Also, not all commodities are always completely categorised or
+ordered; we are working to add the additional data
+
+</div>
 <& footer &>