On 21/08/2009, at 5:12 PM, Joseph Wright wrote:

> No, I'd agree. There is something of a balancing act to do here, at
> least without something like \EditInstance (I'd suggest
> \EditInstanceFromTemplate based on my suggestion that
> \DeclareInstanceFromTemplate is more accurate than just  
> \DeclareInstance).

I prefer the shorter names simply for brevity. I think with good  
documentation the ideas behind
    type -> template -> instance
should be concrete enough that the macro names don't need to be that  
explicit.

As long as we give clear examples I think this will be the case. Note  
that the current documentation is a little more abstract in its  
descriptions such that it took a couple of read-throughs before you  
and I (anyway) were thinking about the terms in the same way.

I think that's more of a documentation problem than a macro name  
problem.

(Not that I'm against renaming things if you like!)

> I imagine that we will end up providing one or more very general
> templates with some restricted ones to solve at least parts of the
> issue.

One question that I should just test on my own before asking is "do  
restricted templates cascade?" (...testing...) And the answer is no:

\documentclass{article}
\usepackage{template}
\begin{document}
\DeclareTemplateType{xxx}{0}
\DeclareTemplate{xxx}{test}{0}
{
   xkey=n  \xkey, ykey=n  \ykey, zkey=n  \zkey,
}
{
   \DoParameterAssignments
   (x: \xkey)(y: \ykey)(z: \zkey)
}
\DeclareRestrictedTemplate{xxx}{test2}{test}{xkey=a}
\DeclareRestrictedTemplate{xxx}{test3}{test2}{ykey=b}
\DeclareInstance{xxx}{bar}{test3}{zkey = c}
\UseInstance{xxx}{bar}
\DeclareRestrictedTemplate{xxx}{test2}{test2}{xkey=A}
\UseInstance{xxx}{bar}
\end{document}

The first \UseInstance has xkey and ykey set by the restricted  
templates 'test2' and 'test3', respectively. If we then use  
\DeclareRestrictedTemplate to "edit" the 'test2' template then the  
'bar' instance does not change.

So templates should be considering somewhat "immutable" and perhaps  
\DeclareRestrictedTemplate should call a warning if attempted to  
redefine an existing template as in the example above.

(Else templates themselves could keep track of their instances and  
push down the changes to each of their instances if a template is  
edited -- which would actually involve just re-instantiating the  
instance with the original parameters -- but that seems rather mad to  
me.)

> So you might imagine
>
> \DeclareTemplate { sectioning } { std-complete-customisation } ...
>
> \DeclareRestrictedTemplate { sectioning }
>  { std-font-variable } { std-complete-customisation }
> \DeclareRestrictedTemplate { sectioning }
>  { std-spacing-variable } { std-complete-customisation }
>
> where we put all of the possible changes in the first one then cut  
> down
> on the possibles in the second one.

The problem being, now, that std-font-variable can't change its  
spacing, and std-spacing-variable can't change its font :) That seems  
an odd trade-off to make; how would you ever choose which instance  
should be put into the document?

Since templates don't cascade (i.e., changes to higher templates don't  
flow on to templates and instances down the line) the idea of a  
restricted template seems more limited to cases when you literally  
need to restrict setting certain parameters in order to keep the  
template (or, rather, the design that the template produces) working.

> There is also the point that the template values will probably have a
> default. So if you only want to change one thing from what is "out of
> the box" then you only need
>
> \DeclareInstance { type } { name } { template }
>  { one-changed-key = value }
>
> The problem only comes if you want to change a few keys in an instance
> that already sets several things in the template.

Thinking about things more, I think you're right that the defaults of  
the template are likely to be the parameters that a document's default  
instance takes. And if they're not the template defaults, they'll be  
defined in some sort of obvious configuration file. So I'm starting to  
think that my whole line of questioning is slightly off the mark.

Will