From 91bff8b117cc3a87060411cf6c36a123452b8c22 Mon Sep 17 00:00:00 2001
From: Martin Krizek <mkrizek@redhat.com>
Date: Jun 17 2015 11:32:51 +0000
Subject: docs: Update 'Provided Variables' section


Differential Revision: https://phab.qadevel.cloud.fedoraproject.org/D391

---

diff --git a/docs/source/taskyaml.rst b/docs/source/taskyaml.rst
index 310ffcb..f4ff65f 100644
--- a/docs/source/taskyaml.rst
+++ b/docs/source/taskyaml.rst
@@ -89,13 +89,13 @@ dependencies are specified as part of the environment description.
 Task Execution
 ==============
 
-Every task is defined in the ``task`` block of the task yaml file. The task
-consists of one or more steps which consist of a name, directive and optional
+Every task is defined in the ``actions`` block of the formula yaml file. The task
+consists of one or more actions which consist of a name, directive and optional
 export of data.
 
 .. code-block:: yaml
 
-  task:
+  actions:
       - name: using directivename for something
         directivename:
             arg1: value1
@@ -106,7 +106,7 @@ export of data.
 Variable Storage and Syntax
 ---------------------------
 
-The task yaml file uses standard `string.Template`_ syntax for variables. You
+The formula yaml file uses standard `string.Template`_ syntax for variables. You
 can use ``$variable`` or ``${variable}`` format, and you need to make the dollar
 sign doubled if you want to include it literally (``$$not_a_variable``).
 Variables can be created during task execution or provided by default by the
@@ -120,15 +120,31 @@ Provided Variables
 The task runner provides the following variables without a need for them to be
 explicitly specified:
 
-  * ``workdir``
-  * ``jobid``
-
-.. note::
-
-  The ``jobid`` is used primarially for reporting to render proper log and job
-  urls. It can be specified on the command line but isn't required for local
-  execution. If a ``jobid`` is not explicitly provided at execution time, a
-  sane default value will be provided by the runner.
+  * ``artifactsdir`` contains a path to the artifacts directory. ``artifactsdir``
+    is used by tasks to store their various outputs like logs, archives,
+    images or any other output. Artifacts, the content of ``artifactsdir``,
+    are then exposed and accessible via http, e.g.
+    https://taskotron.fedoraproject.org/artifacts/20150423/0a93d8fa-ea09-11e4-9d4b-525400062113/.
+    See also uuid_.
+  * ``checkname``, not suprisingly, contains a task name of the task currently
+    being run by the runner. The reason why it's not called taskname rather
+    than ``checkname`` is that there were changes in Taskotron terminology
+    in the past and the name persisted. Before 3rd party task support is
+    introduced, the terminology will be unified.
+  * ``jobid`` is used primarially for reporting to render proper log and job
+    urls. It can be specified on the command line but isn't required for local
+    execution. If a ``jobid`` is not explicitly provided at execution time, a
+    sane default value will be provided by the runner.
+
+    .. _`uuid`:
+  * ``uuid`` is an identification of a run which is unique across all parts of
+    Taskotron. It can be specified on the command line. If a ``uuid`` is not
+    explicitly provided at execution time, a
+    sane default value will be provided by the runner.
+  * ``workdir`` is often used by :ref:`taskotron-directives` which store files
+    that serve as inputs for the task about to be run by the runner. ``workdir``
+    also can be used for temporary files that the task might need during its
+    execution.
 
 Created Variables
 -----------------
@@ -139,7 +155,7 @@ used later, it must first be exported.
 
 .. code-block:: yaml
 
-  task:
+  actions:
       - name: first step
         directive_one:
             arg1: value1