Update tagging example and documentations for tags

Author: Julia Wellmann

docs/advanced.rst

@@ -419,6 +419,10 @@ For example:
 The ``tag`` attribute can be used within any ``<element>`` within the input file (except the ``<jube>``).
 If several different ``tag`` attribute values are used in a script, they can be specified as a list separated by spaces from the command line.
 
+To keep track of all tags, a description for each tag can be defined within the ``<tags>``, where ``<check_tags>`` is also defined, using
+``<tag name="...">Description</tag>``. To force a description of all possible tags, the ``forced`` attribute can be set to true,
+so that an error is thrown if a tag is not documented.
+
 All ``<elements>`` which contain a special ``tag="..."`` attribute will be hidden if the value of the tag evaluates to ``false``.
 This means that JUBE will ignore the elements with these tags in its internal processing.
 Caution: This can lead to erroneous execution if you forget to set the necessary tags for execution, as JUBE will ignore e.g. a ``<parameter>`` provided with the corresponding ``tag`` attribute that evaluates to false.

docs/commandline.rst

@@ -410,6 +410,26 @@ Show benchmark status RUNNING or FINISHED.
 
 .. index:: complete
 
+tag
+~~~
+
+Show tags description
+
+.. code-block:: none
+
+   jube tag [-h] [-i ID [ID ...]] [PATH]
+
+``-h``, ``--help``
+   show command help information
+
+``-i ID [ID ...]``, ``--id ID [ID ...]``
+   |ID_DESCRIPTION|
+
+``PATH``
+   path to input file or directory which contains benchmarks, default: .
+
+.. index:: complete
+
 complete
 ~~~~~~~~
 

docs/glossar.rst

@@ -62,6 +62,12 @@ Glossary
       If no benchmark id is given, last benchmark found in directory will be used. If benchmark directory is missing, current
       directory will be used.
 
+   tag
+      Show tag description for the given benchmark.
+
+      If path to input file or benchmark directory is missing, current directory will be used. If no benchmark id is given,
+      last benchmark found in directory will be used.
+
    continue
       Continue an existing benchmark. Not finished steps will be continued,
       if they are leaving pending mode.
@@ -127,6 +133,20 @@ Glossary
 
          <comment>...</comment>
 
+  tags_tag
+      Specify tag description and combination of tags that must be set.
+
+      .. code-block:: xml
+
+         <tags forced="...">
+           <check_tags>...</check_tags>
+           <tag name="...">...</tag>
+         </tags>
+
+      * ``forced`` is optional, if it is set to ``true``, you will be forced to describe every possible tag. (default: ``false``)
+      * multiple ``<check_tags>`` and ``<tag>`` are allowed
+      * In the ``<tag>``, you can write a description for the tag with the given name.
+
    check_tags_tag
       Specify combination of tags that must be set.
 

docs/release_notes.rst

@@ -25,6 +25,7 @@ Release notes
 ~~~~~~~~~~~~~
 Release: XXXX-XX-XX
 
+* Added: New `<tags>` tag, which includes the `<tag>` tag to write a description for each tag specified in the input file.
 * Added: A new operator `^` (exclusive disjunction (`xor`)) for the `tag` attribute and `<check_tags>`.
 * Added: New `primekey` attribute for the `key`-tag of the `database` to define whether this `key` is a primary key of the database or not. Can be set to `true` or `false` (default: `false`).
 * Added: New environment variable `JUBE_VERBOSE` to set the verbosity level.
@@ -35,7 +36,9 @@ Release: XXXX-XX-XX
 * Changed: The `outpath` attribute of the `<benchmark>` tag no longer needs to be specified if either the command line option `--outpath` is set or the new environment variable `JUBE_BENCHMARK_OUTPATH` is used. The command line option overrides the environment variable, which in turn overrides the attribute in the input file.
 * Changed: The convert type warning is only logged to the `analyse.log` file and no longer printed to the console output.
 * Changed: If the `title` attribute of a database `key` is set, then this title is used as the name of the database column instead of the parameter or pattern name.
+* Changed: The `<check_tags>` tag is now a subelement of the new `<tags>` tag.
 * Deprecated: The `primekeys` attribute of the `database` is no longer supported. Use the new `primekey` attribute of the `database` `key` instead.
+* Deprecated: `<check_tags>` will no longer be supported on a global level. Instead, it should be specified in the `<tags>` tag.
 * Removed: Comma character (`,`) is no longer supported in `check_tags` and `tag` attributes. Instead use `|`, `^` `+` and `!`.
 * Fixed: Allow YAML scripts to include a list of nested parametersets with `!include`.
 * Fixed: Allow YAML scripts to use the tag attribute in the `<path>` of the `<include-path>`-tag.

examples/tagging/tagging.xml

@@ -1,6 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <jube>
-  <check_tags>deu|eng</check_tags> <!-- check if tag deu or eng was set -->
+  <tags forced="true">
+    <check_tags>deu|eng</check_tags>
+    <tag name="deu">For german strings</tag>
+    <tag name="eng">For english strings</tag>
+  </tags>
 
   <benchmark name="tagging" outpath="bench_run">
     <comment>Tags as logical combination</comment>

examples/tagging/tagging.yaml

@@ -1,4 +1,9 @@
-check_tags: deu|eng  #check if tag deu or eng was set
+tags:
+  check_tags: deu|eng  #check if tag deu or eng was set
+  forced: True
+  tag:
+    - {name: deu, _: For german strings}
+    - {name: eng, _: For english strings}
 
 name: tagging
 outpath: bench_run