chiark / gitweb /
~yarrgweb / ypp-sc-tools.db-live.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Reorganise docs to include new howto material in intro etc.
[ypp-sc-tools.db-live.git] / yarrg / web / docs
diff --git a/yarrg/web/docs b/yarrg/web/docs
index 6ed64d1e223f0cb2c7300160eacac3c7c989ee8f..6511b7e7114318e6d45e1b13cf6acee392dfe854 100755 (executable)
--- a/yarrg/web/docs
+++ b/yarrg/web/docs
@@ -33,18 +33,7 @@
 
 
 </%doc>
 
 
 </%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
 <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.
 
 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
 <h2>Bookmarkable URLs</h2>
 
 Mostly, you can bookmark the specific pages and queries.  Select the
@@ -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.
 
 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
 
 If you specify only one island or one archipelago, the site shows only
 arbitrage trades.  If you want single-hop trades within an
@@ -101,7 +95,7 @@ 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.
 
 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
 
 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
@@ -119,8 +113,9 @@ like:
 <dd>The capacity of a war brig minus 1%
 <dt>13t 20kl
 <dd>13 tonnes (13,000kg), 20 kilolitres (20,000l)
 <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>
 <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>
 
 
 <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>
+
+If the first term specifies only one of mass or volume, all the
+subsequent terms may only adjust that same value.
 
 
-<h3>Expected losses</h3>
+<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
 
 In theory if you were guaranteed to have a trouble-free voyage it
 would be worth trading goods at very low margins.  However, in
@@ -169,14 +168,33 @@ possible to do both.
 
 <p>
 
 
 <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
 
 <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.
 
 case it is taken as the loss for each league of the voyage.
 
+<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!
+
+</div>
 <& footer &>
 <& footer &>
yarrg production database