From b256744c32629da33147327cab41d973f5313ca7 Mon Sep 17 00:00:00 2001
From: Mike Gerwitz <gerwitm@lovullo.com>
Date: Tue, 24 Mar 2015 13:48:11 -0400
Subject: [PATCH] NEGATE moved into `numeric/common' with _negate_

Together with documentation.
---
 core/base.xml           | 12 +----
 core/numeric/common.xml | 99 +++++++++++++++++++++++++++--------------
 2 files changed, 66 insertions(+), 45 deletions(-)

diff --git a/core/base.xml b/core/base.xml
index 1b893ab7..2fad3cd2 100644
--- a/core/base.xml
+++ b/core/base.xml
@@ -99,17 +99,7 @@
 
 
   <section title="Convenience">
-    Negation is a common task and it was tedious in older versions of
-    TAME\footnote{Before it was even called TAME, actually.}  For
-    these situations, \ref{NEGATE} is provided to avoid having to use
-    a~\ref{const} expression.
-
-    <const name="NEGATE" value="-1"
-           desc="Negate a value"
-           sym="-" />
-
-
-    Similarly, $0$~is a~common value.  Where a value is required (such
+    $0$~is a~common value.  Where a value is required (such
     as a~template argument), \ref{ZERO} may be used.  TAME now
     supports a~constant-scalar syntax ({\tt #0}; \todo{reference this
     in documentation}), making this largely unnecessary.
diff --git a/core/numeric/common.xml b/core/numeric/common.xml
index 3e7c1fcd..44fe0b29 100644
--- a/core/numeric/common.xml
+++ b/core/numeric/common.xml
@@ -26,54 +26,85 @@
   <import package="../base" />
 
 
-  <template name="_inc_" desc="Increment value [by 1]">
-    <param name="@values@" desc="Value to increment (nodes)" />
 
-    <param name="@value@" desc="Value to decrement by (default 1)">
-      <text>1</text>
-    </param>
+  <section title="Stepping">
+    Due to the declarative nature of~TAME, recursive operations
+    needing to step are~not all that common.  These operations are
+    useful when converting between 1-indexed and 0-indexed data.
 
-    <c:sum>
-      <param-copy name="@values@" />
-      <c:const value="@value@" type="integer" desc="Increment by 1" />
-    </c:sum>
-  </template>
+    \ref{_inc_} increments a value by a~single step (default~1).
+
+    <template name="_inc_"
+              desc="Increment value [by 1]">
+      <param name="@values@" desc="Value to increment (nodes)" />
+
+      <param name="@value@" desc="Value to decrement by (default 1)">
+        <text>1</text>
+      </param>
+
+
+      <c:sum>
+        <param-copy name="@values@" />
+
+        <c:const value="@value@"
+                 desc="Increment by 1" />
+      </c:sum>
+    </template>
+
+
+    \ref{_dec_} decrements a value by a~single step (default~1).
+
+    <template name="_dec_"
+              desc="Decrement value [by 1]">
+      <param name="@values@" desc="Value to decrement (nodes)" />
+
+      <param name="@value@" desc="Value to decrement by (default 1)">
+        <text>1</text>
+      </param>
+
+
+      <c:sum>
+        <param-copy name="@values@" />
+
+        <t:negate>
+          <c:const value="@value@"
+                   desc="Decrement by 1" />
+        </t:negate>
+      </c:sum>
+    </template>
+  </section>
 
 
 
-  <template name="_dec_" desc="Decrement value [by 1]">
-    <param name="@values@" desc="Value to decrement (nodes)" />
+  <section title="Negation">
+    Negation is a common task and it was tedious in older versions of
+    TAME\footnote{Before it was even called TAME, actually.}  For
+    these situations, \ref{NEGATE} is provided to avoid having to use
+    a~\ref{const} expression.  To avoid a {\tt product} expression
+    altogether, use~\ref{_negate_}.
 
-    <param name="@value@" desc="Value to decrement by (default 1)">
-      <text>1</text>
-    </param>
+    <const name="NEGATE" value="-1"
+           desc="Negate a value"
+           sym="-" />
 
 
-    <c:sum>
-      <param-copy name="@values@" />
+    <template name="_negate_"
+              desc="Negate an expression">
+      <param name="@values@" desc="Expression to negate" />
+      <param name="@label@"  desc="Application label (default empty)">
+        <text></text>
+      </param>
 
-      <c:product>
+      <c:product label="@label@">
         <c:value-of name="NEGATE" />
-        <c:const value="@value@" type="integer" desc="Decrement by 1" />
+        <param-copy name="@values@" />
       </c:product>
-    </c:sum>
-  </template>
+    </template>
+  </section>
 
 
 
-  <template name="_negate_" desc="Negate a value">
-    <param name="@values@" desc="Value to decrement (nodes)" />
-    <param name="@label@" desc="Application label">
-      <!-- default empty -->
-      <text></text>
-    </param>
-
-    <c:product label="@label@">
-      <c:value-of name="NEGATE" />
-      <param-copy name="@values@" />
-    </c:product>
-  </template>
-
+  <!-- Everything below this line must be moved. -->
 
 
   <template name="_percent-of_" desc="Take percentage of a value">