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