chiark / gitweb /
Merge branch 'stable-3.x'
[ypp-sc-tools.main.git] / yarrg / web / docs
index 2abe504..c211683 100755 (executable)
@@ -33,7 +33,7 @@
 
 
 </%doc>
-<html><head><title>Website documentation - YARRG</title>
+<html lang="en"><head><title>Website documentation - YARRG</title>
 </head><body>
 
 <a href="lookup">YARRG</a> -
@@ -42,6 +42,8 @@
 <a href="intro">introduction</a>
 |
 <b>documentation</b>
+|
+<a href="devel">development</a>
 
 <h1>Looking up data in YARRG</h1>
 
@@ -56,9 +58,9 @@ from YARRG.  It offers a variety of enquiry options.
 
 <p>
 
-This website documentation page contains information about the
-database website which you may not be able to divine from the online
-user interface.
+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.
 
 <h2>Bookmarkable URLs</h2>
 
@@ -99,7 +101,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.
 
-<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
@@ -108,13 +110,41 @@ which trades excessively cumbersome goods (eg. hemp, wood, iron).
 
 <p>
 
-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.
+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.
+
+<p>
+
+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>Estimated loss per league</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
@@ -132,24 +162,44 @@ 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%.
+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="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!
 
 <& footer &>