Update documentation about external contest formats.

Author: giomasce

docs/External contest formats.rst

@@ -28,9 +28,15 @@ You can follow this description looking at `this example <https://github.com/cms
 
 - for each task :samp:`{task_name}`, a directory :file:`{task_name}` that contains the description of the task and all the files needed to build the statement of the problem, the input and output cases, the reference solution and (when used) the solution checker.
 
-The exact structure of these files and directories is detailed below. Note that providing confusing input to ``cmsYamlImporter`` can, unexpectedly, confuse it and create inconsistent tasks and/or strange errors. For confusing input we mean parameters and/or files from which it can infer no or multiple task types or score types.
+The exact structure of these files and directories is detailed below. Note that this loader is not particularly reliable and providing confusing input to it may lead to create inconsistent or strange data on the database. For confusing input we mean parameters and/or files from which it can infer no or multiple task types or score types.
 
-As the name suggest, this format was born among the Italian trainers group, thus many of the keywords detailed below used to be in Italian. Now they have been translated to English, but Italian keys are still recognized for backward compatibility and are detailed below. Please note that, although so far this is the only format natively supported by CMS, it is far from ideal: in particular, it has grown in a rather untidy manner in the last few years (CMS authors are planning to develop a new, more general and more organic, format, but unfortunately it doesn't exist yet). Thus, instead of converting your tasks to the Italian format for importing into CMS, it is suggested to write a loader for the format you already have. Please get in touch with CMS authors to have support.
+As the name suggest, this format was born among the Italian trainers group, thus many of the keywords detailed below used to be in Italian. Now they have been translated to English, but Italian keys are still recognized for backward compatibility and are detailed below. Please note that, although so far this is the only format natively supported by CMS, it is far from ideal: in particular, it has grown in a rather untidy manner in the last few years (CMS authors are planning to develop a new, more general and more organic, format, but unfortunately it doesn't exist yet).
+
+For the reasons above, instead of converting your tasks to the Italian format for importing into CMS, it is suggested to write a loader for the format you already have. Please get in touch with CMS authors to have support.
+
+.. warning::
+
+   The authors offer no guarantee for future compatibility for this format. Again, if you use it, you do so at your own risk!
 
 
 General contest description
@@ -42,11 +48,11 @@ The :file:`contest.yaml` file is a plain YAML file, with at least the following
 
 - ``description`` (string; also accepted: ``nome``): the contest's name (description), shown to contestants in the web interface.
 
-- ``tasks`` (list of strings; also accepted: ``problemi``): a list of the tasks belonging to this contest; for each of these strings, say :samp:`{task_name}`, there must be a file named :file:`{task_name}.yaml` in the contest directory and a directory called :file:`{task_name}`, used to extract information about that task; the order in this list will be the order of the tasks in the web interface.
+- ``tasks`` (list of strings; also accepted: ``problemi``): a list of the tasks belonging to this contest; for each of these strings, say :samp:`{task_name}`, there must be a directory called :file:`{task_name}` in the contest directory, with content as described :ref:`below <externalcontestformats_task-directory>`; the order in this list will be the order of the tasks in the web interface.
 
 - ``users`` (list of associative arrays; also accepted: ``utenti``): each of the elements of the list describes one user of the contest; the exact structure of the record is described :ref:`below <externalcontestformats_user-description>`.
 
-- ``token_mode``: the token mode for the contest, as in :ref:`configuringacontest_tokens`; it can be ``disabled``, ``infinite`` or ``finite``.
+- ``token_mode``: the token mode for the contest, as in :ref:`configuringacontest_tokens`; it can be ``disabled``, ``infinite`` or ``finite``; if this is not specified, the loader will try to infer it from the remaining token parameters (in order to retain compatibility with the past), but you are not advised to rely on this behavior.
 
 The following are optional keys.
 
@@ -80,7 +86,10 @@ The following are optional keys.
 
 - ``ip`` (string): the IP address or subnet from which incoming connections for this user are accepted, see :ref:`configuringacontest_login`.
 
-- ``hidden`` (boolean; also accepted: ``fake``): when set to true set the ``hidden`` flag in the user, see :ref:`configuringacontest_login`; defaults to false (the case-sensitive _string_ ``True`` is also accepted).
+- ``hidden`` (boolean; also accepted: ``fake``): when set to true set the ``hidden`` flag in the user, see :ref:`configuringacontest_login`; defaults to false (the case-sensitive *string* ``True`` is also accepted).
+
+
+.. _externalcontestformats_task-directory:
 
 Task directory
 --------------
@@ -89,11 +98,11 @@ The content of the task directory is used both to retrieve the task data and to
 
 These are the required files.
 
-- :file:`task.yaml`: this file contains the name of the task and describes some of its properties. Its content is detailed below.
+- :file:`task.yaml`: this file contains the name of the task and describes some of its properties; its content is detailed :ref:`below <externalcontestformats_task-description>`; in order to retain backward compatibility, this file can also be provided in the file :file:`{task_name.yaml}` in the root directory of the *contest*.
 
 - :file:`statement/statement.pdf` (also accepted: :file:`testo/testo.pdf`): the main statement of the problem. It is not yet possible to import several statement associated to different languages: this (only) statement will be imported according to the language specified under the key ``primary_language``.
 
-- :file:`input/input{%d}.txt` and :file:`output/output{%d}.txt` for all integers :samp:`{%d}` between 0 (included) and ``n_input`` (excluded): these are of course the input and (one of) the correct output files.
+- :file:`input/input{%d}.txt` and :file:`output/output{%d}.txt` for all integers :samp:`{%d}` between 0 (included) and ``n_input`` (excluded): these are of course the input and reference output files.
 
 The following are optional files, that must be present for certain task types or score types.
 
@@ -112,6 +121,8 @@ The following are optional files, that must be present for certain task types or
 - :file:`att/*`: each file in this folder is added as an attachment to the task, named as the file's filename.
 
 
+.. _externalcontestformats_task-description:
+
 Task description
 ----------------
 
@@ -123,7 +134,7 @@ The task YAML files require the following keys.
 
 - ``n_input`` (integer): number of test cases to be evaluated for this task; the actual test cases are retrieved from the :ref:`task directory <externalcontestformats_task-directory>`.
 
-- ``token_mode``: the token mode for the task, as in :ref:`configuringacontest_tokens`; it can be ``disabled``, ``infinite`` or ``finite``.
+- ``token_mode``: the token mode for the task, as in :ref:`configuringacontest_tokens`; it can be ``disabled``, ``infinite`` or ``finite``; if this is not specified, the loader will try to infer it from the remaining token parameters (in order to retain compatibility with the past), but you are not advised to relay on this behavior..
 
 The following are optional keys.
 
@@ -147,5 +158,3 @@ The following are optional keys that must be present for some task type or score
 
 - ``primary_language`` (string): the statement will be imported with this language code; defaults to ``it`` (Italian), in order to ensure backward compatibility.
 
-
-.. _externalcontestformats_task-directory: