QED
User Manual
Version 1.40

About

QED, or Question Editing Database, is a full-featured quiz bowl question-editing program designed to allow one or more users secure access to a database of question files. It allows a group of question-writers collaborating on one or more packets to input their questions in an orderly way, edit each other's questions, and then aggregates the questions for an administrator to compile into packets.

Questions? Comments? Contact Carlo Angiuli at carlo@aegisquestions.com. QED is free to use, and you may modify the source code as long as the name and original author are maintained, but the version number is changed to indicate a non-standard copy. QED is ©2006-2007 Carlo Angiuli.

Requirements

Server Requirements

QED is a monolithic Perl script, and as such, requires a server with Perl installed. It was developed on Perl 5.8.6, and should run properly on any version of Perl 5. It does not use any non-standard modules. The modules currently employed are: DBI (with DBD::mysql driver), CGI, CGI::Carp, Digest::MD5, MIME::Lite, and Net::SMTP. (The last two are only used for sending database backups.)

The server must also accept CGI POST commands, and references the Apache environment variables of REMOTE_ADDR, SCRIPT_URI, and QUERY_STRING.

QED also uses two tables (one each for users and questions) of a SQL-compatible (preferably MySQL) database. It was developed with MySQL 5.0.18 but should work with any recent version of MySQL. Other database software might not share the same query syntax.

If you don't have access to any of the above, or if you have no idea what any of it means, you probably won't be able to run QED yourself. Aegis Questions is offering to host your copy of QED for you if this is the case. Contact us for more information. Otherwise, you are free to use it on your own server. Because it is contained entirely in a single file and two MySQL tables, it should be very simple to deploy.

Client Requirements

On the client side, QED only uses cookies, JavaScript, CGI POST, and CSS, so any computer that can use the Internet reasonably well can use QED. I recommend an updated browser for best results with CSS.

Setting Up QED

Setting up QED doesn't require much knowledge of Perl or MySQL. Assuming you are logged into a Linux server terminal:

  1. Save qed.pl on your server by using wget http://aegisquestions.com/qed/qed.pl to fetch from aegisquestions.com.
  2. Run the command chmod 755 qed.pl to make the program executable. (You might need to give it a different extension or move it to a cgi-bin folder if your hosting service has specific requirements for scripts.)
  3. Open qed.pl with a text editor (like vim) and change the user variables at the top of the program as necessary.
  4. In the MySQL database you specified in the program, run the following queries to create the tables and an admin user for yourself. (Note that the database format is slightly different from that of version 1.0.)
    1. CREATE TABLE users (user CHAR(10), password CHAR(32), flags INT(11)); [where users is the user table]
    2. CREATE TABLE questions (id INTEGER AUTO_INCREMENT PRIMARY KEY, type TEXT, category TEXT, question TEXT, answer TEXT, owner TEXT, round TEXT, comment TEXT); [where questions is the question table]
    3. INSERT INTO users (user, password, flags) VALUES ('myusername', MD5('mypassword'), '1'); [where myusername is your username, mypassword is your password, and 1 gives admin privileges]
  5. Navigate to the program in your browser, log in, and configure the rest from the Admin interface.

Normal User Options (Blue)

If there are more than a couple users, they should probably not all have admin access. Non-admins have their user name written in black at the upper-right, without (Administrator) or (Question Set) after it. All users can access the blue tabs, and they work as follows:

Home

A welcome message and the number of questions the user currently has. You can customize the message yourself.

New

An interface for creating a new question. Type, category, and computational/noncomputational, can be chosen by the user, and there are textboxes for the question and answer. (The available types and categories are loaded in arrays at the top of the program, and can be easily modified.) There is also a comment box with which users can mark their own questions for their own or an admin's attention. Admins can also leave comments on others' questions.

List

To regular users, this provides a table with the type, category, question (first 50 characters), and answer (first 50 characters) of all of the questions created by the user himself. It also provides a search feature that allows questions to be more easily located by restricting the questions shown, or by sorting the table by any of the columns either ascending or descending. Clicking on a row brings up a screen where the user can edit the question they selected. (The Edit screen is very similar to the New screen, except that the question is already loaded, and there is a Delete Question button.)

Admins get a slightly different interface: they can also see ID and Owner columns, and can choose to view others' questions or questions already placed into question sets. (Typically, questions disappear from List view after they're added to sets, in an effort to maintain the stability of sets while they're being compiled.)

About

An About screen.

Administrator Options (Red)

Users designated "Administrators" can access the normal user options in blue, as well as the administrator-only options in red. Admins have their names written in red at the upper-right, followed by (Administrator). There may be any number of administrators, though there should be at least one so that the database can be maintained and question sets can be created. The administrator options work as follows:

Admin

This is the general information screen for administrators. It provides a simple feature to email the database to yourself, as a backup in CSV format. Below this, it displays the number of users and questions in the databases, followed by all of the user-changeable options at the top of the QED script. First is $org_name, the name of the organization, which appears on the login screen and the upper-right corner of the screen in light blue. Next are the MySQL settings, $mysql_database, $mysql_host, $mysql_port, $mysql_user, and $mysql_pass. Database is the name of the MySQL database itself, and host is the address at which the database can be found. The default MySQL port is 3306. User and pass are the login information; the password is hidden on the Admin page for security. $dtbu and $dtbq are the names of the user and question tables in the MySQL database specified above. "users" and "questions" works great for me, but you can change these if there is a name conflict in your database, or if you want to store multiple separate QED installations on a single MySQL server. @types and @categories are arrays containing all the possible question types and categories. The default is Tossup and Bonus for question types, with an Illinois (modified IHSA) category set. None of these options are hardcoded in the program, and can be easily changed by editing the top of the script even without knowledge of Perl.

Users

This screen displays the entire user table in the MySQL database. This screen allows administrators to change normal users to admins, admins to normal users, delete users, and create users. Administrators can also log in as another user instantly by clicking on the link next to their name. The table indicates whether each user is a normal user, administrator, or a question set.

Stats

On this page, admins can see a detailed category breakdown of the questions written by all users or any individual user.

Rounds

On this page, admins can create question sets and select a question set for editing. Deleting question sets is performed through the "Users" page described above.

Question Set Options (Green)

Logins designated "Question Sets" can still access the normal user options in blue, though they are mainly used for the question set options in green. Question Sets have their names written in green at the upper-right, followed by (Question Set). There may be any number of question sets, though they should all be disjoint. The question set options work as follows:

Options

This page allows users to acquire or unacquire questions by their ID numbers. It provides a fast way to acquire questions if you already know which questions you want to acquire; it also is the only way that questions can be unacquired. The meaning of question acquisition will be discussed below.

Stats

This page shows a detailed category and author breakdown of the questions in the question set, either all together, or by packet.

Acquire

Question sets need to "acquire" questions from the database for their use. This screen operates the same way as the "List" view, except that it has a checkmark next to each question. Checking the box and hitting Acquire at the bottom of the page will add that question to the question set for placement in a packet. If you have already hit Acquire on a question but wish to unacquire it, you need to input its ID under "Options." If you already know the IDs of the questions you would like to acquire, you may input them more quickly under "Options" as well.

Organize

After acquiring questions to a question set, those questions have to be divided among packets within that set in the Organize screen. The "Add another" and "Remove last" buttons allow you to add or remove packets from the set. ("Remove last" is small and red because all questions in the packet being removed are moved back to "Unassigned," meaning that it could potentially undo a fair amount of work.)

You start by viewing all questions in "Unassigned," that is, all acquired questions not in a packet. If you want to view the questions in particular packet, you can click on the link for that packet on the right-hand column. Otherwise, check the box next to every question you'd like to move, and select the radio button for the packet you'd like to move them to. Hitting Submit Changes finalizes your selection.

Order

After questions are assigned to packets with Organize, they need to be ordered within that packet. At the top of the screen, there is a list of all the existing packets for that question set. Click on a packet to order the questions in it. Each question will have a box next to it for a number indicating which question position it occupies within the round. These can either be changed manually, or be set sequentially by clicking on the questions in order. (They will be given the "next number" as shown above the table, and this number will be incremented after each click.) Note: Most formats have paired tossups and bonuses. If they are to be output interleaved instead of separately, the first tossup must be numbered 1, and the first bonus 2, etc. QED does not enforce pairing of any kind, and does not understand that they are both part of question 1. (The logical format of the round is managed through Output.)

Output

Once a round is finished, you need to output it in a more useful fashion. This screen shows all the existing packets in the question set, providing links to the prettified versions of each round. QED comes with a standard parser designed for outputting Illinois format. If you need anything different, you need to modify the parser itself. The parser code is located in the output_question sub at the bottom of qed.pl. It is distinct from the rest of the code, and is heavily commented. The questions themselves (along with their placement data) are passed to the subroutine, and the subroutine is well-separated from the rest of QED. Making your own or editing the provided one does require some knowledge of Perl.


QED, Question Editing Database is © Carlo Angiuli, 2006-2007.