--- /dev/null
+ 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.