Content-Type: text/plain; charset=US-ASCII; format=flowed; delsp=yes
Content-Transfer-Encoding: 7bit
Mime-Version: 1.0 (Apple Message framework v935.3)
References: <874332F9-007B-4945-87D5-48B28BBC11CC@gmail.com>
            <4A8E304C.4050208@morningstar2.co.uk>
Message-ID:  <F64AA87D-A646-4C0B-A7B3-57ED46AA5B78@gmail.com>
Date:         Fri, 21 Aug 2009 15:35:13 +0930
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: Will Robertson <wspr81@GMAIL.COM>
Subject: Re: template customising
To: LATEX-L@LISTSERV.UNI-HEIDELBERG.DE
In-Reply-To:  <4A8E304C.4050208@morningstar2.co.uk>
Precedence: list
Status: R

On 21/08/2009, at 2:57 PM, Joseph Wright wrote:

> Will Robertson wrote:
>> I imagine markup like
>>
>>    \EditInstance{sectioning}{chapter}% template is implicit!
>>        { ...keyvals... }
>>
>> but I don't know if my desire for this construct illustrates a
>> misunderstanding of mine of the system.

On second thought, I just realised that you need to know what template  
is being used in order to know which keyvals you want to change. The  
above could just as well, then, be

    \EditInstance{sectioning}{starts-new-page}{chapter}
        { ...keyvals... }

> From Frank's explanation, my understanding is slightly different. The
> key is to remember where templates it into all of this. Taking my
> example from before, and sticking with the current naming scheme, we
> might have
>
> \DeclareTemplateType { sectioning } 3
> \DeclareTemplate { sectioning } { starts-new-page } 3
>  { <key definitions> { <code> }
> \DeclareTemplate { sectioning } { space-before-and-after }
>  { <key definitions> { <code> }
> \DeclareRestrictedTemplate { sectioning }
>  { starts-new-page-no-number } { starts-new-page }
>  { <key settings> }
> \DeclareInstance { sectioning } { chapter } { starts-new-page }
>  { <key settings> }
> \DeclareCollectionInstance { frontmatter } { sectioning }
>  { chapter } { starts-new-page-no-number }
>  { <key settings>}
>
> \DeclareDocumentCommand \chapter { s o m } {
>  % Code to include
>  \UseInstance { sectioning } { chapter }
> }

So far I agree with all this :)
If this is how Frank sees how templates should be used, then I think  
we're all on the same page.

> If I'm designing a document and want to completely change \chapter, I
> have a few options:
>
> 1) If one of the existing templates can do what I want with the right
> keyval settings, I re-declare the instance. So if I want to alter font
> sizes and so on but not more general layout, I do
>
> \DeclareInstance { sectioning } { chapter } { starts-new-page }
>  { <new key settings> }
>
> plus probably
>
> \DeclareCollectionInstance { frontmatter } { sectioning }
>  { chapter } { starts-new-page-no-number }
>  { <new key settings>}

Right, and I also agree with your other proposals for when you want to  
change things more radically. But...

> In all three cases, the document command is left alone.

(I think this is the desirable approach.)

> Of course, this
> leaves open the question of how much variation each template leaves
> open. I can see your argument for creating instances with only minor
> adjustments from existing ones ("All I want to do is change length a  
> to
> length b, leaving everything else alone."). My feeling is that the  
> idea
> is that document classes should be much clearer on the settings they
> use, so the cost of copying a template and altering only a few lines  
> is
> worth it in clarity of what is going on.

...sometimes there are simply lots of settings to adjust! :)
Something like a single section heading template could feasibly have

  - number size & font
  - title size & font
  - title paragraph shape
  - number indent
  - number-to-title skip
  - pre-material (penalty & skip & possible rule)
  - post-material (ditto)

I agree that most of these *should* be reset when any of them are, but  
sometimes you just want to change the pre/post-skip or whatever, and I  
don't think it's convenient to have to find the definition of the  
instance and copy/paste the whole thing.

> The danger of allowing
> something like \EditInstance is that you can easily get back to ad hoc
> changes here and there with no clear separation of design and  
> document code.

Provided that the \EditInstance goes together with the other  
customisations for the document, I don't really see how this blurs the  
line between the two. Isn't it just a more convenient way to  
completely redeclare the instance without knowing the original settings?

But maybe you're right, and I'm trying to add a feature to solve a  
problem that is better solved in another way (e.g., by declaring more  
and more restricted templates and redefining the instances from  
scratch as you suggest).

Will