admin-doc: Document how to use variables

1 files changed, 28 insertions, 2 deletions

diff --git a/doc/admin/000.mdwn b/doc/admin/000.mdwn
index cb15f91..984832b 100644
--- a/doc/admin/000.mdwn
+++ b/doc/admin/000.mdwn
@@ -297,8 +297,7 @@ so the following is equivalent to the above.
 
 Gitano defines a number of variables to be used in conditions. See
 table. These provide values that predicates test. The list of values
-depends on the operation being run. FIXME: Need help from Daniel to
-complete a table.
+depends on the operation being run.
 
 Table: Gitano variables
 
@@ -335,6 +334,33 @@ ref update   newsha              SHA1 Object ID of the new tip of the ref
 ref update   oldsha              SHA1 Object ID of the tip of the ref before the update.
 ------------ ------------------- -----------------------------------------------------------------------
 
+Variables are used as interpolations for the value of a predicate.
+
+Interpolations are written in the form `${variable}`.
+If the variable is not defined then it expands to the empty string.
+
+So a rule that permits the owner of a repository to do whatever they want is:
+
+    define repo_is_set repository pcre .
+    define is_owner config/project/owner exact ${user}
+    allow "Owners may do anything to repositories they own" repo_is_set is_owner
+
+Since `user` and `config/project/owner` are both predicates and variables
+`is_owner` can be written the other way around too.
+
+    define is_owner user exact ${config/project/owner}
+
+The only constraint to worry about is that variables can't have multiple values.
+So `group` can't be used as a variable, but can be a predicate.
+
+If you had a config option for the contributors to a project
+you would be unable to check it with:
+
+    define is_contributor user exact ${config/project/contributors}
+
+However it you could check for it with:
+
+    define is_contributor config/project/contributors exact ${user}
 
 ## Include statements in rulesets