GENERAL DESCRIPTION OF "RELABEL". Peter Ungar, peterungar@yahoo.com Aug. 18, 2008 WARNINGS. If your .TeX files contain extended characters (characters coded by bytes > 127) then this program will not work for you. Relabeli.exe and Relabelmac assume the only extended characters in the file are the ones put in to tell Relabel what kind of item the subsequent characters are the identifier of. TeX ignores lines starting with % but Relabel is not programmed to do that. Hence extended characters have to be removed from commented-out text for the relabeling to work correctly. ------------------------------------------- The program RELABEL is designed to make it easy to renumber the items and change the references to them in a text file after you have inserted or deleted or moved material. LaTeX does this at the typesetting stage, but that creates a discrepancy between labels in the source text and the typeset text. It also involves more typing than RELABEL. The MS-DOS version of RELABEL, Relabeli.exe, works on Windows Vista and earlier versions but both the file to be relabeled and the output file must obey MS-DOS filename rules: at most 8 characters before the . and no spaces. I don't know whether Relabelmac works on current Macintosh computers. 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 10 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. 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. 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 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 even after you have entered a new chapter. Therefore, a chapter identifier is not needed in a full identifier of another type of item; the section number suffices to make the label unique in the entire text. Putting the chapter number there too will cause an error. 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. If you are using WinEdt and MikTeX, you can typeset from a source text with the label tags in it; MikTeX ignores the tags. In case your TeX program does not ignore extended characters, RELABEL gives the option of an output file without label tags. NAMES OF FILES RELABELi.exe is an old MS-DOS program. Input and output file names must consist of 8 or fewer characters and contain no spaces. Otherwise RELABELi.exe hangs up without a message. 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. In case the Macintosh version, RELABELMAC, still works on your Macintosh, note the following. The Creator of the output files is *TEX, for convenient use with the excellent TeX program TEXTURES. You can change the creator in the 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 periods(.). 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 digits and letters of the English alphabet (ASCII characters 48-57, 65-90 and 97-122). 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 place an extended character just before the identifier. There are two different tags that can be used for each type of item. The reason is that some extended characters are easier to type on Windows computers while others are easier on Macs. The input file may contain either one of the choices in each place, so that Relabeli.exe can process a file written on a Macintosh, conversely. At large ferers to items numbered consecutively in the entire file. An identifier of such an item should not have chapter, section and subsection identifiers and will be changed to a single number. MS-DOS MACINTOSH At large: ASCII 220: Option a, ASCII 140: fiGure: ASCII 221: Option g, ASCII 169: Formula: ASCII 222: Option f, ASCII 196: Problem: ASCII 223: Option p, ASCII 185: Definition: ASCII 224: Option d, ASCII 182: Theorem: ASCII 225: Option t, ASCII 160: Lemma: ASCII 226: Option l, ASCII 194: Chapter: ASCII 227: Option c, ASCII 141: Section: ASCII 228: Option s, ASCII 167: suBsection: ASCII 229: Option b, ASCII 186: Reference tag: ASCII 222: Option f, ASCII 196: The blank Option t is bewildering but if you copy and paste it works. 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.) WARNING TO WinEdt users: In all the settings I was able to try, WinEdt produced extended characters different from the above when I used the ALT key. To get the required byte into the text select CHARACTER MAP from the TOOLS menu. Double clicking a character will insert it into the text where the caret is. Another way: type the characters into a Wordpad text file, keep that window open and copy and paste the characters. 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.