MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
References: <874332F9-007B-4945-87D5-48B28BBC11CC@gmail.com>
Message-ID:  <19087.54678.292071.47911@morse.mittelbach-online.de>
Date:         Sat, 22 Aug 2009 13:25:10 +0200
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: Frank Mittelbach <frank.mittelbach@LATEX-PROJECT.ORG>
Subject: Re: template customising
To: LATEX-L@LISTSERV.UNI-HEIDELBERG.DE
In-Reply-To:  <874332F9-007B-4945-87D5-48B28BBC11CC@gmail.com>
Precedence: list
Status: R

Will Robertson writes:

 > I've now got a new question. Following Joseph's examples, we might  
 > have something like \chapter which uses an instance 'chapter' of type  
 > 'sectioning'.
 > 
 > What should be done at the document design level to customise the look  
 > of the chapter headings? I don't think we want to have to redefine  
 > \chapter, so there are two options:
 > 
 > 1. create a fresh instance called 'chapter' with the desired parameters,
 > 2. "edit" the current 'chapter' instance.

I guess we first have to get clear about which use case we are tackling here. 

If we want to change the interface of "chapter" in the document, ie change the
document user level (which would be layer -1 in my model outlined in the mail
yesterday) then one would change the \chapter command definition and possibly
the semantics on layer 0 if the change to the document model is extensive.

But I guess you meant changing the typographical representation of "chapter"
and in that case the change should happen on layer 1, i.e., modifying the
instance that implements "chapter" in this layout.

 > The first option is what is necessary in, say, titlesec. I've got to  
 > admit it's not my favourite, because it requires you to possibly set  
 > or re-set a bunch of parameters that you were already happy with. (And  
 > you also have to know the name of the template it was produced with.)

At the moement this is the only way to change a layout, i.e. one has to
replace one instance declaration with another, even if you only want to
replace a single key/val setting.

 > Let's say then that I'd like to be able to edit the instance  
 > 'chapter'; is there any way to be able to do this?
 > 
 > 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.

Technically that would be possible I think, but I don't see how it would fit a
workable use-case for the designer level.

There is no way (in my opinion) for a person that wants to change the layout
to do so without knowing which template has been used in producing the
particular instance. If he or she doesn't know then there is no way to know
which keyvals to use either. After all one important point about templates is
that while they attempt to implement the same semantics (ie an object of a
certain template type) they might do so in totally different ways. For
example, with sectioning, one template might measure vertical distances
baseline to baseline while some other might specify before/after skips etc.

Therefore a declaration that updates an existing instance should carry the
name of the used template as in 

   \EditInstance{<template type>}{<instance name>}{<template name>}
          { <keyvals> }

This way the command can also ensure that the current <instance name> was
actually made using <template name> which is important both for clarity and
applicability.


In practical terms there is not much difference fully copying an instance
declaration and changing a keyval or two and doing the same by something like
\EditInstance. But there is a focus difference: if one copies the whole
instance declaration to the document one doesn't see what modifications to the
standard design have been done without comparing the instance declarations in
detail whereas

   \EditInstance{sectioning}{chapter}{plain-head-A}
          { font = optima }

directly tells that only the heading font gots modified. So it might be a good
idea to provide such an interface extension for layer 1

frank