Arrows and flow
===============

An edge is one statement: the two shapes it joins and a glyph between them.
``->`` is an arrow, ``<-`` is the same arrow read the other way (``B <- A``
and ``A -> B`` are one edge), ``<->`` carries a head at both ends and ``--``
is a line with no heads. A shape named for the first time by an edge is
declared by it as a box, so the smallest diagrams need no ``box`` lines at
all:

.. sheeptext-example::
   :label: A simple arrow chain
   :alt: Three boxes connected left to right by arrows

   "queue" -> "worker" -> "store"

The text is the box's handle. Mention it again and you mean the same box;
give it a capitalised handle (``Queue``) and you can write the name bare.
A label follows the shape the arrow points at, and a chain labels each hop:

.. sheeptext-example::
   :label: A labelled arrow
   :alt: A start box with a labelled arrow leading to an end box

   A: box "start"
   B: box "end"
   A -> B "Leads to"

Two distinct boxes with one caption need explicit handles (``a: box "foo"``,
``b: box "foo"``, ``a -> b``). A handle that is a near miss of one you
declared still creates a new box. Here ``Revie`` is a third box, rather than
an arrow to ``Review``. The editor shows a non-blocking hint at ``Revie`` with
the declared name. Open the example and change ``Revie`` to ``Review``: the
extra box disappears and the arrow ends at the existing one.

.. sheeptext-example::
   :label: A near-miss name creates another box
   :alt: A Test box points to a new Revie box beside the existing Review box

   Test: box "Test suite"
   Review: box "Code review"
   Test -> Revie "report"

Next: add and format :doc:`text`.