mirror of https://github.com/dirtbags/moth.git
Corrected/clarified more documentation
This commit is contained in:
Jack Miner
parent
0df56eaf04
commit
fe42550be4
18
README.md
18
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.
|
||||
|
|
|
|||
|
|
@ -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 <<EOD >index.mdwn
|
||||
$ cat <<EOD >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.
|
||||
>
|
||||
> 
|
||||
> 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 <<EOD >key
|
||||
$ cat <<EOD >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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue