diff options
Diffstat (limited to 'support/relabel/Relabeldocument.txt')
-rw-r--r-- | support/relabel/Relabeldocument.txt | 286 |
1 files changed, 286 insertions, 0 deletions
diff --git a/support/relabel/Relabeldocument.txt b/support/relabel/Relabeldocument.txt new file mode 100644 index 0000000000..d9de637b50 --- /dev/null +++ b/support/relabel/Relabeldocument.txt @@ -0,0 +1,286 @@ + 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. |