From 1b9f247f4c0dc8dbc8e3f1d336bde29612d0df7e Mon Sep 17 00:00:00 2001
From: Matt Shin <matthew.shin@metoffice.gov.uk>
Date: Thu, 18 Jan 2018 09:03:33 +0000
Subject: [PATCH 1/2] CUG: doc param logical quirk

---
 doc/src/cylc-user-guide/cug.tex | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/doc/src/cylc-user-guide/cug.tex b/doc/src/cylc-user-guide/cug.tex
index e338a79f9b..426a12f8a0 100644
--- a/doc/src/cylc-user-guide/cug.tex
+++ b/doc/src/cylc-user-guide/cug.tex
@@ -4779,6 +4779,20 @@ \subsubsection{Parameter Offsets In The Graph}
     graph = "proc_small => proc_big => proc_huge"
 \end{lstlisting}
 
+However, a mixture of conditional logic in these statements may create
+surprises. For example:
+
+\begin{lstlisting}
+    graph = foo<m-1> & baz => foo<m>  # for m = cat, dog
+\end{lstlisting}
+currently expands to:
+\begin{lstlisting}
+    graph = foo_cat & baz => foo_dog
+# when users may expect it to be:
+#    graph = foo_cat => foo_dog
+#    graph = baz => foo_cat & foo_dog
+\end{lstlisting}
+
 \subsubsection{Task Families And Parameterization}
 
 Task family members can be generated by parameter expansion:

From ee2d5f239fff7b4256f52c0422255b1d9617b93a Mon Sep 17 00:00:00 2001
From: Matt Shin <matthew.shin@metoffice.gov.uk>
Date: Mon, 22 Jan 2018 15:13:52 +0000
Subject: [PATCH 2/2] Doc: param logical quirk with heavier statement

---
 doc/src/cylc-user-guide/cug.tex | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/doc/src/cylc-user-guide/cug.tex b/doc/src/cylc-user-guide/cug.tex
index 426a12f8a0..4a191653eb 100644
--- a/doc/src/cylc-user-guide/cug.tex
+++ b/doc/src/cylc-user-guide/cug.tex
@@ -4779,8 +4779,9 @@ \subsubsection{Parameter Offsets In The Graph}
     graph = "proc_small => proc_big => proc_huge"
 \end{lstlisting}
 
-However, a mixture of conditional logic in these statements may create
-surprises. For example:
+However, a quirk in the current system means that you should avoid mixing
+conditional logic in these statements. For example, the following will do the
+unexpected:
 
 \begin{lstlisting}
     graph = foo<m-1> & baz => foo<m>  # for m = cat, dog
@@ -4793,6 +4794,14 @@ \subsubsection{Parameter Offsets In The Graph}
 #    graph = baz => foo_cat & foo_dog
 \end{lstlisting}
 
+For the time being, writing out the logic explicitly will give you the correct
+graph.
+
+\begin{lstlisting}
+    graph = """foo<m-1> => foo<m>  # for m = cat, dog
+               baz => foo<m>"""
+\end{lstlisting}
+
 \subsubsection{Task Families And Parameterization}
 
 Task family members can be generated by parameter expansion: