removed the #swap syntax

everything has been carefully diffed to ensure there's no regression in the verified parts of the output

Force-Push: yes
Change-Id: I32c887c7ca8c132a49899d9ef327c8ff9fb782fb

1 files changed, 16 insertions, 35 deletions

diff --git a/transform.e b/transform.e
index e23453b..e69545e 100644
--- a/transform.e
+++ b/transform.e
@@ -3154,21 +3154,18 @@ allocate-transformation-state s" transformation-state" variable
 ~ swaps the top two items, and roll-subitems creates an
 ~ -entry-type-roll-subitems, which rolls them, or unrolls them with a negative
 ~ parameter.
+
+~   In general, the order in which provide-* commands execute will most likely
+~ match the order in which the corresponding bytes are output. This may not
+~ always match the order in which the comment template wants to pretty-print
+~ them. Therefore, you will want to use these commands to get the subitem
+~ stack in the proper order.
 ~
 ~   In using these commands that manipulate the subitem stack, it's important
 ~ to remember that, when formatting happens, the left-to-right output of
 ~ subitems in the final output comment is top-to-bottom on the subitem stack,
 ~ because they're popped in order. This is the opposite of the usual visual
 ~ representation of stacks, and can easily be confusing.
-~ TODO this seems worth a semantic change once the output vetting is done
-~
-~   One more thing: The order in which provide-* commands execute will most
-~ likely match the order in which the corresponding bytes are output. This may
-~ not always match the order in which the comment template wants to
-~ pretty-print them. Therefore, anywhere you can use # you can also use #swap
-~ to manipulate the subitem-entry stack. The #swap command must be its own
-~ separate space-delimited word within a comment body; the space immediately
-~ following it is stripped from the output.
 ~
 ~   It's probably clear from the extreme emphasis this documentation has taken
 ~ on describing the order things happen in, but it is quite common to define
@@ -3901,31 +3898,11 @@ allocate-transformation-state s" transformation-state" variable
         ~ return a zero to indicate that.
         drop 0
       } {
-        dup s" #swap" stringcmp 0 = {
-          ~ (input point, first non-word character or 0, word pointer)
-          drop
-
-          ~   If we underflow the stack, we'll get zeroes back here. In order
-          ~ to avoid causing more confusing problems later, we make sure to
-          ~ discard the zeroes instead of pushing them. As above, the
-          ~ reasoning is that it's easier to diagnose what's wrong with this
-          ~ subsystem when it runs to completion.
-          pop-subitem-entry-stack
-          pop-subitem-entry-stack
-          swap
-          dup { push-subitem-entry-stack } { drop } if-else
-          dup { push-subitem-entry-stack } { drop } if-else
-
-          ~   We want to ignore the next character, so that this word can be
-          ~ used without creating spurious spaces in the output.
-          1
-        } {
-          ~ (input point, first non-word character or 0, word pointer)
+        ~ (input point, first non-word character or 0, word pointer)
 
-          ~   Here as well, we want to treat the next character normally, so
-          ~ we return zero.
-          emitstring 0
-        } if-else
+        ~   Here as well, we want to treat the next character normally, so
+        ~ we return zero.
+        emitstring 0
       } if-else
       ~ (input point, first non-word character or 0, should ignore space)
 
@@ -4077,8 +4054,12 @@ allocate-transformation-state s" transformation-state" variable
 
         dup hex-output-metadata-entry-type @
         hex-output-metadata-entry-type-swap-subitems = {
-          ~   Just like in hex-emit-template-string, we want to make sure to
-          ~ discard the zeroes we get if we underflow the stack.
+          ~   If we underflow the stack, we'll get zeroes back here. In order
+          ~ to avoid causing more confusing problems later, we make sure to
+          ~ discard the zeroes instead of pushing them. Just like in
+          ~ hex-emit-template-string, the reasoning is that it's easier to
+          ~ diagnose what's wrong with this subsystem when it runs to
+          ~ completion.
           pop-subitem-entry-stack
           pop-subitem-entry-stack
           swap