% \iffalse -*- LaTeX -*- % % This is file `cjwoutl.dtx'. You can run this file through LaTeX2e % to produce the .dvi documentation. You should also have received % the file `cjwoutl.ins'. Run it through LaTeX2e to extract the % actual package file. % % \fi \def\fileversion{0.6} \def\filedate{1996/04/26} %% \CharacterTable %% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z %% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z %% Digits \0\1\2\3\4\5\6\7\8\9 %% Exclamation \! Double quote \" Hash (number) \# %% Dollar \$ Percent \% Ampersand \& %% Acute accent \' Left paren \( Right paren \) %% Asterisk \* Plus \+ Comma \, %% Minus \- Point \. Solidus \/ %% Colon \: Semicolon \; Less than \< %% Equals \= Greater than \> Question mark \? %% Commercial at \@ Left bracket \[ Backslash \\ %% Right bracket \] Circumflex \^ Underscore \_ %% Grave accent \` Left brace \{ Vertical bar \| %% Right brace \} Tilde \~} %% % \CheckSum{327} % % \iffalse % %<*driver> \NeedsTeXFormat{LaTeX2e} \ProvidesFile{cjwoutl.dtx} [\filedate\space v\fileversion\space Auto-Numbered Outlines--CJW] \documentclass{ltxdoc} \IfFileExists{cjwoutl.sty} {\usepackage{cjwoutl}} {\GenericError{(cjwoutl.dtx)\@spaces\@spaces\@spaces}{Error: You must first LaTeX the file `cjwoutl.ins' \MessageBreak and extract the `cjwoutl.sty' package before \MessageBreak processing the documentation}{}{}} \GetFileInfo{cjwoutl.sty} \EnableCrossrefs % \DisableCrossrefs % Say \DisableCrossrefs if index is ready % \OnlyDescription % comment out for implementation details \RecordChanges \begin{document} \DocInput{cjwoutl.dtx} \end{document} % % \fi % % \def\pkg#1{\textsf{#1}} % \def\env#1{\textsf{#1}} % \providecommand{\ie}{\emph{i.e.},\ } % % ^^A % Change List: % % \changes{v0.5}{1995/05/13}{Added \texttt{\protect\bslash outlindent} as % indentation size.} % % \title{The \pkg{cjwoutl} Package\thanks{% % This file has version \fileversion{} as of \filedate.}} % \author{Colin J.~Wynne\thanks{E-Mail at: % \texttt{cwynne@brutus.mts.jhu.edu}, % \texttt{cwynne@jhu.edu}\,.}} % \date{\filedate} % % \maketitle % % \setcounter{StandardModuleDepth}{1} % % {\parskip 0pt ^^A % This is the hack used by |doc.dtx|. % ^^A % (bug in \LaTeX?) % \tableofcontents % } % % \section*{Introduction} % % This package originated as a simple set of macros for doing outlines % under \PlainTeX. The original macros simply provided % $n$|\parindent| as a left indentation for a single paragraph. % This was almost three years ago. The macros improved somewhat with % my knowledge of (and experience with) \TeX. Last summer I finally % had the time to add what I had always wanted---automatic level % numbering. % % This year I decided to find out just what \LaTeX{} was all about. % After deciding that it wasn't that bad, I rewrote (and improved yet % again) the outlining macros. Conveniently enough, a large chunk of % the original \PlainTeX{} code dedicated to resetting the proper % counters disappeared with the change to \LaTeX. % % At a basic level, the \env{outline} environment functions like % \env{enumeration}. However, one needn't nest the calls of the % \env{outline} environment. Rather, the macros used to identify the % entries of the outline itself take care of this. % % I think this code is now both fairly generic and rather useful, and % I would be more than happy to know that it is useful to others. % Feel free to e-mail me with comments, suggestions, etc. The % \PlainTeX{} version is still available by request for anyone who % might want it. % % % \section{Making an Outline} % % \DescribeEnv{outline} % An outlined portion of a document is implemented, naturally enough, % inside an environment, the \env{outline} environment. There is one % optional argument to the |\begin| command. If the argument |new| is % given, then the outline counters will be reset. Otherwise, the % values of the counters will be exactly as they were at the end of % the last \env{outline} environment. % % \DescribeMacro{\outl} % Inside of an \env{outline} environment, there are two main user % macros, one for auto-labelled entries and one for user-supplied % labels. For labels to be automatically numbered and printed, the % user simply enters |\outl|\meta{level}. The \meta{level} is simply % an integer which corresponds to the depth within the outline. For % example, level one of an outline begins at the left margin (more % precisely, the \emph{text} begins at the left margin with the label % offset by 1\,en to the left of that) and in a standard outline, and, % indeed, according to this package's defaults, a capitalised roman % numeral is used as a label. Therefore % \begin{verbatim} % \begin{outline} % \outl{1}This is outline level one. % \end{outline} % \end{verbatim} % will produce % \begin{outline} % \outl{1}This is outline level one. % \end{outline} % The package supplies seven defined levels of outline as well as a % default `level'. The default is used for any levels over seven. % These levels will still receive the correct indentation % \DescribeMacro{\outlindent} % (specifically, level $n$ is prefaced by |\leftskip = |^^A % $(n-1)$|\outlindent| worth of space), but will all receive the % default label, normally a bullet. Thus, the user is provided with % the following: % \begin{outline}[new] % \outl{1}\dots % \outl{2}\dots % \outl{3}\dots % \outl{4}\dots % \outl{5}\dots % \outl{6}\dots % \outl{7}\dots % \outl{8}\dots % \outl{9}\dots % \outl{10}\dots % \end{outline} % Note that levels eight through ten have the default bullet for a % label, though the indentation levels are preserved. There are a few % special symbols which can be given as the \meta{level} argument. If % the user enters a |+|, |-| or |=| then the indentation level of that % entry will be respectively one greater, one less or the same as that % of the previous entry. Thus, % \begin{verbatim} % \begin{outline} % \outl{1} Level one, % \outl{+} Level two, % \outl{=} Level two, % \outl{-} Level one. % \end{outline} % \end{verbatim} % gives % \begin{outline}[new] % \outl{1} Level one, % \outl{+} Level two, % \outl{=} Level two, % \outl{-} Level one. % \end{outline} % % \DescribeMacro{\ol} % The macro |\ol| is almost identical to the |\outl| macro, except % that it takes a second argument: |\ol|\meta{level}\meta{label}. The % \meta{level} argument functions identically, and the \meta{label} % argument is set as entered 1\,en to the left of the text. % \DescribeMacro{\npp}\DescribeMacro{\unpp} Two macros are derived from % |\ol|. Both take a \meta{level} argument. The |\npp| macro is % essentially |\ol|\meta{level}|{\null}\indent|. The |\unpp| macro % does not indent the first line of text. (The macros stand for ``new % paragraph'' and ``unindented |\npp|''.) % % \DescribeMacro{\outlstyle} % There is also a macro to allow for some modifications in how an % outline entry is typeset. The default style, |plain|, does nothing. % \DescribeMacro{firstpar} % \DescribeMacro{\firstparfont} % An alternate style, called |firstpar|, sets the first paragraph of % an outline entry in |\firstparfont|. By default, this is italics, % but the font command can, of course, be renewed by the user. To % change styles, one simply calls |\outlstyle|\meta{style}; for % example, % \begin{verbatim} % \outlstyle{firstpar} % \end{verbatim} % calls the |firstpar| outline style. % % N.B.: There is one `secret' left to tell. Unless one wants to reset % the counters by calling |\begin{outline}[new]|, it is really % unnecessary to call the environment. Instead, one can simply use % the |\ol| or |\outl| commands as desired. The only caveat is that % the final outline grouping must be closed. Therefore, the % |\endoutline| macro \emph{must} be called. Granted, this doesn't % make a whole big difference. I happen to use this `feature' simply % because I have used these macros since long before it was written in % a \LaTeX-environment format. YMMV. % % \subsection{Outline Labels} % % \DescribeMacro{outlN} % The counters for the different levels are named |outl|$n$, where $n$ % is a lowercase roman numeral. Therefore, this package defines % |outli|, |outlii|,\ldots,|outlvii|. This is, as one easily sees, % similar to the numbering scheme for the \env{enumeration} % environment. % \DescribeMacro{\theoutlN} % \DescribeMacro{\labeloutlN} % The numbering style for level $n$ is given by the macro |\theoutlN|. % The actual label which is printed for an entry at level $n$ is given % (naturally enough) by |\labeloutlN|. The default label is % |\labeloutldef|. The example above showed the label at the sixth % level as `(a)'. The relevant definitions are: % \begin{verbatim} % \renewcommand{\theoutlvi}{\alph{outlvi}} % \renewcommand{\labeloutlvi}{(\theoutlvi)} % \end{verbatim} % \DescribeMacro{\labelfont} % The labels themselves are typeset in |\labelfont|, which can also be % set by the user. The default is bold-extended. % % \changes{v0.6}{1996/04/26}{Added info about cross-referencing.} % \subsection{Cross References} % % Cross references function as expected for outlines, using the % |\label| and |\ref| commands. The |\outl| function defines the % current reference string, so the |\label| should be put after the % |\outl| to which it refers. For example, we might have the code % \begin{verbatim} % \begin{outline}[new] % \outl{1} Main entry. % \outl{+} Next level. % \outl{+} The price of tea in China.\label{ol:tea} % \end{outline} % \end{verbatim} % producing % \begin{outline}[new] % \outl{1} Main entry. % \outl{+} Next level. % \outl{+} The price of tea in China.\label{ol:tea} % \end{outline} % whereupon the reference |ol:tea| would refer to tea in % China~\ref{ol:tea}. % % \StopEventually{\PrintChanges\PrintIndex} % % % \section{The Code} % % \iffalse %<*package> \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{cjwoutl} [1995/04/24 v0.5 Auto-Numbered Outlines--CJW] \DeclareOption*{% \PackageWarning{cjwoutl}{Unknown option `\CurrentOption'}} \ProcessOptions % \fi % % \subsection{Allocations} % % Since the levels of an outline are defined by a |\leftskip| command, % it is necessary to determine when a group needs to be closed. % Therefore, we define a test to see if we are in a group. % \begin{macrocode} \newif\ifoutl@group % \end{macrocode} % This essentially keeps the first outline entry from closing a % non-existent group. Two lengths, |\aboveoutlskip| and % |\belowoutlskip|, initially set to the equivalent values for math % displays, are used to separate an \env{outline} environment from the % surrounding text. % \changes{v0.6}{1996/04/26}{Added \texttt{\protect\bslash aboveoutlskip} % and \texttt{\protect\bslash belowoutlskip} lengths based on values for % displays.} % \begin{macrocode} \newlength{\aboveoutlskip} \setlength{\aboveoutlskip}{\abovedisplayskip} \newlength{\belowoutlskip} \setlength{\belowoutlskip}{\belowdisplayskip} % \end{macrocode} % The |\outlindent| macro controls the increment between adjacent % outline levels. Its default value is |\parindent|. % \begin{macrocode} \newlength{\outlindent} \setlength{\outlindent}{\parindent} % \end{macrocode} % % Now we define the counters to be used. The first two identify the % requested indentation level and the previous level. % \begin{macrocode} \newcounter {outl@indsize} \newcounter {outl@lastind} % \end{macrocode} % \begin{macro}{outlN} % Next come the counters for the levels themselves. % \begin{macrocode} \newcounter {outli} % I. \newcounter {outlii} [outli] % A. \newcounter {outliii}[outlii] % 1. \newcounter {outliv} [outliii] % a. \newcounter {outlv} [outliv] % i. \newcounter {outlvi} [outlv] % (a) \newcounter {outlvii}[outlvi] % (i) % \end{macrocode} % There is also a counter definition for the default label. This will % be explained below. % \begin{macrocode} \newcounter {outldef}[outlvii] % \end{macrocode} % \end{macro} % \begin{macro}{\theoutlN} % Now we can set the proper level numbering. % \begin{macrocode} \renewcommand{\theoutli} {\Roman{outli}} \renewcommand{\theoutlii} {\Alph{outlii}} \renewcommand{\theoutliii} {\arabic{outliii}} \renewcommand{\theoutliv} {\alph{outliv}} \renewcommand{\theoutlv} {\roman{outlv}} \renewcommand{\theoutlvi} {\alph{outlvi}} \renewcommand{\theoutlvii} {\roman{outlvii}} % \end{macrocode} % Again we have the default label, which I \emph{promise} will be % explained. % \begin{macrocode} \renewcommand{\theoutldef} {} % \end{macrocode} % \end{macro} % \begin{macro}{\labeloutlN} % Now the label formats will be defined. % \begin{macrocode} \newcommand{\labeloutli} {\theoutli.} \newcommand{\labeloutlii} {\theoutlii.} \newcommand{\labeloutliii} {\theoutliii.} \newcommand{\labeloutliv} {\theoutliv.} \newcommand{\labeloutlv} {\theoutlv.} \newcommand{\labeloutlvi} {(\theoutlvi)} \newcommand{\labeloutlvii} {(\theoutlvii)} \newcommand{\labeloutldef} {\ensuremath{\bullet}} % \end{macrocode} % \end{macro} % This next group of definitions are taken from the standard classes' % definitions for the \env{enumeration} environment. I have not % plumbed the cross-referencing code deeply enough to see how these % macros are applied, but I take it on faith from |classes.dtx| that % it works. % \changes{v0.6}{1996/04/26}{Tweaked \texttt{\protect\bslash p@}\ldots{} % definitions based on information in \emph{The \LaTeX{} Companion}.} % \begin{macrocode} \renewcommand{\p@outli} {} \renewcommand{\p@outlii} {\theoutli.} \renewcommand{\p@outliii} {\p@outlii\theoutlii.} \renewcommand{\p@outliv} {\p@outliii\theoutliii.} \renewcommand{\p@outlv} {\p@outliv\theoutliv.} \renewcommand{\p@outlvi} {\p@outlv\labeloutlv.} \renewcommand{\p@outlvii} {\p@outlvi\labeloutlvi.} % \end{macrocode} % And now we have the promised explanation of having a counter for the % default labels. Simply put, the |\p@|\ldots{} commands are defined % \emph{via} |\setcounter|. To be able to supply cross-references for % outline entries above the seven numbered levels it seems necessary % to have the relevant counter definition already made. I could be % wrong on this, and maybe I could have defined the cross-reference % label directly. If so, let me know. Anyway, that was the % explanation---probably not worth the wait, was it? % \begin{macrocode} \renewcommand{\p@outldef} {\p@outlvii\ldots} % \end{macrocode} % % \subsection{The Environment} % % \begin{environment}{outline} % The \env{outline} environment itself has a very simple definition. % It has a single optional argument. The default value of the % argument is fairly arbitrary, so long as it isn't |new|. % \changes{v0.6}{1996/04/26}{Added the new skip values to the beginning % and end macros for the environment.} % \begin{macrocode} \newenvironment{outline}[1][keep]% % \end{macrocode} % To start the environment, we must simply test to see if the counters % should be reset or not. % \begin{macrocode} {\def\@tempa{#1} \def\@tempb{new} \ifx\@tempa\@tempb \outl@reset \fi \penalty\predisplaypenalty\vspace{\aboveoutlskip}}% % \end{macrocode} % To finish an outlined section of a document, we include a |\par| (to % make sure the |\leftskip| functions correctly), close the last % outline group and let it be known that we are no longer in an % outline. % \begin{macrocode} {\par\endgroup\global\outl@groupfalse% \penalty\postdisplaypenalty\vspace{\belowoutlskip}} % \end{macrocode} % The macro to reset the outline counters is about as straightforward % as possible. % \begin{macrocode} \newcommand{\outl@reset}{% \setcounter{outli} {0} \setcounter{outlii} {0} \setcounter{outliii}{0} \setcounter{outliv} {0} \setcounter{outlv} {0} \setcounter{outlvi} {0} \setcounter{outlvii}{0}} % \end{macrocode} % \end{environment} % % \subsection{Outline Styles} % % \begin{macro}{\outlstyle} % Outline styles are implemented as a macro call to the desired style % just before the text of the outline entry is typeset. \ie in % abstract terms, the |\ol| or |\outl| macros will have % \begin{tabular}{l} % \meta{label}\meta{style-macro}\textit{Text text text\ldots} % \end{tabular} % The styles are macros named |\ols@|\meta{style}. Thus, the % |\outlstyle| macro shecks to see if the style is defined. If not, % it emits a warning and selects the plain style. % \begin{macrocode} \newcommand{\outlstyle}[1]{% \@ifundefined{ols@#1} {\PackageWarning{cjwoutl}{Outline style `#1' is undefined. Using style `plain' instead}% \def\outl@style{\ols@plain}} % \end{macrocode} % \end{macro} % If the requested style exists, we point the macro |\outl@style| % towards it. (Note: if anyone can think of a better way to write % this, let me know. I wanted to do it as a |\let|, but couldn't % figure out the correct sequence of |\expandafter|s to get it to % evaluate correctly.) % \begin{macrocode} {\def\outl@style{\csname ols@#1\endcsname}}} % \end{macrocode} % Now we define the two basic styles, |plain| and |firstpar|. % \begin{macrocode} \def\ols@plain{\@empty} % \end{macrocode} % The |firstpar| style simply takes the first paragraph of the entry % as an argument and sets it in |\firstparfont|. % \begin{macrocode} \def\ols@firstpar#1\par{% \bgroup\firstparfont #1\par\egroup} \DeclareOldFontCommand{\firstparfont}{\normalfont\itshape}{\relax} % \end{macrocode} % Lastly, we select |plain| as the default style. % \begin{macrocode} \outlstyle{plain} % \end{macrocode} % % \subsection{The Entries} % % \begin{macro}{\ol} % The |\ol| macro first takes care of the outline groupings and then % processes the \meta{level} argument given by the user. % \begin{macrocode} \newcommand{\ol}[2]{% \outl@checkgroups \outl@processlvl{#1}% % \end{macrocode} % We do some minor error handling---like disallowing negative numbers. % If a numerical argument is given, the |\outl@processlvl| macro % decrements it by one---thus, the actual |outl@indsize| is not the % level number that the user enters, but rather the number of % |\outlindent|s for the requested level, and the first entry occurs at % zero indents, \ie on the left margin. Thus zero, and not one, is % the minimum value which can be assigned to |\outl@indsize|. % \begin{macrocode} \ifnum \c@outl@indsize < 1\relax% \setcounter{outl@indsize}{0}% \leftskip = 0pt% \else% \leftskip = \c@outl@indsize\outlindent% \fi% % \end{macrocode} % We specify that the first paragraph of an entry should not be % indented and we make the label. % \changes{v0.6}{1996/04/26}{Moved the \texttt{\protect\bslash llap} command % into \texttt{\protect\bslash theoutlabel}---otherwise the reference % strings were being defined inside groups and being lost.} % \begin{macrocode} \noindent\theoutlabel{#2}% % \end{macrocode} % The |\ignorespaces| macro allows the user to enter |\outl{1} Text| % instead of the slightly less readable |\outl{1}Text| in the source % file without the extra spaces showing up in the document. Anyway, % then we call |\outl@style| which has been defined to be the selected % style macro. % \begin{macrocode} \ignorespaces\outl@style} % \end{macrocode} % \end{macro} % % The |\npp| and |\unpp| macros are straightforward derivatives of the % |\ol| macro. % \begin{macrocode} \newcommand{\npp}[1]{\ol{#1}{\null}\null\indent} \newcommand{\unpp}[1]{\ol{#1}{\null}} % \end{macrocode} % % \begin{macro}{\outl} % The |\outl| macro is more or less identical to |\ol| above. % \begin{macrocode} \newcommand{\outl}[1]{% \outl@checkgroups \outl@processlvl{#1}% \ifnum \c@outl@indsize < 1\relax% \setcounter{outl@indsize}{0}% \leftskip = 0pt% \else% \leftskip = \c@outl@indsize\outlindent% \fi% % \end{macrocode} % The difference is in calling the |\outl@label| macro which takes % care of the automatic labels. % \begin{macrocode} \noindent\outl@label{\c@outl@indsize}% \ignorespaces\outl@style} % \end{macrocode} % \end{macro} % % \begin{macro}{\outl@checkgroups} % Now we define the macro that balances the outline groupings. If we % are already in a group, provide a |\par| to get the |\leftskip| % right, then close the group and change the group flag. % \begin{macrocode} \newcommand{\outl@checkgroups}{% \ifoutl@group \par\endgroup\global\outl@groupfalse \smallbreak \fi % \end{macrocode} % Since we have just finished an outline group, we can set % |outl@lastind|, then provide appropriate space (encouraging breaks % between enries) and start a new group. % \begin{macrocode} \setcounter{outl@lastind}{\c@outl@indsize} \smallbreak \begingroup \global\outl@grouptrue} % \end{macrocode} % \end{macro} % % \begin{macro}{\outl@processlvl} % The \meta{level} argument can be a number or one of |+|, |-| and % |=|. The check is implemented as a set of nested |\if| statements. % \begin{macrocode} \newcommand{\outl@processlvl}[1]{% \def\@tempa{+}\def\@tempb{-}\def\@tempc{=} \def\@tempd{#1} \ifx\@tempa\@tempd \addtocounter{outl@indsize}{1} \else\ifx\@tempb\@tempd \addtocounter{outl@indsize}{-1} \else\ifx\@tempc\@tempd % Nothing---stay at same level. \else \setcounter{outl@indsize}{\@tempd} % \end{macrocode} % If we are setting to a new level number, we decrement by one, as % mentioned in the definition of |\ol|, in order to convert the level % number to an indentation size. % \begin{macrocode} \addtocounter{outl@indsize}{-1} \fi \fi \fi} % \end{macrocode} % \end{macro} % % \subsection{Labels} % % \begin{macro}{\outl@label} % The |\outl@label| macro, called by |\outl| with the |outl@indsize| % as an argument, simply decides which level to make by way of an % |\ifcase| statement. % \begin{macrocode} \newcommand{\outl@label}[1]{% \ifcase #1 \@dolabeli\or\@dolabelii\or\@dolabeliii% \or\@dolabeliv\or\@dolabelv\or\@dolabelvi% \or\@dolabelvii\else\@dolabeldef% \fi} % \end{macrocode} % \end{macro} % The labels are set in |\labelfont|. I have a set of personal macros % that define a |\labelfont| for other uses, so the declaration is % surrounded by a test. % \begin{macrocode} \@ifundefined{labelfont} {\DeclareOldFontCommand{\labelfont}% {\normalfont\bfseries\mathversion{bold}}{\mathbf}} {} % Do nothing---|\labelfont| is already defined % \end{macrocode} % The generic form of the outline labels is given by |\theoutlabel|. % \begin{macrocode} \newcommand{\theoutlabel}[1]{% \llap{\hbox{\labelfont#1\enskip}}} % \end{macrocode} % Finally we define the macros which are called for the auto-numbering % and label creation for the |\outl| macro. % \changes{v0.6}{1996/04/26}{Changed \texttt{\protect\bslash stepcounter} % call to \texttt{\protect\bslash refstepcounter} in order to get % cross-referencing to work right.} % \begin{macrocode} \newcommand{\@dolabeli}{% \refstepcounter{outli}\theoutlabel{\labeloutli}} \newcommand{\@dolabelii}{% \refstepcounter{outlii}\theoutlabel{\labeloutlii}} \newcommand{\@dolabeliii}{% \refstepcounter{outliii}\theoutlabel{\labeloutliii}} \newcommand{\@dolabeliv}{% \refstepcounter{outliv}\theoutlabel{\labeloutliv}} \newcommand{\@dolabelv}{% \refstepcounter{outlv}\theoutlabel{\labeloutlv}} \newcommand{\@dolabelvi}{% \refstepcounter{outlvi}\theoutlabel{\labeloutlvi}} \newcommand{\@dolabelvii}{% \refstepcounter{outlvii}\theoutlabel{\labeloutlvii}} \newcommand{\@dolabeldef}{% \refstepcounter{outldef}\theoutlabel{\labeloutldef}} % \end{macrocode} % And with that, we are finished. % % \iffalse % % \fi % % \Finale