From fe42550be452e862fbe55f44bd5b8bd74d66526d Mon Sep 17 00:00:00 2001 From: Jack Miner <3ch01c@gmail.com> Date: Tue, 23 Feb 2016 12:13:38 -0700 Subject: [PATCH] Corrected/clarified more documentation --- README.md | 18 ++++++++++----- doc/writing-puzzles.md | 52 ++++++++++++++++++++---------------------- 2 files changed, 37 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 3428cfa..71f1563 100644 --- a/README.md +++ b/README.md @@ -28,16 +28,16 @@ for details. Dependencies -------------------- If you're using Xubuntu 14.04 LTS, you should have everything you need except -[LUA](http://lua.org). +[LUA](http://lua.org) and [Markdown](https://daringfireball.net/projects/markdown/). - $ sudo apt-get install lua5.2 -y + $ sudo apt-get install lua5.2 markdown -y How to set it up -------------------- It's made to be virtualized, so you can run multiple contests at once if you want. -If you were to want to run it out of `/opt/moth`, +If you want to run it out of `/opt/moth`, do the following: $ mkdir -p /opt/moth/mycontest @@ -52,13 +52,15 @@ Installing Puzzle Categories Puzzle categories are distributed in a different way than the server. After setting up (see above), just run + $ /opt/moth/mycontest/bin/install-category /path/to/my/category +If you want to create puzzles, also check out [How to Create Puzzle Categories](doc/writing-puzzles.md). Running It ------------- -Get your web server to serve up your contest. Here's one way to do it +Get your web server to serve up your contest. In addition to static files, it'll need to do CGI. Here's one way to do it on Xubuntu 14.04 LTS with [lighttpd](https://lighttpd.net) where the contest is at `/opt/moth/mycontest` and `mothd` is running as user `moth`: First, install lighttpd and backup the configuration: @@ -66,7 +68,7 @@ First, install lighttpd and backup the configuration: $ sudo apt-get install lighttpd -y $ cp /etc/lighttpd/lighttpd.conf /etc/lighttpd/lighttpd.conf.orig -Add `mod_cgi` to the `ServerModules` section, an alias, and CGI handling to `/etc/lighttpd/lighttpd.conf`: +Add `mod_cgi` to the `ServerModules` section, an alias to point to your contest, and CGI handling for your contest files to `/etc/lighttpd/lighttpd.conf`: alias.url = ("/moth" => "/opt/moth/mycontest/www") $HTTP["url"] =~ "/moth/" { @@ -79,7 +81,7 @@ Restart your server: * Stopping web server lighttpd [ OK ] * Starting web server lighttpd [ OK ] -Make sure user `moth` can access contest content and run the daemon. +Make sure user `moth` can access your content and run the daemon. $ sudo chown -R moth:moth /opt/moth/mycontest $ sudo -u moth /opt/moth/mothd @@ -93,3 +95,7 @@ Install sets it so the web user on your system can write to the files it needs t but if you're using Apache, it plays games with user IDs when running CGI. You're going to have to figure out how to configure your preferred web server. + +Everything Else +--------------- +If anything is missing in this documentation, create an issue/PR or email somebody. diff --git a/doc/writing-puzzles.md b/doc/writing-puzzles.md index f48e880..f9d369f 100644 --- a/doc/writing-puzzles.md +++ b/doc/writing-puzzles.md @@ -1,4 +1,4 @@ -How to create puzzle categories +How to Create Puzzle Categories =============================== The contest has multiple "puzzle" categories. Each category contains a @@ -58,7 +58,7 @@ unique: you may not have two 5-point puzzles. Point values should roughly reflect how difficult a problem is to solve. It's not terribly important that a 200-point puzzle be ten times harder than a 20-point puzzle, but it is crucial that a 25-point puzzle be -roughly as difficult as a 20-point puzzle. Poorly-weighted puzzles has +roughly as difficult as a 20-point puzzle. Poorly-weighted puzzles have been the main reason students lose interest. Step 3: Set up your puzzle structure @@ -80,34 +80,32 @@ value puzzle. In the "sandwich" category we have only 5, 10, and Step 4: Write puzzles --------------------- -Now that your skeleton is set up, you can begin to fill it in. In each -point-value subdirectory, there can be three special files, and as many -downloadable files as you like, in addition to CGI and any downloadable -but non-listed files you would like. +Now that your skeleton is set up, you can begin to fill it in. In each point- +value subdirectory, there are some required files: -Special files are: +* **00index.mdwn**: A plain text file formatted with [Markdown](http://daringfireball.net/projects/markdown/). This file usually +contains a description of the puzzle. +* **00answer.txt**: A plain text file with acceptable answers, one per line. +Answers are matched exactly (ie. they are case-sensitive). +* **00author.txt**: A plain text file with the puzzle author's name. -* index.md: a plain text file formatted with - [markdown](http://daringfireball.net/projects/markdown/), displayed - before the list of normal files in the puzzle directory. -* 00answers.txt: a plain text file with acceptable answers, one per line. Answers - are matched exactly (ie. they are case-sensitive). -* 00author.txt: a plain text file with the puzzle author's name. -* summary: a single line explaining to contest organizers what's going - on in this puzzle. - -All remaining files, except those with filenames beginning with a comma -(","), are listed on the puzzle page for download. - -Any file ending with ".cgi" will be run as CGI. You can search the web -for how to write a CGI. Available languages are Python, Lua, and Bourne -Shell. +You can add other files to this subdirectory, and they will show up in a list +below the puzzle description. Sometimes you want files to be accessible, but +not show up in the list (e.g., images in the puzzle description). In this case, +you can create a `00manifest.txt` file and add each filename you want to be +listed on its own line. **Filenames beginning with `00` will ignored.** Any +file ending with `.cgi` will be run as CGI. You can search the web for [how to +write a CGI](http://bfy.tw/4PXC). Some available languages are +[Python](http://python.org), [LUA](http://lua.org), and +[Bourne Shell](http://bfy.tw/4PXJ). Let's make our 5-point sandwich question! $ cd 5 - $ cat <index.mdwn + $ cat <00index.mdwn > Welcome to the Sandwich category! + > --------------------------------- + > > In this category you will learn how to make a tasty sandwich. > The key ingredients in a sandwich are: bread, spread, and filling. > When making a sandwich, you need to first put down one slice of bread, @@ -115,22 +113,22 @@ Let's make our 5-point sandwich question! > include cheese, sprouts, and cold cuts. When you are done, apply > another slice of bread on top, and optionally tie it together with > a fancy toothpick. - > + > ![](sandwich.jpg) > Now that you know the basics of sandwich-making, it's time for a > question! How many slices of bread are in a sandwich? > EOD - $ cat <key + $ cat <00answers.txt > 2 > TWO > two > EOD - $ echo "How many slices of bread in a sandwich" > summary - $ + $ echo "3ch01c" > 00author.txt If you wanted to provide a PDF of various sandwiches, this would be the time to add that too: $ cp /tmp/sandwich-types.pdf . + $ echo "sandwich-types.pdf" >> 00manifest.txt In a real category, you might provide an executable, hard drive image, or some other kind of blob.