LATEX-L Archives

Mailing list for the LaTeX3 project

LATEX-L@LISTSERV.UNI-HEIDELBERG.DE

Options: Use Classic View

Use Monospaced Font
Show HTML Part by Default
Condense Mail Headers

Topic: [<< First] [< Prev] [Next >] [Last >>]

Print Reply
Sender: Mailing list for the LaTeX3 project <[log in to unmask]>
Date: Wed, 19 Aug 2009 16:07:51 +0100
Reply-To: Mailing list for the LaTeX3 project <[log in to unmask]>
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
In-Reply-To: <[log in to unmask]>
Content-Type: text/plain; charset=ISO-8859-1
From: Joseph Wright <[log in to unmask]>
Parts/Attachments: text/plain (145 lines)
Frank Mittelbach wrote:
>  > So, following my
>  > division-of-the-document example, the base layer could be
>  > 
>  > \DeclareTemplateClass { sectioning } 3 % Assuming 3 args.
> 
> yep, except (or in addition) with the declaration that should be a
> documentation of the semantics defined by the templatetype/class. Of course,
> we don't have a way to verify it being obeyed other than by human, but it is
> an integral part of the definition. (might well be another argument that
> receives text - at the moment it is just documentation that provides this
> essential part).

My example was just at the code level: you are quite right that some
documentation should be provided.  You could consider some kind of
code-based solution (where at least the arguments have to be described),
but I'm not sure that gains much.

>  > then there might be some templates: for an book-like document there
>  > might be two:
>  > 
>  > \DeclareTemplate { sectioning } { chapter } { <keys> } { <code> }
>  > \DeclareTemplate { sectioning } { section } { <keys> } { <code> }
> 
> well, I'm not to keen on the wording you use here; templates types/classes are
> independent of document classes, and therefore templates essentially
> too. Starting from that observation I would typically not use names like
> "chapter" or "section" but rather something more conveying the idea of what
> range of layouts this template can produce. But as they are just names we are
> fine for now (I think fncyhead package in 2e (if you think of it as a kind of
> template idea) comes up with template names named after their originators, so
> anything is possible.

I was struggling to some up with good names, and was just thinking along
the "like the LaTeX2e base <whatever>". However, you are right that
something like

\DeclareTemplate { sectioning } { starts-new-page }
  { <keys> } { <code> }
\DeclareTemplate { sectioning } { space-before-and-after }
  { <keys> } { <code> }

(or something more snappy) would be better.

>  > (Based on the \cs_set:Nn idea, I'm not keen on repeating the number of
>  > arguments here: should be picked up from the type.)
> 
> yes it could but I'm personally not too keen on this kind of indirection but
> that again is a totally separate discussion and should worry us now.

I assume "should *not* worry us now". There are several things to
decide, of course, but if we can get them discussed over not too long a
period it would be good.  I'll perhaps come back to this issue, and some
other naming ones, in another mail.

>  > Finally, there are instances (I'm going to use a function
>  > "\DeclareTemplateInstance": explanation in a moment).
>  > 
>  > \DeclareTemplateInstance { sectioning } { chapter } { chapter }
>  >   { <keys> }
>  > \DeclareTemplateInstance { sectioning } { section } { section }
>  >   { <keys> }
>  > \DeclareTemplateInstance { sectioning } { section } { subsection }
>  >   { <keys> }
>  > \DeclareTemplateInstance { sectioning } { section } { subsubsection }
>  >   { <keys> }
> 
> ok, except that this is a classic case better for choosing different names as
> I said earlier: I mean there is nothing really wrong with calling a template
> that defines a range of chapter layouts "chapter" but in my opinion that name
> is better reserved for the instance in a document class while using some more
> layout specific names for the templates .

Following my modified example:

\DeclareTemplateInstance { sectioning } { starts-new-page }
  { chapter } { <keys> }
\DeclareTemplateInstance { sectioning } { space-before-and-after }
  { section } { <keys> }
\DeclareTemplateInstance { sectioning } { space-before-and-after }
  { subsection } { <keys> }
\DeclareTemplateInstance { sectioning } { space-before-and-after }
  { subsubsection } { <keys> }

[snip]

> \DeclareTemplateInstance is fine enough since that is precisely what the
> function does, taking a template of a certain type/class and instantiating it.
> 
> However, conceptually speaking
> 
> \UseTemplateInstance        and  \DeclareTemplateClass/Type
> 
> are both wrong, because in case of an instance as in 
> 
> 
>  \DeclareDocumentCommand \chapter { s o m } {
>      \UseTemplateInstance { sectioning } { chapter }
>   }
> 
> we don't actually care whether or not that came from a template through
> instantiation, do we? If worst come to worst one could write the "chapter"
> instance by hand without any template involved: all that is required is that
> by the end of the day calling 
> 
>      \UseXXX { sectioning } { chapter }
> 
> results in picking up a defined number of argument (three in our example)
> processing them according to the semantic description behind "sectioning"
> 
> For that reason both commands aren't really tied to templates even though in
> practical terms in most cases realization is done via templates and
> instantiation of templates
> 
> 
> Having said all this I would propose that you stick with the old names (and
> order of arguments) for now, rather than "improving" names as we go along as
> that is likely to make things worse and make it much more difficult to test
> out different implementations.
> 
> It needs an holistic view to see what works best and while I agree that naming
> argument orders etc can and should be improved, I don't think we are ready for
> this.

My general concern is to try to get template to the point where things
won't change again at the interface level. So I'm keen we agree on
things like naming and argument order, as in the longer term it's important.

From what you say, it sounds as if we are better looking at things a
slightly different way. The key connection is between instances and
types, with templates as a likely but not essential "glue". So is
something like:

\DeclareInstanceType         (was \DeclareTemplateType)
\DeclareTemplate             (no change)
\DeclareInstanceFromTemplate (was \DeclareInstance)
\UseInstance                 (no change)

any more logical?  In that way, you can imagine declaring an instance in
some other way than from a template. I'm not looking for change for
changes sake, but am trying to make sure that things are as clear as
possible for anyone using the system.
-- 
Joseph Wright

ATOM RSS1 RSS2