documentation for where-vessels

diff --git a/yarrg/README.where-vessels b/yarrg/README.where-vessels
new file mode 100644 (file)
index 0000000..190b7b3
--- /dev/null
+++ b/yarrg/README.where-vessels
@@ -0,0 +1,140 @@
+                       where-vessels
+                       =============
+
+where-vessels displays a map of the ocean with your ships marked on it.
+
+
+USAGE:
+======
+
+    $ cd .../ypp-sc-tools/yarrg
+    $ ./where-vessels [options]
+
+    Then, in your YPP client:
+      * go to the docks of any island
+      * click on the button "Where are my vessels"
+      * press Ctrl-A Ctrl-C
+
+    In where-vessels, click "Acquire"
+
+You will probably want to create a "vessel-notes" file to get the best
+use out of where-vessels, see below.
+
+If you don't have exactly one YPP client open and logged in then you
+will have to pass --ocean and --pirate options.
+
+If there was trouble acquiring the data (or loading the notes, see
+below) you can click on the error message to open a window giving
+information about the problem.
+
+
+OPTIONS:
+========
+
+ --pirate PIRATE   Treat vessels belonging to PIRATE as your own
+ --ocean OCEAN     Use map of OCEAN
+
+ --notes SOURCE
+   Use SOURCE as the vessel notes; default is "vessel-notes" in the
+   current directory.  See below.  SOURCE may be of the following forms:
+     SCHEME:... eg http:...    URL, fetched with Tcl's http package
+     |COMMAND ARG ARG          command (Tcl list) whose output is the notes
+     NOTES-FILE                ordinary file
+
+ --vessel-info-source RSYNC-SRC
+     Update information about vessels, subclasses, icons, etc. from
+     RSYNC-SRC.  Default is yarrg.chiark.net::yarrg/vessel-info.
+     If RSYNC-SRC is the empty string, do not update and just use
+     local data from icons/* and _vessel_info_cache.
+
+ --clipboard-file FILE
+     Use FILE as the initial clipboard containing a set of vessels to
+     display, rather than waiting for Acquire.  Useful for testing or
+     if you want to save your vessel locations for when you're not
+     logged in.  The easiest way to create a suitable FILE is
+     xclipboard
+
+ --local-html-dir DIR
+     Do not fetch ocean map from Yppedia.  Instead, use copy in DIR.
+
+
+VESSEL NOTES:
+=============
+
+The information collected via the clipboard from the Yohoho Puzzle
+Pirates client does not include any information about who owns the
+ship.  (Sadly, it doesn't even include whether the ship is yours, even
+though this can be seen on the screen by looking at whether the icon
+has a blue fringe.)
+
+It also doesn't include any information about how the ship is stocked,
+what might be recorded on the Officer Notice Board about how it is to
+be used, etc.
+
+So to help you make sense of your fleet, where-vessels can read a file
+of notes about each ship.  The lines in this file are of the form:
+  <vessel-id> <name> = <owning pirate name> [<flags>]
+
+If your vessel-notes file doesn't mention a ship, you can click on the
+message "1 warning(s)" below "Reload notes" and it will open a window
+showing what the problem is.  This will include, for ships missing
+from the notes, a template line for each ship, eg:
+    # Eta Island:
+    1730081   High Silverside               =
+Copy and paste the line with the ship name to your vessel-notes file
+and fill it in, eg:
+    1730081   High Silverside               =  Anaplian   T
+You probably don't want to copy the line with the island name into
+your vessel-notes; it's just there to help you identify and find the
+ship in question (for example if you want to look at it in-game), but
+it will become out of date if the ship moves.
+
+Blank lines are ignored, as are lines starting with #.
+
+It is best if you can arrange to have a single notes file for the
+whole crew, and find some what to edit it collectively.
+
+Flags:
+------
+
+The "flags" field has nothing to do with the in-game political entity
+known as a Flag.  It's a mostly free-form text field, with the
+following properties:
+ - It is displayed next to each ship on the map (so ships with
+    non-identical flags are not grouped and counted)
+ - You can filter ships by entering a Perl regexp on the flags
+ - It may not contain spaces
+
+It is therefore usually best to use the flags field for one-letter
+codes referring to the properties of each ship.  Here is an example,
+from the Special Circumstances shared vessel-notes file:
+
+# Don't edit if you're not logged into Puzzle Pirates.
+# To avoid simultaneous clashing edits, please coordinate with
+# your other Fleet Officers using the in-game chat.
+
+# Flags for the column after the owner.
+#
+#  L   Ship is public special use.  Eg the chart library.
+#
+#  S   Ship is personal special use.  Eg, personal storage
+#      for a stall or personal trading.
+#
+#  P   Ship is stocked and otherwise suitable for pillaging etc:
+#      It is normally kept well stocked with rum and cannonballs and
+#      doesn't mind much where it's left.
+#
+#  T   Ship is stocked and otherwise suitable for trading or memming:
+#      It is normally kept stocked with a little rum but few if any
+#      cannonballs.  It doesn't mind much where it's left.
+#
+#  G   Ship is often used for the ad-hoc storage of commodities eg
+#      as part of trading activities.
+#
+#  R   Ship is borrowable but with some restrictions; ONB has details.
+#
+#  A   Ship is an auxiliary vessel (eg a supply sloop) or normally
+#      sails as part of a convoy.
+#
+#  DO NOT rely on this file to be up to date.  Check the Officer
+#  Notice Board before borrowing a ship.