Clarify download everything doc

contrib/download-everything.sh

@@ -0,0 +1,51 @@
+#! /bin/sh
+
+url=${1%/}
+teamid=$2
+
+case "$url:$teamid" in
+    *:|-h*|--h*)
+        cat <<EOD; exit 1
+Usage: $0 MOTHURL TEAMID
+
+Downloads all content currently open,
+and writes it out to a zip file.
+
+MOTHURL   URL to the instance
+TEAMID    Team ID you used to log in
+EOD
+        ;;
+esac
+
+tmpdir=$(mktemp -d moth-dl.XXXXXX)
+bye () {
+    echo "bye now"
+    rm -rf $tmpdir
+}
+trap bye EXIT
+
+fetch () {
+    curl -s -d id=$teamid "$@"
+}
+
+echo "=== Fetching puzzles and attachments"
+fetch $url/state > $tmpdir/state.json
+cat $tmpdir/state.json \
+| jq -r '.Puzzles | to_entries[] | .key as $k | .value[] | select (. > 0) | "\($k)  \(.)"' \
+| while read cat points; do
+    echo "   + $cat $points"
+    dir=$tmpdir/$cat/$points
+    mkdir -p $dir
+    fetch $url/content/$cat/$points/puzzle.json > $dir/puzzle.json
+    cat $dir/puzzle.json | jq .Body > $dir/puzzle.html
+    cat $dir/puzzle.json | jq -r '.Attachments[]?' | while read attachment; do
+        echo "     - $attachment"
+        fetch $url/content/$cat/$points/$attachment > $dir/$attachment
+    done
+done
+
+zipfile=$(echo $url | grep -o '[a-z]*\.[a-z.]*').zip
+echo "=== Writing $zipfile"
+(cd $tmpdir && zip -r - .) > $zipfile
+
+echo "=== Wrote $zipfile"

docs/download-everything.md

@@ -0,0 +1,30 @@
+Download All Unlocked Puzzles
+========================
+
+We get a lot of requests to "download everything" from an event.
+Here's how you could do that:
+
+What You Need
+------------
+
+* The URL to your puzzle server. We will call this `$url`.
+* Your Team ID. We will call this `$teamid`.
+* A way to POST `id=$teamid` 
+    with `Content-Type: x-www-form-encoded` to a URL, 
+    and save the result. 
+    We will call this procedure "Fetch".
+* A way to parse JSON files
+
+Steps
+-----
+
+1. Fetch `$url/state`. This is the State object.
+2. In the State object, `Puzzles` maps category name to a list of open puzzle point values.
+3. For each category (we will call this `$category`):
+    1. For each point value:
+        1. If the point value is 0, skip it. 0 indicates all puzzles in this category are unlocked.
+        2. Fetch `$url/content/$category/$points/index.json`. This is the Puzzle object.
+        3. In the Puzzle object, `Body` contains the HTML body of the puzzle.
+        4. In the Puzzle object, `Attachments` contains a list of attachments.
+            For each attachment (we will call this `$attachment`):
+            1. Fetch `$url/content/$category/$points/$attachment`.