From: Ian Jackson Date: Thu, 3 Sep 2009 16:50:29 +0000 (+0100) Subject: Rename docs to intro; write new docs X-Git-Tag: 3.4~10^2 X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~yarrgweb/git?p=ypp-sc-tools.main.git;a=commitdiff_plain;h=2bc58b52308e6baee9d353b507861925815ec5be Rename docs to intro; write new docs --- diff --git a/yarrg/web/docs b/yarrg/web/docs old mode 100755 new mode 100644 index 0ea31cf..2abe504 --- a/yarrg/web/docs +++ b/yarrg/web/docs @@ -33,106 +33,123 @@ -YARRG (Yet Another Revenue Research Gatherer) +Website documentation - YARRG -

Introduction to YARRG

+YARRG - + Yet Another Revenue Research Gatherer +| +introduction +| +documentation + +

Looking up data in YARRG

YARRG (Yet Another Revenue Research Gatherer) is a third-party tool for helping find profitable trades and trade routes in Yohoho Puzzle -Pirates. It was inspired by -PCTB. +Pirates. See the Introduction for more details.

-The system has two main parts: this website which maintains a -searchable database of commodity prices, and an upload client, which -screenscrapes the commodity data from the Puzzle Pirates game client -and uploads it to the database. +The Market prices database is the main output +from YARRG. It offers a variety of enquiry options. -

Market prices database

-The lookup page gives access to the uploaded data. +This website documentation page contains information about the +database website which you may not be able to divine from the online +user interface. -

Uploading from Linux

Bookmarkable URLs

-The YARRG upload client uploads both to YARRG and to the -PCTB testing server. +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.

-The current official version of YARRG for use as an upload -client can browsed here: - http://www.chiark.greenend.org.uk/~ijackson/ypp-sc-tools/master/ -See particularly the -YARRG README. +(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.) + +

Dynamic confirmation of meaning of text entry boxes

+ +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'. + +

Trades for route

+ +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.

-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: -

-git-clone http://www.chiark.greenend.org.uk/~ijackson/ypp-sc-tools/master/.git ypp-sc-tools
-cd ypp-sc-tools
-cd yarrg
-make
-

-this will download the code into the directory ypp-sc-tools, -and build the software. + +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.

-When new versions of the upload client are released, you can: -

-cd .../ypp-sc-tools
-git-pull
-cd yarrg
-make
-

-to fetch the new version. +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. -

Uploading from Windows

Vessel capacity

-There is not currently an upload client for Windows which feeds data -into YARRG. It would probably be straightforward to modify the -Windows PCTB v5 upload client to upload to YARRG as well. The -mechanism and format for uploading is documented in -README.devel. +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). -

YARRG development, contribution and troubleshooting

Free Software (aka Open Source)

+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. -YARRG is Free Software - you may share and modify it. See the -licences for details. +

Estimated loss per league

+ +In theory if you were guaranteed to have a trouble-free voyage it +would be worth trading goods at very low margins. However, in +practice problems can arise: you may be attacked and lose your stock, +or market conditions may change between your collection and delivery +of the goods.

-Not only the client but also the webserver code is Free. The website -code can be found in the same tree as above, in the web -directory. +We model this by pretending that you expect to lose a fixed proportion +of your stock each league you sail. This expected loss does not +appear in the trade tables (although the distance does), but it does +affect the way the voyage trading plan optimiser chooses which trades +to do.

-But in case we have made changes but not yet pushed them -(perhaps because we haven't done a release), and to make it easy for -anyone else who runs a copy of the website to provide everyone with -the source for their version, the website code itself lets you download -an up-to-date tarball of its -actually-running source code. +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.

-If you would like to run a (perhaps modified) copy of the YARRG -website it would be very easy for us to make our system send you -copies of updates submitted by users of the official YARRG client, in -the format expected by the code you'll be running. Please just ask -us. +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. -

Contacting the YARRG developers

-Email Ian Jackson ijackson (at) chiark.greenend.org.uk. Or talk to -any Fleet Officer or above of the crew Special Circumstances on the -Midnight Ocean. +You can enter the value in the box either as a percentage, or as a +fraction 1/divisor, eg 1/200 is the same as 0.5%. -<& footer, isdocs => 1 &> +<& footer &> diff --git a/yarrg/web/footer b/yarrg/web/footer index 8af45ad..9c892fc 100644 --- a/yarrg/web/footer +++ b/yarrg/web/footer @@ -48,7 +48,7 @@ You may share and modify the code and the website, according to the terms of the GNU General Public Licence and the GNU Affero General Public Licence respectively (v3 or later). % if (!$isdocs) { -Please see the YARRG documentation webpage for +Please see the YARRG introduction webpage for details of how to obtain the client and server code and full details of the licences. % } diff --git a/yarrg/web/intro b/yarrg/web/intro new file mode 100755 index 0000000..3088cce --- /dev/null +++ b/yarrg/web/intro @@ -0,0 +1,147 @@ +<%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 + 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 . + + 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 introduction. + + + +YARRG (Yet Another Revenue Research Gatherer) + + +YARRG - + Yet Another Revenue Research Gatherer +| +introduction +| +documentation + +

Introduction to YARRG

+ +YARRG (Yet Another Revenue Research Gatherer) is a third-party tool +for helping find profitable trades and trade routes in Yohoho Puzzle +Pirates. It was inspired by +PCTB. + +

+ +The system has two main parts: this website which maintains a +searchable database of commodity prices, and an upload client, which +screenscrapes the commodity data from the Puzzle Pirates game client +and uploads it to the database. + +

Market prices database

+ +The lookup page gives access to the uploaded data; +there is also documentation to help with using that +website. + +

Uploading from Linux

+ +The YARRG upload client uploads both to YARRG and to the +PCTB testing server. + +

+ +The current official version of YARRG for use as an upload +client can browsed here: + http://www.chiark.greenend.org.uk/~ijackson/ypp-sc-tools/master/ +See particularly the +YARRG README. + +

+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: +

+git-clone http://www.chiark.greenend.org.uk/~ijackson/ypp-sc-tools/master/.git ypp-sc-tools
+cd ypp-sc-tools
+cd yarrg
+make
+

+this will download the code into the directory ypp-sc-tools, +and build the software. + +

+ +When new versions of the upload client are released, you can: +

+cd .../ypp-sc-tools
+git-pull
+cd yarrg
+make
+

+to fetch the new version. + +

Uploading from Windows

+ +There is not currently an upload client for Windows which feeds data +into YARRG. It would probably be straightforward to modify the +Windows PCTB v5 upload client to upload to YARRG as well. The +mechanism and format for uploading is documented in +README.devel. + +

YARRG development, contribution and troubleshooting

+ +

Free Software (aka Open Source)

+ +YARRG is Free Software - you may share and modify it. See the +licences for details. + +

+ +Not only the client but also the webserver code is Free. The website +code can be found in the same tree as above, in the web +directory. + +

+ +But in case we have made changes but not yet pushed them +(perhaps because we haven't done a release), and to make it easy for +anyone else who runs a copy of the website to provide everyone with +the source for their version, the website code itself lets you download +an up-to-date tarball of its +actually-running source code. + +

+ +If you would like to run a (perhaps modified) copy of the YARRG +website it would be very easy for us to make our system send you +copies of updates submitted by users of the official YARRG client, in +the format expected by the code you'll be running. Please just ask +us. + +

Contacting the YARRG developers

+ +Email Ian Jackson ijackson (at) chiark.greenend.org.uk. Or talk to +any Fleet Officer or above of the crew Special Circumstances on the +Midnight Ocean. + +<& footer, isdocs => 1 &> diff --git a/yarrg/web/lookup b/yarrg/web/lookup index 35b6ce7..448ad6e 100755 --- a/yarrg/web/lookup +++ b/yarrg/web/lookup @@ -141,6 +141,8 @@ tr.datarow1 { background: #ffffff; } YARRG - Yet Another Revenue Research Gatherer | +introduction +| documentation

<%perl> diff --git a/yarrg/web/query_route b/yarrg/web/query_route index 296c012..96e8c32 100644 --- a/yarrg/web/query_route +++ b/yarrg/web/query_route @@ -94,7 +94,7 @@ Enter route (islands, or archipelagoes, separated by |s or commas; -Vessel capacity: +Vessel or capacity: <&| qtextstring, qa => $qa, dbh => $dbh, prefix => 'cs', thingstring => 'capacitystring', emsgstore => \$emsg, perresult => sub {