1: %$Id: process.tex,v 3.1 2008/03/23 18:04:51 boris Exp $
2: %$Log: process.tex,v $
3: %Revision 3.1 2008/03/23 18:04:51 boris
4: %documentation update
5: %
6: %Revision 3.0 2008-03-23 17:50:50 boris
7: %Added Lev's corrections
8: %
9: %Revision 2.7 2005/02/20 03:24:43 boris
10: %Wrote readme
11: %
12: %Revision 2.6 2005/01/24 03:28:53 boris
13: %Re-added
14: %
15: %Revision 2.4 2002/02/04 16:53:15 boris
16: %Added numletters
17: %
18: %Revision 2.3 2002/02/04 16:52:37 boris
19: %Added num
20: %
21: %Revision 2.2 2002/02/04 15:43:34 boris
22: %Added new features
23: %
24: %Revision 2.1 2002/02/04 15:04:53 boris
25: %Started anew
26: %
27: %
28: %Revision 1.9 1998/11/29 21:56:12 boris
29: %Добавил благодарности
30: %
31: %Revision 1.8 1998/11/29 21:50:48 boris
32: %Добавил изменения в формате.
33: %
34: %Revision 1.7 1998/11/17 22:48:33 boris
35: %Отказался от попытки включить программу в файл -- не совместимы с кои-8
36: %:(
37: %
38: % Revision 1.6 1998/11/17 17:02:51 boris
39: % Добавил регистрационные номера в формат.
40: %
41: % Revision 1.5 1998/11/15 04:52:25 boris
42: % Написал интерфейс.
43: %
44: %Revision 1.4 1998/11/15 03:38:25 boris
45: %Написал раздел "Форматы"
46: %
47: %Revision 1.3 1998/11/15 02:35:43 boris
48: %Исправил заголовки
49: %
50: \documentclass{article}
51: %
52: % Руссификация. Бывает и новее...
53: %
54: \usepackage[koi8-r]{inputenc}
55: \usepackage[russian]{babel}
56: \usepackage{t1enc}
57: \usepackage{amsmath}
58: \newcommand{\prog}[1]{\ensuremath{\text{{\textsl{#1}}}}}
59:
60:
61:
62: \begin{document}
63:
64: \title{Программа для обработки писем в ИГП и ИЧБ}
65: \author{Boris Veytsman, \texttt{borisv@lk.net}}
66: \date{Март 2008}
67: \maketitle
68: \thispagestyle{empty}
69: \tableofcontents
70:
71: \section{Введение}
72:
73: С тех пор, как количество команд в IGP превысило первый десяток,
74: подведение итогов тура стало тяжким бременем для дежурной
75: команды. Прочесть невероятное количество писем, извлечь ответы,
76: составить таблицу, да еще Собрание Сочинений\dots{} На это вполне может
77: уйти целиком рабочий день. Именно с этой целью по предложению Якова
78: Зайдельмана написана эта программа. Позднее эта программа
79: переписывалась при изменении регламента соревнований, добавлении ИЧБ и
80: т.д.
81:
82: Идея состоит в следующем. Самый важный этап в деятельности дежурной
83: команды---решить, заслуживает ли данный ответ плюса или минуса. Это мы
84: автоматизировать не можем. Но это автоматизировать и не надо. А вот
85: все остальное автоматизировать можно и нужно. Значит, программа должна
86: делать следующее:
87: \begin{enumerate}
88: \item Извлекать ответы из файла с письмами команд
89: \item Записывать их в файл, где все ответы были бы рядом, и было бы
90: оставлено место для оценки
91: \item Читать этот файл \emph{после} того, как дежурная команда
92: проставит оценки и составлять таблицу и собрание сочинений.
93: \item Время от времени создавать список команд, чьи ответы уже
94: получены, и слать на информационный лист.
95: \end{enumerate}
96: Необходимо учесть еще несколько важных обстоятельств:
97: \begin{enumerate}
98: \item Команда может прислать несколько писем. В этом случае более
99: позднее письмо считается более авторитетным, чем более раннее. Мы
100: будем предполагать для простоты, что более поздние письма находятся
101: в файле с письмами позже более ранних. Дело дежурной
102: команды---обеспечить такой порядок писем (может быть, вручную
103: корректируя взбрыки e-mailа).
104: \item Дежурная команда может оценивать ответы параллельно их
105: получению. Поэтому нельзя ``забывать'' старые оценки, читая новые.
106: \item В последнее время в ИГП и ИЧБ принято два зачёта: спринт и
107: стайер. При этом соблюдаются следующеи правила:
108: \begin{enumerate}
109: \item Если команда сдала ответ в спринте и не сдала ответ в стайере,
110: учитывается ответ, сданный в спринте.
111: \item При равенстве количества ответов в стайере победу в стайере
112: одерживает команда, показавшая лучший результат в спринте.
113: \end{enumerate}
114: \end{enumerate}
115:
116:
117: \section{Форматы}
118:
119:
120: \subsection{Письма с ответами}
121:
122: \begin{enumerate}
123: \item Каждое письмо содержит в строке Subject: строку в латиннице:
124: \begin{verbatim}
125: Subject: Otvety komandy "Nazvanie_komandy", NNN
126: \end{verbatim}
127: При этом название команды не должно содержать кавычек, а
128: \prog{NNN}---регистрационный номер команды. Если у команды еще нет
129: регистрационного номера, допускается его НЕ указывать
130: \item В теле письма может быть все, что угодно, вплоть до строки
131: \begin{verbatim}
132: *** "Название_команды", NNN
133: \end{verbatim}
134: При этом название команды может быть как в латиннице, так и в
135: кириллице, но быть \emph{одинаковым} для всех писем от данной команды
136: \item Каждый ответ имеет следующую структуру:
137: \begin{verbatim}
138: #NN. Текст ответа
139: Текст ответа
140: ...
141: \end{verbatim}
142: Здесь \prog{NN}---номер вопроса, а за ним следует текст ответа
143: (возможно, из нескольких строк)
144: \item Ответы заканчиваются строкой
145: \begin{verbatim}
146: ***
147: \end{verbatim}
148: После этой строки может следовать все, что угодно.
149: \item В тексте письма не рекомендуется употребление символов
150: ``\prog{\#}'' и ``\prog{*}'' и \emph{запрещается} их
151: употребление первыми в строке (или после пробелов).
152: \end{enumerate}
153:
154: \paragraph{Пример:}
155: \begin{verbatim}
156: Date: 12 Nov 98 18:31:53 MSK
157: From: Aleksandr Ivanov <ivanov@boga.net>
158: To: catamaran@hal.plmsc.psu.edu
159: Subject: Otvety komandy "Stop", 222
160:
161: Здравствуйте, уважаемые игроки Катамарана!
162:
163: Большое спасибо за вопросы.
164:
165: *** "Стоп", 222
166: #1. Сид
167: #2. Мышка-наружка
168: #3. Ллойд-Джордж
169: #4. В жирафа
170: #5. Шалтай-Болтай, Барклай де Толлли
171: #6. У Геркулесовых столпов.
172: #7. В коров
173: #8. Глокая куздра
174: #9. Александр Македонский и Гордий I
175: #10. Поставить точку над i.
176: #11. Кольцо Нибелунгов, Вагнер, Мефистофель
177: #12. Венера
178: ***
179:
180: Капитан команды "Стоп"
181: Александр Иванов
182: \end{verbatim}
183:
184:
185: \subsection{Формат файла с результатами}
186:
187: Файл с результатами состоит из ответов. Каждый ответ имеет следующую
188: структуру:
189: \begin{enumerate}
190: \item Заголовок
191: \begin{verbatim}
192: #NN. Frequency: f. Score: s
193: \end{verbatim}
194: Здесь \prog{NN}---номер вопроса, а \prog{s}---оценка, один из
195: трех символов: \prog{+}, \prog{-} или \prog{?}.
196: \item Собственно текст ответа:
197: \begin{verbatim}
198: Текст ответа
199: Текст ответа
200: ...
201: \end{verbatim}
202: При этом каждая строка текста начинается с двух пробелов.
203: \item В конце всех ответов идет строка из трех звездочек:
204: \begin{verbatim}
205: ***
206: \end{verbatim}
207: \end{enumerate}
208:
209:
210: \subsection{Формат таблицы результатов}
211:
212: У таблицы результатов есть три формата.
213: \begin{enumerate}
214: \item Длинный формат
215: \begin{verbatim}
216: N 1 2 3 4 5 6 7 8 9 10 11 12 О Р КОМАНДА
217: 111 + + + + + + + + + + + + 12.04 359 Марсиане
218: 436 + + + + + + + + + + + + 12.02 359 Venera II
219: [...]
220: \end{verbatim}
221:
222: \item Промежуточный формат
223: \begin{verbatim}
224: N 12345 67890 12 О Р КОМАНДА
225: 111 +++++ +++++ ++ 12.04 359 Марсиане
226: 436 +++++ +++++ ++ 12.04 359 Venera II
227: [...]
228: Рейтинг
229: 1 2 3 4 5 6 7 8 9 10 11 12
230: 24 21 34 24 41 43 18 31 26 32 36 29
231: \end{verbatim}
232:
233:
234: \item Короткий формат
235: \begin{verbatim}
236: N 123456789012 О Р КОМАНДА
237: 111 ++++++++++++ 12.04 359 Марсиане
238: 436 ++++++++++++ 12.04 359 Venera II
239: [...]
240: Рейтинг
241: 1 2 3 4 5 6 7 8 9 10 11 12
242: 24 21 34 24 41 43 18 31 26 32 36 29
243: \end{verbatim}
244: \end{enumerate}
245: В последних графах стоит полное число взятых вопросов и суммарный
246: рейтинг соответственно. В последней строке таблицы---рейтинги
247: вопросов. В коротком формате вместо строки с рейтингом отдельная
248: таблица ``Рейтинг''. В графе ``О'' стоят набранные командой очки в
249: данном зачёте (до десятичной точки) и в предыдущем (после точки).
250:
251: При печати незачетных вопросов взятый вопрос помечается буквой
252: \prog{X}, а невзятый, как обычно, \prog{-}.
253:
254: \subsection{Формат собрания сочинений}
255:
256: Собрание ответов на каждый вопрос имеет следующую структуру:
257: \begin{enumerate}
258: \item Заголовок раздела
259: \begin{verbatim}
260: ВОПРОС NN:
261: \end{verbatim}
262: \item По два заголовка подразделов:
263: \begin{verbatim}
264: ЗАСЧИТАНЫ ОТВЕТЫ:
265: \end{verbatim}
266: и
267: \begin{verbatim}
268: НЕ ЗАСЧИТАНЫ ОТВЕТЫ:
269: \end{verbatim}
270: \item Каждый ответ имеет формат:
271: \begin{verbatim}
272: s Текст ответа
273: Текст ответа
274: ... [f]
275: \end{verbatim}
276: Здесь \prog{s}---один из символов \prog{+} или \prog{-},
277: \prog{f}---частота ответа, которая печатается только если она не равна
278: единице.
279: \end{enumerate}
280:
281:
282:
283: \section{Пользовательский интерфейс}
284:
285:
286: \subsection{Файл настроек}
287: \label{sec:conf}
288:
289: Настройки программы хранятся в файле \prog{parameters.pl}. Пример
290: этого файла приведен ниже:
291: \begin{verbatim}
292: # В этом файле собраны ЛОКАЛЬНЫЕ параметры -- "настройки"
293: #
294: # Количество зачётов
295: $ROUNDS=2;
296:
297: ###############################################################
298: # Следующие настройки индивидуальны для каждого раунда, начиная
299: # с первого
300: ###############################################################
301:
302: # Первый раунд
303:
304: # Название раунда
305:
306: $NAME[1]="Спринт";
307:
308: # Вопросы раунда
309:
310: $MINQUEST[1]=1;
311: $MAXQUEST[1]=12;
312:
313: # Файлы раунда. Следующий перекрывает предыдущий.
314: # Список заключён в квадратные скобки, отдельные файлы разделены ЗАПЯТЫМИ.
315: # $FILES[1] = [ "sprint.mail", "sprint-extra.mail" ];
316: #
317: # ВНИМАНИЕ: формат этого параметра изменился с предыдущей версии!
318:
319: $FILES[1]= [ 'sprint.mail' ];
320:
321: # Внезачётные вопросы раунда. В квадратных скобках, номера разделены ЗАПЯТЫМИ.
322: # Во втором раунде эти вопросы тоже будут вне зачёта (но можно будет и
323: # учесть, см. ниже описание $NOCOUNT[2]).
324: # $NOCOUNT[1] = [];
325: # $NOCOUNT[1] = [ 2, 3, 4 ];
326:
327: $NOCOUNT[1]= [];
328:
329:
330: # Второй раунд
331:
332: # Название раунда
333:
334: $NAME[2]="Стайер";
335:
336: # Вопросы раунда
337:
338: $MINQUEST[2]=1;
339: $MAXQUEST[2]=18;
340:
341: # Список заключён в квадратные скобки, отдельные файлы разделены ЗАПЯТЫМИ.
342: # $FILES[2] = [ 'predvarit.mail', 'osnovn.mail' ];
343: #
344: # ВНИМАНИЕ: формат этого параметра изменился с предыдущей версии!
345:
346: $FILES[2]= [ 'stayer.mail' ];
347:
348: # Внезачётные вопросы в этом раунде. В квадратных скобках, через ЗАПЯТУЮ.
349: # Этот список ДОБАВЛЯЕТСЯ к уже перечисленным в $NOCOUNT[1]. Однако
350: # если вы хотите исключить какой-то из ранее указанных вопросов (например,
351: # в гипотетической ситуации "вопрос номер 5 был исправлен слишком поздно,
352: # поэтому в Спринте не учитывается, а для Стайера используется"), то
353: # укажите его номер со знаком минус: "3 -5 6"
354: # $NOCOUNT[2] = [];
355: # $NOCOUNT[2] = [ 3, -5, 6 ];
356:
357: $NOCOUNT[2]= [];
358:
359:
360: #########################################################
361: # Теперь общие настройки
362: #########################################################
363:
364:
365: #
366: # Адрес листа z-info
367: #
368: $address = 'z-info@chgk.info';
369: #$address="boris";
370: #
371: # Обратный адрес дежурной команды и ее название
372: #
373: $fromaddress = 'Boris Veytsman <borisv@lk.net>';
374: $DK = '"Дракоша"';
375: #
376: # $date -- системная процедура, которая вычисляет МОСКОВСКОЕ
377: # время. В Линуксе zdump это делает хорошо. В других операционных
378: # системах надо как-то исхитряться... На самый худой конец, используйте
379: # $date='';
380: #
381: $date = "export TZ='Europe/Moscow'; date";
382:
383: #
384: # Процедуры, которые печатают заголовок и конец мейла-напоминания
385: #
386: sub printheader
387: {
388: print <<"END";
389: To: $address
390: From: $fromaddress
391: Subject: Svodka
392: MIME-Version: 1.0
393: Content-type: text/plain; charset=koi8-r
394: Content-Transfer-Encoding: 8bit\n
395:
396: Уважаемые знатоки!
397:
398: С вами говорит робот команды $DK
399:
400: END
401: print "На момент ", `$date`, "в зачёте '$NAME[$round]' сданы ответы от команд:\n\n";
402: }
403:
404:
405: sub printfooter
406: {
407: print <<END;
408:
409: --
410: Good luck
411:
412: -Robot
413: END
414:
415: }
416: \end{verbatim}
417:
418:
419: \subsection{Основная программа}
420:
421: Дежурный по туру складывает все письма в файл. Время от времени он
422: запускает команду
423: \begin{verbatim}
424: processmail.pl [-d] [-t table_file] [-o results]
425: \end{verbatim}
426: где
427: \begin{description}
428: \item[table\_file] файл с предыдущими оценками (по умолчанию
429: отсутствует),
430: \item[results] файл с результатами (по умолчанию---стандартный
431: выход).
432: \end{description}
433:
434: В этом файле вручную расставляются плюсы и минусы.
435:
436: Флаг \prog{-d} означает ``Debigging mode''. В этом режиме программа
437: печатает массу дополнительной информации.
438:
439: \subsection{Сводка}
440:
441: Время от времени дежурный запускает программу
442: \begin{verbatim}
443: reminder.pl [-r номер_раунда]
444: \end{verbatim}
445: Она генерирует список команд, которые имеются в файле с таблицей (по
446: умолчанию---стандартный вход), и посылает его на z-info.
447:
448:
449: \subsection{Результаты}
450:
451: Итоговая таблица и собрание сочинений генерируются программами
452: \begin{verbatim}
453: createtable.pl [-d] [-s|-m] [-t table_file] [-o results]
454: collection.pl [-d] [-t table_file] [-o results]
455: \end{verbatim}
456: Ее ключи имеют то же смысл, что и у программы \prog{processmail.pl}.
457: Флаг \prog{-s} означает выбор короткой формы таблицы, а флаг \prog{-m}
458: означает выбор промежуточной формы.
459:
460: \section{Программа}
461:
462:
463: \subsection{Внутреннее представление данных}
464:
465: Сведения о командах хранятся в хэше \prog{\%teams} со следующими
466: полями:
467: \begin{description}
468: \item[ключ] название команды
469: \item[элемент] ссылка на анонимный хэш \prog{\%teams\{\$team\}} с
470: полями:
471: \begin{description}
472: \item[\prog{regnum}] регистрационный номер
473: \item[[\prog{numletters}] количество писем с ответами
474: \item[\prog{answers}] ссылка на массив из ответов
475: \item[\prog{score}] общий итог
476: \item[\prog{rating}] общий рейтинг
477: \end{description}
478: \end{description}
479:
480: Сведения о вопросах хранятся в массиве \prog{\%answers}. Его
481: элементы---ссылки на анонимные хэши. Ключи в хэшах---тексты ответов,
482: а элементы---опять таки ссылки на хэши следующего содержания:
483: \begin{description}
484: \item[\prog{score}] \prog{+}, \prog{-} или \prog{?}
485: \item[\prog{teams}] хэш команд, давших этот ответ
486: \end{description}
487:
488:
489:
490: \section{Благодарности}
491:
492: Я благодарен Якову Зайдельману, Льву Горенштейну, Алексу Покрасу и
493: Дмитрию Рубинштейну за помощь в разработке этой программы. Версия~3
494: программы (поддержка незачетных вопросов и промежуточного формата
495: таблицы) была написана Львом Горенштейном.
496:
497: \end{document}
498:
499: %%% Local Variables:
500: %%% mode: latex
501: %%% TeX-master: t
502: %%% End:
503:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>