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