LATEX-L Archives

Mailing list for the LaTeX3 project


Options: Use Forum View

Use Monospaced Font
Show Text Part by Default
Show All Mail Headers

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

Print Reply
Lars Hellström <[log in to unmask]>
Reply To:
Mailing list for the LaTeX3 project <[log in to unmask]>
Sun, 8 Nov 2009 15:57:22 +0100
text/plain (212 lines)
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?


> 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 

>  > >   - 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- ...}{

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