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       * press Ctrl-A Ctrl-C
  17
  18     In where-vessels, click "Acquire"
  19
  20 You will probably want to create a "vessel-notes" file to get the best
  21 use out of where-vessels, see below.
  22
  23 If you don't have exactly one YPP client open and logged in then you
  24 will have to pass --ocean and --pirate options.
  25
  26 If there was trouble acquiring the data (or loading the notes, see
  27 below) you can click on the error message to open a window giving
  28 information about the problem.
  29
  30
  31 OPTIONS:
  32 ========
  33
  34  --pirate PIRATE   Treat vessels belonging to PIRATE as your own
  35  --ocean OCEAN     Use map of OCEAN
  36
  37  --notes SOURCE
  38    Use SOURCE as the vessel notes; default is "vessel-notes" in the
  39    current directory.  See below.  SOURCE may be of the following forms:
  40      SCHEME:... eg http:...    URL, fetched with Tcl's http package
  41      |COMMAND ARG ARG          command (Tcl list) whose output is the notes
  42      NOTES-FILE                ordinary file
  43
  44  --vessel-info-source RSYNC-SRC
  45      Update information about vessels, subclasses, icons, etc. from
  46      RSYNC-SRC.  Default is yarrg.chiark.net::yarrg/vessel-info.
  47      If RSYNC-SRC is the empty string, do not update and just use
  48      local data from icons/* and _vessel_info_cache.
  49
  50  --clipboard-file FILE
  51      Use FILE as the initial clipboard containing a set of vessels to
  52      display, rather than waiting for Acquire.  Useful for testing or
  53      if you want to save your vessel locations for when you're not
  54      logged in.  The easiest way to create a suitable FILE is
  55      xclipboard
  56
  57  --local-html-dir DIR
  58      Do not fetch ocean map from Yppedia.  Instead, use copy in DIR.
  59
  60
  61 VESSEL NOTES:
  62 =============
  63
  64 The information collected via the clipboard from the Yohoho Puzzle
  65 Pirates client does not include any information about who owns the
  66 ship.  (Sadly, it doesn't even include whether the ship is yours, even
  67 though this can be seen on the screen by looking at whether the icon
  68 has a blue fringe.)
  69
  70 It also doesn't include any information about how the ship is stocked,
  71 what might be recorded on the Officer Notice Board about how it is to
  72 be used, etc.
  73
  74 So to help you make sense of your fleet, where-vessels can read a file
  75 of notes about each ship.  The lines in this file are of the form:
  76   <vessel-id> <name> = <owning pirate name> [<flags>]
  77
  78 If your vessel-notes file doesn't mention a ship, you can click on the
  79 message "1 warning(s)" below "Reload notes" and it will open a window
  80 showing what the problem is.  This will include, for ships missing
  81 from the notes, a template line for each ship, eg:
  82     # Eta Island:
  83     1730081   High Silverside               =
  84 Copy and paste the line with the ship name to your vessel-notes file
  85 and fill it in, eg:
  86     1730081   High Silverside               =  Anaplian   T
  87 You probably don't want to copy the line with the island name into
  88 your vessel-notes; it's just there to help you identify and find the
  89 ship in question (for example if you want to look at it in-game), but
  90 it will become out of date if the ship moves.
  91
  92 Blank lines are ignored, as are lines starting with #.
  93
  94 It is best if you can arrange to have a single notes file for the
  95 whole crew, and find some what to edit it collectively.
  96
  97 Flags:
  98 ------
  99
 100 The "flags" field has nothing to do with the in-game political entity
 101 known as a Flag.  It's a mostly free-form text field, with the
 102 following properties:
 103  - It is displayed next to each ship on the map (so ships with
 104     non-identical flags are not grouped and counted)
 105  - You can filter ships by entering a Perl regexp on the flags
 106  - It may not contain spaces
 107
 108 It is therefore usually best to use the flags field for one-letter
 109 codes referring to the properties of each ship.  Here is an example,
 110 from the Special Circumstances shared vessel-notes file:
 111
 112 # Don't edit if you're not logged into Puzzle Pirates.
 113 # To avoid simultaneous clashing edits, please coordinate with
 114 # your other Fleet Officers using the in-game chat.
 115
 116 # Flags for the column after the owner.
 117 #
 118 #  L    Ship is public special use.  Eg the chart library.
 119 #
 120 #  S    Ship is personal special use.  Eg, personal storage
 121 #       for a stall or personal trading.
 122 #
 123 #  P    Ship is stocked and otherwise suitable for pillaging etc:
 124 #       It is normally kept well stocked with rum and cannonballs and
 125 #       doesn't mind much where it's left.
 126 #
 127 #  T    Ship is stocked and otherwise suitable for trading or memming:
 128 #       It is normally kept stocked with a little rum but few if any
 129 #       cannonballs.  It doesn't mind much where it's left.
 130 #
 131 #  G    Ship is often used for the ad-hoc storage of commodities eg
 132 #       as part of trading activities.
 133 #
 134 #  R    Ship is borrowable but with some restrictions; ONB has details.
 135 #
 136 #  A    Ship is an auxiliary vessel (eg a supply sloop) or normally
 137 #       sails as part of a convoy.
 138 #
 139 #  DO NOT rely on this file to be up to date.  Check the Officer
 140 #  Notice Board before borrowing a ship.