Achim Blumensath wrote:
> But in order to comment on the details they should be
> published first. You said several times that you couldn't release the
> code of template because it depends on some unfinished other things.
> Perhaps it would be a good idea to just post a list of those templates
> without an actual implementation, just with a description of the
> arguments, attributes, and semantics.
i spend the last couple of hours in writing up ideas and template descriptions
for templates related to TOC formatting since i think this is an interesting
area and since it is something for which I have had a couple of templates done
some time ago.
i don't think that those templates are right but i guess they can serve as a
basis to discuss this area and i hope they spawn further discussion and
interest.
the document below (xcontents.dtx) deliberately doesn't contain any code so
the gentle reader is invited to implement the described template him/herself
:-) or even better come up with better ones.
have fun
frank
----------- xcontents.dtx ---------------------
% \iffalse
%%
%% (C) Copyright 1999 Frank Mittelbach
%% All rights reserved.
%%
%% Not for general distribution. In its present form it is not allowed
%% to put this package onto CD or an archive without consulting the
%% the authors.
%%
%<*dtx>
\ProvidesFile{xcontents.dtx}
%</dtx>
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{xcontents}
%<driver>\ProvidesFile{xcontents.drv}
% \fi
% \ProvidesFile{xcontents.dtx}
[1999/11/06 v0.10 contents layouts]
%
% \iffalse
%<*driver>
\documentclass{ltxdoc}
\usepackage{textcomp}
% \usepackage{xparse,xlists,xlists-samples}
% \usepackage{ldcdoc}
% next three definitions are big hacks to run the file
% without the above packages
%
\newcommand\NoValue{\texttt{\textbackslash NoValue}}
\newenvironment{TemplateInterfaceDescription}[1]
{\subsection{The Template Type `#1'}%
\begingroup\description
\def\TemplateArgument##1##2{\item[Arg: ##1]##2\par}%
\def\TemplateSemantics{\enddescription\endgroup
\subsubsection*{Semantics}}%
}
{\par\bigskip}
\newenvironment{TemplateDescription}[2]
{\subsection{The Template `#2' (type #1)}%
\subsubsection*{Attributes}
\begingroup\description
\def\TemplateKey##1##2##3##4{\item[##1 (##2)]##3%
\ifx\TemplateKey##4\TemplateKey\else
\hskip0ptplus3em\penalty-500\hskip 0pt plus 1filll Default:~##4%
\fi
\par}%
\def\TemplateSemantics{\enddescription\endgroup
\subsubsection*{Comments}}%
}
{\par\bigskip}
\begin{document}
\DocInput{xcontents.dtx}
\end{document}
%</driver>
% \fi
%
%
% \GetFileInfo{xcontents.dtx}
%
% \title{The \textsf{xcontents} package\thanks{This file
% has version number \fileversion, last
% revised \filedate.}}
% \author{FMi}
% \date{\filedate}
%
% \maketitle
%
% \tableofcontents
%
% \newcommand\keyword[1]{\textsf{#1}}
% \newcommand\template[1]{\textsf{#1}}
%
% \section{Structuring contents information}
%
% In \LaTeXe{} contents information as stored in files like
% |\jobname.toc|, |\jobname.lot|, etc.\@ is a mixture of structured
% data and unstructured data. For example, the line
%\begin{verbatim}
%\contentsline {section}{\numberline {2}Interfaces}{2}
%\end{verbatim}
% is comparably well-structured and thus allows customized processing
% within the table of contents generation. However, the fact that the
% section number appears as part of the heading text argument (even
% though flagged with the command |\numberline|) makes certain types
% of processing unnecessary difficult. Better would be to provide the
% number (if any) as a separate argument.
%
% In addition to |\contentsline| \LaTeXe{} also allows package writers
% (and in fact authors\footnote{Unfortunately this means that the
% author needs to understand how the structured parts of the contents
% files format their data.} via |\addtocontents|) to add arbitrary
% unstructured material to the contents file. In this way formatting
% of the contents data is spread across a large number of places,
% e.g., some heading commands like chapter add vertical space to the
% list of figure files this way.
%
% As an alternative one could think of sending all contents data to a
% single location and, depending on whether one formats a TOC or a LOF
% this data is analysed differently. As an advantage such a scheme
% would allow to provide some of this information in a single
% presentation, e.g., all figures and tables in a single list or even
% having them presented as part of the TOC.
%
% Another problem with the current data structure is its missing
% support for the preparation of partial TOCs, e.g., TOCs per chapter
% or summary TOCs. Of course this information can be extracted in
% theory from the |.toc| file (and there exist packages that provide
% this functionality) a better support from the start could be
% provided without much (or even any) overhead and should therefore be
% considered.
%
% \subsection{Proposal for a new structure}
%
% A toc like file in the new structure consists of code lines
% containing |\contentsobject| calls (and probably nothing else). Each
% such |\contentsobject| command receives (currently) seven arguments
% which are the following:
% \begin{description}
% \item[sequence number]
% Number that is incremented for every contents object being added
% to the output file.\footnote{At the moment this is a single
% counter! fix.} This could be handy if you want to read in a toc
% file to extract just all bits that refer to the current chapter
% (there are other ways but this seems a nice one).
%
% \item[level]
% This is the level of the hierarchy at which the the object lives
% according to the template that generated it (e.g., if generated from
% a heading template it would be the value of the keyword
% \keyword{level-id}.
%
% \iffalse % no longer true!!!
% \item[object number on level]
% This is the unformatted number of the counter of the generating
% object, ie it denotes the number of objects already on this level.
% --- in cases of unnumbered headings, say, where no counter is
% stepped this shows the same number as before which is a little
% weird. perhaps it should show \NoValue{} in that case. anyway,
% right now this is not used but i thought it could be handy to
% have.
% \fi
%
% \item[type]
% This is the object type (a name) which is used to construct the
% \template{contentsobject} template instance name when formatting
% it. In many cases this will be the instance name, but in special
% situation a \template{processcontents} instance can set up a
% \keyword{collection-id} in which case the name will be the string
% concatenation of both.
%
% Note that on a given `level' there might be objects of a different
% type requiring different handling.
%
% \item[object number]
% This is the object number string as generated from |\the...| counter
% representation or \NoValue{} if the object doesn't have a number
% associated with it.
%
% \item[text]
% The object text, e.g., the heading title.
%
% \item[extra text]
% Extra text (such as the authors name in a multi-article
% collection) or \NoValue{} (currently not used by the existing
% templates).
%
% \item[page number]
% The page number as generated from |\thepage|.
% \end{description}
%
% An example of this new structure would be the following:
%\begin{verbatim}
%\contentsobject {1}{1}{section}{1}{A first section}{}{1}
%\contentsobject {2}{2}{subsection}{1.1}{A first subsection}{}{1}
%\contentsobject {3}{2}{subsection}{1.2}{A second subsection with an
% awful long title: some text or other to get us going right?}{}{1}
%\contentsobject {4}{3}{subsubsection}{1.2.1}{A direct subsubsection}{}{1}
%\contentsobject {5}{1}{section}{\NoValue }{Heading two as section}{}{1}
%\contentsobject {6}{2}{subsection}{1.3}{With a direct subsection}{}{1}
%\contentsobject {7}{3}{subsubsection}{1.3.1}{And some subsubsection}{}{1}
%\contentsobject {8}{4}{paragraph}{\NoValue }{A runin paragraph}{}{1}
%\contentsobject {9}{4}{paragraph}{\NoValue }{Another runin paragraph}{}{1}
%\contentsobject {10}{5}{subparagraph}{\NoValue }{Another runin
% subparagraph}{}{1}
%\contentsobject {11}{5}{subparagraph}{\NoValue }{Another runin
% subparagraph number two}{}{1}
%\contentsobject {12}{5}{subparagraph}{\NoValue }{Another runin
% subparagraph number three}{}{1}
%\contentsobject {13}{1}{section}{2}{And another section}{}{1}
%\contentsobject {14}{2}{subsection}{2.1}{that has a subsection}{}{1}
%\contentsobject {15}{1}{section}{3}{A test}{}{2}
%\contentsobject {16}{2}{subsection}{\NoValue }{with an unnumbered
% subsection}{}{2}
%\end{verbatim}
%
% \section{Interfaces}
%
% The \texttt{contentsobject} template type has the same arguments as
% the |\contentsobject| command in the above data structure except that
% the third argument (type) is missing since it is used to produce the
% instance name.\footnote{For clarity it might be better to make this
% the first argument of \texttt{\textbackslash contentsobject}!}
%
% \begin{TemplateInterfaceDescription}{contentsobject}
%
% \TemplateArgument{1}
% {The sequence number of this object in the data structure}
%
% \TemplateArgument{2}
% {Level of this contents object in the hierarchy}
%
% \TemplateArgument{3}
% {Object number in the document if present or \NoValue}
%
% \TemplateArgument{4}
% {Object text (e.g., heading title)}
%
% \TemplateArgument{5}
% {Additional info if present or \NoValue}
%
% \TemplateArgument{6}
% {Page Number}
%
% \TemplateSemantics
%
% Todays version has quite a mouthful of arguments but perhaps we
% want even more or different ones. Passing on the level is useful
% especially if we globally keep the previous level in a variable
% for inspection. Thus an object can do different actions depending
% on the level of the previous element.
%
% The sequence number can be used to find an element fast, e.g., in
% case one is interested only in all objects belonging to a certain
% chapter.
%
% \end{TemplateInterfaceDescription}
%
%
% \begin{TemplateDescription}{contentsobject}{std}
%
% \TemplateKey{pre-v-action}{f0}
% {What to do before typesetting the object (vertically)}
% {\texttt{\textbackslash endgraf}}
%
% \TemplateKey{object-decls}{f0}
% {General declarations applicable to all or most parts of the
% object formatting (e.g., font settings)}
% {do nothing}
%
% \TemplateKey{object-indent}{l}
% {Indentation of whole object from left margin.}
% {0pt}
%
% \TemplateKey{number-width}{l}
% {Width of the space reserved for the document object
% number. Space is reserved regardless of whether or not the
% number is present.}
% {}
%
% \TemplateKey{right-margin-sep}{l}
% {Distance from right margin for all lines except the last}
% {25pt}
%
% \TemplateKey{pnum-width}{l}
% {Width of the space reserved for the page number (thus defines
% the maxium width of the last line of the object)}
% {15pt}
%
% \TemplateKey{number-format}{f1}
% {How to format the document object number if present
% (\texttt{object-decls} still
% apply unless overwritten)}
% {set flush left}
%
% \TemplateKey{title-format}{f1}
% {How to format the main text (\texttt{object-decls} still
% apply unless overwritten)}
% {identity}
%
% \TemplateKey{pnum-format}{f1}
% {How to format the page number (\texttt{object-decls} still
% apply unless overwritten)}
% {set flush right}
%
% \TemplateKey{leaders-action}{f0}
% {What to use as leaders}
% {typeset `.'}
%
% \TemplateKey{leaders-sep}{l}
% {Separation between two `leaders' as defined by \texttt{leaders-action}}
% {4pt}
%
% \TemplateSemantics
% This template is closely modelled after the
% |\@dottedcontentsline| of \LaTeXe{}. It should most likely be
% redesigned. Stuff like \texttt{leaders-action} should get
% generalised to something like a \texttt{hmaterial} template
% instance etc.
% \end{TemplateDescription}
%
% \begin{TemplateDescription}{contentsobject}{pnumfirst}
%
% \TemplateKey{pre-v-action}{f0}
% {What to do before typesetting the object (vertically)}
% {\texttt{\textbackslash endgraf}}
%
% \TemplateKey{object-width}{l}
% {Width to format the object into.}
% {\texttt{\textbackslash linewidth}}
%
% \TemplateKey{object-indent}{l}
% {Indentation of whole object from left margin.}
% {0pt}
%
% \TemplateKey{object-decls}{f0}
% {General declarations applicable to all or most parts of the
% object formatting (e.g., font settings)}
% {do nothing}
%
% \TemplateKey{pnum-width}{l}
% {Width of the space reserved for the page number. The page
% number is formatted at the left leaving \texttt{object-width}
% minus this value for other parts of the object}
% {30pt}
%
% \TemplateKey{title-format}{f1}
% {How to format the main text (\texttt{object-decls} still
% apply unless overwritten)}
% {Identity}
%
% \TemplateKey{pnum-format}{f1}
% {How to format the page number (\texttt{object-decls} still
% apply unless overwritten)}
% {set flush right}
%
% \TemplateKey{pnum-title-sep}{l}
% {Separation between box containing the page number and the
% title text.}
% {5pt}
%
% \TemplateSemantics
% This template sets the page number to the left of the (heading)
% text. Therefore it is not appropriate if the contents object is
% itself numbered and for this reason will warn if it detects an
% document object number.
% \end{TemplateDescription}
%
%
%
% \begin{TemplateInterfaceDescription}{processcontents}
%
% \TemplateArgument{none}{---}
% \TemplateSemantics
% Formats externally collected contents objects according to
% additionally declared templates.
%
% \end{TemplateInterfaceDescription}
%
%
% \begin{TemplateDescription}{processcontents}{std}
%
% \TemplateKey{start-action}{f0}
% {Action to carry out before processing any contents objects}
% {Do nothing}
%
% \TemplateKey{stop-action}{f0}
% {Action to carry out after processing all contents objects}
% {Do nothing}
%
% \TemplateKey{file-name}{n}
% {Base name of the file in which contents object are stored
% (default is \texttt{\textbackslash jobname}}
% {\texttt{\textbackslash jobname}}
%
% \TemplateKey{file-extension}{n}
% {Extension of the file in which the contents objects are stored}
% {}
%
% \TemplateKey{contents-depth}{c}
% {Level down to which contents objects are still formatted}
% {2}
%
%
% \TemplateKey{collection-id}{n}
% {String that is prepended to contents object instances names}
% {Empty}
%
% \TemplateSemantics
% Again this is basically providing the functionality of \LaTeXe's
% |\@starttoc| with the obvious generalisations. As with the rest
% this needs proper redesign.
%
% \end{TemplateDescription}
%
%
%
% \StopEventually{}
%
% \section{Implementation}
%
% \begin{macrocode}
\endinput
% \end{macrocode}
%
% \begin{macrocode}
%</package>
% \end{macrocode}
%
%
% \Finale
%
|
