This file is built for L^{A}TEX 2ε, so we make sure an error is generated when it is used with another format

 1 ⟨+package⟩\NeedsTeXFormat{LaTeX2e}

Now announce the package name and its version: 2 ⟨∗dtx⟩

 3 \ProvidesFile{changebar.dtx}

4 ⟨/dtx⟩

 5 ⟨+package⟩\ProvidesPackage{changebar}
 6  [1995/06/27 v3.2b Indicate changes with marginal bars]

1 A driver for this document

The next bit of code contains the documentation driver file for TEX, i.e., the file that will produce the documentation you are currently reading. It will be extracted from this file by the docstrip program.

7 ⟨∗driver⟩

 8 \documentclass{ltxdoc}

We do want an index, using linenumbers

 9 \EnableCrossrefs
10 \CodelineIndex

This document uses some extra doc style macros.

11 \makeatletter
12 \def\DescribeVar#1{\leavevmode\@bsphack
13  \marginpar{\raggedleft\PrintDescribeEnv{#1}}%
14  \SpecialVarUsageIndex{#1}\@esphack\ignorespaces}
15 \def\SpecialVarMainIndex#1{\@bsphack
16  \index{#1\actualchar{\tt #1}\encapchar main}%
17  \@esphack}
18 \def\SpecialVarUsageIndex#1{\@bsphack
19  \index{#1\actualchar{\tt #1}\encapchar usage}%
20  \@esphack}
21 \let\@SpecialMainIndex\SpecialMainIndex
22 \def\Var{\let\SpecialMainIndex\SpecialVarMainIndex\macro}
23 \def\endVar{\endmacro\let\SpecialMainIndex\@SpecialMainIndex}
24 \makeatother

Some commonly used abbreviations

25 \newcommand\Lopt[1]{\textsf {#1}}
26 \newcommand\Lenv[1]{\textsf {#1}}
27 \newcommand\file[1]{\texttt {#1}}
28 \newcommand\Lcount[1]{\textsl {\small#1}}
29 \newcommand\pstyle[1]{\textsl {#1}}

We also want the full details.

30 \begin{document}
31 \DocInput{changebar.dtx}
32 \end{document}

33 ⟨/driver⟩

The Changebar document style option ^{∗}

Johannes Braams Kooienswater 62 2215 AK Zoetermeer The Netherlands

                   JLBraams@cistron.nl

Printed November 29, 1995

Contents

1 A driver for this document 1

2 Introduction 2

3 The user interface 2 3.1 The package options … 3 3.2 Macros defined by the

package . . . . . . . . . . 3 3.3 Changebar parameters . . 3

4 Deficiencies and bugs 4

5 The basic algorithm 4

Abstract This document style-option implements a way to indicate modifications in a L^{A}TEX-document by putting bars in the margin. It realizes this by making use of the \special commands supported by ‘dvi drivers’. Currently four different drivers are supported. More can easily be added.

2 Introduction

IMPORTANT NOTE: Just as with cross references and labels, you usually need to process the document twice (and sometimes three times) to ensure that the changebars come out correctly. However, a warning will be given if another pass is required.

FEATURES:

• Changebars may be nested within each other. Each level of nesting can be given a different thickness bar.

• Changebars may be nested in other environments including floats and footnotes.

• Changebars are applied to all the material within the “barred” environment, including floating bodies regardless of where the floats float to. An exeception to this are margin floats.

• Changebars may cross page boundaries.

∗This file has version number v3.2b, last revised 1995/06/27.

3 The user interface

This package has options to specify some details of its operation, and also defines several macros.

3.1 The package options

One set of package options specify the driver that will be used to print the document can be indicated. The driver may be one of:

• DVItoLN03

• DVItoPS

• DVIps

• emTEX

The drivers are represented in the normal typewriter method of typing these names, or by the same entirely in lower case.

The position of the bars may either be on the inner edge of the page (the left column on a recto or single-sided page, the right column of a verso page) by use of the innerbars package option (the default), or on the outer edge of the page by use of the the outerbars package option.

The package also implements tracing for its own debugging. The package options traceon and traceoff control tracing.

3.2 Macros defined by the package

\cbstart All material between the macros \cbstart and \cbend is barred. The nesting of

\cbend multiple changebars is allowed. The macro \cbstart has an optional parameter that specifies the width of the bar. The syntax is \cbstart[⟨dimension⟩]. If no width is specified, the current value of the parameter \changebarwidth is used. Note that \cbstart and \cbend can be used anywhere but must be correctly nested with floats and footnotes. That is, one cannot have one end of the bar inside a floating insertion and the other outside, but that would be a meaningless thing to do anyhow.

changebar Apart from the macros \cbstart and \cbend a proper L^{A}TEX environment is defined. The advantage of using the environment whenever possible is that L^{A}TEX will do all the work of checking the correct nesting of different environments.

\cbdelete The macro \cbdelete puts a square bar in the margin to indicate that some text was removed from the document. The macro has an optional argument to specify the width of the bar. When no argument is specified the current value of the parameter \deletebarwidth will be used.

\nochangebars The macro \nochangebars disables the changebar commands.

3.3 Changebar parameters

\changebarwidth The width of the changebars is controlled with the L^{A}TEX length parameter \changebarwidth. Its value can be changed with the \setlength command. Changing the value of \changebarwidth affects all subsequent changebars subject to the scoping rules of \setlength.

\deletebarwidth The width of the deletebars is controlled with the L^{A}TEX length parameter \deletebarwidth. Its value can be changed with the \setlength command. Changing the value of \changebarwidth affects all subsequent deletebars subject to the scoping rules of \setlength.

\changebarsep The separation between the text and the changebars is determined by the value

of the L^{A}TEX length parameter \changebarsep.

changebargrey When one of the supported dvi to PostScript translators is used the ‘blackness’ of the bars can be controlled. The L^{A}TEX counter changebargrey is used for this purpose. Its value can be changed with a command like:

    \setcounter{changebargrey}{85}

The value of the counter is a percentage, where the value 0 yields black bars, the value 100 yields white bars.

outerbars The changebars will be printed in the ‘inside’ margin of your document. This means they appear on the left side of the page. When twoside is in effect the bars will be printed on the right side of even pages. This behaviour can be changed by including the command \outerbarstrue in your document.

4 Deficiencies and bugs

• The macros blindly use specials points \cb@minpoint through \cb@maxpoint. If this conflicts with another set of macros, the results will be unpredictable. (What is really needed is a \newspecialpoint, analogous to \newcount etc. — it’s not provided because the use of the points is rather rare.)

   • There is a limit of (bslash cb@maxpoint−bslash cb@minpoint+1)/2 bars

per page (two special points per bar). Using more than this number yeilds unpredictable results (but that could be called a feature for a page with so many bars). This limitation could be increased if desired.

• Internal macro names are all of the form \cb@xxxx. No checking for conflicts with other macros is done.

• This implementation does not work with two (or more) column printing.

• The algorithms may fail if a floating insertion is split over multiple pages. In L^{A}TEX floats are not split but footnotes may be. The simplest fix to this is to prevent footnotes from being split but this may make TEX very unhappy.

• The \cbend normally gets “attached” to the token after it rather than the one before it. This may lead to a longer bar than intended. For example, consider the sequence ‘word1 \cbend word2’. If there is a line break between ‘word1’ and ‘word2’ the bar will incorrectly be extended an extra line. This particular case can be fixed with the incantation ‘word1\cbend{} word2’.

5 The basic algorithm

The changebars are implemented using the \specials of various dvi interpreting programs like DVItoLN03 or DVIps. In essence, the start of changebar defines a \special point in the margin at the current vertical position on the page. The end of a changebar defines another point and then joins the two using the “connect”

\special.

This works fine as long as the two points being connected lie on the same page. However, if they don’t, the bar must be artificially terminated at the page break and restarted at the top of the next page. The only way to do this (that I can think of) is to modify the output routine so that it checks if any bar is in progress when it ships out a page and, if so, adds the necessary artificial end and begin.

The obvious way to indicate to the output routine that a bar is in progress is to set a flag when the bar is begun and to unset this flag when the bar is ended. This works most of the time but, because of the asynchronous behavior of the output routine, errors occur if the bar begins or ends near a page break. To illustrate, consider the following scenario.

    blah blah blah          % page n
    blah blah blah
    \cbstart                % this does its thing and set the flag
    more blah
               <-------------- pagebreak occurs here
    more blah
    \cbend                  % does its thing and unsets flag
    blah blah

Since TEX processes ahead of the page break before invoking the output routine, it is possible that the \cbend is processed, and the flag unset, before the output routine is called. If this happens, special action is required to generate an artificial end and begin to be added to page n and n + 1 respectively, as it is not possible to use a flag to signal the output routine that a bar crosses a page break.

The method used by these macros is to create a list of the beginning and end points of each bar in the document together with the page number corresponding to each point. Then, as a page is completed, a modified output routine checks the list to determine if any bars begun on or before the current page are terminated on subsequent pages, and handles those bars appropriately. To build the list, information about each changebar is written to the .aux file as bars are processed. This information is re-read when the document is next processed. Thus, to ensure that changebars are correct, the document must be processed twice. Luckily, this is generally required for L^{A}TEX anyway.

This approach is sufficiently general to allow nested bars, bars in floating insertions, and bars around floating insertions. Bars inside floats and footnotes are handled in the same way as bars in regular text. Bars that encompass floats or footnotes are handled by creating an additional bar that floats with the floating material. Modifications to the appropriate L^{A}TEX macros check for this condition and add the extra bar.