MIME-Version: 1.0
Content-Type: multipart/alternative;
	boundary="----_=_NextPart_001_01BF673A.194E7700"
In-Reply-To:  <f91f17e9@corona.oche.de>
References: <f91f17e9@corona.oche.de>
Content-class: urn:content-classes:message
Subject:      template interfaces and what they mean
Date: Tue, 25 Jan 2000 14:42:38 +0100
Message-ID:  <200001251342.OAA01742@istrati.zdv.uni-mainz.de>
From: "Frank Mittelbach" <frank.mittelbach@LATEX-PROJECT.ORG>
Sender: "Mailing list for the LaTeX3 project" <LATEX-L@URZ.UNI-HEIDELBERG.DE>
To: "Multiple recipients of list LATEX-L" <LATEX-L@URZ.UNI-HEIDELBERG.DE>
Reply-To: "Mailing list for the LaTeX3 project" <LATEX-L@URZ.UNI-HEIDELBERG.DE>
Status: R

This is a multi-part message in MIME format.

------_=_NextPart_001_01BF673A.194E7700
Content-Type: text/plain;
	charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable

part of Achim's reply to "templates for galley" tempted me to think =
about this
once more and offer some thoughts for discussion.

main point is i would like you to think about is, what are the =
invariants of
that interface, ie what can be assumed to be the same from one template =
to the
next (within a type) and what can differ.


Here is the extract from Achim's mail that triggered this:

 > o pshape template. Perhaps it would be a good idea to add two =
arguments
 >   to the pshape template for the horizontal and vertical dimension
 >   (where the exact meaning depends on the template). Say, a template
 >   for a rectangular cutout could interpret the horizontal dimension
 >   as width of the cotout and the vertical dimension as number of =
lines
 >   to be indented.
 >
 > o justification template. I'm not quiet sure how the galley templates
 >   are intented to be used -- the package only defines the templates
 >   themselve no commands to use them. But I think that the =
justification
 >   templates shouldn't be able to choose whether they affect all
 >   paragraphs or only the next one. Instead the user should be able to
 >   tell the system which case is desired everywhere such a template is
 >   used.


to formulate those a bit more abstractly:

 1) how much freedom has a template to interpret its arguments (ie data =
passed
    to it from the document)?

 2) what is the scope a template instance apply itself? is it =
well-defined?

let's tackle 1) first. Achim suggests that the pshape type should get =
two
arguments those meaning should depend on the template. in my opinion =
this is
likely to result in chaos.

the main idea behind the template types is that logical structure of the
document, i.e., the commands and environments therein, are transformed =
into
instance calls of templates of certain types. this is defined via, say, =
an
xpare interface and does define the document class (no formatting yet)
structure.

now the task of the designer is to declare such instances (whose names =
are
fixed by the structural part above). He/she does that by declaring =
instances
using \DeclareInstance{<type>}{<name>}{<template>}... and specifying =
values
for the keys that belong to <template>.

and that should be enough to design a layout (just a lot of =
\DeclareInstance)
nothing more (we leave out the case that there isn't a suitable template =
for a
design looking like ... and just assume that such templates are all =
written)

so to make this work templates of the same type need to interpret data =
coming
from the document (ie via arguments) in the same way. At best I see that =
they
might be allowed to ignore it.

to give an example: in xhj i defined two templates of type measure which
change the measure of the galley. One of the templates does this =
relative to
the current measure in the template and another one does this by specify
absolute values in its keys. This type accepts an argument to overwrite =
the
left margin width. Now if one template would interpret a value coming =
from the
document as "add this to the left margin" and the other as "this is the =
left
margin width" then guess how exchangable those templates get!

as for allowing a template to ignore such values, again an example: =
suppose we
have a list template type which as one of its arguments gets the left
indentation of the list matter (or \NoValue if nothing was specified by =
the
user in the document). The intention is to allow a document syntax like:

  \begin{description}[foobar]

where the string "foobar" defines the width of the indentation (eg could =
be
the widest label), in latex2e thebibliography is in fact an environment =
that
is more or less of this type (except that the argument is not optional)

Now suppose you have a design where nested lists at a certain level are
formatted in a paragraph instead of making each item a separate =
paragraph. In
that case a notion of "left margin" is no longer appropriate. Now one =
could
argue that those two type of lists should not have the same list type, =
but I
think they should since otherwise how do I switch from one such layout =
to the
other for the same "document class" (ie document level syntax)

So allowing to ignore argument values is a weak form of acceptance which =
(in
most cases) allows to format a document in different layouts even if the
document does contain some elements with "formatting like" data.

Of course, another way to avoid this problem would be to disallow =
arguments to
templates which do carry "formatting related" information. But that one =
the
other hand would render the interface much less flexible and if it is =
too
clumsy for the user to guide the layout in certain comon cases that i =
think
something was done wrong.

To return to the pshape template: so I don't think it should get =
arguments
that are interpreted differently by different templates. In fact for =
that
particular template type I don't think it should get arguments at all.

I see this template as something (again) to be used only as part of =
other
templates to define very specialised shapes in certain layouts --- but =
shapes
which are independent of of document data but exist in their own right.

For example, I came recently across a very nicely formatted book whose =
Capter
openings have all be done by having the first paragraph with a triangle =
like
cutout that was part of the design for the chapter head. That's the kind =
of
area where I see applications for pshape.

In contrast, if one wants to provide commands that allow the user to =
directly
manipulate the paragraph shape somehow (one example in a restricted =
sense
being Initials) then this should not be done via the templates provided =
in xhj
but by making use of the lower-level interface that comes with =
galley2.dtx

the module xinitials will do something like that

=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D

do you remember what the second abstract question was? No? Here is =
another
rephrase:

  to what elements should templates apply that do set parameters of =
underlying
  algorithms (in some way or other)

for example the "std" template of type justification sets the =
justification
for all upcoming paragraphs of the galley (potentially at least) while =
the
"single" template sets it only for the next. Achim suggested that not =
the
template but the user should decide on the scope.

Now I agree with him but who is the "user"? The user is the designer of =
the
document class layout and if this "user" says that the first paragraph =
of a
caption should have the first line centered and any following paragraphs
should be justified without indentation then he can do this now by =
setting a

 justification-setup =3Di

key to the appropriate value. by making the (i agree) somewhat different
feeling templates one and the same type I allowed for flexibility in
design. In an earlier implementation I had two types but that resulted =
in
either strange templates (making use of both) or in a lot of repitition, =
ie
the need to have nearly identical templates differing only in one key =
since
that key was of a different type.

another way to look at it is to say that the "single" one is actually =
also
setting all paragraphs in the galley (it sets the first to X and the =
rest to
whatever was before X).

yet another way is to get rid of "single" and implement what i called
"complex" differently since what in practise will be needed are the =
instances
from "std" and from "complex"

does this make some sense?

------------------------------

a related question is whether it is permissable for templates to do =
inheriting
of values while other templates of the same type do set all values. I =
think i
should be permissable for the sake of flexibility, however, it is a fact =
that
this makes looking at a design implementation (ie at a list of
\DeclareInstance commands) a bit diffcult if not used with care.
After all you may have difficulties to guess what is actually gonna be =
used if
such template instances then follow each other.

comments?


frank

------_=_NextPart_001_01BF673A.194E7700
Content-Type: text/html;
	charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV=3D"Content-Type" CONTENT=3D"text/html; =
charset=3Diso-8859-1">
<META NAME=3D"Generator" CONTENT=3D"MS Exchange Server version =
6.5.7654.12">
<TITLE>     template interfaces and what they mean</TITLE>
</HEAD>
<BODY>
<!-- Converted from text/plain format -->

<P><FONT SIZE=3D2>part of Achim's reply to &quot;templates for =
galley&quot; tempted me to think about this</FONT>

<BR><FONT SIZE=3D2>once more and offer some thoughts for =
discussion.</FONT>
</P>

<P><FONT SIZE=3D2>main point is i would like you to think about is, what =
are the invariants of</FONT>

<BR><FONT SIZE=3D2>that interface, ie what can be assumed to be the same =
from one template to the</FONT>

<BR><FONT SIZE=3D2>next (within a type) and what can differ.</FONT>
</P>
<BR>

<P><FONT SIZE=3D2>Here is the extract from Achim's mail that triggered =
this:</FONT>
</P>

<P><FONT SIZE=3D2>&nbsp;&gt; o pshape template. Perhaps it would be a =
good idea to add two arguments</FONT>

<BR><FONT SIZE=3D2>&nbsp;&gt;&nbsp;&nbsp; to the pshape template for the =
horizontal and vertical dimension</FONT>

<BR><FONT SIZE=3D2>&nbsp;&gt;&nbsp;&nbsp; (where the exact meaning =
depends on the template). Say, a template</FONT>

<BR><FONT SIZE=3D2>&nbsp;&gt;&nbsp;&nbsp; for a rectangular cutout could =
interpret the horizontal dimension</FONT>

<BR><FONT SIZE=3D2>&nbsp;&gt;&nbsp;&nbsp; as width of the cotout and the =
vertical dimension as number of lines</FONT>

<BR><FONT SIZE=3D2>&nbsp;&gt;&nbsp;&nbsp; to be indented.</FONT>

<BR><FONT SIZE=3D2>&nbsp;&gt;</FONT>

<BR><FONT SIZE=3D2>&nbsp;&gt; o justification template. I'm not quiet =
sure how the galley templates</FONT>

<BR><FONT SIZE=3D2>&nbsp;&gt;&nbsp;&nbsp; are intented to be used -- the =
package only defines the templates</FONT>

<BR><FONT SIZE=3D2>&nbsp;&gt;&nbsp;&nbsp; themselve no commands to use =
them. But I think that the justification</FONT>

<BR><FONT SIZE=3D2>&nbsp;&gt;&nbsp;&nbsp; templates shouldn't be able to =
choose whether they affect all</FONT>

<BR><FONT SIZE=3D2>&nbsp;&gt;&nbsp;&nbsp; paragraphs or only the next =
one. Instead the user should be able to</FONT>

<BR><FONT SIZE=3D2>&nbsp;&gt;&nbsp;&nbsp; tell the system which case is =
desired everywhere such a template is</FONT>

<BR><FONT SIZE=3D2>&nbsp;&gt;&nbsp;&nbsp; used.</FONT>
</P>
<BR>

<P><FONT SIZE=3D2>to formulate those a bit more abstractly:</FONT>
</P>

<P><FONT SIZE=3D2>&nbsp;1) how much freedom has a template to interpret =
its arguments (ie data passed</FONT>

<BR><FONT SIZE=3D2>&nbsp;&nbsp;&nbsp; to it from the document)?</FONT>
</P>

<P><FONT SIZE=3D2>&nbsp;2) what is the scope a template instance apply =
itself? is it well-defined?</FONT>
</P>

<P><FONT SIZE=3D2>let's tackle 1) first. Achim suggests that the pshape =
type should get two</FONT>

<BR><FONT SIZE=3D2>arguments those meaning should depend on the =
template. in my opinion this is</FONT>

<BR><FONT SIZE=3D2>likely to result in chaos.</FONT>
</P>

<P><FONT SIZE=3D2>the main idea behind the template types is that =
logical structure of the</FONT>

<BR><FONT SIZE=3D2>document, i.e., the commands and environments =
therein, are transformed into</FONT>

<BR><FONT SIZE=3D2>instance calls of templates of certain types. this is =
defined via, say, an</FONT>

<BR><FONT SIZE=3D2>xpare interface and does define the document class =
(no formatting yet)</FONT>

<BR><FONT SIZE=3D2>structure.</FONT>
</P>

<P><FONT SIZE=3D2>now the task of the designer is to declare such =
instances (whose names are</FONT>

<BR><FONT SIZE=3D2>fixed by the structural part above). He/she does that =
by declaring instances</FONT>

<BR><FONT SIZE=3D2>using =
\DeclareInstance{&lt;type&gt;}{&lt;name&gt;}{&lt;template&gt;}... and =
specifying values</FONT>

<BR><FONT SIZE=3D2>for the keys that belong to &lt;template&gt;.</FONT>
</P>

<P><FONT SIZE=3D2>and that should be enough to design a layout (just a =
lot of \DeclareInstance)</FONT>

<BR><FONT SIZE=3D2>nothing more (we leave out the case that there isn't =
a suitable template for a</FONT>

<BR><FONT SIZE=3D2>design looking like ... and just assume that such =
templates are all written)</FONT>
</P>

<P><FONT SIZE=3D2>so to make this work templates of the same type need =
to interpret data coming</FONT>

<BR><FONT SIZE=3D2>from the document (ie via arguments) in the same way. =
At best I see that they</FONT>

<BR><FONT SIZE=3D2>might be allowed to ignore it.</FONT>
</P>

<P><FONT SIZE=3D2>to give an example: in xhj i defined two templates of =
type measure which</FONT>

<BR><FONT SIZE=3D2>change the measure of the galley. One of the =
templates does this relative to</FONT>

<BR><FONT SIZE=3D2>the current measure in the template and another one =
does this by specify</FONT>

<BR><FONT SIZE=3D2>absolute values in its keys. This type accepts an =
argument to overwrite the</FONT>

<BR><FONT SIZE=3D2>left margin width. Now if one template would =
interpret a value coming from the</FONT>

<BR><FONT SIZE=3D2>document as &quot;add this to the left margin&quot; =
and the other as &quot;this is the left</FONT>

<BR><FONT SIZE=3D2>margin width&quot; then guess how exchangable those =
templates get!</FONT>
</P>

<P><FONT SIZE=3D2>as for allowing a template to ignore such values, =
again an example: suppose we</FONT>

<BR><FONT SIZE=3D2>have a list template type which as one of its =
arguments gets the left</FONT>

<BR><FONT SIZE=3D2>indentation of the list matter (or \NoValue if =
nothing was specified by the</FONT>

<BR><FONT SIZE=3D2>user in the document). The intention is to allow a =
document syntax like:</FONT>
</P>

<P><FONT SIZE=3D2>&nbsp; \begin{description}[foobar]</FONT>
</P>

<P><FONT SIZE=3D2>where the string &quot;foobar&quot; defines the width =
of the indentation (eg could be</FONT>

<BR><FONT SIZE=3D2>the widest label), in latex2e thebibliography is in =
fact an environment that</FONT>

<BR><FONT SIZE=3D2>is more or less of this type (except that the =
argument is not optional)</FONT>
</P>

<P><FONT SIZE=3D2>Now suppose you have a design where nested lists at a =
certain level are</FONT>

<BR><FONT SIZE=3D2>formatted in a paragraph instead of making each item =
a separate paragraph. In</FONT>

<BR><FONT SIZE=3D2>that case a notion of &quot;left margin&quot; is no =
longer appropriate. Now one could</FONT>

<BR><FONT SIZE=3D2>argue that those two type of lists should not have =
the same list type, but I</FONT>

<BR><FONT SIZE=3D2>think they should since otherwise how do I switch =
from one such layout to the</FONT>

<BR><FONT SIZE=3D2>other for the same &quot;document class&quot; (ie =
document level syntax)</FONT>
</P>

<P><FONT SIZE=3D2>So allowing to ignore argument values is a weak form =
of acceptance which (in</FONT>

<BR><FONT SIZE=3D2>most cases) allows to format a document in different =
layouts even if the</FONT>

<BR><FONT SIZE=3D2>document does contain some elements with =
&quot;formatting like&quot; data.</FONT>
</P>

<P><FONT SIZE=3D2>Of course, another way to avoid this problem would be =
to disallow arguments to</FONT>

<BR><FONT SIZE=3D2>templates which do carry &quot;formatting =
related&quot; information. But that one the</FONT>

<BR><FONT SIZE=3D2>other hand would render the interface much less =
flexible and if it is too</FONT>

<BR><FONT SIZE=3D2>clumsy for the user to guide the layout in certain =
comon cases that i think</FONT>

<BR><FONT SIZE=3D2>something was done wrong.</FONT>
</P>

<P><FONT SIZE=3D2>To return to the pshape template: so I don't think it =
should get arguments</FONT>

<BR><FONT SIZE=3D2>that are interpreted differently by different =
templates. In fact for that</FONT>

<BR><FONT SIZE=3D2>particular template type I don't think it should get =
arguments at all.</FONT>
</P>

<P><FONT SIZE=3D2>I see this template as something (again) to be used =
only as part of other</FONT>

<BR><FONT SIZE=3D2>templates to define very specialised shapes in =
certain layouts --- but shapes</FONT>

<BR><FONT SIZE=3D2>which are independent of of document data but exist =
in their own right.</FONT>
</P>

<P><FONT SIZE=3D2>For example, I came recently across a very nicely =
formatted book whose Capter</FONT>

<BR><FONT SIZE=3D2>openings have all be done by having the first =
paragraph with a triangle like</FONT>

<BR><FONT SIZE=3D2>cutout that was part of the design for the chapter =
head. That's the kind of</FONT>

<BR><FONT SIZE=3D2>area where I see applications for pshape.</FONT>
</P>

<P><FONT SIZE=3D2>In contrast, if one wants to provide commands that =
allow the user to directly</FONT>

<BR><FONT SIZE=3D2>manipulate the paragraph shape somehow (one example =
in a restricted sense</FONT>

<BR><FONT SIZE=3D2>being Initials) then this should not be done via the =
templates provided in xhj</FONT>

<BR><FONT SIZE=3D2>but by making use of the lower-level interface that =
comes with galley2.dtx</FONT>
</P>

<P><FONT SIZE=3D2>the module xinitials will do something like =
that</FONT>
</P>

<P><FONT =
SIZE=3D2>=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D</FONT>
</P>

<P><FONT SIZE=3D2>do you remember what the second abstract question was? =
No? Here is another</FONT>

<BR><FONT SIZE=3D2>rephrase:</FONT>
</P>

<P><FONT SIZE=3D2>&nbsp; to what elements should templates apply that do =
set parameters of underlying</FONT>

<BR><FONT SIZE=3D2>&nbsp; algorithms (in some way or other)</FONT>
</P>

<P><FONT SIZE=3D2>for example the &quot;std&quot; template of type =
justification sets the justification</FONT>

<BR><FONT SIZE=3D2>for all upcoming paragraphs of the galley =
(potentially at least) while the</FONT>

<BR><FONT SIZE=3D2>&quot;single&quot; template sets it only for the =
next. Achim suggested that not the</FONT>

<BR><FONT SIZE=3D2>template but the user should decide on the =
scope.</FONT>
</P>

<P><FONT SIZE=3D2>Now I agree with him but who is the &quot;user&quot;? =
The user is the designer of the</FONT>

<BR><FONT SIZE=3D2>document class layout and if this &quot;user&quot; =
says that the first paragraph of a</FONT>

<BR><FONT SIZE=3D2>caption should have the first line centered and any =
following paragraphs</FONT>

<BR><FONT SIZE=3D2>should be justified without indentation then he can =
do this now by setting a</FONT>
</P>

<P><FONT SIZE=3D2>&nbsp;justification-setup =3Di</FONT>
</P>

<P><FONT SIZE=3D2>key to the appropriate value. by making the (i agree) =
somewhat different</FONT>

<BR><FONT SIZE=3D2>feeling templates one and the same type I allowed for =
flexibility in</FONT>

<BR><FONT SIZE=3D2>design. In an earlier implementation I had two types =
but that resulted in</FONT>

<BR><FONT SIZE=3D2>either strange templates (making use of both) or in a =
lot of repitition, ie</FONT>

<BR><FONT SIZE=3D2>the need to have nearly identical templates differing =
only in one key since</FONT>

<BR><FONT SIZE=3D2>that key was of a different type.</FONT>
</P>

<P><FONT SIZE=3D2>another way to look at it is to say that the =
&quot;single&quot; one is actually also</FONT>

<BR><FONT SIZE=3D2>setting all paragraphs in the galley (it sets the =
first to X and the rest to</FONT>

<BR><FONT SIZE=3D2>whatever was before X).</FONT>
</P>

<P><FONT SIZE=3D2>yet another way is to get rid of &quot;single&quot; =
and implement what i called</FONT>

<BR><FONT SIZE=3D2>&quot;complex&quot; differently since what in =
practise will be needed are the instances</FONT>

<BR><FONT SIZE=3D2>from &quot;std&quot; and from =
&quot;complex&quot;</FONT>
</P>

<P><FONT SIZE=3D2>does this make some sense?</FONT>
</P>

<P><FONT SIZE=3D2>------------------------------</FONT>
</P>

<P><FONT SIZE=3D2>a related question is whether it is permissable for =
templates to do inheriting</FONT>

<BR><FONT SIZE=3D2>of values while other templates of the same type do =
set all values. I think i</FONT>

<BR><FONT SIZE=3D2>should be permissable for the sake of flexibility, =
however, it is a fact that</FONT>

<BR><FONT SIZE=3D2>this makes looking at a design implementation (ie at =
a list of</FONT>

<BR><FONT SIZE=3D2>\DeclareInstance commands) a bit diffcult if not used =
with care.</FONT>

<BR><FONT SIZE=3D2>After all you may have difficulties to guess what is =
actually gonna be used if</FONT>

<BR><FONT SIZE=3D2>such template instances then follow each =
other.</FONT>
</P>

<P><FONT SIZE=3D2>comments?</FONT>
</P>
<BR>

<P><FONT SIZE=3D2>frank</FONT>
</P>

</BODY>
</HTML>
------_=_NextPart_001_01BF673A.194E7700--