diff --git a/.github/jobs/syntax.sh b/.github/jobs/syntax.sh index 2d7aabfbc1..287c75981c 100755 --- a/.github/jobs/syntax.sh +++ b/.github/jobs/syntax.sh @@ -8,7 +8,6 @@ $MYDIR/syntax-check make configure ./configure --with-baseurl='http://localhost/domjudge/' --with-domjudge-user=root -make install-docs make clean cd doc/manual/ diff --git a/Makefile.global b/Makefile.global index a6d55daf80..d703e4a157 100644 --- a/Makefile.global +++ b/Makefile.global @@ -23,16 +23,8 @@ ifneq ($(wildcard $(TOPDIR)/paths.mk),) include $(TOPDIR)/paths.mk endif -# We should build docs if it not explicitly disabled and we're not -# running "make maintainer-conf" or "make inplace-conf": +# We should build docs if it is explicitly enabled BUILD_DOCS=no -ifneq ($(DOC_BUILD_ENABLED),no) -ifneq ($(MAKECMDGOALS),maintainer-conf) -ifneq ($(MAKECMDGOALS),inplace-conf) -BUILD_DOCS=yes -endif -endif -endif export BUILD_DOCS # Determine revision info: diff --git a/configure.ac b/configure.ac index 4e1d56e153..527b0c80f0 100644 --- a/configure.ac +++ b/configure.ac @@ -259,15 +259,13 @@ AC_PROG_LN_S AC_PROG_MAKE_SET AC_PROG_MKDIR_P -# Check option to build documentation. This option is provided to -# allow disabling it. AC_ARG_ENABLE(doc-build,AS_HELP_STRING([--enable-doc-build], -[enable building documentation (default: yes).])) +[enable building documentation (default: no).])) -if test "x$enable_doc_build" = "xno"; then - AC_SUBST(DOC_BUILD_ENABLED,[no]) -else +if test "x$enable_doc_build" = "xyes"; then AC_SUBST(DOC_BUILD_ENABLED,[yes]) +else + AC_SUBST(DOC_BUILD_ENABLED,[no]) fi # See 'man feature_test_macros' under Linux: @@ -330,12 +328,7 @@ echo " * webserver group.....: $WEBSERVER_GROUP" echo "" echo " * website base URL....: $BASEURL" echo "" -echo -n " * documentation.......: AX_VAR_EXPAND($domjudge_docdir)" -if test "x$DOC_BUILD_ENABLED" != xyes ; then - echo " (disabled)" -else - echo "" -fi +echo " * documentation.......: AX_VAR_EXPAND($domjudge_docdir)" echo "" echo " * domserver...........: AX_VAR_EXPAND($domserver_root)" echo " - bin..............: AX_VAR_EXPAND($domserver_bindir)" diff --git a/doc/manual/.gitignore b/doc/manual/.gitignore index adcc78c6e4..df3a8c0f45 100644 --- a/doc/manual/.gitignore +++ b/doc/manual/.gitignore @@ -2,5 +2,4 @@ /version.py /substitutions.py /html -/team /conf_ref.rst diff --git a/doc/manual/Makefile b/doc/manual/Makefile index 52b3fd1504..326a3843fb 100644 --- a/doc/manual/Makefile +++ b/doc/manual/Makefile @@ -18,41 +18,36 @@ $(SUBST_CONFIGS): %: %.in $(TOPDIR)/paths.mk config: $(SUBST_CONFIGS) -ifeq ($(BUILD_DOCS),yes) docs: config # KLUDGE: call make instead of a dependency so that the html target # will run after config from inside the doc target. docs: - $(MAKE) html team + $(MAKE) html distdocs: - $(MAKE) html team + $(MAKE) html # Run make clean here to get a cleaner tarball and make sure # that make distclean returns to the original tarball state. $(MAKE) clean -endif install-docs: docs $(call install_tree,$(DESTDIR)$(domjudge_docdir)/manual,build/html) - $(INSTALL_DATA) -t $(DESTDIR)$(domjudge_docdir)/manual build/domjudge-team-manual.pdf inplace-install: docs inplace-install-l: ln -sf build/html - ln -sf build/team inplace-uninstall-l: - -rm -f html team + -rm -f html clean-l: - rm -rf build/doctrees build/team/.doctrees - -$(MAKE) -C build/team clean + rm -rf build/doctrees maintainer-clean-l: rm -rf build conf_ref.rst distclean-l: - -rm -f $(SUBST_CONFIGS) html team + -rm -f $(SUBST_CONFIGS) html conf_ref.rst: gen_conf_ref.py ./gen_conf_ref.py @@ -60,9 +55,4 @@ conf_ref.rst: gen_conf_ref.py html: conf_ref.rst sphinx-build -M $@ . build $(subst 1,-Q,$(QUIET)) -team: - sphinx-build -b latex . build/team $(subst 1,-Q,$(QUIET)) - $(MAKE) -C build/team domjudge-team-manual.pdf $(QUIET_REDIRECT) - cp build/team/domjudge-team-manual.pdf build - -.PHONY: docs distdocs install-docs inplace-install html team +.PHONY: docs distdocs install-docs inplace-install html diff --git a/doc/manual/conf.py b/doc/manual/conf.py index 1838ce0e91..4073e6a28c 100644 --- a/doc/manual/conf.py +++ b/doc/manual/conf.py @@ -52,7 +52,6 @@ extensions = [ 'sphinx.ext.ifconfig', # 'sphinx_rtd_theme', - 'rst2pdf.pdfbuilder', ] # Add any paths that contain templates here, relative to this directory. @@ -187,8 +186,6 @@ latex_documents = [ (master_doc, 'DOMjudge.tex', 'DOMjudge Documentation', 'DOMjudge Team', 'manual'), - ('team', 'domjudge-team-manual.tex', 'DOMjudge Team Manual', - 'DOMjudge Team', 'manual'), ] @@ -233,21 +230,3 @@ # -- Extension configuration ------------------------------------------------- - -# Options specifically for the Team manual PDF - -pdf_documents = [ - ('team', u'domjudge-team-manual', u'DOMjudge Team Manual', u'The DOMjudge Developers'), -] - -pdf_compressed = True -pdf_stylesheets = ['sphinx','kerning','a4','sphinx-team'] - -pdf_use_coverpage = False - -# This is of string type, not bool. See: https://github.com/rst2pdf/rst2pdf/pull/846 -pdf_use_toc = '' - -# This is needed to avoid a bug in rst2pdf << 0.94 (Debian buster has 0.93) -# See: https://github.com/rst2pdf/rst2pdf/issues/678 -pdf_invariant = False diff --git a/doc/manual/develop.rst b/doc/manual/develop.rst index e5912f6a63..82e6fbde5e 100644 --- a/doc/manual/develop.rst +++ b/doc/manual/develop.rst @@ -39,19 +39,21 @@ already listed under :ref:`judgehost ` and :ref:`submit client ` requirements):: - sudo apt install autoconf automake bats \ - python-sphinx python-sphinx-rtd-theme rst2pdf fontconfig python3-yaml latexmk - -On Debian 11 (Bullseye) and above, instead install:: - - sudo apt install autoconf automake bats \ - python3-sphinx python3-sphinx-rtd-theme rst2pdf fontconfig python3-yaml \ - latexmk texlive-latex-recommended texlive-latex-extra tex-gyre + sudo apt install autoconf automake When this software is present, bootstrapping can be done by running ``make dist``, which creates the ``configure`` script, -downloads and installs the PHP dependencies via composer and -generates documentation from RST/LaTeX sources. +downloads and installs the PHP dependencies via composer. + +Rebuilding the documentation +---------------------------- + +Should you wish to rebuild the DOMjudge manual, you need the +following software installed:: + + sudo apt install python3-sphinx python3-yaml + +Then run ``make docs`` to rebuild them. Maintainer mode installation ---------------------------- diff --git a/doc/manual/index.rst b/doc/manual/index.rst index 2af6aeffa8..73bd5ddfcb 100644 --- a/doc/manual/index.rst +++ b/doc/manual/index.rst @@ -22,7 +22,6 @@ Appendices .. toctree:: quick-install - team problem-format shadow configuration-reference diff --git a/doc/manual/install-workstation.rst b/doc/manual/install-workstation.rst index 1b862cb7d7..ffe40559f4 100644 --- a/doc/manual/install-workstation.rst +++ b/doc/manual/install-workstation.rst @@ -65,7 +65,7 @@ to inspect its configuration and options. Rebuilding team documentation ----------------------------- -The source of the team manual can be found in ``doc/manual/team.rst``. +The source of the team manual can be found in ``doc/team/``. The team manual can incorporate specific settings of your environment, most notably the URL of the DOMjudge installation. To achieve this, rebuild the team manual *after* configuration of the system. @@ -84,13 +84,8 @@ When DOMjudge is configured and site-specific configuration set, the team manual can be generated with the command ``make docs``. The following should do it on a Debian-like system:: - sudo apt install python-sphinx python-sphinx-rtd-theme rst2pdf fontconfig python3-yaml - cd /doc/ + sudo apt install make texlive-latex-extra texlive-latex-recommended texlive-lang-european + cd /docs/team make docs -On Debian 11 and above, install -``python3-sphinx python3-sphinx-rtd-theme rst2pdf fontconfig python3-yaml`` instead. - -The resulting manual will then be found in the ``team/`` subdirectory. - .. _netrc manual page: https://ec.haxx.se/usingcurl/usingcurl-netrc diff --git a/doc/manual/team.rst b/doc/manual/team.rst deleted file mode 100644 index fb13efb22c..0000000000 --- a/doc/manual/team.rst +++ /dev/null @@ -1,415 +0,0 @@ -DOMjudge team manual -==================== - -.. footer:: - - |DOMjudge| team manual version |version| - page ###Page### / ###Total### - - -.. image:: ../logos/DOMjudgelogo.png - :width: 60pt - :height: 132pt - :alt: DOMjudge logo - :align: right - -This is the manual for the DOMjudge programming contest control system -version |version|. -The summary below outlines the working of the system interface. It -is meant as a quick introduction, to be able to start using the system. -It is however strongly advised that your team reads the entire document. -There are specific details of this contest control system that might -become of importance when you run into problems. - -.. admonition:: Summary - - The web interface of DOMjudge can be found at - |baseurlteam|. See the two figures on the next page for - an impression. - - Solutions have to read all input from 'standard in' and write all - output to 'standard out' (also known as console). You will never have - to open (other) files. Also see our :ref:`code examples `. - - You can submit solutions in two ways: - - Command-line - Use ``submit ``. If your filename is of the form - ``.`` where ```` is the - label of the problem and ```` is a standard extension for - your language, then these will automatically be detected. - It will also try to auto-detect the main class (for Java and Kotlin) or the - main file (for Python). You can override these auto-detections; - for a complete reference of all options and examples, see ``submit --help``. - - Web interface - From your team page, |baseurlteam|, click the green **Submit** - button in the menu bar. Select the files you want to submit. - By default, the problem is selected from the base of the (first) - filename and the language from the extension. The web interface tries - to auto-detect the main class (for Java and Kotlin) or the main file (for - Python) from the file name. Double check that the guess is correct - before submitting. - - Viewing scores, submissions and sending and reading clarification - requests and replies is done through the web interface at - |baseurlteam|. - - -.. raw:: pdf - - PageBreak - -.. raw:: latex - - \clearpage - -Overview of the interface -------------------------- - -.. figure:: team-overview.png - :width: 80% - - The team web interface overview page. - -.. figure:: team-scoreboard.png - :width: 80% - - The scoreboard webpage. - -.. raw:: pdf - - PageBreak - -.. _submitting: - -Submitting solutions --------------------- - -Submitting solutions can be done in two ways: with the command-line -program ``submit`` (if installed) or using the web interface. - -Command-line: ``submit`` -```````````````````````` - -Syntax:: - - submit [options] filename.ext ... - -The submit program takes the name (label) of the problem from -``filename`` and the programming language from the extension -``ext``. - -For Java it uses the filename as a guess for the -main class; for Kotlin it capitalizes filename and appends -``Kt`` to compute the guess for the main class name. For Python, -the first filename is used as a guess for the main file. -These guesses can be overruled with the options -``-p problemname``, ``-l languageextension`` and -``-e entry_point``. - -See ``submit --help`` for a complete list of all options, -extensions and some examples. - -``submit`` will check your file and warns you for some problems: -for example when the file has not been modified for a long time or -when it's larger than the maximum source code size -(see :ref:`the section on restrictions `). - -Filenames must start with an alphanumerical character and may contain only -alphanumerical characters and ``+.\_-``. You can specify multiple files -to be part of this submission (see section -":ref:`How are submissions being judged? `"). - -Then ``submit`` displays a summary with all details of your -submission and asks for confirmation. Check whether you are submitting -the right file for the right problem and language and press ``y`` to -confirm. ``submit`` will report a successful submission or give -an error message otherwise. - -Web interface -````````````` - -Solutions can be submitted from the web interface at |baseurlteam|. -Click the green *Submit* button at the menu bar on every page. -Click the file selection button and select one or -multiple files for submission. DOMjudge will try to determine the -problem, language and main class (in case of Java and Kotlin) or main file -(in case of Python) from the base and extension of the first filename. -Otherwise, select the appropriate values. -Filenames must start with an alphanumerical character and may contain only -alphanumerical characters and ``+.\_-``. - -After you hit the submit button and confirm the submission, you will -be redirected back to your submission list page. On this page, a message -will be displayed that your submission was successful and the -submission will be present in the list. An error message will be -displayed if something went wrong. - -Viewing the results of submissions ----------------------------------- - -The left column of your team web page shows an overview of your submissions. -It contains all relevant information: submission time, programming -language, problem and status. The address of your team page is -|baseurlteam|. - -The top of the page shows your team's row in the scoreboard: your position and -which problems you attempted and solved. Via the menu you can view the public -scoreboard page with the scores of all teams. Many cells will show -additional "title text" information when hovering over them. The -score column lists the number of solved problems and the total time including -penalty time. Each cell in a problem column lists the number of submissions, -and if the problem was solved, the time of the first correct -submission in minutes since contest start. This is included in your -total time together with any penalty time incurred for previous -incorrect submissions. - -Optionally the scoreboard can be 'frozen' some time before the end of the -contest. The full scoreboard view will not be updated anymore, but your -team row on your overview page will be. Your team's rank will then be -displayed as '?'. - -Finally, via the top menu you can also view the list of problems and -view/download problem texts and sample data, if provided by the judges. - -Possible results -```````````````` - -A submission can have the following results (not all of these may be -available depending on configuration of the system): - -CORRECT - The submission passed all tests: you solved this problem! - *Correct submissions do not incur penalty time.* - -COMPILER-ERROR - There was an error when compiling your program. On the submission - details page you can inspect the exact error (this option might be - disabled). - Note that when compilation takes more than |COMPILETIME| seconds, - it is aborted and this counts as a compilation error. - *Compilation errors do not incur penalty time. The administrator of - the contest can change this scoring.* - -TIMELIMIT - Your program took longer than the maximum allowed time for this - problem. Therefore it has been aborted. This might indicate that your - program hangs in a loop or that your solution is not efficient - enough. - -RUN-ERROR - There was an error during the execution of your program. This can have - a lot of different causes like division by zero, incorrectly - addressing memory (e.g. by indexing arrays out of bounds), trying to - use more memory than the limit, reading or writing to files, etc. - Also check that your program exits with exit code 0! - -NO-OUTPUT - Your program did not generate any output. Check that you write to - standard out. - -OUTPUT-LIMIT - Your program generated more output than the allowed limit. The solution - is considered incorrect. - -WRONG-ANSWER - The output of your program was incorrect. This can happen simply - because your solution is not correct, but remember that your output - must comply exactly with the specifications of the judges. See - :ref:`testing ` below for more details. - -TOO-LATE - Bummer, you submitted after the contest ended! Your submission is - stored but will not be processed anymore. - -The judges may have prepared multiple test files for each problem. -DOMjudge will report back the first highest priority non-correct result as verdict. -*Your administrator can decide on different priorities for non-correct results.* - -Clarifications --------------- - -All communication with the judges is to be done through clarification -messages. -These can be found in the right column on your team page. Both -clarification replies from the judges and requests sent by you -are displayed there. - -There is also a button to submit a new clarification request to the -judges; you can associate a specific problem or one of the general -categories to a request. This clarification request is only readable -for the judges. The judges can answer specifically to your team or send a -reply to everyone if it is relevant for all. - -.. _judgingprocess: - -How are submissions being judged? ---------------------------------- - -The DOMjudge contest control system is fully automated. -Judging is done in the following way: - -Submitting solutions -```````````````````` - -With the ``submit`` program or the web interface (see -:ref:`the section on submitting `) you -can submit a solution to a problem to the judges. Note that you have to submit -the source code of your program (and not a compiled program or the output of -your program). - -On the contest control system your program enters a queue, awaiting compilation, -execution and testing on one of the autojudges. - -Compilation -``````````` - -Your program will be compiled on an autojudge machine running Linux. -All submitted source files will be passed to the compiler which -generates a single program to run. For Java and Kotlin the given -main class will be checked; for Python we do a -syntax check using the ``py_compile`` module. - -.. _testing: - -Testing -``````` - -After your program has compiled successfully it will be executed and -its output compared to the output of the judges. Before comparing the -output, the exit status of your program is checked: if your program -exits with a non-zero exit code, the result will be a run-error -even if the output of the program is correct! -There are some restrictions during execution. If your program violates -these it will also be aborted with a run-error, -see :ref:`the section on restrictions `. - -When comparing program output, it has to exactly match to output of -the judges, except that some extra whitespace may be ignored (this -depends on the system configuration of the problems). So take care -that you follow the output specifications. In case of problem -statements which do not have unique output (e.g. with floating point -answers), the system may use a modified comparison function. -This will be documented in the problem description. - -.. _runlimits: - -Restrictions -```````````` - -Submissions are run in a sandbox to prevent abuse, keep the jury system -stable and give everyone clear and equal environments. There -are some restrictions to which all submissions are subjected: - -compile time - Compilation of your program may take no longer than |COMPILETIME| - seconds. After that, compilation will be aborted and the result will - be a compile error. In practice this should never give rise to - problems. Should this happen to a normal program, please inform the - judges right away. - -source size - The total amount of source code in a single submission may not exceed - |SOURCESIZE| kilobytes, otherwise your submission will be rejected. - -memory - The judges will specify how much memory you have available during - execution of your program. This may vary per problem. It is the - total amount of memory (including program code, statically and - dynamically defined variables, stack, Java/Python VM, …)! - If your program tries to use more memory, it will most likely abort, - resulting in a run error. - -creating new files - Do not create new files. The sandbox will not allow this and the file open - function will return a failure. Using the file without handling this error can - result in a runtime error depending on the submission language. - -number of processes - You are not supposed to explicitly create multiple processes (threads). This is - to no avail anyway, because your program has exactly 1 processor core fully - at its disposal. DOMjudge executes submissions in a sandbox where a maximum - of |PROCLIMIT| processes can be run simultaneously (including processes that - started your program). - - People who have never programmed with multiple processes (or have - never heard of "threads") do not have to worry: a normal program - runs in one process. - -.. raw:: pdf - - PageBreak - -.. _codeexamples: - -Code examples -------------- - -Below are a few examples on how to read input and write output for a -problem. - -The examples are solutions for the following problem: the first line -of the input contains the number of testcases. Then each testcase -consists of a line containing a name (a single word) of at most 99 -characters. For each testcase output the string ``Hello !`` -on a separate line. - -Sample input and output for this problem: - -+------------------+-------------------------+ -| Input | Output | -+==================+=========================+ -| | ``3`` | | ``Hello world!`` | -| | ``world`` | | ``Hello Jan!`` | -| | ``Jan`` | | ``Hello SantaClaus!`` | -| | ``SantaClaus`` | | -+------------------+-------------------------+ - -Note that the number ``3`` on the first line indicates that 3 testcases -follow. - -What follows is a number of possible solutions to this problem -for different programming languages. - -.. literalinclude:: ../examples/example.c - :language: c - :caption: *A solution in C* - -.. raw:: latex - - \clearpage - -.. literalinclude:: ../examples/example.cc - :language: cpp - :caption: *A solution in C++* - -.. literalinclude:: ../examples/example.java - :language: java - :caption: *A solution in Java* - -.. literalinclude:: ../examples/example.kt - :language: kotlin - :caption: *A solution in Kotlin* - -.. literalinclude:: ../examples/example.py - :language: python - :caption: *A solution in Python* - -.. literalinclude:: ../examples/example.cs - :language: csharp - :caption: *A solution in C#* - -.. literalinclude:: ../examples/example.pas - :language: pas - :caption: *A solution in Pascal* - -.. literalinclude:: ../examples/example.hs - :language: hs - :caption: *A solution in Haskell* - -Improvements to DOMjudge ------------------------- - -The DOMjudge team would like your feedback. We do not receive much feedback from participants. -If you find something lacking or have improvement ideas, please report them. See https://www.domjudge.org/development. - diff --git a/doc/team/.gitignore b/doc/team/.gitignore new file mode 100644 index 0000000000..b692c0900a --- /dev/null +++ b/doc/team/.gitignore @@ -0,0 +1,6 @@ +_minted-team-manual/ +team-manual.aux +team-manual.log +team-manual.out +team-manual.pdf +gentexconfig diff --git a/doc/team/Makefile b/doc/team/Makefile new file mode 100644 index 0000000000..3c5a5a6107 --- /dev/null +++ b/doc/team/Makefile @@ -0,0 +1,43 @@ +ifndef TOPDIR +TOPDIR=../.. +endif +include $(TOPDIR)/Makefile.global + +MANUALSTEX=team-manual.tex +MANUALSPDF=$(MANUALSTEX:%tex=%pdf) + +docs: gentexconfig $(MANUALSPDF) + +# For distdocs we cannot generate gentexconfig, since paths.mk is not +# yet available: +distdocs: $(MANUALSPDF) + +install-docs: + $(INSTALL_PROG) -t $(DESTDIR)$(domjudge_docdir)/team \ + gentexconfig genteammanual + $(INSTALL_DATA) -t $(DESTDIR)$(domjudge_docdir)/team \ + team-manual.tex team-manual.pdf + $(INSTALL_DATA) -T README $(DESTDIR)$(domjudge_docdir)/README.teammanual + +gentexconfig: gentexconfig.in $(TOPDIR)/paths.mk + $(substconfigvars) + +# 'genteammanual' (re-)generates all versions even if only one is not up-to-date. +$(MANUALSPDF): %pdf: %tex team-manual-preamble.tex + ./genteammanual + +# Cleanup LaTeX logs, etc. after generating documentation for distribution. +distdocs-l: + $(MAKE) clean + +clean-l: + -rm -f $(addprefix team-manual.,aux log out) + -rm -rf _minted-team-manual + +distclean-l: + -rm -f gentexconfig + +maintainer-clean-l: + -rm -f $(MANUALSPDF) + +.PHONY: docs distdocs install-docs diff --git a/doc/team/README b/doc/team/README new file mode 100644 index 0000000000..87853abc5c --- /dev/null +++ b/doc/team/README @@ -0,0 +1,13 @@ +DOMjudge team manual +-------------------- + +The manual for teams automatically incorporates DOMjudge configuration +items. Therefore it is not pre-built, but should be built after you +have configured your system, so teams get the correct information. The +manual can be generated with the 'genteammanuals' command located +under the 'team' subdirectory. Pass the output directory as argument. + +As many things are configurable, we advise to redact the manual to your +specific situation, e.g. by removing unused/disabled features, before +distributing them to the teams. See section 2.16 of the admin-manual for +instructions on rebuilding the team documentation. diff --git a/doc/team/genteammanual b/doc/team/genteammanual new file mode 100755 index 0000000000..b33922cf34 --- /dev/null +++ b/doc/team/genteammanual @@ -0,0 +1,61 @@ +#!/bin/sh +# +# Script to generate team manual including actual configuration +# settings. +# +# Part of the DOMjudge Programming Contest Jury System and licensed +# under the GNU GPL. See README and COPYING for details. + +set -e + +SOURCE=team-manual.tex +PREAMBLE=team-manual-preamble.tex + +NRUNS=3 + +OUTPUTDIR=. +[ -n "$1" ] && OUTPUTDIR="$1" + +if [ ! -f "$PREAMBLE" ]; then + echo "File '$PREAMBLE' not found; are you running" + echo "this script from the team manual directory?" + exit 1 +fi + +if [ ! -d "$OUTPUTDIR" ] || [ ! -w "$OUTPUTDIR" ]; then + echo "Output directory '$OUTPUTDIR' not found or not writable." + exit 1 +fi + +# Set LaTeX command and flags if not given: +[ -z "$LATEX" ] && LATEX=pdflatex +[ -z "$LATEXFLAGS" ] && LATEXFLAGS='--interaction=errorstopmode --shell-escape' + +TEXCONFIG=$(mktemp --tmpdir domjudge-texconfig.XXXXXX) + +if [ -x "gentexconfig" ]; then + ./gentexconfig > "$TEXCONFIG" +else + ./gentexconfig.in > "$TEXCONFIG" +fi + +# Run LaTeX: +# shellcheck disable=SC2059 +{ + [ "$QUIET" ] || printf "Running $NRUNS passes of '%s'..." "$LATEX $LATEXFLAGS $SOURCE" + run=1 + while [ "$run" -le "$NRUNS" ]; do + # shellcheck disable=SC2086 + if ! ( cat "$TEXCONFIG" ; echo \\"input{$SOURCE}" ) | \ + $LATEX $LATEXFLAGS -jobname "${SOURCE%.tex}" -output-directory "$OUTPUTDIR" >/dev/null ; then + printf "\\nTeX-ing failed in run $run, see '%s' for details.\\n" "${SOURCE%tex}log" + exit 1 + else + [ "$QUIET" ] || printf " $run" + fi + run=$((run+1)) + done + [ "$QUIET" ] || printf "\\n" ; +} # end shellcheck disable + +rm -f "$TEXCONFIG" diff --git a/doc/team/gentexconfig.in b/doc/team/gentexconfig.in new file mode 100755 index 0000000000..d6df1f5f95 --- /dev/null +++ b/doc/team/gentexconfig.in @@ -0,0 +1,47 @@ +#!/usr/bin/env php + 'https://example.com/domjudge/', + 'DOMJUDGE_VERSION' => 'unknown', + 'SOURCESIZE' => 256, + 'COMPILETIME' => 30, + 'PROCLIMIT' => 15, + 'SUBMITCLIENT_ENABLED' => 'yes', + ]; + +foreach ($configvars as $var => $default) { + $value = defined($var) ? constant($var) : $default; + echo '\\def\\' . str_replace('_', '', $var) . '{' . $value . "}\n"; +} + +exit(0); diff --git a/doc/team/team-manual-preamble.tex b/doc/team/team-manual-preamble.tex new file mode 100644 index 0000000000..403ea2fc22 --- /dev/null +++ b/doc/team/team-manual-preamble.tex @@ -0,0 +1,82 @@ +\documentclass[11pt,a4paper,twoside]{article} + +\usepackage[hmargin=2.7cm,vmargin=3cm]{geometry} +\usepackage{moreverb} +\usepackage{minted} +\usepackage{graphicx} +\usepackage{wrapfig} +\usepackage{expdlist} +\usepackage{svn} +\usepackage{fancyhdr} +\usepackage{extramarks} +\usepackage{color} +\usepackage[colorlinks=true,urlcolor=blue,linkcolor=blue]{hyperref} +\usepackage{ifthen} + +\pagestyle{fancy} +\renewcommand{\sectionmark}[1]{\markboth{\thesection.\ #1}{}} +\renewcommand{\familydefault}{\sfdefault} + +% Begin new paragraphs without indentation but vertical space. +\setlength{\parindent}{0pt} +\setlength{\parskip}{1.5ex plus 0.5ex minus 0.2ex} + +% Setup framebox margin and frame rule size. +\setlength{\fboxsep}{0pt} +\setlength{\fboxrule}{0.6pt} +\setminted{frame=single,framesep=1ex} + +\newcommand{\DOMjudge}{\textsc{DOM}judge } + +% Display commands, arguments, etc. in texttt font and don't break those. +\newcommand{\cmd}[1]{\mbox{\texttt{#1}}} + +% Only show text if the submitclient is configured +\newcommand{\ifcmdsubmit}[1]{\ifthenelse{\equal{\SUBMITCLIENTENABLED}{yes}}{#1}{}} + +% Our titlepage, should be called at start of team manual document +% Argument list: +% #1 - DOMjudge version +% #2 - Document revision +% #3 - Last modified date +% #4 - Generated date +% Also define the following words for language overrides: +\newcommand{\versionrevison}{Version/revision} +\newcommand{\lastmodified}{Last modified} +\newcommand{\generated}{Generated} +\makeatletter +\newcommand{\titlestuff}[4]{% + + \thispagestyle{plain} + \vspace*{-2cm} + \parbox[t]{\linewidth}{% + \begin{wrapfigure}[1]{r}{2cm} + \vspace*{-1cm}\hfill + \includegraphics[height=4cm]{../logos/DOMjudgelogo.pdf} + \end{wrapfigure} + {\fontfamily{phv}\fontseries{b}\fontsize{26pt}{28pt}\selectfont \@title \par} + } + \vskip 2cm + + % Setup fancy headers/footers (here because we need SVN stuff defined) + \def\setupfancystuff{% + \fancyhead{} + \fancyfoot{} + \fancyfoot[RO,LE]{\thepage} + \fancyfoot[LO,RE]{% + \color[gray]{0.5}\vspace{-0.3cm} + \DOMjudge team manual -- \generated: #4 \\ + } + } + + % First for fancy page style: + \setupfancystuff + \fancyhead[RO,LE]{\slshape \firstleftmark} + + % No headers for plain page style (titlepage): + \fancypagestyle{plain}{% + \setupfancystuff + \renewcommand{\headrulewidth}{0pt} + } +} +\makeatother diff --git a/doc/team/team-manual.tex b/doc/team/team-manual.tex new file mode 100644 index 0000000000..0dedc02896 --- /dev/null +++ b/doc/team/team-manual.tex @@ -0,0 +1,397 @@ +\input{team-manual-preamble} + +\usepackage[english]{babel} + +% For inclusion of the correct date (last modified) and revision. +% Use the \SVN command to get language dependent formatting of the +% date. We need to do some %/$ comment character magic to satisfy both +% TeX and 'git log' format string formatting both with and without +% expansion of the $Format$ keyword below with 'git archive'. +\SVN $Date: 1900-01-01 00:00:00 +0000 $ +\SVN $Rev: unpublished $ +% $Format: +%n\SVN %x24Date: %ai %x24$ +% $Format: +%n\SVN %x24Rev: %h %x24$ + +\title{\DOMjudge team manual} + +\hypersetup{ + pdftitle={DOMjudge team manual}, + pdfauthor={DOMjudge Developers: domjudge-devel at domjudge.org}, + pdfsubject={Instruction for teams using the interface of the DOMjudge jury system during a programming contest}, + pdfkeywords={DOMjudge,manual,team,judge,jury,programming,contest,icpc,acm} +} + +\begin{document} + +\titlestuff{\DOMJUDGEVERSION}{\SVNRev}{\SVNDate}{\today} + +\section*{Summary} + +DOMjudge works through a web interface that can be found at +\url{\BASEURL team}. See figures~\ref{fig:team-overview} +and~\ref{fig:team-scoreboard} on the next page for an impression. + +Solutions have to read all input from `standard in' and write all +output to `standard out' (also known as console). You will never have +to open (other) files. Also see our code examples~\ref{codeexamples}. + +You can submit solutions% +\ifcmdsubmit{ with the command-line program \cmd{submit} or} +from the web interface: +\begin{description}[\breaklabel\setlabelstyle{\bfseries}] +\ifcmdsubmit{ +\item[Command-line] +Use \cmd{submit }. If your filename is of the form +\cmd{.} where \cmd{} is the +label of the problem and \cmd{} is a standard extension for +your language, then these will automatically be detected. +It will also try to auto-detect the main class (for Java and Kotlin) or the +main file (for Python). You can override these auto-detections; +for a complete reference of all options and examples, see \cmd{submit --help}. +} +\item[Web interface] +From your team page, \url{\BASEURL team}, click the green \textbf{Submit} +button in the menu bar. Select the files you want to submit. +By default, the problem is selected from the base of the (first) +filename and the language from the extension. The web interface tries +to auto-detect the main class (for Java and Kotlin) or the main file (for +Python) from the file name. Double check that the guess is +correct before submitting. +\end{description} + +Viewing scores, submissions and sending and reading clarification +requests and replies is done through the web interface at +\url{\BASEURL team}. + +\emph{End of summary} + +\begin{figure}[p] + \centering + \fbox{\includegraphics[width=\textwidth]{team-overview}} + \caption{The team web interface overview page.} + \label{fig:team-overview} +\end{figure} + +\begin{figure}[p] + \centering + \fbox{\includegraphics[width=\textwidth]{team-scoreboard}} + \caption{The scoreboard webpage.} + \label{fig:team-scoreboard} +\end{figure} + +\newpage + +\section{Submitting solutions}\label{submit} + +Submitting solutions can be done +\ifcmdsubmit{ +in two ways: with the command-line +program \cmd{submit} (if installed) or +} using the web interface. + +\ifcmdsubmit{ +\subsection{Command-line: \cmd{submit}} + +\textbf{Syntax:} \cmd{submit [options] filename.ext ...} + +The submit program takes the name (label) of the problem from +\cmd{filename} and the programming language from the extension +\cmd{ext}. + +For Java it uses the \cmd{filename} as a guess for the +main class; for Kotlin it capitalizes \cmd{filename} and appends +\cmd{Kt} to compute the guess for the main class name. For Python, +the first filename is used as a guess for the main file. +dd +These guesses can be overruled with the options +\cmd{-p problemname}, \cmd{-l~languageextension} and +\cmd{-e~entry\_point}. + +See \cmd{submit --help} for a complete list of all options, +extensions and some examples. + +\cmd{submit} will check your file and warns you for some problems: +for example when the file has not been modified for a long time or +when it's larger than the maximum source code size +(see section~\ref{runlimits}). + +Filenames must start with an alphanumerical character and may contain only +alphanumerical characters and \cmd{+.\_-}. You can specify multiple files +to be part of this submission (see section~\ref{howjudged} `How are +submissions being judged?'). + +Then \cmd{submit} displays a summary with all details of your +submission and asks for confirmation. Check whether you are submitting +the right file for the right problem and language and press `y' to +confirm. \cmd{submit} will report a successful submission or give +an error message otherwise. + +\subsection{Web interface} +} + +Solutions can be submitted from the web interface at \url{\BASEURL team}. +Click the green \textit{Submit} button at the menu bar on every page. +Click the file selection button and select one or +multiple files for submission. \DOMjudge will try to determine the +problem, language and main class (in case of Java and Kotlin) or main file +(in case of Python) from the base and extension of the first filename. +Otherwise, select the appropriate values. +Filenames must start with an alphanumerical character and may contain only +alphanumerical characters and \cmd{+.\_-}. + +After you hit the submit button and confirm the submission, you will +be redirected back to your submission list page. On this page, a message +will be displayed that your submission was successful and the +submission should be present in the list. An error message will be +displayed if something went wrong. + +\section{Viewing the results of submissions} + +The left column of your team web page shows an overview of your submissions. +It contains all relevant information: submission time, programming +language, problem and status. The address of your team page is +\url{\BASEURL team}. + +The top of the page shows your team's row in the scoreboard: your position and +which problems you attempted and solved. Via the menu you can view the public +scoreboard page with the scores of all teams. Many cells will show +additional ``title text'' information when hovering over them. The +score column lists the number of solved problems and the total time including +penalty time. Each cell in a problem column lists the number of submissions, +and if the problem was solved, the time of the first correct +submission in minutes since contest start. This is included in your +total time together with any penalty time incurred for previous +incorrect submissions. + +Optionally the scoreboard can +be `frozen' some time before the end of the contest. The full scoreboard view +will not be updated anymore, but your team row will. Your team's rank will +be displayed as `?'. + +Finally, via the top menu you can also view the +list of problems and view/download problem texts and sample data, if +provided by the judges. + +\subsection{Possible results} + +A submission can have the following results (not all of these may be +available depending on configuration of the system): + +\begin{description}[\setleftmargin{4.5cm}] +\item[CORRECT] +The submission passed all tests: you solved this problem! +\textit{Correct submissions do not incur penalty time.} + +\item[COMPILER-ERROR] +There was an error when compiling your program. On the submission +details page you can inspect the exact error (this option might be +disabled). +Note that when compilation takes more than \COMPILETIME\ seconds, it is aborted and +this counts as a compilation error. +\textit{Compilation errors do not incur penalty time. The administrator of the contest can change this scoring.} + +\item[TIMELIMIT] +Your program took longer than the maximum allowed time for this +problem. Therefore it has been aborted. This might indicate that your +program hangs in a loop or that your solution is not efficient +enough. + +\item[RUN-ERROR] +There was an error during the execution of your program. This can have +a lot of different causes like division by zero, incorrectly +addressing memory (e.g. by indexing arrays out of bounds), trying to +use more memory than the limit, reading or writing to files, etc. +Also check that your program exits with exit code 0! + +\item[NO-OUTPUT] +Your program did not generate any output. Check that you write to +standard out. + +\item[OUTPUT-LIMIT] +Your program generated more output than the allowed limit. The +solution is considered incorrect. + +\item[WRONG-ANSWER] +The output of your program was incorrect. This can happen simply +because your solution is not correct, but remember that your output +must comply exactly with the specifications of the judges. See +section~\ref{testing} below for more details. + +\item[TOO-LATE] +Bummer, you submitted after the contest ended! Your submission is +stored but will not be processed anymore. +\end{description} + +The judges may have prepared multiple test files for each +problem. \DOMjudge will report back the first highest priority +non-correct result as verdict. +\textit{Your administrator can decide on different priorities +for non-correct results.} + +\section{Clarifications} + +All communication with the judges is to be done through clarification +messages. +These can be found in the right column on your team page. Both +clarification replies from the judges and requests sent by you +are displayed there. + +There is also a button to submit a new clarification request to the +judges; you can associate a specific problem or one of the general +categories to a request. This clarification request is only readable +for the judges. The judges can answer specifically to your team or send a +reply to everyone if it is relevant for all. + +\section{How are submissions being judged?}\label{howjudged} + +The \DOMjudge contest control system is fully automated. +Judging is done in the following way: + +\subsection{Submitting solutions} + +With% +\ifcmdsubmit{ the \cmd{submit} program or} +the web interface (see section~\ref{submit}) you can submit a solution +to a problem to the judges. Note that you have to submit the source code +of your program (and not a compiled program or the output of your +program). + +On the contest control system your program enters a queue, awaiting compilation, +execution and testing on one of the autojudges. + +\subsection{Compilation} + +Your program will be compiled on an autojudge machine running Linux. +All submitted source files will be passed to the compiler which +generates a single program to run. For Java and Kotlin the given +main class will be checked; for Python we do a +syntax check using the \cmd{py\_compile} module. + +\subsection{Testing}\label{testing} + +After your program has compiled successfully it will be executed and +its output compared to the output of the judges. Before comparing the +output, the exit status of your program is checked: if your program +exits with a non-zero exit code, the result will be a \textsc{run-error} +even if the output of the program is correct! +There are some restrictions during execution. If your program violates +these it will also be aborted with a \textsc{run-error}, +see section~\ref{runlimits}. + +When comparing program output, it has to exactly match to output of +the judges, except that some extra whitespace may be ignored (this +depends on the system configuration of the problems). So take care +that you follow the output specifications. In case of problem +statements which do not have unique output (e.g. with floating point +answers), the system may use a modified comparison function. +This will be documented in the problem description. + +\subsection{Restrictions}\label{runlimits} + + +Submissions are run in a sandbox to prevent abuse, keep the jury system stable and give everyone +clear and equal environments. There are some restrictions to which all submissions are subjected: + +\begin{description}[\setlabelphantom{number of processes}] +\item[compile time] +Compilation of your program may take no longer than \COMPILETIME\ +seconds. After that, compilation will be aborted and the result will +be a compile error. In practice this should never give rise to +problems. Should this happen to a normal program, please inform the +judges right away. + +\item[source size] +The total amount of source code in a single submission may not exceed +\SOURCESIZE\ kilobytes, otherwise your submission will be rejected. + +\item[memory] +The judges will specify how much memory you have available during execution of +your program. This may vary per problem. +It is the total amount of memory (including +program code, statically and dynamically defined variables, stack, +Java/Python VM, \dots)! If your program tries to use more memory, it will +most likely abort, resulting in a run error. + +\item[creating new files] +Do not create new files. The sandbox will not allow this and the file open +function will return a failure. Using the file without handling this error can +result in a runtime error depending on the submission language. + +\item[number of processes] +You are not supposed to explicitly create multiple processes (threads). This is +to no avail anyway, because your program has exactly 1 processor core fully +at its disposal. To increase stability of the system, \DOMjudge +executes submissions in a sandbox where a maximum of \PROCLIMIT\ processes +can be run simultaneously (including processes that started your program). + +People who have never programmed with multiple processes (or have +never heard of ``threads'') do not have to worry: a normal program +runs in one process. + +\end{description} + +\newpage +\appendix + +\section{Code examples}\label{codeexamples} + +Below are a few examples on how to read input and write output for a +problem. + +The examples are solutions for the following problem: the first line +of the input contains the number of testcases. Then each testcase +consists of a line containing a name (a single word) of at most 99 +characters. For each testcase output the string ``Hello $<$name$>$!'' +on a separate line. + +Sample input and output for this problem: + +\begin{tabular}{|p{0.473\textwidth}|p{0.473\textwidth}|} +\hline +\textbf{Input} & \textbf{Output} \\ +\hline +\verbatiminput{../examples/example.in} & +\verbatiminput{../examples/example.out} \\ +\hline +\end{tabular} + +Note that the number 3 on the first line indicates that 3 testcases +follow. + +What follows is a number of possible solutions to this problem for different +programming languages. + +A solution for this problem in C: +\inputminted{c}{../examples/example.c} + +\newpage + +A solution in C++: +\inputminted{cpp}{../examples/example.cc} + +A solution in Java: +\inputminted{java}{../examples/example.java} + +A solution in Python: +\inputminted{python}{../examples/example.py} + +\newpage + +A solution in C\#: +\inputminted{csharp}{../examples/example.cs} + +A solution in Pascal: +\inputminted{pascal}{../examples/example.pas} + +And finally a solution in Haskell: +\inputminted{haskell}{../examples/example.hs} + +\section{Improvements to \DOMjudge} + +The DOMjudge team would like your feedback. We do not receive much feedback +from participants. If you find something lacking or have improvement ideas, +please report them. See \url{https://www.domjudge.org/development}. + +\end{document} diff --git a/doc/manual/team-overview.png b/doc/team/team-overview.png similarity index 100% rename from doc/manual/team-overview.png rename to doc/team/team-overview.png diff --git a/doc/manual/team-scoreboard.png b/doc/team/team-scoreboard.png similarity index 100% rename from doc/manual/team-scoreboard.png rename to doc/team/team-scoreboard.png