Contest Arbitrator GIT

   ***** Contest Arbitrator ("Судья Соревнований") *****
                    версия 0.3.2

               РУКОВОДСТВО ПОЛЬЗОВАТЕЛЯ


 Программа Contest Arbitrator (contesta) предназначена для выполнения судейства
радиолюбительских соревнований. Изначально программа была написана по заказу и для
облегчения судейства мероприятий клуба RU-QRP. Открытые исходные коды, а также
модульная структура программы contesta позволяет использовать ее для судейства и
любых других соревнований.

Программа contesta находится в стадии разработки и тестирования.
Любые замечания и предложения по ее улучшению принимаются по адресу: ur4mck@gmail.com


I, УСТАНОВКА

 На данный момент программа contesta работает на платформах Linux и Windows (Проверено
на Linux Debian, CentOS Linux, Xubuntu и Microsoft Windows XP SP 2).

Если Вы собираете программу из исходных кодов, обратитесь за инструкцией к файлу INSTALL
внутри директории с исходным кодом.

Если Вы используете готовые исполняемые файлы, то следуйте инструкциям ниже.

Программа contesta является самодостаточной. Это означает, что для ее работы требуется
только операционная система и минимальный объем оперативной памяти.

Для запуска программы на платформе Win32 требуется Windows 95 или выше.
Для запуска программы на платформе Linux требуется библиотека libc-2.5 или выше.

Программа contesta не требует установки, она может работать из любой директории.
Однако, для упрощения работы с ней рекомендуется скопировать все файлы в специально
созданную для программы директорию на локальном диске, например, в C:\contesta

Таким образом, в этой директории у Вас будут находиться:

  contesta.exe           - программа Contest Arbitrator
  /conf                        - примеры конфигурационных файлов для соревнований RU-QRP

 Эти файлы откомпилированы для операционной системы Windows. Если Вам они нужны для Linux,
то Вам необходимо откомпилировать программу самостоятельно (см. инструкции в файле INSTALL).

 Проверьте, что программа запускается на Вашем компьютере. Для этого выполните следующие действия:

  1. Откройте командную строку (Пуск -> Выполнить -> в поле "Открыть" напишите cmd)

  2. В появившемся черном окне перейдите в директорию, в которую Вы скопировали .exe файлы
     программы contesta (в нашем примере это "C:\contesta"). Для этого в командной строке наберите:

      cd C:\contesta

     и нажмите [Enter]. После этого Вы должны увидеть, что сменилась текущая директория
     (последняя строка в консоли будет такой:

      C:\contesta>

  3. Теперь попробуйте запустить программу с ключом "-h". Так Вы увидите доступные опции
     программы и убедитесь, что программа запускается на Вашем компьютере. Для этого
     в командной строке наберите:

      contesta -h

     и Вы увидите краткую справку по опциям программы:

      c:\contesta>contesta -h
      Contest Arbitrator version 0.3.2
       (c) 2009-2013 by Dmitry Gorokh, UR4MCK
       This program is FREEWARE

      Usage: contesta [options] [files]
       Available options are:
         -h           - Show usage information
         -c <file>    - Specify configuration file
         -d <path>    - Specify directory with log files (default is current directory)
         -o <file>    - Specify output file with results (default is stdout)
         -r <path>    - Specify directory for log analyzis reports (default is ./reports)
         -u <path>    -Specify directory for UBN files (default is ./ubn)

      Please report bugs to ur4mck@gmail.com

      c:\contesta>

II. КОНФИГУРАЦИЯ

 Программа Contest Arbitrator является консольной программой и требует указания параметров
того или иного соревнования в конфигурационном файле.

 Файл конфигурации представляет собой обычный текстовый файл в удобочитаемым для человека формате.
Пример файлов конфигурации для вы найдете в директории /conf.

 Прежде чем начать судейство нового соревнования, нужно обязательно создать для него файл
конфигурации. Для этого можно просто скопировать файл-пример conf/general.conf в другой файл и
отредактировать его.

 Ниже приведено краткое описание формата файла конфигурации.


      ОПИСАНИЕ ФОРМАТА ФАЙЛА КОНФИГУРАЦИИ

 Файл конфигурации состоит из пары "имя параметра" и "значение", а также из комментариев к ним.
Каждый параметр, определяющий соревнование, начинается с имени параметра, после чего через пробел
указывается его значение. Числовые значения указываются как есть (без кавычек или скобок),
строковые параметры (нечисловые или такие, в которых присутствует пробел) ОБЯЗАТЕЛЬНО указываются
в кавычках. Символ '#' (без кавычек) означает, что до конца строки написан комментарий и этот текст
игнорируется программой. В файле конфигурации могут присутствовать пробелы и табуляторы в любых
местах, они, также как и пустые строки, игнорируются программой contesta. Описанный формат совместим
с принятым в операционных системах семейства *nix и мире OpenSource.

 Откройте в текстовом редакторе файл conf/general.conf и посмотрите, какие параметры там присутствуют.

 Параметр "name" - определят название соревнований. Это название фигурирует в результатах анализа
                   отчетов и итоговой рейтинговой таблице.
 Пример:
        name "RU-QRP Wake-Up! Sprint"


 Параметр "id" - определяет условный идентификатор соревнований. Он используется внутри программы
                 contesta для выбора того или иного контестового модуля.
                 Перечень идентификаторов указан в комментариях в файле conf/general.conf:
 Пример:
        id 1


 Параметр "start" - указывает на начальную дату и время соревнований. Формат такой:
                    "год-месяц-день часыминуты". Время указывается в UTC.
 Пример:
        start "2009-06-06 0600"


 Параметр "end" - указывает на конечную дату и время соревнований. Формат такой же, как и для "start".
                  Обратите внимание, что конечная дата и время указывает следующую минуту сразу
                  после последней минуты соревнований. Так, если в конфигурационном файле указано
                  окончание соревнований в 2009-06-06 0800, то последняя минута соревнований будет
                  2009-06-06 0759 (точнее время - 07:59:59)
 Пример:
        end "2009-06-06 0800"


 Параметр "rounds" - определяет количество туров (раундов) в соревнованиях. Если раунды не
                     используются, удалите этот параметр из файла конфигурации или укажите его
                     равным 1 или 0. Все раунды делят время проведения соревнований на равные интервалы.
 Пример:
        rounds 4


 Параметр "max_dt" - устанавливает для соревнований максимально допустимое время расхождения во времени в
                     отчетах участников. Время указывается в секундах. Так, 3-х минутное допустимое
                     расхождение будет иметь значение 180 (сек).
 Пример:
        max_dt 180


 Параметр "band_list" - определяет перечень допустимых в соревновании радиолюбительских диапазонов.
                        Список состоит из названий диапазонов перечисленных через запятую.
                        Допустимые диапазоны: 160M, 80M, 40M, 20M, 15M, 10M, 6M, 2M, 222, 432,
                                              902, 1.2G, 2.3G, 3.4G, 5.7G, 10G, 24G, 47G, 75G,
                                              119G, 142G, 241G, Light, ALL.
                        Список диапазонов соответствует описанию формата Cabrillo v3.
 Пример:
        band_list "40M,20M"


 Параметр "mode_list" - также как и band_list, этот параметр определяет список допустимых в
                        соревновании режимов работ. Допустимые режимы:
                        CW, SSB, DIGI, RTTY, MIXED, ALL.
 Пример:
        mode_list "CW"


 Параметр "signature" - для обеспечения возможности ручного редактирования судьей отчетов участников
                        требуется указание этого параметра. Эта своеобразная подпись судьи, которая
                        должна совпадать со значением, вручную добавляемого в отчет тэга "SIGNATURE:".
                        Подписью может являться любая строка символов. Редактирование отчетов с использованием
                        подписи может потребоваться, когда судья решает, что какое-либо конкретное QSO в
                        отчете требуется отметить для того, чтобы программа contesta форсировала решение 
                        засчитывать или нет это QSO для очков и(или) для множителя. Подпись с тэгом "SIGNATURE:" 
                        (без кавычек) в отчете может располагаться в любом месте между тэгами
                        "START-OF-LOG:" и "END-OF-LOG:".

                        Для отметок QSO в отчетах определены следующие символы (без кавычек):

                                '+' - засчитывать QSO для очков
                                '-' - не засчитывать QSO для очков
                                '*' - засчитывать QSO для множителя
                                '%' - не засчитывать QSO для множителя

                        Допускается указание нескольких отметок сразу (без пробелов), но не более двух.
                        Например, '+*' (без кавычек) означает не делать автоматическую проверку этого
                        QSO, а сразу засчитывать его для очков и для множителя.
                        Отрицательные отметки ('-', '%') имеют приоритет над положительными. Так, если
                        будет указана отметка '+-' или '-+' это будет означать не засчитывать очков.

                        Отметки указываются в самом конце значения тэга "QSO:"
                        Примеры:

                          QSO: 14000 CW 2009-06-06 0749 DL9ZP         599 040  CBS  RX3PR        559 042  AA/9 +
                          QSO: 14000 CW 2009-06-06 0757 DL9ZP         599 041  PR   UA1AFT        599 052  JMG  -*

                        В первом примере - засчитывать QSO без проверки. Во втором - не засчитывать QSO для
                        очков, но засчитывать для множителя.

                        При отсутствии тэга "SIGNATURE:" в отчете с отметками они не распознаются программой.
                        Если в отчете присутствует тэг "SIGNATURE:" со значением отличным от подписи в
                        конфигурационном файле, программа предупреждает о мошенничестве выводом сообщения
                        в результат анализа.
 Пример:
        signature "UR4MCK signature"


 Параметр "skip_rst_snt" - если значение равно 1, то при перекрестной проверке не сверяется отправленный RST.
                           Если значение равно 0 или отсутствует в файле конфигурации, то проверка осуществляется.

 Пример:
        skip_rst_snt 1


 Параметр "skip_rst_rcv" - аналогично:
                                0 - проверять принятый RST
                                1 - не проверять принятый RST
 Пример:
        skip_rst_rcv 0


 Параметр "skip_num_snt" - аналогично:
                                0 - проверять отправленный порядковый номер
                                1 - не проверять отправленный порядковый номер
 Пример:
        skip_num_snt 1


 Параметр "skip_num_rcv" - аналогично:
                                0 - проверять принятый порядковый номер
                                1 - не проверять принятый порядковый номер
 Пример:
        skip_num_rcv 0


 Параметр "skip_chk_snt" - аналогично:
                                0 - проверять отправленный контрольный номер (или слово)
                                1 - не проверять отправленный контрольный номер (или слово)
 Пример:
        skip_chk_snt 0


 Параметр "skip_chk_rcv" - аналогично:
                                0 - проверять принятый контрольный номер (или слово)
                                1 - не проверять принятый контрольный номер (или слово)
 Пример:
        skip_chk_rcv 0


 Параметр "uniq_mult" - управляет подсчетом множителей:
                                0 - все множители
                                1 - уникальные множители
 Пример:
        uniq_mult 1


 Параметр "strict_eval" - Определяет используется ли строгий режим судейства:
                                0 - обычный режим
                                1 - строгий режим
 Пример:
        strict_eval 0

 Параметр "allow_dupes" - разрешает повторные связи:
                                0 - Повторные связи запрещены и обозначаются ошибкой
                                1 - Повторные связи разрешены
 Пример:
        allow_dupes 1

 Параметр "report_dir" - директория для размещения файлов с результатами предварительного анализа
 Пример:
       report_dir "reports"

 Параметр "ubn_dir" - директория, в которой будут размещаться UBN-файлы
 Пример:
         ubn_dir "ubn"

 Параметр "log_emails" - список e-mail адресов, на которые следует высылать исправленные отчеты
 Пример:
         log_emails "contest@qrp.ru, rw3ai@mail.ru"

 Параметр "cfm_unresolved" - задает минимальное кол-во непроверенных QSO, чтобы засчитать их как
                                                            правильные QSO и для множителя.
                         Минимальное: 2
                         По-умолчанию: 2
 Пример:
         cfm_unresolved 3

 Параметр "search_tags" - определяет нужно ли пытаться искать подходящие теги для тех из них, которые
                                                     были написаны в отчете с ошибкой. Работает только при ignore_tags 0.
                                    0 - не искать и не исправлять ошибочные теги
                                    1 - искать и пытаться исправлять ошибочно написанные или недопустимые теги
 Пример:
          search_tags 0

 Параметр "ignore_tags" - игнорировать любые ошибки в неизвестных тегах.
                                   0 - не игнорировать неизвестные теги (сообщать предупреждение)
                                   1 - игнорировать неизвестные или ошибочно написанные теги
 Пример:
         ignore_tags 1

 Параметр "www" - URL (ссылка) на ресурс в сети, где публикуется информация по контесту
 Пример:
         www "http://qrp.ru/contest"


 Другие параметры конфигурационного файла появятся по мере необходимости.

 Теперь, когда Вы знакомы с параметрами конфигурации программы contesta, создайте (или отредактируйте)
файл конфигурации для своего соревнования. Обязательными параметрами являются:

   name, id, start, end, max_dt, band_list, mode_list.

 Разместите Ваш файл конфигурации в одной директории с программой contesta. (На самом деле этот файл
может находиться где угодно, но, размещая его рядом с программой Вы упрощаете указание пути к нему).


III. СУДЕЙСТВО СОРЕВНОВАНИЙ

 После того, как Вы познакомились с программой и ее конфигурацией, можно приступать к главной цели -
выполнению автоматического судейства. Естественно, что для судейства требуются отчеты участников.
 На данный момент поддерживаются отчеты в формате Cabrillo (v2, v3, Ermak). Желательно (но необязательно)
чтобы отчеты располагались в одной директории. Имена отчетов и их расширения могут быть любыми.
Перечень отчетов указывается программе contesta в командной строке.

 В качестве примера создайте директорию logs и скопируйте туда отчеты участников (например, за Wake-Up).
Теперь снова вернитесь к командной строке и вызовите программу contesta с такими параметрами:

    contesta -c conf/wakeup.conf -d logs/ -o results.txt

 Как видно, Вы передаете программе файл конфигурации wakeup.conf с помощью опции '-c', указываете на
директорию с отчетами с помощью опции '-d' и указываете файл для записи результатов с помощью
опции '-o'. Если разные отчеты хранятся в разных местах, их нужно перечислять в командной строке через пробел.

 После нажатия на [Enter] Вы запускаете судейство программы. Все результаты анализа отчетов, а также
итоговый рейтинг записываются в файл указанный в опции '-o' (results.txt в этом примере). О критических
ошибках и предупреждениях программа contesta сообщает в командную строку. Остальные сообщения направляются
в файл с результатами.

 Откройте файл результатов в текстовом редакторе и ВНИМАТЕЛЬНО просмотрите все результаты. Возможно, какие-то
отчеты содержат ошибки и нуждаются в ручной правке. По окончании исправления ошибок в отчетах, снова
запускайте программу contesta как указано выше. Имеет смысл держать оригинальные и правленые отчеты
раздельно.

 В зависимости от конфигурации того или иного контеста, программа судейства может создавать файлы с результатами
анализа каждого отчета в отдельности. По-умолчанию результаты предварительного анализа размещаются в
директории ./reports, а UBN-файлы - в директории ./ubn. Эти файлы могут рассылаться участникам при необходимости.

 В самом конце файла результатов располагается итоговая таблица соревнований. Каждый раз, когда программа
судейства запускается с новым набором отчетов, эти результаты динамически обновляются. Имейте ввиду,
что если для каких-то QSO невозможно рассчитать кол-во очков, то они не входят в итоговую таблицу.
По этой же причине, когда получены не все отчеты, для некоторых участников в таблице количество очков
может быть равным нулю.

 Итоговая таблица результатов соревнований после ее проверки главным судьей подлежит публикации
в официальных источниках.


IV. РЕШЕНИЕ ПРОБЛЕМ

 Работа над программой Contest Arbitrator продолжается. Ваша помощь в тестировании и улучшении программы
обязательно будет полезна разработчику. Каждая новая версия проходит тестирование в разных условиях,
однако без всестороннего испытания разными людьми с разными входными данными нельзя гарантировать
полное отсутствие ошибок и правильность результатов соревнований. Если Вы обнаружили ошибку, то повторите
и опишите все действия с программой.  Также не забудьте указать какую версию программы contesta Вы используете,
какая у Вас установлена операционная система, какой тип процессора и количество оперативной памяти.
Обязательно распишите по шагам, какие действия приводят к возникновению ошибки и как, по Вашему мнению,
должна вести себя программа. Любая подробная информация может оказаться полезной в деле скорейшего
устранения ошибок!

V. ОБРАТНАЯ СВЯЗЬ

 По любым вопросам относительно программы Contest Arbitrator Вы можете связаться с автором
по адресу: ur4mck@gmail.com

 Приветствуются сообщения об ошибках и предложения по улучшению программы.

 Программа Contest Arbitrator выпускается под свободной лицензией GNU GPL v3.
 Если Вы собираетесь использовать исходный код программы Contest Arbitrator в своем продукте, то
ссылка на проект Contest Arbitrator обязательна. Также обязательно условие чтобы Ваш новый продукт
предоставлялся с исходными кодами по лицензии GNU GPL.

 Программа Contest Arbiitrator является свободной (freeware) и Вы можете свободно копировать и
изменять ее в соответствии с лицензией GNU GPL. Подробная информация о GNU GPL на сайте:
http://www.gnu.org/licenses/gpl.html

-----
Written by UR4MCK
06.09.2009
Revision: 11.03.2015