summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/ednotes/lblchng1.sty
blob: 379a7a56541b99b57adee987dad9a17a506e940e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
%% LblChng1.sty--tell about the first changed LaTeX label. 
\def\fileversion{0.32c} \def\filedate{2005/10/01} 

%% Copyright (C) 2005 Uwe L\"uck 
%% Munich, http://contact-ednotes.sty.de.vu. 
%% Current maintainer is Uwe L\"uck. 

%% This program can be redistributed and/or modified under the terms
%% of the LaTeX Project Public License distributed from CTAN
%% archives in directory macros/latex/base/lppl.txt; either
%% version 1.3a of the License, or any later version.
%% We did our best to help you, but there is NO WARRANTY. 

%% * SUMMARY: * 
%% 
% This package is intended to be a (primitive) tool for 
% fixing oscillating page breaks -- a problem that especially 
% sometimes occurs in typesetting critical editions. Thus it 
% addresses especially users of LaTeX packages lineno, ednotes, 
% and ledmac (maybe even manyfoot and numline). When it has been 
% invoked and some label(s) get an entry in the .aux file 
% differing, with respect to page number, to that of the 
% previous run, the first such label is reported on screen (and 
% in the .log), including the differing page numbers. This 
% should help in finding the first unstable page -- which is 
% vital. The file also contains rather detailed explanations and 
% discussions. 
% 
%% * CRITICAL EDITIONS, PACKAGES: * 
%% 
% For informations about macro packages mentioned in the present 
% text, or about critical edition typesetting in general, I 
% refer you to the web page http://ednotes.sty.de.vu . 
%
%% * THE PROBLEM TO BE SOLVED: * 
%% 
% Sometimes it happens that LaTeX's final warning "Label(s) may 
% have changed. Rerun to get cross-references right." appears at 
% *every* run, i.e., rerunning doesn't help. Or instead, it may 
% be noticed that certain cross-references keep being wrong. 
% The only reason I know of is that the runs oscillate between 
% two decisions about what material should be put onto a certain 
% page. And the only reason I know for this is that the space 
% consumed by some cross-reference depends on the page breaking. 
% I know this problem from critical edition typesetting. 
% 
%% * OUTLINE of the SOLUTION offered here: * 
%% 
% I simply propose that the user makes up her mind on the nasty 
% page breaks and forces some at a certain lines, or contributes 
% her opinion, through \pagebreak (or maybe even \nopagebreak, I 
% have no idea whether this can be useful). -- A float (`figure' 
% or `table') may contribute to the problem as well, so you may 
% move its LaTeX code or change the placement options (through 
% the brackets argument). 
% 
% Typically, one position of such oscillating causes further 
% page breaking oscillations for many ensuing pages, yielding a
% bunch of wrong cross-references and countings. Of course, the 
% user then should settle the first occurrence of oscillating 
% before bothering with others -- all the rest of them may 
% disappear when the first one is fixed. 
% 
% One problem with this solution ("?") is that it may be 
% bothersome to find out where the first oscillation occurs 
% indeed (by looking through the .dvi's or .pdf's). The present 
% package tries to help with this. 
% 
% With Peter R. Wilson's ledmac, you have the "ballast" 
% procedure for influencing page breaks. (It is due to John
% Lavagnino, Dominik Wujastyk, and Wayne Sullivan, inherited 
% from EDMAC). It saves you from looking for good positions for 
% \pagebreak's. I might offer something similar (with 
% lineno.sty/ednotes.sty). However, I would like to object that 
% the "ballast" procedure chooses between two page break 
% possibilities rather "by chance" (reinforcing the first break 
% idea encountered while the other idea might turn out to be 
% better). But I must concede: One of the two breaks between the 
% runs oscillate may turn out not to work, or even both of them 
% -- when the cross-references have been adjusted to that 
% decision. The "ballast" procedure may then save some time for 
% you. On the other hand, if *both* decisions turn out not to 
% work, I wonder whether the "ballast" method will certainly 
% find a working one. 
% 
%% * USAGE: *
%% 
% 1. \usepackage{lblchng1} in every LaTeX document that you 
% create, or in every critical edition LaTeX document that you 
% create, or only when you run into the problem of not settling 
% label definitions. (Hope that you then remember that there is 
% such a package!) 
% 
% 2a. You will be told about the page numbers where some \label 
% (or, with Stephan I. B\"ottcher's lineno.sty or its extension 
% ednotes.sty, some \linelabel) appears. Observe the page breaks 
% in the .dvi's or .pdf's in the corresponding region. Note that 
% the passage which causes the oscillation may be a number of 
% pages earlier than the page number mentioned in the warning. 
% (Sorry, this is the price of cheapness.) You can get rid of 
% the warning without fixing the real problem -- fixing a late 
% page break preceding the \label -- but this may cause badly 
% filled pages earlier. So it will be wise to identify the very 
% first passage causing oscillating page breaks. -- Another 
% conjecturing hint: According to the diagnosis that I delivered 
% above, the first oscillation happens near a cross-reference 
% whose length varies due to the oscillation. So look for some 
% \ref (or \lineref) referring forward(!). If you are lucky, the 
% \ref refers to the label whose change has been warned about. 
% 
% 2b. If you are working with *ednotes.sty*: ednotes.sty v1.1 
% does something similar with internal informations about each 
% note, and it delivers a similar message on screen and in .log. 
% It reports on three page numbers. However, the first 
% oscillation happens (I think) at most one page before the 
% reported ones. 
% 
% 3a. As indicated above, try to force a certain page break at 
% this passage through \pagebreak (or \nopagebreak?) -- or 
% change the position of a `figure' or `table' in code or in 
% output (brackets argument), if it seems to contribute to the 
% problem. Concerning \pagebreak (\nopagebreak), I personally 
% also think of using the optional argument in the brackets, 
% while I feel unable to judge the value of this. -- I also 
% recommend that you use \typeout near the \pagebreak or so to 
% remind yourself of the \pagebreak -- in case the \pagebreak 
% after some changes suddenly produces a very bad page break 
% and you don't examine the output with sufficient carefulness, 
% being in a hurry, e.g. 
% 
% 3b. With *ledmac*, you may experiment with the "ballast" 
% amount until that first oscillation stops. 
% 
%% * A minor WARNING: * (LaTeX version)
%% 
% A remark as of 1995/07/13 in ltmiscen.dtx makes me wonder 
% whether the present package works with older versions of 
% LaTeX.
% 
%% * CRITICAL EDITIONS: * (lineno.sty, ednotes.sty, ledmac) 
%% 
% 1. With Stephan I. B\"ottcher's lineno.sty and its extension 
% ednotes.sty, oscillating page breaking also results in wrong 
% pagewise numbering of lines and in wrongly placed-and-numbered 
% footnotes. I am thinking of refining lineno.sty in addition to 
% the present package. On the other hand, I conjecture that 
% wrong pagewise numbering is *always* (at least sufficiently 
% often) closely accompanied by oscillating cross-references, so 
% the present package may offer sufficient help. -- Well, sorry, 
% this may remain being true with respect to lineno.sty, but 
% since March 2005, ednotes.sty treats its internal line number 
% references in a way that makes them "invisible" to 
% lblchng1.sty. This is very necessary for huge editions with, 
% say, 10.000 notes or more, for a memory capacity reason. 
% ednotes.sty uses an own procedure to detect page number 
% changes, to which lblchng1.sty adds perhaps only little. 
% 
% 2. I guess that even ledmac users may find the present package 
% useful, to find out where they have to watch when trying to 
% adjust the "ballast" appropriately. However, its usefulness 
% depends on how dense LaTeX \label's appear in the edited text. 
% Indeed, it is the pages with the numerous critical footnotes 
% fall where oscillations are likely to occur. \label's may be 
% here when the comments refer to certain sections etc. of the 
% edited text, OK, but will they? The line number references 
% preceding the single notes (just on these "critical" -- in 
% two senses -- pages) might be much more helpful, yet they are, 
% with ledmac.sty, not implemented by \label. And it is wise not 
% to implement them by \label, similarly as with ednotes.sty 
% above. (ednotes.sty still uses \label, to be sure, but it 
% redefines \newlabel in a way that is specific to ednotes.sty's 
% way of storing data about the notes.)
% 
%% * WONDERING REMARK: *
%% 
% Oscillating label definitions do not necessarily result in 
% anything wrong. The page number in the label definition may 
% oscillate while not being used by any \pageref. -- I have no 
% idea at present what this tells us to do if it happens so ... 
% 
%% * ACKNOWLEDGEMENTs: *
%% 
%  This package is due to Roy Flechner's confidence in our 
%  ednotes.sty and to frightening observations he reported to 
%  us. Thanks also to Peter Wilson for moral support. 

%% Please send comments via http://contact-ednotes.sty.de.vu. 

%% * IMPLEMENTATION: * %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\NeedsTeXFormat{LaTeX2e}[1994/10/30] 
%% <- \@onelevel@sanitize; also \CheckCommand \reserved@a. 
\ProvidesPackage{lblchng1}[\filedate\space\fileversion\space 
                           ^^Jexhibiting first changed label]

%% * Main idea: * 
% Testing on label changes is done by \@testdef -- at least I 
% assume this here (and I will somewhat check it). I refine it 
% so it shows the label name and the page numbers -- clearly, 
% what could I do else? (Well, I could redefine \label so ...) 
% 
%% If LaTeX's \@testdef changes, the present package may better 
%% be updated: 
\CheckCommand*\@testdef[3]{%
  \def\reserved@a{#3}\expandafter \ifx \csname #1@#2\endcsname
  \reserved@a  \else \@tempswatrue \fi}
\def\@testdef#1#2#3{%% This is what I expect LaTeX to use. 
  \@ifundefined{#1@#2}\@tempswatrue{%% Like LaTeX: 
    \def\@tempa{#3}% 
    \expandafter 
    \ifx \csname #1@#2\endcsname \@tempa 
    \else \@tempswatrue 
%% v0.3: moved disabling \@newl@bel from here to below. 
    \fi %% But now: 
%% To be sure, I additionally assume that the page number is the 
%% second thing, and more. I have had bad experience with 
%% hyperref and thus do not assume that there are just two 
%% things in the last argument of \newlabel. 
    \def\@tempb##1##2##3\@nil##4{% 
      \def##4{##2}\@onelevel@sanitize##4}% 
%% Well, why not use some initially defined \@LC@extractpno 
%% instead of this \@tempb? %% TODO
%% -- With modern large and fast TeX versions, one should not 
%% waste a second with such considerations. -- However: 
%% different effects concerning compatibility. 
    \expandafter \@tempb \@tempa \@nil\@tempa 
    \expandafter\expandafter\expandafter 
      \@tempb \csname#1@#2\endcsname \@nil\@tempb 
    \ifx\@tempa\@tempb \else 
      \typeout{^^JPackage `lblchng1':^^J% 
        *** Page number of label `#2' is changing: ***^^J% 
        \space\space\space\space
        was \@tempb, will be \@tempa.^^JWatch whether 
        this stops and references get right.}% 
%% Further testing wouldn't change anything: 
      \def\@newl@bel{\@gobblefour\relax}\fi}}
%% Warning: this could create an incompatibility with some other 
%%          package or with some LaTeX version. 
%% Again: this extra line doesn't pay well nowadays. 

\endinput 

VERSION HISTORY: 

v0.1   2005/02/15  First release for Roy Flechner. 
v0.2b  2005/02/16  Attempt at \getpagewiselinenumbers -- in 
                   vain. Improved explanations. 
v0.2   2005/02/17  Changed implementation back; but keep 
                   completely disabling \newlabel after the 
                   report. Only page numbers are reported. 
                   (CTAN and ednotes.news received slightly 
                   different explanations than Roy Flechner.)
v0.3   2005/02/17  \@newl@ble turned off with page no. change 
                   only. Doc. warns on compatibility. 
v0.31  2005/02/27  Additional line on screen. 
v0.32  2005/03/08  Adapted explanations to ednotes.sty v1.1; 
                   warned about usefulness with critical 
                   editions. Changed some headings. 
                   Acknowledgements. 
v0.32a 2005/03/21  Minor corrections. 
v0.32c 2005/10/01  Another typo fix.