diagram(n)                   Documentation toolbox                  diagram(n)



______________________________________________________________________________

NAME
       diagram - Diagram drawing

SYNOPSIS
       package require Tcl  8.5

       package require Tk  8.5

       package require diagram  1

       ::diagram objectName canvas ?script?

       diagramObject new direction name ?key value...?

       diagramObject new element name attributes cmdprefix

       diagramObject new alias name cmdprefix

       diagramObject new command name arguments body

       diagramObject new attribute name ?key value...?

       diagramObject unknown attribute cmdprefix

       diagramObject draw script

       arc attr...

       arrow attr...

       --> attr...

       <--> attr...

       <--> attr...

       block script attr...

       box attr...

       circle attr...

       O attr...

       diamond attr...

       <> attr...

       drum attr...

       ellipse attr...

       line attr...

       -- attr...

       move attr

       spline attr...

       text attr...

       west

       w

       left

       l

       south

       s

       down

       bottom

       bot

       b

       east

       e

       right

       r

       north

       n

       up

       top

       t

       northwest

       nw

       up-left

       upleft

       leftup

       northeast

       ne

       up-right

       upright

       rightup

       southwest

       sw

       down-left

       downleft

       leftdown

       southeast

       se

       down-right

       downright

       rightdown

       number cm

       number mm

       number inch

       number pt

       number number

       by distance direction

       point1 + point2

       point1 - point2

       point by distance direction

       point1 | point2

       n between poin1 point2

       intersect elem1 elem2

       element names ?pattern?

       element corner

       element corner1 corner2...

       element ?corner1... ?names ?pattern??]?

       nth ?corner?

       nth last ?corner?

       nth shape ?corner?

       nth last shape ?corner?

       last ?corner?

       last shape ?corner?

       1st

       2nd

       3rd

______________________________________________________________________________

DESCRIPTION
       Welcome to diagram, a package for the easy construction of diagrams
       (sic), i.e. 2D vector graphics, sometimes also called pictures.  Note
       that this package is not a replacement for Tk's canvas, but rather a
       layer sitting on top of it, to make it easier to use.  In other words,
       using the canvas as the core graphics engine diagram abstracts away
       from the minutiae of handling coordinates to position and size the
       drawn elements, allowing the user to concentrate on the content of the
       diagram instead.

       This is similar to Brian Kernighan's PIC language for troff, which is
       the spiritual ancestor of this package.

       This document contains the reference to the API and drawing (language)
       commands. Its intended audience are users of the package wishing to
       refresh their memory.  Newcomers should read the Diagram Language
       Tutorial first.  Developers wishing to work on the internals of the
       package and its supporting packages should look at section Diagram
       Classes first, and then the comments in the sources of the packages
       itself.

       In the remainder of the document we first describe the APIs of the
       diagram class and its instances, followed by the language reference for
       the drawing language itself.

API
   CLASS API
       The package exports the API described here.

       ::diagram objectName canvas ?script?
              The command creates a new instance of a diagram controller and
              returns the fully qualified name of the object command as its
              result.  The new instance is connected to the specified canvas
              object, which is used as the diagrams graphics engine. This is
              usually an instance of Tk's canvas, however any object which is
              API compatible to Tk's canvas can be used here.

              The API of this object command is described in the following
              section, Object API. It may be used to invoke various operations
              on the object.

              If the script argument is specified then method draw will be
              invoked on it.

   OBJECT API
       Instances of the diagram class support the following methods:

       diagramObject new direction name ?key value...?
              This method defines a new named direction and its attributes.
              The latter is given through the key/value pairs coming after the
              name.

              Users are mostly free to specify arbitrary attributes with
              whatever meaning they desire. The exception are the names angle
              and opposite. They are special to the diagram package and have a
              fixed meaning.

              angle  This attribute specifies the angle of the direction in
                     degrees, where 0 points east (to the right) and 90 points
                     north (up).

              opposite
                     This attribute specifies the name of the direction which
                     should be considered as complementary to the named one.

       diagramObject new element name attributes cmdprefix
              This method defines a new graphics element for the drawing
              language. I.e. name will become a new command in the language,
              and the specified command prefix (cmdprefix) will be called to
              perform the actual drawing.

              attributes specifies the set of attributes for which data has to
              be available. I.e. the system will run the ...-callbacks for
              these attributes.  See the method new attribute for more
              information on attribute definitions.

              The command prefix is expected to conform to the following
              signature:

              cmdprefix canvas attributes
                     Where canvas is the handle of the canvas widget to draw
                     to, and attributes is a dictionary holding the attributes
                     for the element, be they user-specified, or defaults.

                     The results of the command has to be a list containing at
                     least two and at most four items. These are, in order:

                     [1]    The list of canvas items the drawn element
                            consists of.

                     [2]    The dictionary of named locations in the element,
                            its corners.

                     [3]    An optional mode, either "relative" or "absolute".
                            When not returned "relative" is assumed. In the
                            case of a relative element position the attributes
                            "with" and "at" are used to determine the final
                            position of the new element.

                     [4]    An optional name of a direction. If not the empty
                            string this is handed to the automatic layouter as
                            the new direction to follow.

       diagramObject new alias name cmdprefix
              This method defines a new command for the drawing language. I.e.
              name will become a new command in the language, and the
              specified command prefix (cmdprefix) will be called on use of
              this new command. Any arguments given to the command are simply
              passed to the prefix. There is no fixed siganture.

              Note that the prefix is run in the context of the drawing
              language, allowing the direct use of any existing commands.

       diagramObject new command name arguments body
              This is like new alias except that the new command is defined as
              a procedure in the language's context, with regular argument
              list and body.

       diagramObject new attribute name ?key value...?
              This method defines a new named attribute which can be used by
              graphical elements. The handling of the attribute by the
              processor is declared through the key/value pairs coming after
              the name.

              The accepted keys and their meanings are:

              key    The value of this key is the name of the key under which
                     the attribute's value shall be stored in the attribute
                     dictionary given to the drawing command after attribute
                     processing is complete.

                     This key is optional. If it is not specified it defaults
                     to the name of the attribute.

              get    The value of this key is a command prefix which will be
                     invoked to retrieve the attribute's argument(s) from the
                     command line.

                     This key is optional. If it is not specified a default is
                     used which takes the single word after the attribute name
                     as the attribute's value.

                     The signature of the command prefix is

                     cmdprefix wordqueue
                            Where wordqueue is the handle of a queue object
                            conforming to the API of the queues provided by
                            package struct::queue. This queue contains the
                            not-yet-processed part of the attribute
                            definitions, with one entry per word, with the
                            first entry the word after name of the attribute.
                            In other words, the attribute's name has already
                            been removed from the queue.

                            The result of the command is the value of the
                            attribute, which may have been taken from the
                            queue, or not.

              transform
                     The value of this key is a command prefix which will be
                     invoked to transform the retrieved value (See get) into
                     their final form.

                     This key is optional. If it is not specified no
                     transformation is done.  The signature of the command
                     prefix is

                     cmdprefix value
                            Where value is the value to transform.

                            The result of the command is the final value of
                            the attribute.

              type   The value of this key is a command prefix which will be
                     invoked to validate the attribute's argument(s).

                     This key is optional. If it is not specified no
                     validation is done.

                     The signature of the command prefix is that of snit
                     validation types. See the documentation of the snit
                     package.

              merge  The value of this key is a command prefix which will be
                     invoked to insert the transformed and validated attribute
                     value into the dictionary of collected attributes.

                     This key is optional. If it is not specified a default
                     merge is chosen, based on the data for key aggregate, see
                     below.  The signature of the command prefix is

                     cmdprefix value dict
                            Where value is the value to insert, and dict the
                            dictionary of attributes and values collected so
                            far.

                            The result of the command is the new dictionary of
                            attributes.

              aggregate
                     The value of this key is a boolean flag. It has an effect
                     if and only if the key merge was not specified. This key
                     is optional. If it is not specified it defaults to False.

                     If the key is effective, the value of False means that
                     the attribute's value is set into the dictionary using
                     the value of key key (see above) as index, overwriting
                     any previously specified value.

                     If the key is effective, the value of True means that the
                     attribute's value is added to the dictionary using the
                     value of key key (see above) as index, extending any
                     previously specified value.  This means that the final
                     value of the attribute as seen after processing will be a
                     list of the collected values.

              default
                     The value of this key is a command prefix which will be
                     invoked after collection of attributes has been completed
                     and this attribute is in the list of required attributes
                     for the drawing element (See argument attributes of
                     method new element).

                     Note that the connection is made through the value of key
                     key, not through the attribute name per se.

                     Further note that this command prefix is invoked even if
                     a user specified attribute value is present. This allows
                     the command to go beyond simply setting defaults, it can
                     calculate and store derived values as well.

                     This key is optional. If an element requires this
                     attribute, but default is not specified then nothing will
                     be done.

                     The signature of the command prefix is

                     cmdprefix init
                            This method is run when the attribute is defined,
                            its responsibility is to initialize anything in
                            the language namespace for the attribute and
                            default processing.

                            The result of this method is ignored.

                     cmdprefix fill varname
                            This method is run to put defaults, or derived
                            values into the attribute dictionary named by
                            varname. This variable will be found in the
                            calling context.

                            The result of this method is ignored.

                     cmdprefix set name value
                            This method is run to push current a attribute
                            value into the language namespace, to make it the
                            new default.

                            The result of this method is ignored.

              linked This key is effective if and only if key default is not
                     specified. In that case is supplies a default handling
                     for default, linking the attribute to a variable in the
                     language context.

                     The value for this key is a 2-element list containing the
                     name of the variable to link to, and its initial value,
                     in this order.

       diagramObject unknown attribute cmdprefix
              This method registers the command prefix with the subsystem
              processing the attributes for element commands, telling it to
              call it when it encounters an attribute it is unable to handle
              on its on.

              It is allowed to register more than callback, these will be
              called in order of registration (i.e. first to last), until one
              of the callbacks accepts the current input.  The command prefix
              is expected to conform to the following signature:

              cmdprefix wordqueue
                     Where wordqueue is the handle of a queue object
                     conforming to the API of the queues provided by package
                     struct::queue.  This queue contains the not-yet-processed
                     part of the attribute definitions, with one entry per
                     word, with the first entry the name of the attribute
                     which could not be processed.

                     The results of the command has to be a boolean value
                     where True signals that this callback has accepted the
                     attribute, processed it, and the new state of the
                     wordqueue is where the general processing shall continue.

                     Given the signature the command has basically two ways of
                     handling (rewriting) the attributes it recognizes:

                     [1]    Replace the attribute (and arguments) with a
                            different attribute and arguments.

                     [2]    Push additional words in front to get the general
                            processing unstuck.

       diagramObject draw script
              This method runs the given script in the context of the drawing
              language definitions.  See section Language Reference for
              details on the available commands.

              Note that script is trusted.  It is executed in the current
              interpreter with access to its full abilities.  For the
              execution of untrusted diagram scripts this interpreter should
              be a safe one.

LANGUAGE REFERENCE
   ELEMENTS
       This section lists the commands for the predefined drawing elements,
       aka shapes. These commands are all defined in the language's context.
       All commands of this section return the handle of the newly created
       element as their result. This handle also exists as a command which can
       be used to query the element for its corners (names, values).  See
       section Miscellaneous Commands.  IMAGE: figure-02-basic-shapes

       arc attr...
              IMAGE: figure-02-arc An open element with the corresponding
              corners, i.e. "start", "end", and "center".  Note however that
              it also has the compass rose of closed elements as its corners,
              with the center of the arc's circle as the center of the compass
              and the other points on the circle the arc is part of.  It
              handles the attributes

              anchor name

              ljust

              rjust

              above

              below  IMAGE: figure-22-text-anchoring-3 Specifies the anchor of
                     the text which is to be placed at the element's center,
                     by name. I.e. this attribute defines the text's position
                     relative to the element's center.  The value is ignored
                     if no text was specified for the element.  If not
                     specified the system falls back to the value taken from
                     the language variable anchor, which itself defaults to
                     center.  The legal values are all those accepted by
                     Tk_GetAnchor
                     [http://www.tcl.tk/man/tcl8.5/TkLib/GetAnchor.htm].  The
                     commands without arguments are all shorthands with the
                     anchor implied. Note that they do not combine, only the
                     last is used. For comined directions the main attribute
                     command, anchor has to be used.

                     ljust  "anchor west"

                     rjust  "anchor east"

                     above  "anchor south"

                     below  "anchor north"

              clockwise

              cw     Specifies the direction of the arc element, here going
                     clockwise.  The complementary attribute is
                     counterclockwise.  If not specified the system falls back
                     to the value taken from the language variable clockwise,
                     which itself defaults to false, for counter-clockwise
                     direction.

              color spec
                     IMAGE: figure-21-style-colors Specifies the color used to
                     draw the lines of the element.  If not specified the
                     system falls back to the value taken from the language
                     variable linecolor, which itself defaults to black.

              counterclockwise

              ccw    Specifies the direction of the arc element, here counter-
                     clockwise.  The complementary attribute is clockwise.  If
                     not specified the system falls back to the value taken
                     from the language variable clockwise, which itself
                     defaults to false, for counter-clockwise direction.

              fillcolor spec
                     IMAGE: figure-21-style-colors Specifies the color used to
                     draw the inside of the element.  If not specified the
                     system falls back to the value taken from the language
                     variable fillcolor, which itself defaults to the empty
                     string, signaling "no filling".

              from location
                     Specifies the location where the arc element begins.
                     Defaults to the current location as maintained by the
                     layouting system.

              justify left|center|right
                     Specifies how multi-line text associated with the element
                     is positioned within its box.  The value is ignored if no
                     text was specified for the element.  If not specified the
                     system falls back to the value taken from the language
                     variable justify, which itself defaults to left.  The
                     legal values are left, right, and center.

              radius length
                     Specifies the radius of the arc element, or rather, the
                     radius of the circle the shown arc is a part of.  If not
                     specified the system falls back to the value taken from
                     the language variable arcradius, which itself defaults to
                     the pixel equivalent of 1 cm.

              stroke width
                     IMAGE: figure-20-style-stroke Specifies the width of the
                     lines drawn for the the element, in pixels.  If not
                     specified the system falls back to the value taken from
                     the language variable linewidth, which itself defaults to
                     1.

              style spec
                     IMAGE: figure-18-style-dash Specifies the style used to
                     draw the lines of the element.  If not specified the
                     system falls back to the value taken from the language
                     variable linestyle, which itself defaults to solid lines.
                     The legal values are all those accepted by Tk_GetDash
                     [http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm], and
                     additionally all which are listed below:

                     solid, empty string
                            Draw solid line.

                     dash, dashed, -
                            Draw a dashed line.

                     dot, dotted, .
                            Draw a dotted line.

                     dash-dot, -.
                            Draw a dash-dotted line

                     dash-dot-dot, -..
                            Draw a dash-dot-dotted line.

                     Note that the values "solid", "dot(ted)", "dash(ed)",
                     "dash-dot", and "dash-dot-dot" are all accepted as
                     shorthands for the style command using them as argument.

              text string
                     Specifies the text to associate with the element.
                     Defaults to nothing.  When specified multiple times the
                     actually shown text is the concatenation of the
                     individual strings, vertically stacked, with the first
                     string specified being the topmost element.

              textcolor spec
                     Specifies the color used to draw the text of an element
                     with.  Ignored if there is no text.  If not specified the
                     system falls back to the value taken from the language
                     variable textcolor, which itself defaults to black.

              textfont spec
                     Specifies the font used to draw the text of an element
                     with.  Ignored if there is no text.  If not specified the
                     system falls back to the value taken from the language
                     variable textfont, which itself defaults to Helvetica
                     12pt.

              to location
                     Specifies the location where the arc element ends.
                     Defaults to a location such that a 90-degree arc is drawn
                     in the chosen direction, starting at from.

       arrow attr...

       --> attr...

       <--> attr...

       <--> attr...
              IMAGE: figure-02-arrow An alias for the line element (see
              below), with the attribute arrowhead preset to ->, <->, or <-.
              The arrow is equivalent to -->.

       block script attr...
              A closed element with the corresponding corners, i.e. the eight
              directions of the compass rose, and "center".  The main effect
              is the aggregration of all elements created by the script into
              one element.  This also means that while the elements created by
              the script are visible in the element history while the script
              is executing, afterward the history contains only the block
              itself, and not the elements it is composed of.

              The script has access to the current state of all variables in
              the language context.  Any changes to the variables will be
              reverted after execution of the block.  However, also, any
              variables set in the script will be exported as corners of the
              element, allowing users to define their own named locations in
              the block.

              Regarding the layout mechanism any changes made by the script
              are reverted after the element is done.  In other words, a block
              is an implicit group.

              Blocks handle all attributes, propgating their settings into the
              script as the default values active during script execution.

       box attr...
              IMAGE: figure-02-box A closed element with the corresponding
              corners, i.e. the eight directions of the compass rose, and
              "center".  It handles the attributes

              anchor name

              ljust

              rjust

              above

              below  IMAGE: figure-22-text-anchoring-3 Specifies the anchor of
                     the text which is to be placed at the element's center,
                     by name. I.e. this attribute defines the text's position
                     relative to the element's center.  The value is ignored
                     if no text was specified for the element.  If not
                     specified the system falls back to the value taken from
                     the language variable anchor, which itself defaults to
                     center.  The legal values are all those accepted by
                     Tk_GetAnchor
                     [http://www.tcl.tk/man/tcl8.5/TkLib/GetAnchor.htm].  The
                     commands without arguments are all shorthands with the
                     anchor implied. Note that they do not combine, only the
                     last is used. For comined directions the main attribute
                     command, anchor has to be used.

                     ljust  "anchor west"

                     rjust  "anchor east"

                     above  "anchor south"

                     below  "anchor north"

              at location
                     Specifies the location of the element's corner named by
                     the attribute with.  Defaults to the current location as
                     maintained by the layouting system.

              color spec
                     IMAGE: figure-21-style-colors Specifies the color used to
                     draw the lines of the element.  If not specified the
                     system falls back to the value taken from the language
                     variable linecolor, which itself defaults to black.

              fillcolor spec
                     IMAGE: figure-21-style-colors Specifies the color used to
                     draw the inside of the element.  If not specified the
                     system falls back to the value taken from the language
                     variable fillcolor, which itself defaults to the empty
                     string, signaling "no filling".

              height length

              ht length
                     Specifies the height of the element.  If not specified
                     the system falls back to the value taken from the
                     language variable boxheight, which itself defaults to the
                     pixel equivalent of 2 cm.

              justify left|center|right
                     Specifies how multi-line text associated with the element
                     is positioned within its box.  The value is ignored if no
                     text was specified for the element.  If not specified the
                     system falls back to the value taken from the language
                     variable justify, which itself defaults to left.  The
                     legal values are left, right, and center.

              slant angle
                     Specifies the angle by which the box element is slanted,
                     in degrees.  If not specified the system falls back to
                     the value taken from the language variable slant, which
                     itself defaults to 90, i.e. vertical, no slant.  0
                     degrees is slanting straight east, pointing to the right.
                     90 degrees is slanting to the north, pointing straight
                     up.

              stroke width
                     IMAGE: figure-20-style-stroke Specifies the width of the
                     lines drawn for the the element, in pixels.  If not
                     specified the system falls back to the value taken from
                     the language variable linewidth, which itself defaults to
                     1.

              style spec
                     IMAGE: figure-18-style-dash Specifies the style used to
                     draw the lines of the element.  If not specified the
                     system falls back to the value taken from the language
                     variable linestyle, which itself defaults to solid lines.
                     The legal values are all those accepted by Tk_GetDash
                     [http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm], and
                     additionally all which are listed below:

                     solid, empty string
                            Draw solid line.

                     dash, dashed, -
                            Draw a dashed line.

                     dot, dotted, .
                            Draw a dotted line.

                     dash-dot, -.
                            Draw a dash-dotted line

                     dash-dot-dot, -..
                            Draw a dash-dot-dotted line.

                     Note that the values "solid", "dot(ted)", "dash(ed)",
                     "dash-dot", and "dash-dot-dot" are all accepted as
                     shorthands for the style command using them as argument.

              text string
                     Specifies the text to associate with the element.
                     Defaults to nothing.  When specified multiple times the
                     actually shown text is the concatenation of the
                     individual strings, vertically stacked, with the first
                     string specified being the topmost element.

              textcolor spec
                     Specifies the color used to draw the text of an element
                     with.  Ignored if there is no text.  If not specified the
                     system falls back to the value taken from the language
                     variable textcolor, which itself defaults to black.

              textfont spec
                     Specifies the font used to draw the text of an element
                     with.  Ignored if there is no text.  If not specified the
                     system falls back to the value taken from the language
                     variable textfont, which itself defaults to Helvetica
                     12pt.

              width length

              wid length
                     Specifies the width of the element.  If not specified the
                     system falls back to the value taken from the language
                     variable boxwidth, which itself defaults to the pixel
                     equivalent of 2 cm.

              with corner
                     Specifies the corner of the element to place at the
                     location given by the attribute at.  Defaults to the
                     current corner as maintained by the layouting system,
                     except if the value for at was specified by the user. In
                     that case it defaults to center.

       circle attr...

       O attr...
              IMAGE: figure-02-circle A closed element with the corresponding
              corners, i.e. the eight directions of the compass rose, and
              "center".  It handles the attributes

              anchor name

              ljust

              rjust

              above

              below  IMAGE: figure-22-text-anchoring-3 Specifies the anchor of
                     the text which is to be placed at the element's center,
                     by name. I.e. this attribute defines the text's position
                     relative to the element's center.  The value is ignored
                     if no text was specified for the element.  If not
                     specified the system falls back to the value taken from
                     the language variable anchor, which itself defaults to
                     center.  The legal values are all those accepted by
                     Tk_GetAnchor
                     [http://www.tcl.tk/man/tcl8.5/TkLib/GetAnchor.htm].  The
                     commands without arguments are all shorthands with the
                     anchor implied. Note that they do not combine, only the
                     last is used. For comined directions the main attribute
                     command, anchor has to be used.

                     ljust  "anchor west"

                     rjust  "anchor east"

                     above  "anchor south"

                     below  "anchor north"

              at location
                     Specifies the location of the element's corner named by
                     the attribute with.  Defaults to the current location as
                     maintained by the layouting system.

              color spec
                     IMAGE: figure-21-style-colors Specifies the color used to
                     draw the lines of the element.  If not specified the
                     system falls back to the value taken from the language
                     variable linecolor, which itself defaults to black.

              diameter length

              diam length
                     Specifies the diameter of the circle element, as an
                     alternative way to specify its radius.  Effective if and
                     only if the radius was not specified. I.e. if both
                     diameter and radius are specified then the radius
                     infomration has precendence.  This attribute has no
                     default, because the defaults are taken from the radius.

              fillcolor spec
                     IMAGE: figure-21-style-colors Specifies the color used to
                     draw the inside of the element.  If not specified the
                     system falls back to the value taken from the language
                     variable fillcolor, which itself defaults to the empty
                     string, signaling "no filling".

              justify left|center|right
                     Specifies how multi-line text associated with the element
                     is positioned within its box.  The value is ignored if no
                     text was specified for the element.  If not specified the
                     system falls back to the value taken from the language
                     variable justify, which itself defaults to left.  The
                     legal values are left, right, and center.

              radius length

              rad length
                     Specifies the radius of the circle element.  If not
                     specified the system falls back to the value taken from
                     the language variable circleradius, which itself defaults
                     to the pixel equivalent of 1 cm.

              stroke width
                     IMAGE: figure-20-style-stroke Specifies the width of the
                     lines drawn for the the element, in pixels.  If not
                     specified the system falls back to the value taken from
                     the language variable linewidth, which itself defaults to
                     1.

              style spec
                     IMAGE: figure-18-style-dash Specifies the style used to
                     draw the lines of the element.  If not specified the
                     system falls back to the value taken from the language
                     variable linestyle, which itself defaults to solid lines.
                     The legal values are all those accepted by Tk_GetDash
                     [http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm], and
                     additionally all which are listed below:

                     solid, empty string
                            Draw solid line.

                     dash, dashed, -
                            Draw a dashed line.

                     dot, dotted, .
                            Draw a dotted line.

                     dash-dot, -.
                            Draw a dash-dotted line

                     dash-dot-dot, -..
                            Draw a dash-dot-dotted line.

                     Note that the values "solid", "dot(ted)", "dash(ed)",
                     "dash-dot", and "dash-dot-dot" are all accepted as
                     shorthands for the style command using them as argument.

              text string
                     Specifies the text to associate with the element.
                     Defaults to nothing.  When specified multiple times the
                     actually shown text is the concatenation of the
                     individual strings, vertically stacked, with the first
                     string specified being the topmost element.

              textcolor spec
                     Specifies the color used to draw the text of an element
                     with.  Ignored if there is no text.  If not specified the
                     system falls back to the value taken from the language
                     variable textcolor, which itself defaults to black.

              textfont spec
                     Specifies the font used to draw the text of an element
                     with.  Ignored if there is no text.  If not specified the
                     system falls back to the value taken from the language
                     variable textfont, which itself defaults to Helvetica
                     12pt.

              with corner
                     Specifies the corner of the element to place at the
                     location given by the attribute at.  Defaults to the
                     current corner as maintained by the layouting system,
                     except if the value for at was specified by the user. In
                     that case it defaults to center.

       diamond attr...

       <> attr...
              IMAGE: figure-02-diamond A closed element with the corresponding
              corners, i.e. the eight directions of the compass rose, and
              "center".  It handles the attributes

              anchor name

              ljust

              rjust

              above

              below  IMAGE: figure-22-text-anchoring-3 Specifies the anchor of
                     the text which is to be placed at the element's center,
                     by name. I.e. this attribute defines the text's position
                     relative to the element's center.  The value is ignored
                     if no text was specified for the element.  If not
                     specified the system falls back to the value taken from
                     the language variable anchor, which itself defaults to
                     center.  The legal values are all those accepted by
                     Tk_GetAnchor
                     [http://www.tcl.tk/man/tcl8.5/TkLib/GetAnchor.htm].  The
                     commands without arguments are all shorthands with the
                     anchor implied. Note that they do not combine, only the
                     last is used. For comined directions the main attribute
                     command, anchor has to be used.

                     ljust  "anchor west"

                     rjust  "anchor east"

                     above  "anchor south"

                     below  "anchor north"

              aspect number
                     Specifies the aspect ratio, i.e ratio of width to height,
                     of the diamond element.  The manner in which a default is
                     calculated when not specified also depends on the
                     specifications of the attributes width and height, if
                     any.

                     If both width, and height are specified then any
                     specification of aspect is ignored, as it is implicitly
                     defined in the width and height as well, and this takes
                     precedence. A missing specification is ignored in that
                     case well, i.e. no defaults are required.

                     If the aspect is specified, and one of the attributes
                     width or height, then the missing attribute is calculated
                     from the two which are specified. No defaults are
                     required for these cases either.

                     If only one of the attributes width or height is
                     specified then the system uses a fallback for the aspect,
                     the value taken from the language variable diamondaspect,
                     which itselfs defaults to 2.

                     If none of of the attributes width or height is specified
                     then the system uses a fallback for the width, the value
                     taken from the language variable boxwidth, which itselfs
                     defaults to the pixel equivalent of 2 cm. For the aspect
                     it uses either the user-specified value or the default
                     taken as described in the previous paragraph.

              at location
                     Specifies the location of the element's corner named by
                     the attribute with.  Defaults to the current location as
                     maintained by the layouting system.

              color spec
                     IMAGE: figure-21-style-colors Specifies the color used to
                     draw the lines of the element.  If not specified the
                     system falls back to the value taken from the language
                     variable linecolor, which itself defaults to black.

              fillcolor spec
                     IMAGE: figure-21-style-colors Specifies the color used to
                     draw the inside of the element.  If not specified the
                     system falls back to the value taken from the language
                     variable fillcolor, which itself defaults to the empty
                     string, signaling "no filling".

              height length
                     Specifies the height of the diamond element.  The manner
                     in which a default is calculated when not specified also
                     depends on the specifications of the attributes aspect
                     and width, if any.

                     If both width, and height are specified then any
                     specification of aspect is ignored, as it is implicitly
                     defined in the width and height as well, and this takes
                     precedence. A missing specification is ignored in that
                     case well, i.e. no defaults are required.

                     If the aspect is specified, and one of the attributes
                     width or height, then the missing attribute is calculated
                     from the two which are specified. No defaults are
                     required for these cases either.

                     If only one of the attributes width or height is
                     specified then the system uses a fallback for the aspect,
                     the value taken from the language variable diamondaspect,
                     which itselfs defaults to 2.

                     If none of of the attributes width or height is specified
                     then the system uses a fallback for the width, the value
                     taken from the language variable boxwidth, which itselfs
                     defaults to the pixel equivalent of 2 cm. For the aspect
                     it uses either the user-specified value or the default
                     taken as described in the previous paragraph.

              justify left|center|right
                     Specifies how multi-line text associated with the element
                     is positioned within its box.  The value is ignored if no
                     text was specified for the element.  If not specified the
                     system falls back to the value taken from the language
                     variable justify, which itself defaults to left.  The
                     legal values are left, right, and center.

              stroke width
                     IMAGE: figure-20-style-stroke Specifies the width of the
                     lines drawn for the the element, in pixels.  If not
                     specified the system falls back to the value taken from
                     the language variable linewidth, which itself defaults to
                     1.

              style spec
                     IMAGE: figure-18-style-dash Specifies the style used to
                     draw the lines of the element.  If not specified the
                     system falls back to the value taken from the language
                     variable linestyle, which itself defaults to solid lines.
                     The legal values are all those accepted by Tk_GetDash
                     [http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm], and
                     additionally all which are listed below:

                     solid, empty string
                            Draw solid line.

                     dash, dashed, -
                            Draw a dashed line.

                     dot, dotted, .
                            Draw a dotted line.

                     dash-dot, -.
                            Draw a dash-dotted line

                     dash-dot-dot, -..
                            Draw a dash-dot-dotted line.

                     Note that the values "solid", "dot(ted)", "dash(ed)",
                     "dash-dot", and "dash-dot-dot" are all accepted as
                     shorthands for the style command using them as argument.

              text string
                     Specifies the text to associate with the element.
                     Defaults to nothing.  When specified multiple times the
                     actually shown text is the concatenation of the
                     individual strings, vertically stacked, with the first
                     string specified being the topmost element.

              textcolor spec
                     Specifies the color used to draw the text of an element
                     with.  Ignored if there is no text.  If not specified the
                     system falls back to the value taken from the language
                     variable textcolor, which itself defaults to black.

              textfont spec
                     Specifies the font used to draw the text of an element
                     with.  Ignored if there is no text.  If not specified the
                     system falls back to the value taken from the language
                     variable textfont, which itself defaults to Helvetica
                     12pt.

              width length
                     Specifies the width of the diamond element.  The manner
                     in which a default is calculated when not specified also
                     depends on the specifications of the attributes aspect
                     and height, if any.

                     If both width, and height are specified then any
                     specification of aspect is ignored, as it is implicitly
                     defined in the width and height as well, and this takes
                     precedence. A missing specification is ignored in that
                     case well, i.e. no defaults are required.

                     If the aspect is specified, and one of the attributes
                     width or height, then the missing attribute is calculated
                     from the two which are specified. No defaults are
                     required for these cases either.

                     If only one of the attributes width or height is
                     specified then the system uses a fallback for the aspect,
                     the value taken from the language variable diamondaspect,
                     which itselfs defaults to 2.

                     If none of of the attributes width or height is specified
                     then the system uses a fallback for the width, the value
                     taken from the language variable boxwidth, which itselfs
                     defaults to the pixel equivalent of 2 cm. For the aspect
                     it uses either the user-specified value or the default
                     taken as described in the previous paragraph.

              with corner
                     Specifies the corner of the element to place at the
                     location given by the attribute at.  Defaults to the
                     current corner as maintained by the layouting system,
                     except if the value for at was specified by the user. In
                     that case it defaults to center.

       drum attr...
              IMAGE: figure-02-drum A closed element with the corresponding
              corners, i.e. the eight directions of the compass rose, and
              "center".  It handles the attributes

              anchor name

              ljust

              rjust

              above

              below  IMAGE: figure-22-text-anchoring-3 Specifies the anchor of
                     the text which is to be placed at the element's center,
                     by name. I.e. this attribute defines the text's position
                     relative to the element's center.  The value is ignored
                     if no text was specified for the element.  If not
                     specified the system falls back to the value taken from
                     the language variable anchor, which itself defaults to
                     center.  The legal values are all those accepted by
                     Tk_GetAnchor
                     [http://www.tcl.tk/man/tcl8.5/TkLib/GetAnchor.htm].  The
                     commands without arguments are all shorthands with the
                     anchor implied. Note that they do not combine, only the
                     last is used. For comined directions the main attribute
                     command, anchor has to be used.

                     ljust  "anchor west"

                     rjust  "anchor east"

                     above  "anchor south"

                     below  "anchor north"

              aspect number
                     Specifies the aspect ratio, i.e ratio of width to height,
                     of the ellipses which are used to draw the top and bottom
                     of the drum element.  If not specified the system falls
                     back to the value taken from the language variable
                     drumaspect, which itself defaults to 0.35.

              at location
                     Specifies the location of the element's corner named by
                     the attribute with.  Defaults to the current location as
                     maintained by the layouting system.

              color spec
                     IMAGE: figure-21-style-colors Specifies the color used to
                     draw the lines of the element.  If not specified the
                     system falls back to the value taken from the language
                     variable linecolor, which itself defaults to black.

              fillcolor spec
                     IMAGE: figure-21-style-colors Specifies the color used to
                     draw the inside of the element.  If not specified the
                     system falls back to the value taken from the language
                     variable fillcolor, which itself defaults to the empty
                     string, signaling "no filling".

              height length

              ht length
                     Specifies the height of the element.  If not specified
                     the system falls back to the value taken from the
                     language variable boxheight, which itself defaults to the
                     pixel equivalent of 2 cm.

              justify left|center|right
                     Specifies how multi-line text associated with the element
                     is positioned within its box.  The value is ignored if no
                     text was specified for the element.  If not specified the
                     system falls back to the value taken from the language
                     variable justify, which itself defaults to left.  The
                     legal values are left, right, and center.

              stroke width
                     IMAGE: figure-20-style-stroke Specifies the width of the
                     lines drawn for the the element, in pixels.  If not
                     specified the system falls back to the value taken from
                     the language variable linewidth, which itself defaults to
                     1.

              style spec
                     IMAGE: figure-18-style-dash Specifies the style used to
                     draw the lines of the element.  If not specified the
                     system falls back to the value taken from the language
                     variable linestyle, which itself defaults to solid lines.
                     The legal values are all those accepted by Tk_GetDash
                     [http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm], and
                     additionally all which are listed below:

                     solid, empty string
                            Draw solid line.

                     dash, dashed, -
                            Draw a dashed line.

                     dot, dotted, .
                            Draw a dotted line.

                     dash-dot, -.
                            Draw a dash-dotted line

                     dash-dot-dot, -..
                            Draw a dash-dot-dotted line.

                     Note that the values "solid", "dot(ted)", "dash(ed)",
                     "dash-dot", and "dash-dot-dot" are all accepted as
                     shorthands for the style command using them as argument.

              text string
                     Specifies the text to associate with the element.
                     Defaults to nothing.  When specified multiple times the
                     actually shown text is the concatenation of the
                     individual strings, vertically stacked, with the first
                     string specified being the topmost element.

              textcolor spec
                     Specifies the color used to draw the text of an element
                     with.  Ignored if there is no text.  If not specified the
                     system falls back to the value taken from the language
                     variable textcolor, which itself defaults to black.

              textfont spec
                     Specifies the font used to draw the text of an element
                     with.  Ignored if there is no text.  If not specified the
                     system falls back to the value taken from the language
                     variable textfont, which itself defaults to Helvetica
                     12pt.

              width length

              wid length
                     Specifies the width of the element.  If not specified the
                     system falls back to the value taken from the language
                     variable boxwidth, which itself defaults to the pixel
                     equivalent of 2 cm.

              with corner
                     Specifies the corner of the element to place at the
                     location given by the attribute at.  Defaults to the
                     current corner as maintained by the layouting system,
                     except if the value for at was specified by the user. In
                     that case it defaults to center.

       ellipse attr...
              IMAGE: figure-02-ellipse A closed element with the corresponding
              corners, i.e. the eight directions of the compass rose, and
              "center".  It handles the attributes

              anchor name

              ljust

              rjust

              above

              below  IMAGE: figure-22-text-anchoring-3 Specifies the anchor of
                     the text which is to be placed at the element's center,
                     by name. I.e. this attribute defines the text's position
                     relative to the element's center.  The value is ignored
                     if no text was specified for the element.  If not
                     specified the system falls back to the value taken from
                     the language variable anchor, which itself defaults to
                     center.  The legal values are all those accepted by
                     Tk_GetAnchor
                     [http://www.tcl.tk/man/tcl8.5/TkLib/GetAnchor.htm].  The
                     commands without arguments are all shorthands with the
                     anchor implied. Note that they do not combine, only the
                     last is used. For comined directions the main attribute
                     command, anchor has to be used.

                     ljust  "anchor west"

                     rjust  "anchor east"

                     above  "anchor south"

                     below  "anchor north"

              at location
                     Specifies the location of the element's corner named by
                     the attribute with.  Defaults to the current location as
                     maintained by the layouting system.

              color spec
                     IMAGE: figure-21-style-colors Specifies the color used to
                     draw the lines of the element.  If not specified the
                     system falls back to the value taken from the language
                     variable linecolor, which itself defaults to black.

              fillcolor spec
                     IMAGE: figure-21-style-colors Specifies the color used to
                     draw the inside of the element.  If not specified the
                     system falls back to the value taken from the language
                     variable fillcolor, which itself defaults to the empty
                     string, signaling "no filling".

              height length

              ht length
                     Specifies the height of the element.  If not specified
                     the system falls back to the value taken from the
                     language variable boxheight, which itself defaults to the
                     pixel equivalent of 2 cm.

              justify left|center|right
                     Specifies how multi-line text associated with the element
                     is positioned within its box.  The value is ignored if no
                     text was specified for the element.  If not specified the
                     system falls back to the value taken from the language
                     variable justify, which itself defaults to left.  The
                     legal values are left, right, and center.

              stroke width
                     IMAGE: figure-20-style-stroke Specifies the width of the
                     lines drawn for the the element, in pixels.  If not
                     specified the system falls back to the value taken from
                     the language variable linewidth, which itself defaults to
                     1.

              style spec
                     IMAGE: figure-18-style-dash Specifies the style used to
                     draw the lines of the element.  If not specified the
                     system falls back to the value taken from the language
                     variable linestyle, which itself defaults to solid lines.
                     The legal values are all those accepted by Tk_GetDash
                     [http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm], and
                     additionally all which are listed below:

                     solid, empty string
                            Draw solid line.

                     dash, dashed, -
                            Draw a dashed line.

                     dot, dotted, .
                            Draw a dotted line.

                     dash-dot, -.
                            Draw a dash-dotted line

                     dash-dot-dot, -..
                            Draw a dash-dot-dotted line.

                     Note that the values "solid", "dot(ted)", "dash(ed)",
                     "dash-dot", and "dash-dot-dot" are all accepted as
                     shorthands for the style command using them as argument.

              text string
                     Specifies the text to associate with the element.
                     Defaults to nothing.  When specified multiple times the
                     actually shown text is the concatenation of the
                     individual strings, vertically stacked, with the first
                     string specified being the topmost element.

              textcolor spec
                     Specifies the color used to draw the text of an element
                     with.  Ignored if there is no text.  If not specified the
                     system falls back to the value taken from the language
                     variable textcolor, which itself defaults to black.

              textfont spec
                     Specifies the font used to draw the text of an element
                     with.  Ignored if there is no text.  If not specified the
                     system falls back to the value taken from the language
                     variable textfont, which itself defaults to Helvetica
                     12pt.

              width length

              wid length
                     Specifies the width of the element.  If not specified the
                     system falls back to the value taken from the language
                     variable boxwidth, which itself defaults to the pixel
                     equivalent of 2 cm.

              with corner
                     Specifies the corner of the element to place at the
                     location given by the attribute at.  Defaults to the
                     current corner as maintained by the layouting system,
                     except if the value for at was specified by the user. In
                     that case it defaults to center.

       line attr...

       -- attr...
              IMAGE: figure-02-line An open element with the corresponding
              corners, i.e. "start", "end", and "center".  It handles the
              attributes

              anchor name

              ljust

              rjust

              above

              below  IMAGE: figure-22-text-anchoring-3 Specifies the anchor of
                     the text which is to be placed at the element's center,
                     by name. I.e. this attribute defines the text's position
                     relative to the element's center.  The value is ignored
                     if no text was specified for the element.  If not
                     specified the system falls back to the value taken from
                     the language variable anchor, which itself defaults to
                     center.  The legal values are all those accepted by
                     Tk_GetAnchor
                     [http://www.tcl.tk/man/tcl8.5/TkLib/GetAnchor.htm].  The
                     commands without arguments are all shorthands with the
                     anchor implied. Note that they do not combine, only the
                     last is used. For comined directions the main attribute
                     command, anchor has to be used.

                     ljust  "anchor west"

                     rjust  "anchor east"

                     above  "anchor south"

                     below  "anchor north"

              arrowhead spec
                     IMAGE: figure-19-style-arrowheads Specifies where to draw
                     arrowheads on the line element, at the beginning or end,
                     at both ends, or none.  If not specified the system falls
                     back to the value taken from the language variable
                     arrowhead, which itself defaults to none.  The legal
                     values are

                     none, -
                            Draw no arrowheads, at neither end of the line.

                     start, first, <-
                            Draw an arrowhead at the beginning of the line,
                            but not at its end.

                     end, last, ->
                            Draw an arrowhead at the end of the line, but not
                            at its beginning.

                     both, <->
                            Draw arrowheads at both ends of the line.

                     Note that the values "start", "end", "-", "->", "<-", and
                     "<->" are all accepted as shorthands for the arrowhead
                     command using them as argument.

              at location
                     Line elements are normally positioned absolutely, using
                     the locations specified through the attributes from,
                     then, and to.  If at is specified however then these
                     positions are translated a last time, moving the line's
                     corner named by the attribute with to the location given
                     by this attribute.

              chop ?length?
                     Specifies the length of the line element to remove from
                     the beginning and/or end.  Defaults to nothing.  If
                     specified once the chopping applies to both beginning and
                     end of the line.  If specified twice or more the last two
                     specifications are used, and applied to beginning and end
                     of the line, in this order.  Whenever the attribute is
                     specified without an explicit length, the system falls
                     back to the value taken from the language variable
                     circleradius, which itself defaults to the pixel
                     equivalent of 1 cm

              color spec
                     IMAGE: figure-21-style-colors Specifies the color used to
                     draw the lines of the element.  If not specified the
                     system falls back to the value taken from the language
                     variable linecolor, which itself defaults to black.

              fillcolor spec
                     IMAGE: figure-21-style-colors Specifies the color used to
                     draw the inside of the element.  If not specified the
                     system falls back to the value taken from the language
                     variable fillcolor, which itself defaults to the empty
                     string, signaling "no filling".

              from location
                     Specifies the location where the line element begins.
                     Defaults to the current location as maintained by the
                     layouting system.

              justify left|center|right
                     Specifies how multi-line text associated with the element
                     is positioned within its box.  The value is ignored if no
                     text was specified for the element.  If not specified the
                     system falls back to the value taken from the language
                     variable justify, which itself defaults to left.  The
                     legal values are left, right, and center.

              noturn Specifies that the direction of line element at its end
                     is not propagated to the layout management.  If not
                     specified the direction of the line becomes the new
                     direction the layout.

              smooth Specifies the use of bezier splines for the line element.
                     If not specified lines are drawn exactly through the
                     specified waypoints, without any smooth curves.

              stroke width
                     IMAGE: figure-20-style-stroke Specifies the width of the
                     lines drawn for the the element, in pixels.  If not
                     specified the system falls back to the value taken from
                     the language variable linewidth, which itself defaults to
                     1.

              style spec
                     IMAGE: figure-18-style-dash Specifies the style used to
                     draw the lines of the element.  If not specified the
                     system falls back to the value taken from the language
                     variable linestyle, which itself defaults to solid lines.
                     The legal values are all those accepted by Tk_GetDash
                     [http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm], and
                     additionally all which are listed below:

                     solid, empty string
                            Draw solid line.

                     dash, dashed, -
                            Draw a dashed line.

                     dot, dotted, .
                            Draw a dotted line.

                     dash-dot, -.
                            Draw a dash-dotted line

                     dash-dot-dot, -..
                            Draw a dash-dot-dotted line.

                     Note that the values "solid", "dot(ted)", "dash(ed)",
                     "dash-dot", and "dash-dot-dot" are all accepted as
                     shorthands for the style command using them as argument.

              text string
                     Specifies the text to associate with the element.
                     Defaults to nothing.  When specified multiple times the
                     actually shown text is the concatenation of the
                     individual strings, vertically stacked, with the first
                     string specified being the topmost element.

              textcolor spec
                     Specifies the color used to draw the text of an element
                     with.  Ignored if there is no text.  If not specified the
                     system falls back to the value taken from the language
                     variable textcolor, which itself defaults to black.

              textfont spec
                     Specifies the font used to draw the text of an element
                     with.  Ignored if there is no text.  If not specified the
                     system falls back to the value taken from the language
                     variable textfont, which itself defaults to Helvetica
                     12pt.

              then location

              then (<direction> ?length?)...

              (<direction> ?length?)...
                     This attribute specifies an intermediate location the
                     line element has to go through.  It can be specified
                     multiple times, with each use adding one additional
                     location to the series which the line will go through.
                     These location will be traversed in the order they were
                     specified.

                     The location can be given explicitly, or as a series of
                     directions with distances. In the latter case the names
                     of all known directions are accepted for the direction
                     part.  If no distance is specified for a direction the
                     system falls back to the value taken from the language
                     variable movelength, which itself defaults to the pixel
                     equivalent of 2 cm.  The whole set of direction,distance
                     pairs is treated as a series of translations which are
                     added up to provide the final translation specifying the
                     intermediate point (relative to the preceding point).

                     The last named direction is propagated to the layout
                     system as the direction to follow. The use of noturn is
                     not able to overide this behaviour.

                     At last, the names of the registered directions also
                     serve as attribute commands, with an implicit attribute
                     then in front of them.

                     If no intermediate or last location is specified for the
                     line the system falls back to a point movelength pixels
                     away from the starting location, in the current direction
                     as maintained by the layouting system

              to location
                     Specifies the location where the line element ends.  This
                     attribute has no default. The default is handled by the
                     attribute then, which makes it appear as if to has a
                     default when not specified.

              with corner
                     Line elements are normally positioned absolutely, using
                     the locations specified through the attributes from,
                     then, and to.  If at is specified however then these
                     positions are translated a last time, moving the line's
                     corner named by the attribute with to the location given
                     by this attribute.  This means that with is effective if
                     and only if the attribute at was specified as well for
                     the line.

       move attr
              An open element with the corresponding corners, i.e. "start",
              "end", and "center".  A move element is in essence an invisible
              line.  While the main effect we are interested in is the change
              it makes to the layout system, it is an actual element, i.e. it
              has the same corners as an ordinary line, and shows up in the
              history as well, allowing future references to all the places it
              touched.  It handles the same attibutes as line elements.

       spline attr...
              IMAGE: figure-02-spline An alias for the line element (see
              above), with the attribute smooth preset.

       text attr...
              IMAGE: figure-02-text A closed element with the corresponding
              corners, i.e. the eight directions of the compass rose, and
              "center".  It handles the attributes

              anchor name

              ljust

              rjust

              above

              below  IMAGE: figure-22-text-anchoring-3 Specifies the anchor of
                     the text which is to be placed at the element's center,
                     by name. I.e. this attribute defines the text's position
                     relative to the element's center.  The value is ignored
                     if no text was specified for the element.  If not
                     specified the system falls back to the value taken from
                     the language variable anchor, which itself defaults to
                     center.  The legal values are all those accepted by
                     Tk_GetAnchor
                     [http://www.tcl.tk/man/tcl8.5/TkLib/GetAnchor.htm].  The
                     commands without arguments are all shorthands with the
                     anchor implied. Note that they do not combine, only the
                     last is used. For comined directions the main attribute
                     command, anchor has to be used.

                     ljust  "anchor west"

                     rjust  "anchor east"

                     above  "anchor south"

                     below  "anchor north"

              at location
                     Specifies the location of the element's corner named by
                     the attribute with.  Defaults to the current location as
                     maintained by the layouting system.

              height length
                     Specifies the height of the text element.  Defaults to
                     the natural height of its text.

              justify left|center|right
                     Specifies how multi-line text associated with the element
                     is positioned within its box.  The value is ignored if no
                     text was specified for the element.  If not specified the
                     system falls back to the value taken from the language
                     variable justify, which itself defaults to left.  The
                     legal values are left, right, and center.

              text string
                     Specifies the text to associate with the element.
                     Defaults to nothing.  When specified multiple times the
                     actually shown text is the concatenation of the
                     individual strings, vertically stacked, with the first
                     string specified being the topmost element.

              textcolor spec
                     Specifies the color used to draw the text of an element
                     with.  Ignored if there is no text.  If not specified the
                     system falls back to the value taken from the language
                     variable textcolor, which itself defaults to black.

              textfont spec
                     Specifies the font used to draw the text of an element
                     with.  Ignored if there is no text.  If not specified the
                     system falls back to the value taken from the language
                     variable textfont, which itself defaults to Helvetica
                     12pt.

              width length
                     Specifies the width of the text element.  Defaults to the
                     natural width of its text.

              with corner
                     Specifies the corner of the element to place at the
                     location given by the attribute at.  Defaults to the
                     current corner as maintained by the layouting system,
                     except if the value for at was specified by the user. In
                     that case it defaults to center.

   ATTRIBUTES
       The set of all attributes supported by all the element commands is
       shown below.  While we speak of them as commands, and provide a syntax,
       they are not truly available as actual commands, but only as part of
       the arguments for an element command.

       Note that some of the attribute names are overloaded, i.e. have
       multiple, different, definitions. During processing of attributes for
       an element the actual definition used is chosen based on the type of
       the element the processing is for.

       Further, as a catch-all clause, any attribute which could not be
       processed according to the definitions below will be treated as the
       argument of an implicit text attribute.

       anchor name

       ljust

       rjust

       above

       below  IMAGE: figure-22-text-anchoring-3 Specifies the anchor of the
              text which is to be placed at the element's center, by name.
              I.e. this attribute defines the text's position relative to the
              element's center.  The value is ignored if no text was specified
              for the element.  If not specified the system falls back to the
              value taken from the language variable anchor, which itself
              defaults to center.  The legal values are all those accepted by
              Tk_GetAnchor [http://www.tcl.tk/man/tcl8.5/TkLib/GetAnchor.htm].
              The commands without arguments are all shorthands with the
              anchor implied. Note that they do not combine, only the last is
              used. For comined directions the main attribute command, anchor
              has to be used.

              ljust  "anchor west"

              rjust  "anchor east"

              above  "anchor south"

              below  "anchor north"

       arrowhead spec
              IMAGE: figure-19-style-arrowheads Specifies where to draw
              arrowheads on the line element, at the beginning or end, at both
              ends, or none.  If not specified the system falls back to the
              value taken from the language variable arrowhead, which itself
              defaults to none.  The legal values are

              none, -
                     Draw no arrowheads, at neither end of the line.

              start, first, <-
                     Draw an arrowhead at the beginning of the line, but not
                     at its end.

              end, last, ->
                     Draw an arrowhead at the end of the line, but not at its
                     beginning.

              both, <->
                     Draw arrowheads at both ends of the line.

              Note that the values "start", "end", "-", "->", "<-", and "<->"
              are all accepted as shorthands for the arrowhead command using
              them as argument.

       aspect number
              Specifies the aspect ratio, i.e ratio of width to height, of the
              diamond element.  The manner in which a default is calculated
              when not specified also depends on the specifications of the
              attributes width and height, if any.

              If both width, and height are specified then any specification
              of aspect is ignored, as it is implicitly defined in the width
              and height as well, and this takes precedence. A missing
              specification is ignored in that case well, i.e. no defaults are
              required.

              If the aspect is specified, and one of the attributes width or
              height, then the missing attribute is calculated from the two
              which are specified. No defaults are required for these cases
              either.

              If only one of the attributes width or height is specified then
              the system uses a fallback for the aspect, the value taken from
              the language variable diamondaspect, which itselfs defaults to
              2.

              If none of of the attributes width or height is specified then
              the system uses a fallback for the width, the value taken from
              the language variable boxwidth, which itselfs defaults to the
              pixel equivalent of 2 cm. For the aspect it uses either the
              user-specified value or the default taken as described in the
              previous paragraph.

       aspect number
              Specifies the aspect ratio, i.e ratio of width to height, of the
              ellipses which are used to draw the top and bottom of the drum
              element.  If not specified the system falls back to the value
              taken from the language variable drumaspect, which itself
              defaults to 0.35.

       at location
              Specifies the location of the element's corner named by the
              attribute with.  Defaults to the current location as maintained
              by the layouting system.

       at location
              Line elements are normally positioned absolutely, using the
              locations specified through the attributes from, then, and to.
              If at is specified however then these positions are translated a
              last time, moving the line's corner named by the attribute with
              to the location given by this attribute.

       chop ?length?
              Specifies the length of the line element to remove from the
              beginning and/or end.  Defaults to nothing.  If specified once
              the chopping applies to both beginning and end of the line.  If
              specified twice or more the last two specifications are used,
              and applied to beginning and end of the line, in this order.
              Whenever the attribute is specified without an explicit length,
              the system falls back to the value taken from the language
              variable circleradius, which itself defaults to the pixel
              equivalent of 1 cm

       clockwise

       cw     Specifies the direction of the arc element, here going
              clockwise.  The complementary attribute is counterclockwise.  If
              not specified the system falls back to the value taken from the
              language variable clockwise, which itself defaults to false, for
              counter-clockwise direction.

       color spec
              IMAGE: figure-21-style-colors Specifies the color used to draw
              the lines of the element.  If not specified the system falls
              back to the value taken from the language variable linecolor,
              which itself defaults to black.

       counterclockwise

       ccw    Specifies the direction of the arc element, here counter-
              clockwise.  The complementary attribute is clockwise.  If not
              specified the system falls back to the value taken from the
              language variable clockwise, which itself defaults to false, for
              counter-clockwise direction.

       diameter length

       diam length
              Specifies the diameter of the circle element, as an alternative
              way to specify its radius.  Effective if and only if the radius
              was not specified. I.e. if both diameter and radius are
              specified then the radius infomration has precendence.  This
              attribute has no default, because the defaults are taken from
              the radius.

       fillcolor spec
              IMAGE: figure-21-style-colors Specifies the color used to draw
              the inside of the element.  If not specified the system falls
              back to the value taken from the language variable fillcolor,
              which itself defaults to the empty string, signaling "no
              filling".

       from location
              Specifies the location where the line element begins.  Defaults
              to the current location as maintained by the layouting system.

       from location
              Specifies the location where the arc element begins.  Defaults
              to the current location as maintained by the layouting system.

       height length

       ht length
              Specifies the height of the element.  If not specified the
              system falls back to the value taken from the language variable
              boxheight, which itself defaults to the pixel equivalent of 2
              cm.

       height length
              Specifies the height of the diamond element.  The manner in
              which a default is calculated when not specified also depends on
              the specifications of the attributes aspect and width, if any.

              If both width, and height are specified then any specification
              of aspect is ignored, as it is implicitly defined in the width
              and height as well, and this takes precedence. A missing
              specification is ignored in that case well, i.e. no defaults are
              required.

              If the aspect is specified, and one of the attributes width or
              height, then the missing attribute is calculated from the two
              which are specified. No defaults are required for these cases
              either.

              If only one of the attributes width or height is specified then
              the system uses a fallback for the aspect, the value taken from
              the language variable diamondaspect, which itselfs defaults to
              2.

              If none of of the attributes width or height is specified then
              the system uses a fallback for the width, the value taken from
              the language variable boxwidth, which itselfs defaults to the
              pixel equivalent of 2 cm. For the aspect it uses either the
              user-specified value or the default taken as described in the
              previous paragraph.

       height length
              Specifies the height of the text element.  Defaults to the
              natural height of its text.

       justify left|center|right
              Specifies how multi-line text associated with the element is
              positioned within its box.  The value is ignored if no text was
              specified for the element.  If not specified the system falls
              back to the value taken from the language variable justify,
              which itself defaults to left.  The legal values are left,
              right, and center.

       noturn Specifies that the direction of line element at its end is not
              propagated to the layout management.  If not specified the
              direction of the line becomes the new direction the layout.

       radius length

       rad length
              Specifies the radius of the circle element.  If not specified
              the system falls back to the value taken from the language
              variable circleradius, which itself defaults to the pixel
              equivalent of 1 cm.

       radius length
              Specifies the radius of the arc element, or rather, the radius
              of the circle the shown arc is a part of.  If not specified the
              system falls back to the value taken from the language variable
              arcradius, which itself defaults to the pixel equivalent of 1
              cm.

       slant angle
              Specifies the angle by which the box element is slanted, in
              degrees.  If not specified the system falls back to the value
              taken from the language variable slant, which itself defaults to
              90, i.e. vertical, no slant.  0 degrees is slanting straight
              east, pointing to the right.  90 degrees is slanting to the
              north, pointing straight up.

       smooth Specifies the use of bezier splines for the line element.  If
              not specified lines are drawn exactly through the specified
              waypoints, without any smooth curves.

       stroke width
              IMAGE: figure-20-style-stroke Specifies the width of the lines
              drawn for the the element, in pixels.  If not specified the
              system falls back to the value taken from the language variable
              linewidth, which itself defaults to 1.

       style spec
              IMAGE: figure-18-style-dash Specifies the style used to draw the
              lines of the element.  If not specified the system falls back to
              the value taken from the language variable linestyle, which
              itself defaults to solid lines.  The legal values are all those
              accepted by Tk_GetDash
              [http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm], and
              additionally all which are listed below:

              solid, empty string
                     Draw solid line.

              dash, dashed, -
                     Draw a dashed line.

              dot, dotted, .
                     Draw a dotted line.

              dash-dot, -.
                     Draw a dash-dotted line

              dash-dot-dot, -..
                     Draw a dash-dot-dotted line.

              Note that the values "solid", "dot(ted)", "dash(ed)", "dash-
              dot", and "dash-dot-dot" are all accepted as shorthands for the
              style command using them as argument.

       text string
              Specifies the text to associate with the element.  Defaults to
              nothing.  When specified multiple times the actually shown text
              is the concatenation of the individual strings, vertically
              stacked, with the first string specified being the topmost
              element.

       textcolor spec
              Specifies the color used to draw the text of an element with.
              Ignored if there is no text.  If not specified the system falls
              back to the value taken from the language variable textcolor,
              which itself defaults to black.

       textfont spec
              Specifies the font used to draw the text of an element with.
              Ignored if there is no text.  If not specified the system falls
              back to the value taken from the language variable textfont,
              which itself defaults to Helvetica 12pt.

       then location

       then (<direction> ?length?)...

       (<direction> ?length?)...
              This attribute specifies an intermediate location the line
              element has to go through.  It can be specified multiple times,
              with each use adding one additional location to the series which
              the line will go through. These location will be traversed in
              the order they were specified.

              The location can be given explicitly, or as a series of
              directions with distances. In the latter case the names of all
              known directions are accepted for the direction part.  If no
              distance is specified for a direction the system falls back to
              the value taken from the language variable movelength, which
              itself defaults to the pixel equivalent of 2 cm.  The whole set
              of direction,distance pairs is treated as a series of
              translations which are added up to provide the final translation
              specifying the intermediate point (relative to the preceding
              point).

              The last named direction is propagated to the layout system as
              the direction to follow. The use of noturn is not able to
              overide this behaviour.

              At last, the names of the registered directions also serve as
              attribute commands, with an implicit attribute then in front of
              them.

              If no intermediate or last location is specified for the line
              the system falls back to a point movelength pixels away from the
              starting location, in the current direction as maintained by the
              layouting system

       to location
              Specifies the location where the line element ends.  This
              attribute has no default. The default is handled by the
              attribute then, which makes it appear as if to has a default
              when not specified.

       to location
              Specifies the location where the arc element ends.  Defaults to
              a location such that a 90-degree arc is drawn in the chosen
              direction, starting at from.

       width length

       wid length
              Specifies the width of the element.  If not specified the system
              falls back to the value taken from the language variable
              boxwidth, which itself defaults to the pixel equivalent of 2 cm.

       width length
              Specifies the width of the diamond element.  The manner in which
              a default is calculated when not specified also depends on the
              specifications of the attributes aspect and height, if any.

              If both width, and height are specified then any specification
              of aspect is ignored, as it is implicitly defined in the width
              and height as well, and this takes precedence. A missing
              specification is ignored in that case well, i.e. no defaults are
              required.

              If the aspect is specified, and one of the attributes width or
              height, then the missing attribute is calculated from the two
              which are specified. No defaults are required for these cases
              either.

              If only one of the attributes width or height is specified then
              the system uses a fallback for the aspect, the value taken from
              the language variable diamondaspect, which itselfs defaults to
              2.

              If none of of the attributes width or height is specified then
              the system uses a fallback for the width, the value taken from
              the language variable boxwidth, which itselfs defaults to the
              pixel equivalent of 2 cm. For the aspect it uses either the
              user-specified value or the default taken as described in the
              previous paragraph.

       width length
              Specifies the width of the text element.  Defaults to the
              natural width of its text.

       with corner
              Specifies the corner of the element to place at the location
              given by the attribute at.  Defaults to the current corner as
              maintained by the layouting system, except if the value for at
              was specified by the user. In that case it defaults to center.

       with corner
              Line elements are normally positioned absolutely, using the
              locations specified through the attributes from, then, and to.
              If at is specified however then these positions are translated a
              last time, moving the line's corner named by the attribute with
              to the location given by this attribute.  This means that with
              is effective if and only if the attribute at was specified as
              well for the line.

   CORNERS
       Corners are named values for in elements, usually locations.

       o      The closed elements define corners for the compass rose,
              including the "center", and their "width" and "height".

              IMAGE: figure-27-corners-closed


       o      block elements additionally export all variables which were set
              during their definition as corners.

       o      The open elements on the other hand define "start", "end", and
              "center". The first two map to the locations originally provided
              through the attributes from and to of the element.

              IMAGE: figure-28-corners-open


       o      The center of line and move elements is the location halfway
              between "start" and "end" corners, this is regardless of any
              intermediate locations the element may have.

       o      The line and move elements additionally name all their locations
              as corners using numbers as names, starting from 1 (equivalent
              to "start"), in order of traversal.

              IMAGE: figure-15-spline-1


       o      The center of arc elements is the center of the circle the arc
              is part off.

       o      The arc elements additionally define the compass rose of closed
              elements as well.

   NAMED DIRECTIONS
       The named directions are commands which tell the layout system in which
       direction to go when placing the next element without an explicit
       position specification.  They can also be used as arguments to the
       attribute then, and the command by for relative points, see there for
       the relevant syntax.

       The diagram core defines the directions of the compass rose, plus a
       number of aliases. See below for the full list.

       IMAGE: figure-27-corners-closed

       This overlaps with the pre-defined corners for closed elements. This is
       used by the layout system, when are going in direction X the name of
       the opposite direction is the name of the corner at which the new
       element will be attached to the current position, and if this corner
       does not exist the nearest actual corner by angle is used.

       west

       w

       left

       l

       south

       s

       down

       bottom

       bot

       b

       east

       e

       right

       r

       north

       n

       up

       top

       t

       northwest

       nw

       up-left

       upleft

       leftup

       northeast

       ne

       up-right

       upright

       rightup

       southwest

       sw

       down-left

       downleft

       leftdown

       southeast

       se

       down-right

       downright

       rightdown

   MISCELLANEOUS COMMANDS
       number cm

       number mm

       number inch

       number pt
              These commands allow the specification of distances and
              coordinates in metric and imperial units, returning the
              equivalent distance or coordinate in pixels, which is the unit
              used internally for all calculations.

              The conversion factors are based on the result of tk scaling and
              are computed once, at the time the package is sourced, future
              changes of the tk scaling factor have no effect.

       number number

              IMAGE: figure-50-point-cons-absolute

              This command takes the x and y coordinates of a location and
              returns the absolute point for it.

       by distance direction

              IMAGE: figure-51-point-cons-relative

              This command takes a distance and direction (angle in degress,
              or registered direction name) and returns the relative point for
              it, i.e. the delta or translation it represents.

              Note also the (dis)similarities to the directional
              specifications for the attribute then of line and move elements.
              Where we say here

              by 50 east

              for the attribute we say

              ... then east 50 ...

              or just

              ... then east ...

       point1 + point2

              IMAGE: figure-48-point-vectoradd

              This command interprets two points as vectors and adds them
              together.  If at least one of the points is absolute the result
              is absolute as well.  The result is a relative point if and only
              if both points are relative.

       point1 - point2

              IMAGE: figure-49-point-vectorsub

              This command interprets two points as vectors and subtracts the
              second from the first.  If at least one of the points is
              absolute the result is absolute as well.  The result is a
              relative point if and only if both points are relative.

       point by distance direction
              This command is a more convenient, or at least shorter, form of


                  [$point + [by $distance $direction]]


       point1 | point2

              IMAGE: figure-31-point-projection

              This command calculates the projection of two points, i.e. the
              result is the point having the x-coordinate of point1 and the y-
              coordinate of point2.

       n between poin1 point2

              IMAGE: figure-29-point-interpolation-1

              This command computes the point which is n*100 percent of the
              way between point1 and point2, and returns it as its result.
              This means that for

              n == 0 The result is point1.

              n == 1 The result is point2.

              n == 0.5
                     The result is half way between the two points.

              etc.  Note that it is allowed to use values < 0 and > 1 for n

       intersect elem1 elem2

              IMAGE: figure-32-point-intersection

              This command takes two open elements, computes the lines going
              through their "start"- and "end"-corners, and returns the point
              where these two lines intersect.  The command throws an error if
              the lines do not intersect, or are coincident.

       element names ?pattern?
              This command returns a list containing the names of all corners
              for the element. If a pattern is specified then only the names
              matching it (via string match are returned. Otherwise all names
              are returned (equivalent to a default pattern of *).

       element corner
              This command returns the value for the corner of the element.
              This can be anything, including points and elements.

       element corner1 corner2...
              This is a convenience shorthand for


              [[[$elem $corner1] $corner2] ...]


              assuming that the value for

               [$elem $corner1]
       again an element.

       element ?corner1... ?names ?pattern??]?
              This is a convenience shorthand for


              [[[$elem $corner1] ...] names ?pattern?]


              assuming that the value for

               [$elem $corner1]
       again an element.

       nth ?corner?
              This command asks the diagram history for the nth element
              created, searching from the beginning of the history (counting
              from 1) and returns it as its result.  If the corner is
              specified then the value for this corner is returned instead.

       nth last ?corner?
              This command asks the diagram history for the nth element
              created, searching from the end of the history and returns it as
              its result.  If the corner is specified then the value for this
              corner is returned instead.

       nth shape ?corner?
              This command asks the diagram history for the nth element
              created, of the given shape, searching from the beginning of the
              history (counting from 1) and returns it as its result.  If the
              corner is specified then the value for this corner is returned
              instead.

       nth last shape ?corner?
              This command asks the diagram history for the nth element
              created, of the given shape, searching from the end of the
              history and returns it as its result.  If the corner is
              specified then the value for this corner is returned instead.

       last ?corner?

       last shape ?corner?
              Convenience commands mapping to "1st last" and "1st last shape".

       1st

       2nd

       3rd    Aliases for 1th, 2th, and 3th, for readability, usable whereever
              nth can ocur.

   VARIABLES
       The language context contains a number of predefined variables which
       hold the default values for various attributes. These variables, their
       uses, and values are:

       anchor The default value for the attribute anchor.  Initialized to
              center.  The legal values are all those accepted by Tk_GetAnchor
              [http://www.tcl.tk/man/tcl8.5/TkLib/GetAnchor.htm].

       arcradius
              The default value for the attribute radius of arc elements.
              Initialized to the pixel equivalent of 1 cm.

       arrowhead
              The default value for the attribute arrowhead.  Initialized to
              none.  The legal values are

              none, -
                     Draw no arrowheads, at neither end of the line.

              start, first, <-
                     Draw an arrowhead at the beginning of the line, but not
                     at its end.

              end, last, ->
                     Draw an arrowhead at the end of the line, but not at its
                     beginning.

              both, <->
                     Draw arrowheads at both ends of the line.

       boxheight
              The default value for the attribute height of box, diamond and
              ellipse elements.  Initialized to the pixel equivalent of 2 cm.

       boxwidth
              The default value for the attribute width of box, diamond and
              ellipse elements.  Initialized to the pixel equivalent of 2 cm.

       clockwise
              The default value for the attributes clockwise and
              counterclockwise of arc elements.  Initialized to False, for
              counter-clockwise direction.

       circleradius
              The default value for the attribute radius of circle elements,
              and also the default for the attribute chop, when specified
              without an explicit length.  Initialized to the pixel equivalent
              of 1 cm.

       drumaspect
              The default value for the attribute aspect of drum elements.
              Initialized to 0.35.

       fillcolor
              The default value for the attribute fillcolor of all elements
              which can be filled.  Initialized to the empty string, signaling
              that the element is not filled.

       justify
              The default value for the attribute justify.  Initialized to
              left.  The legal values are left, right, and center.

       linecolor
              The default value for the attribute color of all elements having
              to draw lines (all but text).  Initialized to black.

       linestyle
              The default value for the attribute style of all elements having
              to draw some line.  Initialized to solid.  The legal values are
              all those accepted by Tk_GetDash
              [http://www.tcl.tk/man/tcl8.5/TkLib/GetDash.htm], and
              additionally all which are listed below:

              solid, empty string
                     Draw solid line.

              dash, dashed, -
                     Draw a dashed line.

              dot, dotted, .
                     Draw a dotted line.

              dash-dot, -.
                     Draw a dash-dotted line

              dash-dot-dot, -..
                     Draw a dash-dot-dotted line.

       linewidth
              The default value for the attribute stroke of all elements
              having to draw some line.  Initialized to 1 (pixels).

       movelength
              The default value for the directional specification of
              intermediate locations by the attribute then of line and move
              elements.  Initialized to the pixel equivalent of 2 cm.

       slant  The default value for the attribute slant of box elements.
              Initialized to 90 degrees, i.e. slant straight up.

       textcolor
              The default value for the attribute textcolor of all elements
              having to draw some text.  Initialized to black.

       textfont
              The default value for the attribute textfont of all elements
              having to draw some text.  Initialized to Helvetica 12pt.

DIAGRAM CLASSES The intended audience of this section are developers wishing
       to work
       on the internals of the diagram package.  Regular users of diagram can
       skip this section without missing anything.

       The main information seen here is the figure below, showing the
       hierarchy of the classes implementing diagram.

       IMAGE: figure-00-dependencies

       At the bottom, all at the same level are the supporting packages like
       snit, etc. These can all be found in Tcllib.

       Above them is the set of diagram classes implementing the various
       aspects of the system, i.e.:

       diagram
              The main class, that which is seen by the user.

       diagram::core
              The core engine, itself distributed over four helper classes.

       diagram::basic
              The implementation of the standard shapes, like box, circle,
              etc., based on the extension features of the core.

       diagram::element
              Core support class, the database of created elements. It also
              keeps the history, i.e. the order in which elements were
              created.

       diagram::attribute
              Core support class, the generic handling of definition and
              processing of attributes.

       diagram::direction
              Core support class, the database of named directions.

       diagram::navigation
              Core support class, the state of layout engine, i.e. current
              position and directin, and operations on it.

       diagram::point
              General support class handling various vector operations.

REFERENCES
BUGS, IDEAS, FEEDBACK
       This document, and the package it describes, will undoubtedly contain
       bugs and other problems.  Please report such in the category diagram of
       the Tklib Trackers [http://core.tcl.tk/tklib/reportlist].  Please also
       report any ideas for enhancements you may have for either package
       and/or documentation.

KEYWORDS
       2D geometry, arc, arrow, box, canvas, circle, diagram, diamond,
       drawing, drum, ellipse, image, interpolation, intersection, line, move,
       picture, plane geometry, plotting, point, raster image, spline, text,
       vector

CATEGORY
       Documentation tools



tklib                                 0.3                           diagram(n)
