minor changes in documentation

doc/src/cylc-user-guide/cug.tex

@@ -1869,7 +1869,8 @@ \subsection{Jinja2}
 \end{lstlisting}
 \lstset{language=suiterc}
 \begin{lstlisting}
-title = "A Jinja2 Hello World! suite"
+[meta]
+    title = "A Jinja2 Hello World! suite"
 [scheduling]
     [[dependencies]]
         graph = "hello"
@@ -1885,7 +1886,8 @@ \subsection{Jinja2}
 \end{lstlisting}
 \lstset{language=suiterc}
 \begin{lstlisting}
-title = "A Jinja2 Hello World! suite"
+[meta]
+    title = "A Jinja2 Hello World! suite"
 [scheduling]
     [[dependencies]]
         graph = "hello => BYE"
@@ -2256,7 +2258,8 @@ \subsection{Scheduling - Dependency Graphs}
 \begin{minipage}[b]{0.5\textwidth}
 \lstset{language=suiterc}
 \begin{lstlisting}
-title = "Dependency Example 1"
+[meta]
+    title = "Dependency Example 1"
 [cylc]
     UTC mode = True
 [scheduling]
@@ -2445,7 +2448,8 @@ \subsubsection{Graph Types}
 \begin{minipage}[b]{0.5\textwidth}
 \lstset{language=suiterc}
 \begin{lstlisting}
-title = some one-off tasks
+[meta]
+    title = some one-off tasks
 [scheduling]
     [[dependencies]]
         graph = "foo => bar & baz => qux"
@@ -2471,7 +2475,8 @@ \subsubsection{Graph Types}
 \begin{minipage}[b]{0.5\textwidth}
 \lstset{language=suiterc}
 \begin{lstlisting}
-title = some cycling tasks
+[meta]
+    title = some cycling tasks
 # (no dependence between cycle points)
 [scheduling]
     [[dependencies]]
@@ -3266,8 +3271,9 @@ \subsubsection{Trigger Types}
 \begin{minipage}[b]{0.5\textwidth}
 \lstset{language=suiterc}
 \begin{lstlisting}
-title = automated failure recovery
-description = """
+[meta]
+    title = automated failure recovery
+    description = """
 Model task failure triggers diagnosis
 and recovery tasks, which take themselves
 out of the suite if model succeeds. Model
@@ -5130,9 +5136,11 @@ \subsubsection{Jinja2 Default Values And Template Inputs}
 \begin{lstlisting}
 #!Jinja2
 
-title = "Jinja2 example: use of defaults and external input"
+[meta]
 
-description = """
+    title = "Jinja2 example: use of defaults and external input"
+
+    description = """
 The template variable FIRST_TASK must be given on the cylc command line
 using --set or --set-file=FILE; two other variables, LAST_TASK and
 N_MEMBERS can be set similarly, but if not they have default values."""

doc/src/cylc-user-guide/suiterc.tex

@@ -30,13 +30,13 @@ \subsection{[meta]}
 Section containing metadata items for this suite. Several items
 (title, description, URL) are pre-defined and are used by the GUI. Others can be 
 user-defined and passed to suite event handlers to be interpreted according to your 
-needs. For example, the value of an "suite-priority" item could determine how an event 
+needs. For example, the value of a ``suite-priority'' item could determine how an event 
 handler responds to failure events.
 
 
 \subsubsection[title]{ [meta] \textrightarrow title}
 
-A single line description of the suite. It is displayed in the db viewer
+A single line description of the suite. It is displayed in the GUI ``Open Another Suite''
 window and can be retrieved at run time with the
 \lstinline=cylc show= command.
 
@@ -47,8 +47,8 @@ \subsection{[meta]}
 
 \subsubsection[description]{ [meta] \textrightarrow description}
 
-A multi-line description of the suite. It can be retrieved by the db viewer
-right-click menu, or at run time with the \lstinline=cylc show= command.
+A multi-line description of the suite. It can be retrieved at run time with the
+\lstinline=cylc show= command.
 
 \begin{myitemize}
 \item {\em type:} multi-line string
@@ -342,7 +342,7 @@ \subsection{[cylc]}
     \item \%(message)s: event message, if any
 \end{myitemize}
 
-Can also include the patterns from [meta] section of the suite, for example:
+It can also include the patterns from the [meta] section of the suite, for example:
 \begin{myitemize}
     \item \%(suite-priority)s: suite priority
     \item \%(color)s: suite color
@@ -1267,7 +1267,17 @@ \subsection{[runtime]}
 needs. For example, the value of an "importance" item could determine how an event 
 handler responds to task failure events.
 
-\paragraph[title]{[runtime] \textrightarrow [[\_\_NAME\_\_]] \textrightarrow [[[meta]]] \textrightarrow title}
+Any suite meta item can now be passed to task event handlers by prefixing the
+string template item name with ``suite\_'', for example : 
+
+\begin{lstlisting}
+[runtime]
+    [[root]]
+        [[[events]]]
+            failed handler = send-help.sh %(suite\_title)s %(suite\_importance)s %(title)s
+\end{lstlisting}
+
+\subparagraph[title]{[runtime] \textrightarrow [[\_\_NAME\_\_]] \textrightarrow [[[meta]]] \textrightarrow title}
 
 A single line description of this namespace. It is displayed by the
 \lstinline=cylc list= command and can be retrieved from running tasks
@@ -1278,7 +1288,7 @@ \subsection{[runtime]}
 \item {\em root default:} (none)
 \end{myitemize}
 
-\paragraph[description]{[runtime] \textrightarrow [[\_\_NAME\_\_]] \textrightarrow [[[meta]]] \textrightarrow description}
+\subparagraph[description]{[runtime] \textrightarrow [[\_\_NAME\_\_]] \textrightarrow [[[meta]]] \textrightarrow description}
 
 A multi-line description of this namespace, retrievable from running tasks with the
 \lstinline=cylc show= command.
@@ -1288,7 +1298,7 @@ \subsection{[runtime]}
 \item {\em root default:} (none)
 \end{myitemize}
 
-\paragraph[URL]{[runtime] \textrightarrow [[\_\_NAME\_\_]] \textrightarrow [[[meta]]] \textrightarrow URL}
+\subparagraph[URL]{[runtime] \textrightarrow [[\_\_NAME\_\_]] \textrightarrow [[[meta]]] \textrightarrow URL}
 \label{TaskURL}
 
 A web URL to task documentation for this suite.  If present it can be browsed
@@ -1314,7 +1324,7 @@ \subsection{[runtime]}
 (Note that URLs containing the suite comment delimiter
 \lstinline=#= must be protected by quotes).
 
-\paragraph[\_\_MANY\_\_]{[runtime] \textrightarrow [[\_\_NAME\_\_]] \textrightarrow [[[meta]]] \textrightarrow \_\_MANY\_\_}
+\subparagraph[\_\_MANY\_\_]{[runtime] \textrightarrow [[\_\_NAME\_\_]] \textrightarrow [[[meta]]] \textrightarrow \_\_MANY\_\_}
 
 Replace \_\_MANY\_\_ with any user-defined metadata item. These, like title, URL, etc. can be passed
 to task event handlers to be interpreted according to your needs. For example, the value of an
@@ -1624,13 +1634,13 @@ \subsection{[runtime]}
     \item \%(message)s: event message, if any
 \end{myitemize}
 
-Can include the patterns from [[[meta]]] section of the task, for example:
+The template can also include the patterns from [[[meta]]] section of the task, for example:
 \begin{myitemize}
     \item \%(importance)s: task priority
     \item \%(color)s: task color
 \end{myitemize}
 
-Also able to include patterns from [meta] section of the suite, for example:
+Patterns from the [meta] section of the suite can also be used, for example:
 \begin{myitemize}
     \item \%(suite\_priority)s: suite priority
     \item \%(suite\_color)s: suite color