User-Agent: Mozilla/5.0 (Windows; U; Windows NT 6.1; en-GB; rv:1.9.2.13)
            Gecko/20101207 Thunderbird/3.1.7
MIME-Version: 1.0
References: <19748.48031.990921.327320@morse.mittelbach-online.de>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit
Message-ID:  <4D2EBA8B.5010504@morningstar2.co.uk>
Date:         Thu, 13 Jan 2011 08:40:43 +0000
Reply-To: Mailing list for the LaTeX3 project
              <LATEX-L@listserv.uni-heidelberg.de>
Sender: Mailing list for the LaTeX3 project <LATEX-L@listserv.uni-heidelberg.de>
From: Joseph Wright <joseph.wright@MORNINGSTAR2.CO.UK>
Subject: Re: xcoffins: missing functions?
To: LATEX-L@listserv.uni-heidelberg.de
In-Reply-To:  <19748.48031.990921.327320@morse.mittelbach-online.de>
Precedence: list
Status: R

On 05/01/2011 18:42, Frank Mittelbach wrote:
> What I have in mind are primarily rules, specified not by giving absolute
> length but rather specifying the end points in relation to the coffin handles.
> A more or less natural extension of this would be something like "leaders" the
> way TeX defines them, or a variation of that. But perhaps that is already too
> much and rules are enough. 
> 
> I don't think that it is right to try to turn the concept of coffins into some
> sort of general purpose graphics language, ie. really complicated things are
> probably better done differently but it would be nice if the more common
> layouts could be easily decribed in this way and right now at least the rules
> seems to me something that is clearly necessary.
> 
> But is there anything else you feel would be essential? And if so what?
> 
> Also, what kind of paramerization would be suitable for such objects (again
> thinking about what is commonly needed and not so much what would be
> theoretically possible in some arcane setup)?

I'd been thinking about this, and it lead me back to some comments on
the more general point about optional arguments.

Currently, we're using positional optional arguments for the coffin
functions, for example

  \JoinCoffins *
    \<coffin1> [ <coffin1-pole1> , <coffin1-pole2> ]
    \<coffin2> [ <coffin2-pole1> , <coffin2-pole2> ]
    ( <x-offset> , <y-offset> )

A good case can be made for reducing the use of arguments in this way
and moving to key-value syntax. I quite like the requirement for the
mandatory items to be separate arguments, but can see that something like:

  \JoinCoffins *
    [
      coffin1-pole1 = <value> ,
      coffin1-pole1 = <value> ,
      coffin2-pole2 = <value> ,
      coffin2-pole2 = <value> ,
      x-offset      = <value> ,
      y-offset      = <value> ,
    ]
    \<coffin1> \<coffin2>

might be a better long-term approach. I've assumed that we'd keep the
optional stuff as optional overall but in one argument, and that the '*'
still makes sense here (an alternative would be 'expand-bounding-box' or
similar as a Boolean). I'm also assuming that two arguments for each
handle is better than

    coffin1-handle = { <pole1> , <pole2> } ,

as at this stage I want to highlight the general point. (I'm not overly
keen on requiring braces in the key-value list if there is an
alternative which is also clear.)

The reason this is relevant to rules is that there are a number of
parameters that come to mind. A rule needs to be placed relative to a
coffin, which as with other alignments may need a handle on the coffin
and an offset. At the rule end, we may need the colour of the rule and a
handle on the rule for the alignment. We also need dimensions for the
rule, but these might want to be relative or absolute. The bounding box
for the coffin may need to expand or may be conserved. Out of this list,
the only absolute requirement is the coffin name. So a key-value list
would seem much more reasonable than optional arguments

  \AddRuleToCoffin *
    [
      absolute-width  = <value> ,
      absolute-height = <value> ,
      coffin-pole1    = <value> ,
      coffin-pole2    = <value> ,
      color           = <value> ,
      color-model     = <value> ,
      relative-width  = <value> ,
      relative-height = <value> ,
      rule-pole1      = <value> ,
      rule-pole2      = <value> ,
      x-offset        = <value> ,
      y-offset        = <value> ,
    ]
    \<coffin>

Obviously, there may need to be some adjustment to the keys. For
example, my model above assumes that absolute and relative dimensions
are given separately, whereas you could have just 'height' and 'width'
with a 'absolute-dimensions' Boolean (I think this might be less clear).
The same arguments about '*' and poles versus handles apply here as with
\JoinCoffins, etc.

The general point for me is that if you want this flexibility for rules
then I think you need a similar interface for the rest of the coffins
module. I also note that it would be possible to extend this approach to
leaders by making rules a special case of a more general
\AddLeadersToCoffin function. (Function names may of course need some
work too!)
-- 
Joseph Wright