neale/moth
neale
/
moth
mirror of https://github.com/dirtbags/moth.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Corrected/clarified more documentation

This commit is contained in:
Jack Miner 2016-02-23 12:13:38 -07:00
parent 0df56eaf04
commit fe42550be4
2 changed files with 37 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
README.md
View File

@ -28,16 +28,16 @@ for details.
Dependencies Dependencies
-------------------- --------------------
If you're using Xubuntu 14.04 LTS, you should have everything you need except 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 How to set it up
-------------------- --------------------
It's made to be virtualized, It's made to be virtualized,
so you can run multiple contests at once if you want. 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: do the following:
$ mkdir -p /opt/moth/mycontest $ mkdir -p /opt/moth/mycontest
@ -52,13 +52,15 @@ Installing Puzzle Categories
Puzzle categories are distributed in a different way than the server. Puzzle categories are distributed in a different way than the server.
After setting up (see above), just run After setting up (see above), just run
$ /opt/moth/mycontest/bin/install-category /path/to/my/category $ /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 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`: 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: First, install lighttpd and backup the configuration:
@ -66,7 +68,7 @@ First, install lighttpd and backup the configuration:
$ sudo apt-get install lighttpd -y $ sudo apt-get install lighttpd -y
$ cp /etc/lighttpd/lighttpd.conf /etc/lighttpd/lighttpd.conf.orig $ 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") alias.url = ("/moth" => "/opt/moth/mycontest/www")
$HTTP["url"] =~ "/moth/" { $HTTP["url"] =~ "/moth/" {
@ -79,7 +81,7 @@ Restart your server:
* Stopping web server lighttpd [ OK ] * Stopping web server lighttpd [ OK ]
* Starting 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 chown -R moth:moth /opt/moth/mycontest
$ sudo -u moth /opt/moth/mothd $ 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, but if you're using Apache,
it plays games with user IDs when running CGI. it plays games with user IDs when running CGI.
You're going to have to figure out how to configure your preferred web server. 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.

52
doc/writing-puzzles.md
View File

@ -1,4 +1,4 @@
How to create puzzle categories How to Create Puzzle Categories
=============================== ===============================
The contest has multiple "puzzle" categories. Each category contains a 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. 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 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 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. been the main reason students lose interest.
Step 3: Set up your puzzle structure 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 Step 4: Write puzzles
--------------------- ---------------------
Now that your skeleton is set up, you can begin to fill it in. In each Now that your skeleton is set up, you can begin to fill it in. In each point-
point-value subdirectory, there can be three special files, and as many value subdirectory, there are some required files:
downloadable files as you like, in addition to CGI and any downloadable
but non-listed files you would like.
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 You can add other files to this subdirectory, and they will show up in a list
[markdown](http://daringfireball.net/projects/markdown/), displayed below the puzzle description. Sometimes you want files to be accessible, but
before the list of normal files in the puzzle directory. not show up in the list (e.g., images in the puzzle description). In this case,
* 00answers.txt: a plain text file with acceptable answers, one per line. Answers you can create a `00manifest.txt` file and add each filename you want to be
are matched exactly (ie. they are case-sensitive). listed on its own line. **Filenames beginning with `00` will ignored.** Any
* 00author.txt: a plain text file with the puzzle author's name. file ending with `.cgi` will be run as CGI. You can search the web for [how to
* summary: a single line explaining to contest organizers what's going write a CGI](http://bfy.tw/4PXC). Some available languages are
on in this puzzle. [Python](http://python.org), [LUA](http://lua.org), and
[Bourne Shell](http://bfy.tw/4PXJ).
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.
Let's make our 5-point sandwich question! Let's make our 5-point sandwich question!
$ cd 5 $ cd 5
$ cat <<EOD >index.mdwn $ cat <<EOD >00index.mdwn
> Welcome to the Sandwich category! > Welcome to the Sandwich category!
> ---------------------------------
>
> In this category you will learn how to make a tasty sandwich. > In this category you will learn how to make a tasty sandwich.
> The key ingredients in a sandwich are: bread, spread, and filling. > 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, > 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 > include cheese, sprouts, and cold cuts. When you are done, apply
> another slice of bread on top, and optionally tie it together with > another slice of bread on top, and optionally tie it together with
> a fancy toothpick. > a fancy toothpick.
> > ![](sandwich.jpg)
> Now that you know the basics of sandwich-making, it's time for a > Now that you know the basics of sandwich-making, it's time for a
> question! How many slices of bread are in a sandwich? > question! How many slices of bread are in a sandwich?
> EOD > EOD
$ cat <<EOD >key $ cat <<EOD >00answers.txt
> 2 > 2
> TWO > TWO
> two > two
> EOD > 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 If you wanted to provide a PDF of various sandwiches, this would be the
time to add that too: time to add that too:
$ cp /tmp/sandwich-types.pdf . $ cp /tmp/sandwich-types.pdf .
$ echo "sandwich-types.pdf" >> 00manifest.txt
In a real category, you might provide an executable, hard drive image, In a real category, you might provide an executable, hard drive image,
or some other kind of blob. or some other kind of blob.