diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/relabel/relabel.doc |
Initial commit
Diffstat (limited to 'support/relabel/relabel.doc')
-rw-r--r-- | support/relabel/relabel.doc | 261 |
1 files changed, 261 insertions, 0 deletions
diff --git a/support/relabel/relabel.doc b/support/relabel/relabel.doc new file mode 100644 index 0000000000..cd1e535c4d --- /dev/null +++ b/support/relabel/relabel.doc @@ -0,0 +1,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. |