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 %