chiark / gitweb /
Store full-colour image with every screenshot
[ypp-sc-tools.main.git] / yoweb-scrape.txt
index 752080a..fc8c99b 100644 (file)
@@ -1,12 +1,19 @@
-Ian Jackson writes ("Choice of vessel for pillaging"):
-> What I really want is something that redacts it into a table (ideally,
-> by trawling the chat log).  I don't suppose someone fancies writing
-> the yoweb screenscraper :-) ?
+               yoweb-scrape
+               ------------
 
-Here it is.  You run it like this:
+This program can:
+  * Fetch information for crew and pirates from yoweb
+  * Display tables of puzzle standings
+  * Keep track of who is on board a vessel
+
+Putting this all together, it can be used to show a table of who's
+good at what when you're running a pillage.
+
+You run it roughly like this:
   ./yoweb-scrape ship-aid ~/yohoho/Aristarchus_midnight_chat-log-iwj 
 It has various other modes - see the usage message.
 
+
 Key features:
 
  * Tracks boarding and departure of pirates and shows a table
@@ -25,51 +32,89 @@ Key features:
    display twirling batons while you wait for data, so that crew
    on board info remains correct.
 
-I know of one key defect:
+ * Can sort pirates by their skills in the key duty puzzles.  Press
+   a single keystroke to sort by:
+      s: sailing                   b: bilging
+      c: carpentry                 g: gunning
+      n: navigation (duty nav)     t: treasure haul
+      d: driving (battle nav)      a: sort by pirate name
+   It will prefer to list near the top pirates whose other skills
+   are weaker.  This functionality is disabled if stdin is not a tty.
+   Other keystrokes:
+      q: quit the program (^C works too)
+
+Things you need to know:
+
+ * Please don't leave it running if you're not in charge.  If everyone
+   runs yoweb-scrape all the time it will produce precisely the load
+   on the yoweb servers that we want to avoid.
+
+ * You must enable the YPP client chat log.  It is disabled by
+   default.  This can be found in the client in the options panel
+   under `Ye'.  Contrary to what the client UI seems to suggest, the
+   filename you specify there is not used directly: information about
+   your pirate name and ocean are added by the client, which is good
+   because yoweb-scrape can dig it out again.
 
  * If you leave and then reboard a vessel, the list of pirates on
    board may be wrong.  This is because the chat log doesn't contain
-   the necessary information.  The script assumes that the set of
-   pirates on board doesn't change while you're off the ship (unless
-   you're away for more than an hour, in which case it assumes the
-   ship is empty when you return to it).
-
-   This means that there needs to be a way to manually add and remove
-   pirates - but there isn't.  I think this could probably be added by
-   someone who could be bothered to replace the `sleep 1' in the main
-   loop by something which looked for keyboard input.
-
-   However it will notice that a pirate is on board if they abandon a
-   duty station (in circumstances where the game reports this in the
-   log, which doesn't seem to be all the time) or you give them a
-   stationing order, and from various other messages that might occur.
+   information about who's on board the ship when you reboard it.
+
+   yoweb-scrape assumes that, unless it is told otherwise (or notices
+   for itself), the set of pirates on board doesn't change while
+   you're off the ship (unless you're away for more than an hour, in
+   which case it assumes the ship is empty when you return to it).
+
+   You can tell it otherwise with specially formatted chat messages.
+   Messages sent or received to officer chat, and messages sent (not
+   received) in private message, are scanned for special `commands' to
+   yoweb-scrape.  (So you can have an officer on board the ship keep
+   your yoweb-scrape up to date if you like.)
+   
+   The commands are of the following format:
+         /a <pirate>...                        /d <pirate>...
+        /a <ship-spec>: <pirate>...    /d <ship-spec>: <pirate>...
+
+   <ship-spec> can be the full name of the ship, or or only the second
+   word (the noun).  It can also be a pattern, where `*' matches any
+   (nonempty) series of characters including spaces, and which counts
+   if it matches either the whole ship name or just the noun.
+
+   For example:
+         /a haddock: aiah
+        /d aiah
+        /a smart sunfish: copperkatie
+        /a s* sunfish: anaplian
+   These are actually sent by typing in the chat box things like:
+         /o /d plonker
+         /off /a hypiscles
+   since other formulations interpret the scraper command as a YPP
+   chat command.  This is deliberate and makes it harder to invoke by
+   mistake.
+
+   If you don't specify a ship, it will assume that it's the ship that
+   you (or the officer speaking) are on board.  (For full details of
+   the matching algorithm, see below.)  If more than one ship is being
+   managed with yoweb-scrape, any user who wishes to issue these
+   commands should say:
+         /a relevant fish: executiveofficer
+   so that everyone else's yoweb-scrape knows which ship they're on
+   and thus which ship their /a commands refer to.
+
+ * For the ship duty puzzle display, and for sorting pirates by
+   skill, we take the best of Sailing and Rigging.
 
 Other things to mention:
 
- * There's nothing really resembling a manual.
-
- * It doesn't notice when you yourself disembark.  That's because
-   that's not recorded in the chat log.
-
- * Many people may find the output rather basic - it's ASCII art - and
-   it's not very customisable.
-
- * It spends a while reading the whole of your chat log which can be
-   very long.  Perhaps it should be smarter (eg, bisect the log
-   to find `nearly now').
-
- * It could have lots more features in general.
+ * There are some things which don't reliably appear in the chat log,
+   for example: when you disembark, and when a pirate leaves a duty
+   station.  That can mean that yoweb-scrape isn't always as up to
+   date as you would like.  You'll just have to tell it manually.
 
  * The `tabulate details of my whole crew' mode takes a long time
    to run.  This is normal; it's trying to spread the load on yoweb
    (perhaps excessively so).
 
- * I have it in git right now but here is just a copy of the single
-   file which is the script.  I'm planning to put my rum calculator
-   and other useful things into the same repo and put it on chiark
-   somewhere.  For my reference, this is from tree revision
-     15799130f8d34856b9cefe3c71103564413fa04a
-
  * I haven't decided on a final copyright licence.  You may treat this
    version as GPLv3.
 
@@ -81,33 +126,27 @@ Other things to mention:
    until after the duplicated hour has passed) as that writes a new
    date record to the log and starts a new series of timestamps.
 
- * You have to enable the chat log for the ship-aid mode.
-
-Ian.
-
-
+ * It's Python so it may eat CPU and memory.
 
-Ian Jackson writes ("Re: Choice of vessel for pillaging"):
-> Ian Jackson writes ("Choice of vessel for pillaging"):
-> > What I really want is something that redacts it into a table (ideally,
-> > by trawling the chat log).  I don't suppose someone fancies writing
-> > the yoweb screenscraper :-) ?
-> 
-> Here it is.  You run it like this:
->   ./yoweb-scrape ship-aid ~/yohoho/Aristarchus_midnight_chat-log-iwj 
-> It has various other modes - see the usage message.
+ * You may need to install some python modules.  BeautifulSoup (yes,
+   really!) is in the Debian package  python-beautifulsoup
 
-A couple more things:
 
- * Please don't leave it running if you're not in charge.  If
-   everyone runs this it will produce precisely the load on the yoweb
-   servers that we want to avoid.
- * It's Python so it may eat CPU and memory.
- * You may need to install some python modules of course.
- * Here's a version which is an attachment rather than asking you
-   to cut-and-paste.  That will save on you mangling it and getting
-   weird python errors.
+Some more details about tracking semantics:
 
-Ian.
+ * The program will notice that a pirate is on board if you give them
+   a stationing order or they abandon a duty station (in circumstances
+   where the game reports this in the log, which doesn't seem to be
+   all the time), and from many of the other messages that occur.
 
-yoweb-scrape as a binary blobule, y [Press RETURN to save to a file]
+ * Matching for ship patterns in /a and /d commands picks the first
+   of the following which applies and is not contradicted by any
+   name or partial name specified in the command:
+      - The ship we think the person telling us is on board
+      - The ship we think we are on board
+      - Any other ship we know about, if at least a something was
+         specified, and provided that is not ambiguous
+      - The specific ship name if it is completely specified,
+         possibly recording this as a new ship
+   <pirate> and <ship> can be in any case and will be converted to
+   the proper mixed-case form automatically.