Frank Mittelbach skrev:
> Lars
>
> > > Here is my current list of candiates:
> > >
> > > - title of the heading
> > > - title version to go in the TOC
> > > - title version to go in the running header
> > > - subtitle of the heading (e.g., an author name, copyright notice ...)
> >
> > That one feels a bit wobbly. But is your thinking that this kind of
> > information is frequently appearing in page heads, and page head
> > contents are being set by this kind of command, so there needs to be a
> > way to pass the information?
>
> you mean the subtitle?
Yes.
> I think this is only of interest to some kind of
> headings and then only to A-heads probably, so i'm not sure about that one
> really, I just tossed it out for discussion. On the other hand, it seems to me
> that for A-heads that is in theory common enough (for example in proceedings)
> that I think it should be included even if for most documents it is not
> necessarily made available on document.
I was mostly thinking that the description seemed very vague -- sort of
"here we can put *one* piece of information that won't fit anywhere
else", which IMHO would be poor API design: meaning of data is
unspecified, and it's not sufficiently flexible. E.g. author name and
copyright information might well be independent.
As for A-heads: I read a book recently that had a separate author for
each chapter, and a division into parts above that. (It also has
copyright information in every page footer, although only a constant
"(C) The authors and <name of publisher>".)
> > > - motto/quote text to display alongside the heading title
>
> having said the above, one probably doesn't need both "sub-title" and "motto"
> as the latter is just another type of sub-title application really.
Depends on whether you look at it graphically or semantically. For
designing a general API, I think you really need to look at it
semantically.
> > > - flag to number heading
> >
> > Or should numbered and unnumbered headings be generated by separate
> > instances? Needs to be thought about.
>
> both is possible of course, but in my opinion a certain design for a heading
> with and without numbers shares so much on the design-level that it seems
> reasonable to provide a single template with a flag to say whether or not to
> generate a number for the heading.
OK, just remember to write down the rationale for these decisions.
> > > do we need a way to specify that something is send to the TOC or to the
> > > running header and if so how do we do that?
> >
> > Isn't that explicit in the above? Or did you rather think about the
> > document-level commands here?
>
> I don't think it is explicit unless you overload things. From a document level
> perspective a writer might want to say
>
> - do not put a title line into the toc
> - do not put a title line into the running header
> - not not number this heading
Ah, so "specify that something is send to the TOC" means whether to put
anything at all there, not what exact text to put there. My bad.
> in 2e that was alway bundled together with the * so it was all or nothing but
> typically the last one was independent of the other two resulting in the
> gymnastics with \addcontentsline near things like a bibliography etc
>
> on the other hand I must confess that I don't see much application for not
> putting somehting into the toc (on an individual basis but in the running
> header or vice versa). Perhaps others have some experience / examples that
> indiciate otherwise?
>
> anyway, starting from a need to be able to specify that on document-level,
> that then needs to be conveyed to the template and without some explicit flags
> that isn't there.
My first gut reaction is that decisions of whether to put a heading in
the TOC or not should be controlled by the choice of instance (or are
they named "objects" now?).
Then I see that you may indeed want to control this from the document
level command, and doing that via selection of instances, like e.g.
\DeclareDocumentCommand{\section}{t* t+ t- ...}{
\UseInstance{heading}{section%
\IfBooleanT{#1}{-nonumber}%
\IfBooleanT{#2}{-notintoc}%
\IfBooleanT{#3}{-norunning}%
}...
}
is probably not very practical.
On the other hand, it is starting to look like a template for handling
all those flags will become rather complicated. Perhaps one should
rather have separate instances for the three functions of "heading on
page", "heading in TOC", and "heading in running head"? In that case,
it is probably the common syntaxes of these that should be discussed
first. (It is of course possible to later wrap them up as instance type
keys in a "controller" template that only processes the flags and
delegates all typesetting to these instance keys.)
An argument for separating these functions is that doing something
innovative in one of the three areas is not making you more likely to
do something innovative in the two others. E.g. a designer might need
to commision a new template for headings because the design does
something that cannot be achieved simply by setting parameters in the
standard template, but it's only the "heading on page" that needs this.
Creating the new template then becomes much more complicated if it also
has to deal with the technicalities of running heads and TOCs. One
might also want to combine one package's nice "heading on page"
features with another package's feature to include author names in the TOC.
> Unless you start overloading the arguments in a way that
> \NoValue for a TOC title means use the main title for TOC while an empty TOC
> title mean do not use one, or something like that.
[Shiver] Only a last resort.
> > > what else is missing or which of the above aren't sensible in the first place?
> >
> > One might consider making one argument a keyval dictionary and collect
> > many of the above in that instead.
>
>
> that would be a document level syntax decision, ie how to write a heading
> command in your document.
No, I meant it as an *implementation level* syntax.
For commands that do complicated things (and it certainly looks as
though the "make heading" instances fall in this category), it is
generally a fact of life that the number of things you /might/ want to
specify as arguments to them grows much faster than the number of
things you would /typically/ specify as arguments to them; maybe a
typical call has use for $\sqrt{n}$ arguments if there are $n$
arguments in total; for e.g. $n=16$ that would come out as $12$ you
don't care about. Having a separate mandatory argument for each of them
quickly becomes unfeasible, as one pretty much has to look up the
specification every time writing a call just to remember which order
the arguments were in.
A better approach, following *nix command line tools, is to have
*options* -- and in particular options that can take values, like
--unified=3, --src-prefix=foo/bar/, or --pretty=full (to mention 3 of
several dozen options of git-diff-tree). TeX doesn't support variadic
commands that well however, so the natural way for us to implement
"options with values" is to have a single mandatory argument whose
value is a dictionary mapping option names to values, and then some
other mandatory arguments for the few things you really need to specify
in almost every call.
I believe I've come across expl3 using keyval lists for dictionaries
maintained internally in the programming level, so I don't see why it
couldn't use it in the API for an object type as well. But of course,
if some other representation of a dictionary is less troublesome, then
by all means use that instead.
> That is and should be transparent to the templates
> which deal with presentation. Templates are deliberately simple: they only
> have madatory arguments (of which some could receive \NoValue and such
> things).
I'm well aware that \oarg's and the like would be inappropriate here.
What I proposed was rather to have a scheme for "named arguments".
> > When needing a title for the TOC:
> >
> > 1. If there is a key "toctitle", then use that value.
> > 2. Otherwise, if there is a key "shorttitle", then use that value.
> > 3. Otherwise, use the full title.
> >
> > When needing a title for the running head:
> >
> > 1. If there is a key "headtitle", then use that value.
> > 2. Otherwise, if there is a key "shorttitle", then use that value.
> > 3. Otherwise, use the full title.
>
> one follow up question: I'm not quite sure what a shorttitle is supposed to be
> in contrast to toctitle or headtitle. do you mean shorttitle just as a means
> to avoid specifying both toctitle and headtitle with the same value
Not only, but it would probably be the most frequent use for it.
> or could
> there be a shorttitle and a toctitle and would that have any semantic meaning?
Yes. In that case, and under a template behaving as above, running
heads would get the shorttitle whereas the TOC gets the toctitle.
Maybe a comparison with BibTeX entries could be instructive: There
you've essentially got two mandatory arguments (entry type and \cite
key) for each entry, and everything else (author, title, etc.) is
supplied as (more or less optional) named arguments -- syntactically a
large keyval list. The analogy isn't prefect, as the entry type borders
on being the equivalent of an instance name, but I'm beginning to
suspect there is a similar variability as to the kinds of information
that might be needed for producing a heading.
Lars Hellström
|
