summaryrefslogtreecommitdiff
path: root/support/relabel/Relabeldocument.txt
diff options
context:
space:
mode:
Diffstat (limited to 'support/relabel/Relabeldocument.txt')
-rw-r--r--support/relabel/Relabeldocument.txt286
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.