Part I:
% XREF001.TEX --
%
% Created at 02:29:35 on Thursday, April 13th, 2006.
% ======================================================================
%
% Modified at 01:03:52 on Thursday, April 13th, 2006.
%
% Macros for sequential numbering and cross-references
%
% Macros \SNUAdvanceChapter, \SNU#1, \SNT#1, \SNF#1,
% \GetSN, \SNC#1, \SNCGetChapter#1, \SNCGetPage#1,
% \SNUGetChapter#1, \SNUGetUnit#1, \SNUGetPage#1,
% \SNTGetTable#1, \SNTGetPage#1, \SNFGetFigure#1,
% \SNFGetPage#1, \SNChapterPrefix
%
% Counters \SNChapter, \SNUnit, \SNTable, \SNFigure,
%
% Here SN abbreviates 'sequential numbering'.
%
% Here we have a start on a fairly general collection of
% macros for sequential numbering and cross-referencing.
%
% For example, maybe in some chapter, that at present is
% chapter 3, we want to sequentially number definitions,
% theorems, remarks, and examples -- call them all 'units'
% -- as in:
%
% 3.1 Definition:
%
% 3.2 Theorem:
%
% 3.3 Definition:
%
% 3.4 Remark:
%
% 3.5 Example:
%
% Then with this package we would select some tags, say,
% starting with SNTag, and type
%
% \SNU{\SNTagA} Definition:
%
% \SNU{\SNTagB} Theorem:
%
% \SNU{\SNTagC} Definition:
%
% \SNU{\SNTagD} Remark:
%
% \SNU{\SNTagE} Example:
%
% So, macro \SNU abbreviates 'sequential numbering with
% units'. So, with macro \SNU we get a case of automatic
% sequential numbering.
%
% Suppose 3.1 Definition: appeared on page 43. Then
% elsewhere we could write
%
% See \SNUGetChapter\SNTagA.\SNUGetUnit\SNTagA Theorem
% on page \SNUGetPage\SNTagA.
%
% and get
%
% See 3.1 Theorem on page 43.
%
% So, we get automatic cross-referencing.
%
% Of course, to do cross-referencing in such a general way,
% need to run TeX at least twice, once to find, for each
% sequentially numbered 'unit', its page and write this
% data to a file, and once to read this file and insert the
% sequential numbering and page numbers where desired in
% cross-references.
%
% The file is \jobname.XRF.
%
% To use this sequential numbering with units,
%
% o At each chapter, after the \eject, if there is
% one, and just before the \hOne, have
%
% \SNUAdvanceChapter
%
% to increment by one the counter \SNChapter and
% set the counter \SNUnit to 0.
%
% o Otherwise use macros
%
% \SNU\SNTagA
% \SNUGetChapter\SNTagA
% \SNUGetUnit\SNTagA
% \SNUGetPage\SNTagA
%
% as illustrated.
%
% o Then run TeX at least twice, basically until
% the file \jobname.XRF quits changing.
%
% So, we get sequential numbering and cross-referencing with
% 'units'. The macros and counters particular to 'units'
% all begin with \SNU.
%
% We let
%
% \newcount\SNUnit
%
% keep track of the number of the unit. So, when we use
%
% \def\SNUAdvanceChapter{\advance\SNChapter by1
% \SNUnit=0}
%
% to increment
%
% \newcount\SNChapter
%
% we also set \SNUnit=0 for the new chapter.
%
% With the \SNU macros as illustrated, will get file
% \jobnane.XRF like
%
% \SNTagA
% 1 1
% 1
% \SNTagB
% 1 2
% 1
% \SNTagC
% 1 3
% 1
% \SNTagD
% 1 4
% 1
% \SNTagE
% 1 5
% 1
% \SNTagF
% 1 6
% 1
% \SNTagG
% 1 7
% 1
% \SNTagH
% 1 8
% 1
% \SNTagI
% 1 9
% 1
%
% So, get three lines for each invocation of \SNU. The
% first line has the tag. The second line has data
% particular to 'units' macros. And the third line has the
% page number.
%
% For in Appendix I, may want units to go
%
% A.I.1.2
%
% that is, to have a 'prefix' of 'A.I.'. To this end there
% is macro
%
% SNChapterPrefix
%
% which is default empty. Setting this macro to
%
% \def\SNChapterPrefix{A.I.}
%
% will give the prefix 'A.I.'. But, such a prefix should
% have no blanks else the parsing of the macros that get
% cross-referencing information will get confused!
%
% But we may also want sequential numbering and
% cross-referencing for tables, figures, equations, etc.
%
% Then the idea is to have more sequential numbering
% macros. But, do not want a proliferation of files. So,
% these other macros should also use the file \jobname.XRF.
% For compatibility, each of these other macros should also
% write three lines to file \jobname.XRF. The main freedom
% is just in the second line.
%
% Each tag, e.g., \SNTagA, becomes a macro. So, each tag
% should be spelled like a TeX macro and have spelling
% different from all other TeX macros in use.
%
% During the first pass of TeX, macros
%
% \SNUGetChapter\SNTagA
%
% \SNUGetUnit\SNTagA
%
% \SNUGetPage\SNTagA
%
% will notice that \SNTagA is not defined and will define
% it as the macro \SNUNone from
%
% \def\SNUNone{CH UN PG}
%
% the three tokens of which are intended to abbreviate,
% respectively, chapter, unit, and page.
%
% Then each of the three macros
%
% \SNUGetChapter\SNTagA
%
% \SNUGetUnit\SNTagA
%
% \SNUGetPage\SNTagA
%
% will return 'CH', 'UN', and 'PG', respectively, as
% temporary place holders and a way to get page breaking
% approximately correct before another pass of TeX that
% will read and use the XRF file written on the previous
% pass.
%
% We also have macros for tables and figures. For tables,
% the names begin with SNT; figures, SNF.
%
% The main challenge was in macro SNU (SNT, SNF) that has
% to write both the sequential numbering and the page
% number. The cause of the challenge was how, really,
% when, TeX actually does page breaking. So, once TeX
% starts a new page, it keeps adding lines until it clearly
% has enough, and maybe too many, lines for that page.
% Then TeX decides where to break the page, uses any left
% over lines for the next page, and continues. So, when a
% macro in the text executes, TeX does not yet know the
% page number but the macro does know the chapter number
% and, say, the unit number.
%
% When TeX sees a \write, TeX temporarily puts the \write
% in a 'whatsit' until the page breaking and then executes
% the \write. 'Whatsits' are discussed starting a line
% 14,007 of the file of TEXBOOK.TEX.
%
% The trick, then, is to have
%
% \def\JUNKA{\the\SNChapter\space\the\SNUnit}
% {\edef\JUNKB{\write\XREFileOut{\JUNKA}}\JUNKB}
% \write\XREFileOut{\the\count0}
%
% In the first line we define \JUNKA that has the data to
% be written. The second line has a group with an \edef
% (define a macro expanded immediately) of a temporary
% macro \JUNKB with the \write and with the data to be
% written and, then, with an invocation of \JUNKB. Due to
% the \edef, the whatsit for the \write has only constants
% and the right constants. Those constants are from
% counters
%
% \SNChapter
% \SNUnit
%
% which might well change by the time the \write is
% executed; but, the constants will still have the values
% we need to have written.
%
% On the third line, we use \write to write the page
% number, and the page number in \count0 is expanded at the
% time of the page breaking and, thus, has the correct page
% number.
%
% Another challenge is how to handle the data read from
% file \jobname.XRF: As each line is read, it has a
% trailing blank. So, have to use and/or parse the blank.
%