LATEX-L Archives

Mailing list for the LaTeX3 project

LATEX-L@LISTSERV.UNI-HEIDELBERG.DE

Options: Use Classic View

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

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

Print Reply
Frank Mittelbach <[log in to unmask]>
Sat, 6 Nov 1999 22:38:51 +0100
text/plain (443 lines)
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
%

ATOM RSS1 RSS2