The <<revision>> macro is a more powerful variation of the <<replace>> macro. It lets you alter a span of passage text by clicking a link from anywhere in the passage.

Code:

Use the script code here: http://www.glorioustrainwrecks.com/files/TwineMacros-Revision-1.1.0.txt
Just as with <<replace>>, you also could do with some CSS. I recommend, for starters:

.revision-span-in {
	opacity: 0;
}
.revision-span:not(.revision-span-out) {
	transition: 1s;
	-webkit-transition: 1s;
}
.revision-span-out {
	position:absolute;
	opacity: 0;
}

Basic usage
First, use the <<revision>> macro to define two different versions of some text:

You see here <<revision tome>>a closed book.<<becomes>>an open book.<<endrevision>> Each section of text separated by <<becomes>> is a different "version" of the text. The name "tome" in the macro is an identifier. You can use any single word you want as an identifier.

Then, you can create a link using the <<revise>> like so:
<<revise tome "Open the book.">>
This creates a link reading "Open the book" that changes any "tome" revision in the passage into the next version - in this case, changing "a closed book" into "an open book".

(Notice that the word "revise" is the verb form of "revision", reflecting the fact that the hyperlink serves as a verb for the player to perform.)

Running code in revisions
Just like with <<replace>>, any macros inside a revision are run as soon as they are made to appear:

<<revision button>>You see a button.<<becomes>>The button is pushed.<<set $button=true>><<endrevision>>
<<revise button "Push it.">>

The above code will set $button to true when you click the "Push it." link.

Multiple versions
You can have many versions of a span of text:

You see here <<revision books>>a closed book.<<becomes>>a chewed book.<<becomes>>paper scraps.<<endrevision>>
<<revise books "Chew book">>

In this case, the link "Chew book" will change "a closed book" into "a chewed book", then "paper scraps". When it reaches the end, the link vanishes.

Back and forth
The <<revert>> macro functions to reverse the effects of the <<revise>> macro.

<<revision box>>Here is a closed box.<<becomes>>Here is an open box.<<endrevision>>
<<revise box "Open the box.">>
<<revert box "Close the box.">>

The <<revert>> macro's link won't be displayed if it's at the first revision, just as the <<revise>> macro won't be visible if it's at the last revision.

<<hoverrevise>>
Click here to read about <<hoverrevise>>.

<<becomes>> vs. <<gains>>
Just as the <<replace>> macro has a variation, <<insert>>, so too does <<becomes>>.

The vase contains:<<revision vase>>Two roses<<gains>>, an orchid<<gains>>, a pencil<<gains>>, a straw<<endrevision>>.
<<revise vase "Put something in the vase">>.

When you click "Put something in the vase", the text changes from "Two roses" to "Two roses, an orchid", then to "Two roses, an orchid, a pencil" and so forth.

You can mix and match <<gains>> and <<becomes>> at will:

<<revision count>>One<<becomes>>Two<<gains>>and a half<<becomes>>Three!<<endrevision>>

This changes from "One" to "Two", "Two and a half", and finally "Three!".

<<cycle>>
Normally, when a <<revision>> macro reaches the end of its revisions, its links disappear. If you change "revision" to "cycle", then you can keep clicking the link to return to the first revision.

You see here <<cycle pet>>a dog<<becomes>>a cat<<endcycle>>.
<<revise pet "Change pet">>

This will change "a dog" to "a cat" and vice-versa, with the link never expiring.

<<insertion>> and <<removal>>
Two other variations exist, which are roughly analogous to <<timedinsert>> and <<timedremove>>.
You look at the plate. <<insertion grain>>1 grain.<<becomes>>2 grains.<<becomes>>3 grains.<<endinsertion>>
For <<insertion>>, the first version "1 grain" is initially invisible. Clicking a <<revise>> link will make it visible. Then, it functions as normal.
You look at the plate. <<removal seed>>3 seeds.<<becomes>>2 seeds.<<becomes>>1 seed.<<endremoval>>
For <<removal>>, the <<revise>> link will remain when you get to "1 seed". Clicking it a final time will remove the text altogether.

Example program
http://www.glorioustrainwrecks.com/files/TwineMacro-RevisionTest.html

Technical details

1. Each version inside a <<revision>> macro is a <span> classed with "revision-span" as well as the kind of version they are ("becomes", "gains"). When they appear, they are given the class "revision-span-in" and their display is set to "inline". When they disappear, they gain the class "revision-span-out" and, after 1 second, their display is set to "none". All of these are inside a container <span> classed with the name of the macro ("insertion", "removal", "cycle", "revision") and the name of the identifier ("book" or whatever the author set it to be).

Version history:

1. 20-4-2013: Added <<hoverrevise>> and support for <<randomise>>.
2. 18-4-2013: Initial

Attachment	Size
TwineMacro-RevisionTest.html	68.47 KB
TwineMacros-Revision-1.1.0.txt	8.18 KB