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.