path: root/Master/texmf-dist/tex/latex/ednotes/lblchng1.sty

%% 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.