summaryrefslogtreecommitdiff
path: root/support/relabel/relabel.doc
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/relabel/relabel.doc
Initial commit
Diffstat (limited to 'support/relabel/relabel.doc')
-rw-r--r--support/relabel/relabel.doc261
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.