Editing Diagrams/Dev/Arrows (section)

== A History of Arrow.hs ==

=== ScaleInv ===
The original semantics we choose for arrows was for only the shaft length to
change under scaling transformations. This was done not only because we
wanted the head size (from here on what ever I say about head applies to
tail as well) to remain constant, but becuase non-uniorm scalings would cause
the head to point in the wrong direction. See http://projects.haskell.org/diagrams/doc/manual.html#scale-invariance. It
turned out that our solution (wrapping the head in the `ScaleInv` wrapper) was
not enough. Once an arrow was stroked, it would not behave correctly under scales.
We solved the problems of keeping the head size constant and making the arrow
point in the correct direction, but now a scaling could cause the head and shaft
to separate. As explained in https://github.com/diagrams/diagrams-lib/issues/112.
Hence the birth of delayed subtrees.

=== DelayedLeaf ===
At the risk of stating the obvious,
<code>Diagrams</code> (i.e. <code>DualTree</code>s) are created from the bottom (leaves) up, but <code>DTree</code>s
and <code>RTrees</code> from the top (root) down. Suppose we are creating an arrow using
diagrams functions and combinators. When we are finished we have essentially added
a subtree to a diagram. That subtree cannot use any of the informtion about
transforms and styles above it in the tree (they have not yet been created) so
the arrow is unable to use its final size and location (i.e. accumulated
transform) in its subtree. Brent's elegant solution was twofold:
# To hold off on creating the arrow by creating a new type of leaf, the <code>DelayedLeaf</code> in addition to <code>Prim b v</code> that we already had. The <code>DelayedLeaf</code> contains a funtion <code>DownAnnots v -> QDiagram b v m</code>, in other words a set of instructions about how to create the arrow once its <code>DownAnnots</code> are known.
# A modification of the <code>arrow'</code> function so that it returns a <code>DelayedLeaf</code>. The function wrapped in the <code>DelayedLeaf</code>, <code>delayedArrow</code> takes as parameter the <code>DownAnnots</code> and hence the styles and transforms.
The upshot is that an arrow gets to know the accumulated <code>DownAnnots</code> above it
to use it's conversion to a diagram.

Since creation of a <code>DTree</code> is top down, by the time
we reach a <code>DelayedLeaf</code> in the `DualTree` we already have all of the accumlated
transforms and styles that will be applied to the arrow. So the <code>DelayedLeaf</code>
can be expanded by running the function <code>DownAnnots v -> QDiagram b v m</code> on
the accumulated <code>DownAnnots</code> and recursively calling <code>fromDTree</code> to insert the
arrow into the <code>DTree</code>. It is import ant to note, though at this point the arrow
is essentially finished, all transforms and style have been applied. By the way, I'm pretty sure that at this point we could have removed the <code>scaleInv</code> wrapper from the head.

(As a side benefit, we are able to use all of the
styles that are applied above the arrow in the tree to do things like change
the color of the entire arrow with functions like <code>lc red</code>.)

There were still some enhancements we wanted to make,
https://github.com/diagrams/diagrams-lib/issues/162, but for the most part all
was well in Arrow land until ...

=== Measure ===
With the death of <code>freeze</code> and the switch to <code>Measure</code> in the units branch, it
seems like <code>headSize</code> should have a value of <code>Measure Double</code>. This means that
<code>headSize</code> can have one of four possible units:
# <code>Local</code> which are transformable and in particular scalable. Note that this is in contrast with our original notion of arrows having scale invariant heads. Although it is somewhat similar in behavior to a <code>freeze</code> followed by a uniform scaling.
# <code>Output</code> this is what we have in 1.1.
# <code>Global</code> which scales based on the final size of the diagram.
# <code>Normalized</code> which scales in relation to a logical size.

See http://www.haskell.org/haskellwiki/Diagrams/Dev/Freezing for more detail
or even better the implementation of `convert` in the units branch,
https://github.com/diagrams/diagrams-core/blob/units/src/Diagrams/Core/Compile.hs#L167.

The backends should only see <code>Output</code> units therefore before passing an <code>RTree</code>
to a backend, all <code>Measure</code>s must be converted to <code>Output</code>. This is done by
traversing the <code>RTree</code> and returning a new <code>RTree</code> where all of the <code>Measure</code>s
have been properly converted. The important thing to notice is that this occurs
after the <code>DelayedLeaf</code> has been expanded and hence the arrow cannot make
any use to the units change to render.

=== What to do ===
I really don't know but some things to think about are:
# I don't think it is possible to adjust the arrow <code>Measure</code> at the <code>RTree</code> level, since arrows make no further use of units after the <code>delayedArrow</code> function is executed during the conversion to <code>DTree</code>. Unless we can come up with another way of creating arrows.
# Does every attribute with a value of <code>Measure</code> have to implement all 4 value types? In particular is it OK for arrows to only implement <code>Output</code> and <code>Local</code>. If this is what we decide then we are done.
# Move the conversion to <code>Output</code> units back up to the <code>QDiagram -> DTree</code> level. We tried this and decided it was a bad idea.
# Find another way (as opposed to delayed leaves) to handle arrows.