yarrg/README.where-vessels

   1                         where-vessels
   2                         =============
   3
   4 where-vessels displays a map of the ocean with your ships marked on it.
   5
   6
   7 USAGE:
   8 ======
   9
  10     $ cd .../ypp-sc-tools/yarrg
  11     $ ./where-vessels [options]
  12
  13     Then, in your YPP client:
  14       * go to the docks of any island
  15       * click on the button "Where are my vessels"
  16       * click anywhere in the main part of the screen
  17       * press Ctrl-A Ctrl-C
  18
  19     In where-vessels, click "Acquire"
  20
  21 You may well want to create a "vessel-notes" file to get the best
  22 use out of where-vessels, see below.
  23
  24 If you don't have exactly one YPP client open and logged in then you
  25 will have to pass --ocean and --pirate options.
  26
  27 If there was trouble acquiring the data (or loading the notes, see
  28 below) you can click on the error message to open a window giving
  29 information about the problem.
  30
  31
  32 OPTIONS:
  33 ========
  34
  35  --ocean OCEAN
  36      Use map of OCEAN.  Default is to guess by looking for an
  37      open Puzzle Pirates client on the same display (logged on
  38      as PIRATE, if --pirate was used).
  39
  40  --pirate PIRATE
  41      Supplies the name of your pirate.  If you also supply a notes
  42      file (see below) where-vessels will treat ships belonging to
  43      PIRATE as your own.  An empty argument means do not care about
  44      vessel ownership.  Default is not to care about ownership without
  45      notes; with notes, default is to look for a Puzzle Pirates client
  46      on the same display (on OCEAN, if --ocean was used).
  47
  48  --notes SOURCE
  49      Use SOURCE as the vessel notes.  See below.
  50      SOURCE may be of the following forms:
  51        empty argument            No notes, this is the default
  52        SCHEME:... eg http:...    URL, fetched with Tcl's http package
  53        |COMMAND ARG ARG          command (Tcl list) whose output is the notes
  54        NOTES-FILE                ordinary file
  55
  56  --filter-separate-lock-owner
  57      In the filter, show two separate 3-button filters for the lock
  58      status, and the ship owner, rather than one 9-button filter with
  59      an option for each combination.  (If there are no notes, only
  60      one 3-button filter, for the lock status, is shown, anyway.)
  61
  62  --vessel-info-source RSYNC-SRC
  63      Update information about vessels, subclasses, icons, etc. from
  64      RSYNC-SRC.  Default is yarrg.chiark.net::yarrg/vessel-info.
  65      If RSYNC-SRC is the empty string, do not update and just use
  66      local data from icons/* and _vessel_info_cache.
  67
  68  --clipboard-file FILE
  69      Use FILE as the initial clipboard containing a set of vessels to
  70      display, rather than waiting for Acquire.  Useful for testing or
  71      if you want to save your vessel locations for when you're not
  72      logged in.  The easiest way to create a suitable FILE is
  73      xclipboard
  74
  75  --local-html-dir DIR
  76      Do not fetch ocean map from Yppedia.  Instead, use copy in DIR.
  77
  78
  79 USER INTERFACE:
  80 ===============
  81
  82 There are some things that won't be obvious from the user interface.
  83
  84 The black square with the blue square inside it is the panner for the
  85 map.
  86
  87 If you get an error message from Acquire, or a message about the
  88 notes, shown as a red, yellow or blue message below the Acquire or
  89 Reload Notes button, you can click on the message to get a pop-up
  90 window with the full error message.
  91
  92 Colonised islands are shown with names in black; uncolonised in grey.
  93 Dotted routes are unpurchaseable charts.  (Information from Yppedia.)
  94
  95 If you click on one of the little white icons on the map, you'll see
  96 an explanation of what that icon string means appear in the top right.
  97 Each element of the icon is explained in turn from left to right.
  98 Then you'll see a list of the ships represented below, ordered by
  99 owning pirate (if known) and then by name.
 100
 101 The "Show" panel allows you to filter the displayed ships.  If you
 102 don't select "These:" then none of the other controls in the "Show"
 103 panel have any effect, so touching any of the latter sets the overall
 104 filtering style back to "These:".
 105
 106 "Copy island names" makes where-vessels "copy" (as in "copy and
 107 paste") a comma-separated list of the names of the islands at which
 108 selected ships are present.  You can then paste this into other tools
 109 (eg, the YARRG website).  (Technically, "copy island names" claims the
 110 X Primary Selection.)
 111
 112 "Display/combine details" allows the map display to be decluttered by
 113 squashing together differing ships:
 114  * "Size round down": selecting a size means that every ship of that
 115    size will be rounded down to the next un-selected size.  Naturally
 116    you cannot select sloops for rounding down!
 117  * "Lock/owner": "Yours?" simply pretends that all unknown ships are
 118    not yours; that is useful if your crew has many ships and you only
 119    bother writing about your own ships in the notes.  "For you" shows
 120    the vessel lock status, except that if it's your ship and unlocked
 121    it shows just that it's yours (and doesn't show whether it's
 122    unlocked or crew use).  "Lock" shows the lock status only.
 123  * Flags: See perlop(1) on the tr/// (aka y///) operator.  All
 124    characters entered into the boxes are literal; ranges etc. are not
 125    supported.
 126 Filtering done by the "Show" panel takes effect before the collapsing
 127 done by "Display/combine details", so you can filter on details which
 128 you are collapsing for display.
 129
 130 If you select (click on) one of the ship names in the list in the top
 131 right, you'll get an icon string below the vessel list which gives the
 132 complete information for that vessel, as it was before the collapsing.
 133
 134
 135
 136 VESSEL NOTES:
 137 =============
 138
 139 The information collected via the clipboard from the Yohoho Puzzle
 140 Pirates client does not include any information about who owns the
 141 ship.  (Sadly, it doesn't even include whether the ship is yours, even
 142 though this can be seen on the screen by looking at whether the icon
 143 has a blue fringe.)
 144
 145 It also doesn't include any information about how the ship is stocked,
 146 what might be recorded on the Officer Notice Board about how it is to
 147 be used, etc.
 148
 149 So to help you make sense of your fleet, where-vessels can read a file
 150 of notes about each ship.  The lines in this file are of the form:
 151   <vessel-id> <name> = <owning pirate name> [<flags>]
 152
 153 If your vessel-notes file doesn't mention a ship, you can click on the
 154 message "1 warning(s)" below "Reload notes" and it will open a window
 155 showing what the problem is.  This will include, for ships missing
 156 from the notes, a template line for each ship, eg:
 157     # Eta Island:
 158     1730081   High Silverside               =
 159 Copy and paste the line with the ship name to your vessel-notes file
 160 and fill it in, eg:
 161     1730081   High Silverside               =  Anaplian   T
 162 You probably don't want to copy the line with the island name into
 163 your vessel-notes; it's just there to help you identify and find the
 164 ship in question (for example if you want to look at it in-game), but
 165 it will become out of date if the ship moves.
 166
 167 Blank lines are ignored, as are lines starting with #.
 168
 169 It is best if you can arrange to have a single notes file for the
 170 whole crew, and find some what to edit it collectively.
 171
 172 Flags:
 173 ------
 174
 175 The "flags" field has nothing to do with the in-game political entity
 176 known as a Flag.  It's a mostly free-form text field, with the
 177 following properties:
 178  - It is displayed next to each ship on the map (so ships with
 179     non-identical flags are not grouped and counted)
 180  - You can filter ships by entering a Perl regexp on the flags
 181  - It may not contain spaces
 182
 183 It is therefore usually best to use the flags field for one-letter
 184 codes referring to the properties of each ship.  Here is an example,
 185 from the Special Circumstances shared vessel-notes file:
 186
 187 # Don't edit if you're not logged into Puzzle Pirates.
 188 # To avoid simultaneous clashing edits, please coordinate with
 189 # your other Fleet Officers using the in-game chat.
 190
 191 # Flags for the column after the owner.
 192 #
 193 #  L    Ship is public special use.  Eg the chart library.
 194 #
 195 #  S    Ship is personal special use.  Eg, personal storage
 196 #       for a stall or personal trading.
 197 #
 198 #  P    Ship is stocked and otherwise suitable for pillaging etc:
 199 #       It is normally kept well stocked with rum and cannonballs and
 200 #       doesn't mind much where it's left.
 201 #
 202 #  T    Ship is stocked and otherwise suitable for trading or memming:
 203 #       It is normally kept stocked with a little rum but few if any
 204 #       cannonballs.  It doesn't mind much where it's left.
 205 #
 206 #  G    Ship is often used for the ad-hoc storage of commodities eg
 207 #       as part of trading activities.
 208 #
 209 #  R    Ship is borrowable but with some restrictions; ONB has details.
 210 #
 211 #  A    Ship is an auxiliary vessel (eg a supply sloop) or normally
 212 #       sails as part of a convoy.
 213 #
 214 #  DO NOT rely on this file to be up to date.  Check the Officer
 215 #  Notice Board before borrowing a ship.