summaryrefslogtreecommitdiff
path: root/support/relabel/relabel.doc
blob: cd1e535c4d8f136b3b89c8e2fb56664c3b18c8d5 (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
261
              GENERAL DESCRIPTION OF "RELABEL".
                    
          Peter Ungar, 914 723 7187  May 25, 1994

  The program RELABEL is designed to make it easy to renumber the
items and change the references to them when you want to
insert or delete material or move it to another part of the
manuscript. LaTeX has a clumsy mechanism of this sort, which gets
into action at the typesetting stage. It creates a permanent
discrepancy between labels in the source text and the final
version. It also involves more typing than RELABEL.

  To use RELABEL, you normally have to type only a single
character in addition to what would be in an old-fashioned
typescript, to tag the string which follows as an identifier for
one of 9 kinds of items. If you are referring to an item which
has not appeared yet, you have to type a second character to
indicate that this is a reference.

  In LaTeX the term "label" is used for the occurrence of, say,
3.2.13 next to the formula, and "reference" for its occurrence
elsewhere.  We shall mostly use the same terminology and use
"identifier" when mean "a label or a reference".

                   TYPES OF IDENTIFIERS.

  RELABEL has provision for identifiers of chapters, sections,
subsections, definitions, theorems, lemmas, figures, formulas,
problems and at-large items. At-large items are numbered
consecutively in the entire file; photo-reproductions printed on
special paper are usually numbered this way.
  
  When RELABEL encounters a subsection heading, the numbers of
all non-heading items other than at-large items are reset to 1.
These item numbers form six independent series but RELABEL treats
them in the same way.  In particular, "lemma"-s are not reset
after each theorem.  Section headings reset the subsection count
too.  A new chapter identifier resets the section count only in
3-level mode, explained below.  It is allowed that some chapters
contain sections and others not, and some sections can contain
subsections and others not. A chapter or section may contain some
material before the sections or subsections start.

  If you do not want item numbers reset each time you start a
subsection, use a non-heading type tag you do not need, e.g.
Lemma, to label subsections.

             THREE OR TWO LEVELS OF TEXT UNITS.

  RELABEL can work with either 3 levels of text units (chapter,
section, subsection) or 2 levels (section, subsection.) In the
3-level mode section numbers are reset to 1 at the beginning of
each chapter except the first. All other counts are reset to 1 at
the beginning of each section or subsection, except for the count
of "at large items" which starts with 1 and is not reset.
3-level mode does not mean that chapters must have sections and
sections must have subsections, only that they may have them.

  If you give RELABEL the wrong number of levels, you will get
error messages. RELABEL does not have a built-in option to
change a text from 2-level to 3-level mode or vice versa, although
one can trick it into doing that.

                   ABBREVIATED IDENTIFIERS.

  In 3-level mode a full identifier must contain the chapter
identifier and, if we are in a section or subsection, then those
identifiers too.  The full identifier of Theorem 4 of chapter 1,
section 2, subsection 3, with the theorem tag (Macintosh version)
would be 1.2.3.4.  Part or all of a section may not be
in a subsection, and part or all of a chapter may not be in any
section. In such parts a full identifier is correspondingly
shorter.  If chapter 1 has no sections then the full label
of theorem 4 would be 1.4. (See later about alternative label
tags for Macintosh and MS-DOS computers.)
 
  In 2-level mode you can still use chapter labels but sections
are numbered consecutively.  Therefore, a chapter identifier
is not needed in a full identifier of another type of item and
will cause an error if used.

  Labels and references to items of the at-large type should NOT
include a text unit identifier.

  You may omit ALL the text unit identifiers (chapter, section,
subsection) in a label or reference; RELABEL will understand that
the text unit is the current one. If you refer to another text
unit, you may not omit ANY identifier, even if you are referring
to another subsection of the present section. RELABEL will also
be confused if you omit some but not all of the identifiers of
the current text unit. Apart from this, you need not be
consistent; you may omit all unit identifiers in one label or
reference and put them all in in the next. You can choose whether
your output have abbreviated or full labels. IF YOU WANT TO MOVE
MATERIAL AROUND, USE RELABEL TO CREATE A FILE WITH  UNABBREVIATED
LABELS. Then you can move, say, Problem 2 from Section 6 into
Section 7 which also has a Problem 2, and they will be assigned
different numbers when you run RELABEL again.

  You may abbreviate labels of sections and subsections but in its
output RELABEL always writes these out in full. In section and
subsection labels RELABEL will even correctly interpret partially
abbreviated labels, i.e. in 3-level mode you can omit the
identifier of the current chapter but retain the identifier of
the currect section.

                 LABEL TAGS IN OUTPUT OPTION

  If further revisions are to be made in the file, we want to
retain the special symbols which identify the various kinds of
labels and references. We do not want them in the final version.

                  NAMES OF THE OUTPUT FILES

   The Macintosh version makes a name for the output file by
appending either an R or a T to the name of the input file.  R 
is for Relabeled and it is appended when the output file still
contains the label tags. T stands for TeX source text, and is
appended if the "no label tags in the output file" option is
selected.

   MS-DOS users do not have the luxury of being able to lengthen
file names. The MS-DOS version of RELABEL asks you to give a name
to the output file.

   In the Macintosh version the Creator of the output files is
*TEX, for convenient use with the excellent TeX program
TEXTURES. You can easily change TextCreator in the source text of
the program.  Less easily, you can change the compiled program by
looking for the TEXTURES creator code *TEX using ResEdit.

                   SPECIFICATION OF IDENTIFIERS.

  The chapter number, if any, the section number, subsection
number and the number  of the item within the unit are separated
by .-s.  Because of this, RELABEL will go wrong if you assign
formula numbers containing decimal points, e.g. 1.5 for something
inserted between 1 and 2. The identifiers you give to chapters,
sections and items within a section should consist of ASCII
characters 48-57, 65-90 and 97-122, digits and letters of the
English alphabet, so you can use 1a instead of 1.5. Lower and
uppercase letters are considered distinct. The parts of the label
separated by .'s should contain at most 12 symbols.  When the
program is reading a label and it encounters a space or any other
symbol which is not a digit or a small letter or ., it concludes
that the label has been read, and that the symbol at hand is the
one following the label. RELABEL recognizes a . immediately
following the label which is not followed by a character or digit
as not part of the label. Thus, when you have proved it, you can
write

Theorem 1.5. Perfect numbers are even.


               TAGS INDICATING THE KIND OF ITEM

   To indicate what something like 5 or 12.JohnSmith is the label
of, we immediately precede the label (without leaving a space) by
a certain character. Characters with bytes < 128 could not be
used because they are needed for the text. We have to allow two
alternative label tags for each of our 10 types of item
because what is easy to remember and write on the Macintosh is
difficult on MS-DOS computers and vice versa.

                      MACINTOSH              MS-DOS

  0: At large:   Option a, ASCII 141:     ASCII 220:
  1: Chapter:    Option c, ASCII 141:     ASCII 227:
  2: Section:    Option s, ASCII 167:     ASCII 228:
  3: suBsection: Option b, ASCII 186:     ASCII 229:
  4: fiGure:     Option g, ASCII 169:     ASCII 221:
  5: Formula:    Option f, ASCII 196:     ASCII 222:
  6: Problem:    Option p, ASCII 185:     ASCII 223:
  7: Definition: Option d, ASCII 182:     ASCII 224:
  8: Theorem:    Option t, ASCII 160:     ASCII 225:
  9: Lemma:      Option l, ASCII 194:     ASCII 226:

Reference tag:   Option f, ASCII 196:     ASCII 222:     

  To produce, say, byte 222 when using MS-DOS programs, hold down
ALT and press the 2 key ON THE NUMERIC KEYPAD 3 times. (If this
does not work, try locking or unlocking the numeric key pad.)

  In the MS-DOS bytes we chose, only the last digit varies, which
makes typing relatively easy. To help remember the last digit,
note that in the top row of the keypad we have chapter, section
and subsection; in the second row, definition, theorem, lemma; in
the third row, figure, formula, problem. For the at-LARGE
type of item we use the LARGE 0 key in the fourth row. Since
formula is the most frequently occurring item, we utilized the
most convenient code for it, and also for the reference tag.

  Both the MS-DOS and the Macintosh versions of RELABEL recognize
either code, or a mixture of the two, in the input. They change it
to the one used in their respective systems in the output.

  The symbols associated with the characters depend on the font.
On MS-DOS computers one gets different characters if one uses
different country codes.  Users of languages other than English
may find that some of the 18 bytes we used in tags are needed for
use in text and have to be replaced.

  Note also that in some fonts some bytes > 127 produce symbols
also associated with bytes < 128.  Therefore, if you see an
ordinary character in the above the tag list, it does not
necessarily mean there will be a conflict with RELABEL.

                      REFERENCE TAGS

  RELABEL checks whether an identifier has occurred earlier.  If
not, it treats it as a label, i.e. the occurrence of an identifier
next to the item it is identifying, rather than a reference.  If
we make a reference to an item which has not yet occurred, we have
to tag it as a reference. This is done by putting just after the
tag which specifies the item kind, one of the two reference
tags shown in the table.  Wneh you have run a file through
RELABEL, backward as well as forward references will have
the reference tag, which enables us to move material to any
other place in the text.

                      EXAMPLE FILES

   Two example files are provided so that the reader can see how
RELABEL works and experiment with it. The files have
memnonic labels, which RELABEL replaces with numbered labels.
RELEX3 has 3 levels of text units, RELEX2 has 2. (RELEX2
will also produce 1 error message.) The files are almost the
same. If you produce a relabeled file with the labels written out
in full and the label tags left in, you can move items and
even entire text units to other places. If you then use RELABEL
again, the text units and items will be provided with appropriate
new labels.

                      ERROR HANDLING

  If you make a mistake when typing the input file name or input
a letter when a number is expected or vice versa, RELABEL will
crash. On the Macintosh it may even cause a system crash and
output a message that a system file may have been damaged. In
fact, the disk drive is not activated on these occasions and
hence no disk file is affected. (If one compiles the Macintosh
version with THINK PASCAL or with METROWERKS PASCAL, the
resulting applications will not cause system crashes in these
circumstances but the THINK PASCAL 3.0 product takes about 3 times
longer to relabel our example files on the MAC+, and the
METROWERKS PASCAL v.1.3 product takes about 10 times as long.)  
  
  If a label has a wrong format or RELABEL can not find a label
which is referred to, there will be an error message and you can
choose to exit RELABEL. (Relex2 has one reference to a
nonexistent label.) Try to complete the run.  In the output file
the incorrect identifiers are replaced by ??? which should make
it easy to find the errors in the input file.

  It helps to avoid errors to put the reference tag into all
references, not just forward references. If you make a tagged
reference to a nonexistent label, e.g. because of a typing error,
RELABEL gives an error message. If the identifier is not tagged
as a reference but has the correct format, RELABEL will consider
it to be a new label and assign the next available number for
that kind of item.