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 02cbeeb..10caaee 100755 (executable)
 
 
 </%doc>
-<html lang="en"><head><title>Website documentation - YARRG</title>
-<link rel="stylesheet" type="text/css" href="style.css">
-</head><body>
-
-<div class="navoptbar">
-<a href="lookup">YARRG</a> -
- Yet Another Revenue Research Gatherer
-|
-<a href="intro">introduction</a>
-|
-<b>documentation</b>
-|
-<a href="devel">development</a>
-</div>
-<div class="docs">
-
+<& docshead &>
 <h1>Looking up data in YARRG</h1>
 
 YARRG (Yet Another Revenue Research Gatherer) is a third-party tool
@@ -66,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
@@ -75,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>
@@ -84,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>
 
@@ -102,7 +92,7 @@ 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><a name="capacity">Vessel capacity</a></h3>
@@ -188,6 +178,51 @@ You can enter the value in the box either as a percentage, or as a
 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
@@ -206,5 +241,55 @@ 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 &>