X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~yarrgweb/git?p=ypp-sc-tools.db-live.git;a=blobdiff_plain;f=yarrg%2FREADME.where-vessels;h=40df2b48aebf8bab18615d28faec3527448db622;hp=190b7b3cabdba527296b29ec8f5b452b3c179060;hb=fe34dba430375e498ef46f82730795af229cee49;hpb=a938c022e63d696a50d0ce7644c6a3bfe9ecc96f

diff --git a/yarrg/README.where-vessels b/yarrg/README.where-vessels
index 190b7b3..40df2b4 100644
--- a/yarrg/README.where-vessels
+++ b/yarrg/README.where-vessels
@@ -17,7 +17,7 @@ USAGE:
 
     In where-vessels, click "Acquire"
 
-You will probably want to create a "vessel-notes" file to get the best
+You may well 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
@@ -31,15 +31,32 @@ information about the problem.
 OPTIONS:
 ========
 
- --pirate PIRATE   Treat vessels belonging to PIRATE as your own
- --ocean OCEAN     Use map of OCEAN
+ --ocean OCEAN
+     Use map of OCEAN.  Default is to guess by looking for an
+     open Puzzle Pirates client on the same display (logged on
+     as PIRATE, if --pirate was used).
+
+ --pirate PIRATE
+     Supplies the name of your pirate.  If you also supply a notes
+     file (see below) where-vessels will treat ships belonging to
+     PIRATE as your own.  An empty argument means do not care about
+     vessel ownership.  Default is not to care about ownership without
+     notes; with notes, default is to look for a Puzzle Pirates client
+     on the same display (on OCEAN, if --ocean was used).
 
  --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
+     Use SOURCE as the vessel notes.  See below.
+     SOURCE may be of the following forms:
+       empty argument            No notes, this is the default
+       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
+
+ --filter-separate-lock-owner
+     In the filter, show two separate 3-button filters for the lock
+     status, and the ship owner, rather than one 9-button filter with
+     an option for each combination.  (If there are no notes, only
+     one 3-button filter, for the lock status, is shown, anyway.)
 
  --vessel-info-source RSYNC-SRC
      Update information about vessels, subclasses, icons, etc. from
@@ -58,6 +75,63 @@ OPTIONS:
      Do not fetch ocean map from Yppedia.  Instead, use copy in DIR.
 
 
+USER INTERFACE:
+===============
+
+There are some things that won't be obvious from the user interface.
+
+The black square with the blue square inside it is the panner for the
+map.
+
+If you get an error message from Acquire, or a message about the
+notes, shown as a red, yellow or blue message below the Acquire or
+Reload Notes button, you can click on the message to get a pop-up
+window with the full error message.
+
+Colonised islands are shown with names in black; uncolonised in grey.
+Dotted routes are unpurchaseable charts.  (Information from Yppedia.)
+
+If you click on one of the little white icons on the map, you'll see
+an explanation of what that icon string means appear in the top right.
+Each element of the icon is explained in turn from left to right.
+Then you'll see a list of the ships represented below, ordered by
+owning pirate (if known) and then by name.
+
+The "Show" panel allows you to filter the displayed ships.  If you
+don't select "These:" then none of the other controls in the "Show"
+panel have any effect, so touching any of the latter sets the overall
+filtering style back to "These:".
+
+"Copy island names" makes where-vessels "copy" (as in "copy and
+paste") a comma-separated list of the names of the islands at which
+selected ships are present.  You can then paste this into other tools
+(eg, the YARRG website).  (Technically, "copy island names" claims the
+X Primary Selection.)
+
+"Display/combine details" allows the map display to be decluttered by
+squashing together differing ships:
+ * "Size round down": selecting a size means that every ship of that
+   size will be rounded down to the next un-selected size.  Naturally
+   you cannot select sloops for rounding down!
+ * "Lock/owner": "Yours?" simply pretends that all unknown ships are
+   not yours; that is useful if your crew has many ships and you only
+   bother writing about your own ships in the notes.  "For you" shows
+   the vessel lock status, except that if it's your ship and unlocked
+   it shows just that it's yours (and doesn't show whether it's
+   unlocked or crew use).  "Lock" shows the lock status only.
+ * Flags: See perlop(1) on the tr/// (aka y///) operator.  All
+   characters entered into the boxes are literal; ranges etc. are not
+   supported.
+Filtering done by the "Show" panel takes effect before the collapsing
+done by "Display/combine details", so you can filter on details which
+you are collapsing for display.
+
+If you select (click on) one of the ship names in the list in the top
+right, you'll get an icon string below the vessel list which gives the
+complete information for that vessel, as it was before the collapsing.
+
+
+
 VESSEL NOTES:
 =============