Web pdp-10.trailing-edge.com

Trailing-Edge - PDP-10 Archives - mit_emacs_170_teco_1220 - info/renum.info
There are no other files named renum.info in the archive.
-*- TEXT -*-
This file documents the RENUM EMACS library. All changes should
be made to INFO;RENUM > on MC and installed at other sites when
significant changes are made.  :TAGS should be run before installing.
Created by SK@MC on 5/23/80.

N.B.  All documentation was specifically designed to be perused
on-line using INFO.  If you are reading these remarks on a piece
of paper, you are losing.

File: RENUM, Node:  TOP,  Up:  (EMACS), Next: Brief

The RENUM library

* Menu:

* Brief::		Brief description of the library
* Novice::		If you have never used RENUM before
* Concepts::		What is meant by "renumbering"
* Features::		Summary of all available features
* Commands::		Commands provided by the RENUM library
* Rules::		Concise summary of scan rules
* Examples::		Menu of various examples
* Draft::		Working drafts vs. final draft.
* Hints::		Hints for certain types of manuscripts
* Messages::		Error/warning messages--what to do
* Caveats::		Things to be aware of
* Unsure::		How to be sure RENUM "does the right thing"
* Customizing::		How to customize RENUM from an init file
* Other::		Using RENUM with other text formatters
* News::		Recent changes, special temporary hacks

How to do specific things
-------------------------------------------------------
* References::		Renumbering bibliographic references
* Equations::		Renumbering equations
* Figures::		Renumbering figures
* Tables::		Renumbering tables
* Headings::		Renumbering section headings
* Sectioning::		Section numbers in renumbered text
* Implicit::		Controlling implicit/explicit input/output
* Insertion::		Inserting a new equation, figure, etc. is easy
* Basic:Commands	The two basic commands you should know


File: RENUM, Node: Brief, Previous: Top, Up: Top, Next: Novice

The RENUM library contains commands to renumber equations, sections,
figures, tables, and references in manuscripts meant for a text
formatter or for direct printing.  The author can insert/delete/move
references to equations, figures, tables, sections and papers
(bibliographic references) and still maintain sequential
numbering on his working draft.  The package will also renumber
an outline as well as just a simple list (*Note Outline:Customizing.).

The features provided by this library make its use more
attractive than using the automatic numbering provided by most
text formatters.  You probably won't have to modify your
existing manuscript much to get it to work with the package.

The library has default settings to accomodate all text
formatters ( *Note Settings: Other.) and each group of default
settings may be easily customized via an init or local modes
list to accomodate any special features the user might want
(*Note Init:Customizing.).

The user only needs to know two M-X commands
(*Note Two:Commands.)  to make all the following features happen:
renumbering of sections, equations, figures, and tables based on
order of appearance, renumbering bibliographic references based
on order of appearance or alphabetical order (by chapter is
optional), sorting of bibliographic references both in the paper
and in the bibliography based on the renumbered "value"
(alphabetic or numeric) with dashes inserted for more than two
consecutive digits, automatic insertion (done before sorting) of
needed bibliographic references from a master reference file
with a warning if the final result does not contain all needed
references, optional bibliographic renumbering before/after
bibliography, renumbering by section (optional), inter- and
intra-section references with prefix inclusion optional for each
section, separate sectioning for figures, tables, equations, and
sections, and bibliography information table generation.  The
library 1) allows forward referencing of figures,
sections, equations, etc., 2) has sophisticated scan rules so
things like "Figures 3 and 2" will be recognized, 3) preserves
suffixes like Equ. 1a, and 4) will operate on a narrowed section
of the buffer if desired.  Most of the conventions can be
modified/customized via an init file.

There is a "draft mode" and a final output mode.  Basically,
the routines can reprocess the same file an infinite number of
times when in draft mode, but can't in final output mode
(*Note Draft:Draft.).   Hence, you can always be editting a
correctly numbered manuscript if desired.

Bugs and suggestions to SK@MIT-MC.


File: RENUM, Node: Novice, Previous: Brief, Up: Top, Next: Concepts

The documentation in this file is organized by topic to allow
you find things of interest fast.  It contains numerous cross
references (footnotes) so you can find what you need even if you
start looking in the wrong place.  Thus, you probably won't want
to visit any of the footnotes your first few times through.

This document is of finite length.  Not all cases can be covered
here.  Rest assured that this package can be used successfully
on almost all styles of manuscripts.  All the tools and some tricks are
described here.  If you can't figure out how to apply the tools
to your manuscript style, feel free to send a :BUG RENUM note.

Once you get acquainted with RENUM you will find it is really
very simple to use:  you pretty much type your manuscipt in
normally and issue a single command to renumber (which will do
nothing if your manuscript is perfectly numbered).

The best way to get acquainted with RENUM is to try it!
If you think you pretty much understand the concepts of
renumbering, then you are all set to go.  Try it on your
manuscript in its current form.  If things don't work right, see
the appropriate node under "How to do specific things" in the
Top node of this documentation.  And be sure to find out about
automatic referencing at some point; it saves a lot of time.  As
you start feeling more secure, you can try some of the more
advanced features when you need them.  After loading RENUM, M-X
Renum ? will list the commands.

For those desiring a more structured approach
we will try one thing at a time: first doing
something simple like learning how to renumber equations.

Once you know all about equations, then try to understand
figures and tables.  Then references and finally sections and
sectioning.  Then read through the hairy example and make sure
you understand what's going on and you are done.

To get you started, here's a menu of nodes to read.  Come back
to this node with the "L" command after visiting each node in
the menu.  Don't go wandering off visiting sub-nodes that look
neat.  If it's important to know right now, it'll be on the
menu.  Also, be sure to use INFO's  "L" command to return here.
This is a winning command that will leave the cursor on the menu
item you visited last.  That way you won't have to keep reading
this cruft.

This menu is not all inclusive.  It is meant to get you started.
From then on, how much you learn is up to you and your needs.

* Menu:

First you should be aware of all the things RENUM can do.  By
visiting the Features node, you will get a menu pointing to all
the features.  Just for curiosity sake, read this node and come
right back.  You can read all the subnodes later.  Our main task
is to get you started.

* Features::	Go to this node and come right back without
visiting any subnodes.

Ok, now you realize RENUM can do a lot of neat stuff for you.
You should understand a few concepts before you renumber stuff.
The most fundamental concept is explained in the next node in
our menu:

* Two Pass::	This node explains the fundamentals of
"renumbering".  Select it now and come back.

Ok, by now you are all "hot-to-trot" and wanna try things out.
Let's start with equations. You will need to know how an
equation is recognized on the first pass and how it is
recognized on the second pass.

* Rules::	This node gives some examples for how and
equation gets recognized and also points you to further info.
The further info you might need to know is contained in the next item
on this menu, so visit the Rules node and come right back.

Ok.  Now lets get a little more detailed information on how
equations are recognized.

* Equations::	Describes in detail the scan rule for equations.

Now, you will need to know how to load the library and what
commands to issue.  The next menu item describes this.  It will
talk about draft mode and a command to complement draft mode.
This is not of importance right now and you can ignore it.

* Commands::	Visit this node and come back.

Ok.  That's it for the rudiments.  Now I suggest you actually
try out the commands on a scatch buffer.  Make sure there are a
couple of spaces at the beginning and end of the buffer before
any of your text you want to renumber since the searches used by
the macro assume that stuff to be renumbered is not on these
extremes.  In any REAL manuscript, you'll never have to worry
about this.  So type a manuscript with say three equations and
a few references to these equations.  Move one of the equations to a
different place and renumber.

If you are a real winner, you are viewing this documentation in
EMACS with the C-X I command.  If you type Q, you can escape back
into EMACS, try everything, and return exactly where you were by
issuing another C-X I.

Delete one of the equations and
renumber.  Note you'll get a warning message that your
manuscript contains references to an equation which does not
exist.  At this point, you would normally have to go back and
delete by hand those references you should have deleted when you
deleted the equation.  But since this is really a test
manuscript, it doesn't really matter.

Now to insert an equation at some point, just give it a unique
number.  If you want to insert an equation between equation 1
and 2, just call it equation 1.5 and place it between equations
1 and 2.  Or you could have called it anything else, e.g.,
\eqno(1) \eqno(34.233) \eqno(2) would get renumbered as 1, 2,
and 3.

After you have tried this, you should realize that people like
to have suffixes like (1a).  RENUM handles this by only
renumbering the "significant" portion of a number as explained
in the next node.

* Suffix::	Visit this menu item and return.

Now you know a little about equations.  Figures are handled in
much the same way.  Here's how a figure is recognized:

* Figures:Scan(f)

Note the rules are much more complicated than the equation scan
sequence. However, this translates into a simpler user
interface.  You can type things like  Figs. 2, 3a, and 4b
and it will be renumbered properly.  Try it in a scatch buffer.

It may mistify you why you would want to use fFigure.  This is
explained shortly.  Unfortunately, to really
appreciate what's going on, you will have to understand
sectioning first:

* Sectioning::

Now that you are an expert in sectioning, the following nodes
will be a review for you:

* Implicit::	Implicit vs. Explicit
* After::	Describes what happens after a scan sequence
spots something to renumber

You might play around with sectioning a bit in a scatch buffer.
Now you can appreciate the explanation of fFigure.

* Forward::	How and why of fFig.

This is it for the tutorial.  I suggest examining the following
three nodes going as deep as you like.  You probably won't want
to return here with the L command, so jot down the names. You
can get to them from the top level or from this node.  Visit
them in the order here:

* Bibliographies:: Describes some of the neat bibliograhphy features
* References::	Describes all about bibliograhpy references
Go as deep as you like here.  This is directly
reachable from the Bibliographies node.
* Draft::	After all this, you will now appreciate the
differences between Draft and Final mode
* Headings::	Section numbers are renumbered as you learned in
the beginning.  Here are the details.

If you've stayed with this so far, you are now an expert and the
hairy example which demonstrates just about everything will seem
trivial.

* Hairy::	This should seem like a trivial example to you
and will be a good review and test on what you
know.

This should be enough so you can access and understand all the
documentation which you didn't visit on this brief tour.
There are lots of nodes worth reading that you haven't seen.
Some neat nodes are the Insertion and the Unsure nodes. I'd
like you to be sure and visit one last node before quitting:

* Caveats::

Any comments on this tutorial should be sent to SK@MC or BUG-RENUM.


File: RENUM, Node: Concepts, Previous: Novice, Up: Top, Next: Features

This node explains some of the basic concepts of the RENUM
Library.  After selecting the Two Pass node, typing "N" will
step through all of them.

* Menu:

* Two Pass::		Explains how the macros renumber your file.
* Implicit::		Explains the difference between implicit
and explicit input and output.
* Insertion::		Explains how to insert a new equation, etc.


File: RENUM, Node: Two Pass, Up: Concepts, Next: Implicit

The basic philosophy behind renumbering is to renumber things
consecutively based on when they are defined.  What text is
considered to be a "definition" depends on what you are
renumbering (*Note Scan: Rules.) and the text formatter you want
the output to go to (*Note Formatters:Other.).  After all the
definitions are sequentially numbered, a second pass is made to
renumber the references to those definitions.  Again, what is
considered to be a reference to a definition depends on what you
are renumbering.

Let's say for instance that we are renumbering equations. We
would like to number the equations based on when the physical
equation actually occurs in the text, e.g., in TEX, a physical
equation will occur where a \eqno(<num>) appears.  Then the
first equation is renumbered to be "1", the second is "2", etc.
After all this is done, a second pass of the file is made and
references to the old numbers are renumbered, e.g., for any
formatter, a reference to an equation is of the form (<num>).
For example,

Original sequence:  (5) \eqno(4)  (5) (4)   \eqno(5)
Renumbered seq:     (2) \eqno(1)  (2) (1)   \eqno(2)

What actually happens is a little bit more well defined and
precisely described below.  Note that "definitions" are anything
meeting the first pass scan rule, and references to a definition
are things meeting the second pass scan rule.

Renumbering of Equations, Figures, and Tables---

This is handled in two passes.  Each type (equ., fig., table) is
done separately. On the first pass through the file, text
meeting the first pass scan rules, called the <oldnum>, will be
looked up in an internally generated table of <oldnum><newnum>
pairs.  If the <oldnum> is found, the <newnum> will replace the
<oldnum> in the buffer.  Otherwise a <newnum> is generated to
replace the <oldnum> and the combination is added to the table.
The <newnum> consists of two parts: the first part is a section
heading (possibly null) which is controlled by the sectioning
option you are using (*Note Newnum: Sectioning.) and the second
part is the value of a counter which is bumped after a new pair
is added to the table and reset to one at the beginning of each
section.

On the second pass, text meeting the second pass scan rules is
looked up in the table and given the corresponding <newnum>. If
the lookup fails, the text is not renumbered, the user is
notified, and the scan continues normally.  If you are not
already totally confused, you should note that it is possible to
only generate a table on the first pass and suspend all
renumbering until the second pass.  This is required if the
second pass scan rule is a subset of the first pass scan rule
(e.g., if the first pass recognizes "eqno(" and the second pass
recognizes just "o(" ) since you must only renumber something
once for every two passes.

Renumbering of Sections---

Sections are renumbered just like Equations, Figures, and
Tables.  The slick feature is in the generation of the
<newnum> which is done in an entirely different way.

Do M-X DescribeRenumber Sections  for info on how sections are
renumbered with attention paid to the level of indexing intended
by the author and on the basis of how the previous section
number was renumbered.

Renumbering of References---

This is accomplished in a single pass unless renumbering in
alphabetic order is requested in which case two passes are
used.


File: RENUM, Node: Implicit, Previous: Two Pass, Up: Concepts, Next: Insertion

Often, when an author refers to something within the current
section, he omits the section number.  This is known as implicit
input.  Of course, when he refers to something outside of the
current section, he must use the complete section number. This
is explicit sectioning.

Any combination of implicit/explicit referencing is permitted
for the user input text.  Explicit renumbering will be used on
renumbering.  However, you can can have the renumber routines
use IMPLICIT renumbering when you are in final print mode
if you precede the section number on the section defintion line
governing the thing to be renumbered with an asterisk, e.g.,
% Section *1.2- or % Figsection *5-. (*Note Implicit: Sectioning.).


File: RENUM, Node: Insertion, Previous: Implicit, Up: Concepts, Next: Features

Inserting new Figures, Equations, Sections, and Tables---

Type a sequence which meets the first pass scan rule for the
thing you are inserting.  Make sure the number you type is is
unique.  A convenient and natural choice for inserting an
equation between (9) and (10) is (9.05).  Note that using "05"
instead of "5" guarantees your number is unique since the
renumber routines will NEVER leave a leading zero in the last
index (the other indices are specified by the % Section
statement).  You may chose to renumber immediately or wait until
you have made many changes.  The final result is the same.
Often though, you are making changes based on pencil corrections
to the last draft so you must make ALL changes before
renumbering.

Inserting new References---

Just type them anywhere.  They are sorted within a group so
the numbers between the [] are in numerical order.


File: RENUM, Node: Features, Previous: Concepts, Up: Top, Next: Commands

Features provided by the library.

Typing 'N' will sequentially scan all features AFTER selecting
the FlexibleInput node.  Depending on how ambitious you are, you
may wish to proceed with the next node as the sub-nodes of this
node are very detailed.

* Menu:

* FlexibleInput::	Flexible input is permitted.
* Sectioning::		Control of insertion of section numbers,
inter- and intra-section referencing.
* Bibliographies::	Automatic, sectioning, integrity check,
sorting, information table generation.
* Draft::		Working drafts vs. final draft.
* Forward::		All macros are two pass.
* Suffix::		Suffixes are preserved.
* Narrowing::		Narrowing the buffer is permitted but risky.


File: RENUM, Node: FlexibleInput, Previous: Features, Up: Features, Next: Sectioning

In most cases, the user won't have to change his manuscript at
all to work with the library.  The scan rules are sufficiently
clever that everything which looks to you like it should be
renumbered is renumbered, and everything that shouldn't isn't
(you can do M-X DescribeRenumber <EFTS> where <EFTS> means one
of {Equations, Figures, Tables, Sections} to see the current
scan rules for each type).

Of course, if you have you own special macro to say, generate an
equation number right justified, you MIGHT want to customize
your init (*Note Init: Customizing.) which is a 2 minute job in
this case even if you aren't a TECO wizard.

Here are just a few examples of what you can do:

Figure 3 shows that Fig. 4a is wrong ...
Figs. 4.5a and 5.1-2a  ...
Figures 4a, 5b, and 6c show ....
Adding Eqs. (43) and (45), Fred showed [Fred68a, Fred69a] ...
From Equations (1), (2), and (3)--(5) we see ...
From Eq. (A10) of Appendix A ...
From Eq. (A.10) of Appendix A ...
From Eq. (A-10) of Appendix A ...
Tables 4.5 and 3.5a are ...
[This follows from charge neutrality] won't be considered
to be references.

You can insert <nl> anywhere a macro expects a <space> so
you don't have to worry where you break the line.  However, the
reverse is not true (viz., in the default package, section ID,
chapter ID, and each reference IN the bibliography must start with
a <nl>).

Note that the significant portion of the number to renumber is
considered to be up to the first two non-digits.  Hence,
alphabetic suffixes are retained.

These examples are a little trickier:

References 4--10 discuss ...
We see in Figs. 4--6 ...

If indeed you are sure the
references be renumbered consecutively, you can type
[foo68a]--[bar78a] and get [1]--[3] or whatever.  Same for
equations, figures, and tables.  However, this form is not
recommended since there is no way to guarantee that they will be
consecutive after many rough drafts.  For references only, you
can do [a, b, c] and if a, b, and c evaluate to say 2, 3, and 1
respectively, you will get [1--3] which is close to what you
wanted and guaranteed to do the right thing (note that there is
a numerical sort on the references).


File: RENUM, Node: Sectioning, Previous: FlexibleInput, Up: Features, Next: Bibliographies

This node describes sectioning for equations, figures, tables,
and section headings.  Bibliographies may also be sectioned
(*Note RefSections: Chapters.).

Each macro breaks the file up into sections based on the value
of qRenumber New Section (default is "% Section" and case is
significant). Each equation, figure, and table in a section
is renumbered with the <section num><seqence num> where
<section num> is the number appearing after the "% Section"
and <sequence num> is the number of this item in the section.
For example, the first equation in % Section 3. would be
renumbered to be "3.1".

The <section num> could be null or a string of digits
separated by . or - (allowed characters determined by qRenumber
Section Separators).  You need not specify a separator at the
end of the number.  If you do, the separator you specify will be
used.  Otherwise a dot will be used (qRenumber Section Default
Separator) for separating the <section num> from the <sequence
num>.

In many cases, you may want to break the file up into different
sections for figures, equations, sections, and tables
(*Note SepSects: HookVariables.).  Hence, you can use the full section
indices for sections (e.g., "... see section 1.2.3") and use a
higher level of indexing for your equations with a different
separator (e.g., "... in Equ. (1.2-5) is the fifth equation in
the section 1.2 hierarchy) and use a null level of indexing for
your figures (e.g. Fig. 1a).

Before something to be renumbered is looked up or inserted into
the internal table, it is first scanned for any non-digits
(note that the something always ends before two-consecutive
non-digits so Fig. 55abc gets looked up as "55").  If there
are any non-digits, it is presumed the user has used EXPLICIT
input, i.e., that he has completely specified what he wants
to look up.  Otherwise, IMPLICIT input is assumed and the
effect as just as if the current section number was typed
before the number.  You must of course use the complete section
number for inter-section references.

On renumbering (output), if the section number of the looked up
value is the same as the current section number, the section
number will be stripped on output (IMPLICIT output) if two
conditions are met: 1) An asterisk must precede the section
number of the section definition line (e.g., % Section *1.2) and
2) you are in final print mode.  The reason for the second
condition is to keep you from screwing yourself since you will
lose information if you move an implicitly numbered thing to a
different section.


File: RENUM, Node: Bibliographies, Previous: Sectioning, Up: Features, Next: Forward

This node briefly explains the things provided by M-X Renumber
References (*Note References: References.).

Automatic referencing---
Keep all the references you will ever use in a single file!!
Only the references needed in the current paper  will be yanked
in for you.  They will be merged with any local references you
might have.  The whole bibliography is then renumbered and
the bibliography is sorted numerically or alphabetically. I
recommend you use the form Foo68a for references.

Ordinal or alphabetic renumbering---
You can renumber your references in order of appearance
(default) or in alphabetic order.  You can have just the names in
the text changed to numbers, just the names in the bibliography
changed to numbers, or both (the default).

Numeric sorting---
Don't worry about putting down authors in the order of
appearence in the paper.  After a group of references is
renumbered, the list is numerically sorted and dashes are
inserted where appropriate, e.g., [a, b, c] becomes [1--3].

Integrity checking---
You are informed if there are any references missing from your
bibliography.

Information table generation---
By giving an argument of 1 to Renumber References or Renumber
All, you can get two tables for each chapter, one sorted
numerically, the other alphabetically, and each giving a
histogram of how often you used each reference.

Chapter sectioning---
You can automatically have your references done by chapter.  You
can insert chapter text in front of the generated numbers.  For
example, % Chapter 4. will cause [foo67a] to become [4.1].


File: RENUM, Node: Forward, Previous: Bibliographies, Up: Features, Next: Draft

Obviously, you can forward reference equations yet to appear.
No special text is required.

OCCASIONALLY, you may want to refer to a Figure in a section which has
not yet appeared.  For example, suppose I want to refer to Fig.
A-1 in Appendix A.  Then if I just say Fig. A-1 and it is the
third figure reference in section 4., it will be renumbered to
Fig. 4.3.  And then if I try to refer to Fig. A-1 in the next
section (say section 5.), it will be changed to Fig.  4.3 too.

The way around this is to always use fFig. when referring to a
forward Fig. This will cause renumbering of these figures to
happen on the second pass and things will happen correctly:  you
will refer to whatever A-1 got renumbered to.

It isn't a bad idea to use fFig. when referring to any figure
which you know will appear in another section.  That way no
matter where the actual figure is moved to, you will always
refer to what that figure got renumbered to.

In final print mode, the "f" will be removed during renumbering.
It must of course remain in draft mode.

The choice of Fig. for the first pass and fFig. for the second
pass was purely arbitrary.  Using dFig. for the first pass
("define Figure") and Fig. for the second pass would work too.
The advantage of the "dFig." scheme is that you don't have to
worry about where the figure you are referring to is going to
be; the disadvantage is you MUST to type "dFig." an awful lot
and this looks ugly.  Also, the "dFig." scheme vioates the
"prime directive" of this library, viz., the libray should work
on most manuscripts without modification.  However, depending on
your manuscripts, you may prefer this alternate form.  It can be
implemented with a trivial addition to your init file
(*Note Init: Customizing.).

Forward references to Tables are handled just like Figures.

Two passes are used in Renumber References if renumbering by
alphabetic order of author name is specified
(*Note Two:Options.).


File: RENUM, Node: Draft, Previous: Forward, Up: Features, Next: Suffix

The draft mode is used to renumber the working manuscript. You
will always win in draft mode and can run the all the macros as
often or as infrequently as you want and still maintain
consistency.

The following things will NOT be done in DRAFT MODE:

1). Bibliographic renumbering and processing.
2). Implicit flag (*) processing.
3). Removal of the "f" in fFig and fTable.

These things ARE done in FINAL OUTPUT MODE which can be
entered/exited by M-X Renumber Complement Draft Mode.  The final
mode can be used before printing the final paper or before
printing each draft.  It differs from DRAFT MODE in that the
buffer looks "prettier" after being renumbered in Final Output
Mode.  The price you pay for this beauty is that you have lost
some "information" which you can never recover.  This is
analogous to running something through DOCOND.

Because of the information lossage after renumbering in final
print mode, you should write your "pretty" buffer out to some
scratch file, run it through your text formatter so you can show
other people how pretty it is, and then DELETE that scatch file.

If you do not heed this warning and start making changes to your
pretty buffer, you will find that:

1) Forward referencing is lost (e.g., a reference to Fig. A-1 in
Appendix A will get renumbered to be a figure in the current
section if the current section appears before the appendix),

2) Adding a new bibliographic reference becomes a pain in the
ass (because you have to look up what number corresponds to a
given reference if you are referencing a previously used
reference and this number will change if you insert a new
reference),

3) If you have used implicit numbering, you will need to
convert to an explicit number before moving an equation, figure,
or table reference to a different section.

To give you incentive to SAVE YOUR FILE before running any of
the macros in final output mode, when you go into Final print
mode, it will volunteer to save your file for you if the buffer
contains any unsaved changes.  It will also delete the visited
filename to encourage you to write the file somewhere else.

You are initially in draft mode (qRenumber Draft Mode is 1).


File: RENUM, Node: Suffix, Previous: Draft, Up: Features, Next: Narrowing

Only characters before the first two non-digits are considered
significant and used in the table lookup.  Hence, suffixes are
preserved because only the looked up text is modified.  Also, if
the first character is alphabetic, it is NOT counted in the
search for the first two non-digits (see the second example).

Examples:

User Input		Significant Part
----------		----------------
1.2.3abcd		   1.2.3
A-1.5x			   A-1.5
1--1.5			   1


File: RENUM, Node: Narrowing, Previous: Suffix, Up: Features, Next: Commands

The routines in this library are set up to work on the
whole buffer even if the buffer is narrowed.  This keeps the
user from screwing himself.

If you want, you can set qRenumber Whole File to 0 and you
will only process the narrowed region.  It is easy to screw
yourself this way if there is any cross-referencing between the
narrowed section and the rest of the manuscript.  I'm not sure
there is any good application of this feature, but it is available.


File: RENUM, Node: Commands, Previous: Features, Up: Top, Next: Rules

After loading the library with M-X Load LibraryRENUM
you will only NEED to know two commands:

M-X Renumber All
M-X Renumber Complement Draft Mode

As you prepare your document, you can run M-X Renumber All to
clean it up periodically. When you want to send it to your text
formatter, do M-X Renum Comp to get out of DRAFT MODE (which you
are put in when the package is loaded) and then do M-X Renum All
and then write the buffer to some file that should be run
through the formatter and then discarded.  NEVER work from a
buffer which has been processed in FINAL PRINT MODE
(*Note Draft: Draft.).

Since all the RENUM library user commands begin with Renumber,
you can do M-X Renumber ?  to get a list of commands.  Or you can
do M-X List LibraryRENUM to get a list of commands with
comments.

M-X Describe will briefly describe each command.


File: RENUM, Node: Rules, Up: Top, Previous: Commands, Next: Examples

Here are some examples of some of the more common forms
of text renumbered on the first and second pass (this isn't
exhaustive):

1st Pass		    2nd Pass
----------------		---------------
Equations	\eqno(2.3a)		    (2.3a)
(1.2-5a)		    (1.2-5a)

Figures		Fig. 5			    fFig. 5
Figs. 1 or 2		    fFigs. 1 or 2
Figures 5, 6 and 7	    fFigures 5, 6 and 7

Tables		Table 1			    fTable 1

Sections	% Section 1.2-		    section 1.2
Section 1.2
References	[Foo68a, Bar85a]

Note, References may actually be renumbered on the first or
second pass depending on the Reference options selected
(*Note Pass:Options.).

For detailed scan rules and how to make something which isn't
really an equation (say) not get mistaken for one, see the
following nodes:

* Menu:

* Equations::			Scan rules for equations
* Figures:Scan(f)		Scan rules for figures
* Tables::			Scan rules for tables
* Sections:Scan(s)		Scan rules for sections
* References:Scan(r)		Scan rules for references
* Modify:Customizing		How to modify the scan rules


File: RENUM, Node: Examples, Up: Top, Previous: Rules, Next: Hints

Examples of sample input

* Menu:

* Simple::		Very short example for a typical paper
* Hairy::		Sample input with comments--illustrates
most features.  Visit here if confused.


File: RENUM, Node: Simple, Up: Examples,  Next: Hairy

This is a very short example of a simple technical paper.

\input ....
..... Fig. 5a   \eqno(2)
... in (2) which was proved by Foo [Foo80a, Foo45a] ...
... Table 2 ....   \eqalignno{ ....(3) ....}

\references     % from file sk;refere >
\vfill
\Appendix A. Proving pi are round      % Section A.
.... given $$2=2 \eqno(1)$$ ...
\end

Note that it differs from the standard TEX manuscript in the
following ways:

1. There are no references in the bibliography since these
are automatically yanked in from the file specified after
the "from file".

2. The references are left as names and only renumbered to
numbers in final print mode.

3. The equations in the appendix should be numbered starting
with A.1 so a % Section A. statement was needed.


File: RENUM, Node: Hairy, Up: Examples, Previous: Simple

This is the test file for RENUM

You can write this node out to a file and try Renumber All
on it both in draft mode and final print mode.

The default package assumes "% Section" denotes a section number
for use by the renumber sections, figures, equations, and tables macros.
This need not be the case.

If the text Renumber References Options 0 appears within the first 1000
characters of the file, it will set the options to 0 (in this case)
which says 1) renumber in order of appearance, 2) change the names
in the text to numbers, 3) change the names in the bibliography
to numbers.  This is the default anyway.

If you run this in final print mode, the "f" in fFig... and fTable
will disappear and implicit output of section numbers (only output the
section number if it refers to something outside of the section) will
work if specified with an asterisk preceding the section number. Also,
references will be processed in final print mode.  By default you are
in Draft Mode so these things won't happen.  You can do M-X Renumber
Complement Draft Mode <nl> to change this.  Note that information is
lost when generating the final print file so do not work from this
file.

The demonstration of bibliographic referencing is towards the
end of this node.

% Section 1.2-  this section number is untouched since section
numbers are renumbered on the basis of the last
number and there is no last number in this case
since this is at the start of the file.  The
whole file is looked at even if your screen is
narrowed.  You can set qRenumber Whole File to
zero if you are sure you know what you are doing.
It doesn't matter if there is any dot after the last
digit.  If there isn't a . or a - at the end
(the contents of q$Renumber Section Separators$),
a dot (q$Renumber Default Section Separator$) is
used as a separator between section number and
consecutive equation, figure, etc. number.

Figs. 3 and 1   These go to 1.2-1 and 1.2-2.
I have chosen implicit input, i.e., the numbers
contain no .'s.  The effect is as if I typed
the section number (  1.2.) before each figure number.
The added space after the left paren prevents
interpretation as a reference to an equation
(the scan rule for an equation is (<digit> or
(<char><digit> .).
Fig. 1.4.       I can also type an explicit section number. The
intention here is to illustrate that if a figure
is moved to a different section, things happen
correctly.  You are always free to insert/delete/move
things and things will always work correctly.
IN OTHER WORDS, YOU WILL ALWAYS WIN IF YOU LET THE
PACKAGE DO ALL YOUR RENUMBERING.  I recommend that
if you chose to input text in implicit mode that
you run Renumber All in draft mode since if you move
an implicit number to another section before it
is made into an explicit number, information is lost
if there were any references to this number.

(5)	        Here is a reference to the 1st equation in this section.

\eqno(5)      This gets renumbered to be equation 1 since an actual
equation would appear at this point.
(4)	An actual equation would also appear at this point
(for those people using \eqalignno).  This gets
changed to equation 2.
(1.2-4)	This is a reference to the above equation
(4)		This is a reference to the above equation

% Section *1-20.  The section number will get changed to 1.3. since
this is the obvious choice:  it is the next section
in the sequence with the level of indexing specified
in this line.  Note that because of the way section
renumbering works, you get 1.3 instead of 1-3 because
the new number is generated from the old number.
The asterisk before the first digit
means that in the final print mode, all
intra-section references will not include the
section number (implicit renumbering). Also, you
can use dashes to separate indexing levels just
like dots.  However, section 1-20 will get
renumbered, but section 1.20 will not so be careful.
(You'll get an error message).  Of course, the
delimiter at the end does not have to be matched.
You are free to mix dots and dashes as in 1.5-1-3.5.

Fig. 3 and 1	These will get changed to 1 and 2 in final output mode
and to 1.3.1 and 1.3.2 in draft mode.

Figs. 2,
6--7		These will get changed to 3, 4--5.  The "--" form is
not recommended (*Note Dash: FlexibleInput.)

\eqno(2)	This gets changed to equation 1.

(2)--(c.6)	This gets changed to a reference to the first equation
in this section, and to an equation in an appendix
(will be renumbered A.2 since equation (c.6) appears
as the second equation in Appendix A.)
(1.2-5)	This is a reference to the first equation in the last
section.
section 5	Here is a reference to the next section.  It will
be renumbered to 2 since the next section will
be renumbered this way.

% Section 5	This is renumbered to 2 like you expect it should.

In the last section (section 1-20) ....
Note the routines are clever enough to leave the
word section alone where it should and look for
a section number when there is one.

% Section A.	Section numbers can also start with a letter for
things like in Appendix A.  There is no good way
to renumber these so renumber sections leaves it
as is. Implicit input is allowed in lettered
sections.  The rule is that if the significant
part of the thing to be renumbered contains any
non-digits, it is considered to be an explicit
reference.  The dot after the A makes a difference
in lettered sections ONLY since a default separator
is not tacked on (see the next section).
Since renumber sections doesn't touch these headings,
if you want to change this to Section C, you should
change the A to a C then change all references of the
form "appendix A" to "appendix C".
\eqno(1.25)
\eqno(c.6)   These are the first two equations in the appendix.
They are numbered A.1 and A.2 as you expect.  And if
you changed the section heading to be section C,
these equations would become C1 and C2

fFig. d4	Here is a forward reference to a figure appearing
later on in the text. It should get renumbered to
fig. b1 (I lower-cased the f so my comment wouldn't
get renumbered---you really have to try to get around
the scan rules).  Note that explicit input was assumed
here.

% Section B
(c.6)		This is a reference to the second equation in the
preceding appendix
Fig. d4.	This is the first figure in the appendix.  Note
that explicit input was assumed here.

Figs. d4a and d2b.	 These change to B1a and B2b.

% Section *9.4	This section number does NOT change to 2.1 because
section numbers are renumbered on the basis of
the last section.  Since the last section is
alphabetic, the section number remains as specified.
Hence, if you have missing sections when you type
in your manuscript, you can insert a single "% Section
<nl>"  to account for all missing sections.

Here is an illustration of the flexibility of the search routines:

Fig.  3, 4, and 8	should go to  1, 2, and 3
Figs. 33 and 40.	should go to 4 and 5
Figures 4.5a and 6.2b   should go to 6a and 7b
misfigure 7 people	won't get renumbered

\eqno(3a)		should go to 1a and 1b
\eqno(3b)

In Equ. (9.4.3a) and (3b) we see ...   should go to 1a and 1b
In Equashuns (9.4.3a) and (3b) we see ...  ditto

fTable 3.  Tables 2   Table 3...  should go to 2 1 2

Now for references.  These are only processed in final
print mode so in your draft if you wnat to add a reference, you
don't have to look up what number you should type.
If you want to write a book and do your references by
chapter you can do:

% chapter 3. in this case the dot is required.

[foo68a]     Here is a reference.  It becomes [3.1].
A reference name must begin with a letter and
must not contain blanks.  Also, each word must
end with a comma or ] so you can type
[this is a test] and it will not think it is a
bunch of references.
% chapter
this begins a chapter with a null number.
I hate chapter numbers on references!!!

[Kogelnik76a, Ippen78a, foo, bar]	will change to [1--4]
[foo, Ippen78a, Kogelnik76a]		will change to [1--3]
[BAR, Foo, Kogelnik76a]			will change to [1, 3, 4]

Note the numeric sorting and the dash insertion where applicable.
Note case is ignored.

\references	% from file mc:sk;references >
\\ [foo] this is a local reference.  Usually I put my references
in the file sk;references >.  It is automatically searched
for references which are then inserted into the file.
\xxx [bar] another reference.  The references will be sorted
in numerical order when done.  The sort command assumes
each record sorted begins with <nl>\
\vfill % the \vfill denotes the end of the bibliography (sort region)

By calling Renumber All or Renumber References with an argument
of 1, you will generate a REF TABLE file for the manuscript giving you
alphabetic and numerically sorted lists of the references as well
as a histogram of how frequently you referenced each one.

Note that automatic searching of file sk;foo bar for references
is accomplished by the sequence:

<nl>\references  % from file sk;foo bar

This line MUST precede any local references you have.
The filename is deleted as a precaution against multiple
runs in final print mode.


File: RENUM, Node: Hints, Up: Top, Previous: Examples, Next: Messages

Hints for certain classes of manuscripts

Very mathematical manuscripts--

If you use sectioning and spaces after your ( in math
mode, you should win.  This provides DOUBLE protection against
inadvertent renumbering and you will also avoid any error
messages.  If you don't want any sectioning on your output file,
just use % Section *1. and in final output mode renumbering, the
section number will disappear.  Note this won't work if you
refer to an equation in the main section from an appendix
section since the 1. will appear.  You'll have to skip using
sectioning in the main section.


File: RENUM, Node: Messages, Up: Top, Previous: Hints, Next: Caveats

RENUM gives various messages from time to time, all of them
self-explanatory.  One message that may occur often is
"Lookup on <stuff> failed on pass 2.  Not renumbered."

There are two causes of this message:  either you typed an
equation number (for example) incorrectly or the scan routines
have inadvertently thought you were referring to an equation.

In the first case, you'll have to renumber the mis-typed number
by hand since the number was not recognized and thus not
renumbered.  You can do this on the original or renumbered
versions as long as you realize the number you type in will be
different depending on which version you modify.

The second case is far more common.  The message can be ignored
since nothing was hurt.  You can circumvent this typeout by
modifying your text slightly so the scan rules fail
(*note Thwart:Rules.).  This modification can be done without
affecting the final output of the text formatter.  For example,
$x (0)$ will pass the scan rules as a reference to equation
(0), but $x(0)$ will not and neither will $x ( 0)$.  However,
the final TEX output will be identical in all these cases.


File: RENUM, Node: Caveats, Up: Top, Previous: Messages, Next: Unsure

The main thing to remember is NEVER NEVER renumber anything
yourself.  You can add/delete/move things to your heart's
content, just don't CHANGE anything.  The only thing you might
want to change is an appendix name.  When you do so, be sure:

1) that all the stuff in the appendix is EXPLICITLY numbered
(just do M-X Renumber All in draft mode)

2) that you change all things of the form "...in Appendix A..."
to "...in Appendix B" if you change A to B.

Sectioning--
To refer to something in another section, you must specify that
section exactly: 1.2-1 is NOT the same as 1.2.1.  You'll get
a warning message if this happens (*note warning:messages.) so
don't lose any sleep over it.

Case--
For equations, figures and tables, case is significant.  This is so
\Fig. \botFigure and \topfFig. will get recognized, but
"misfigure" will not.  Case is also significant on the FIRST
pass of M-X Renumber Sections.  This means that % Section will
get renumbered on the first pass, but % section will get
renumbered on the second pass.  This makes it hard to make an
accidental section definition.


File: RENUM, Node: Unsure, Up: Top, Previous: Caveats, Next: Customizing

This node explains how to be 100% that RENUM will not screw you.

Just do M-X Renumber All in draft mode on your existing
correctly numbered manuscript.  Write out the "renumbered" buffer
to some random file.  Then do a :SRCCOM and see what has been
changed.

If the files are identical, you MAY have won; either the
renumber routines agreed with your numbering scheme or didn't
recognize stuff that it should have and just left things alone.
To test the second hypothesis, either select the "Recog" node or
delete one of the items you thought was not being recognized and
compare the "before" and "after" versions.  If they are
different, you have won.

If the orignal and renumbered files do not agree and/or the
RENUM routines complained about something, see the appropriate
node in this menu.

* Menu:

* Messages::		What to do about RENUM warning messages
* Lossage::		What to do if (A.1) got changed to (46)
* Gainage::		What to do if Fig. 5 got changed to Fig. A.1
* Recog:Rules		What to do if things which should be
renumbered weren't and vice-versa


File: RENUM, Node: Lossage, Up: Unsure,  Next: Gainage

If on renumbering, you find that your section indices like
(1.2) and (A.1) got swallowed, you'll have to add sectioning to
your file.  This is accomplished by adding the text "% Section"
<num> at the beginning of each section.  This will cause all NEW
equations, figures, and tables defined in this section to be
numbered with the specified section number followed by a
sequence number.  The sequence number is 1 for the first item in
the section, 2 for the second item, etc.

Example:

For numbers
of the form		Use
-----------	     ----------
(1.2-1)	    % Section 1.2-
(A.2)	    % Section A.
(4)		    % Section

There are two additional controls you can use to make things
come out just right: see the next node.


File: RENUM, Node: Gainage, Up: Unsure, Previous: Lossage

In some cases, you may think RENUM puts in too much information.
There are two distinct classes of "over-numbering."

If you are referring to something in the current
section, you may wish to have the section number omitted
on renumbering so that the full section numbers are only used if
you reference something outside of the current section.
(*note Implicit:Implicit.)

Separate sectioning can be used to cause say, figures to be
sectioned with a different number than equations
(*note SepSects:Sectioning.), e.g., you may want your figure
numbers to be consecutive from the start of the paper, rather
than the start of each section.

File: RENUM, Node: Customizing, Up: Top, Previous: Unsure, Next: Other

RENUM is sufficiently general that almost any amount of
customization can be easily accomplished either in your EMACS
init file or, on a per-file basis, in a local modes list.

* Menu:

* Examples:CustEx	All common customizations are listed here.
* Details:CustDet	If all else fails.


File: RENUM, Node: CustEx, Up: Customizing, Next: CustGen

You don't have to know TECO to customize!
Frequently used customization for:

* Menu:

* General:CustGen	The info in this node is necessary to
understand the other nodes

* Sectioning:CustSect
* Equations:CustEqu
* Outlines:CustOut	From a simple list of items to a
multi-indexed outline


File: RENUM, Node: CustGen, Up: CustEx,  Next: CustSect

Often you don't need to customize, but just to use your beannie.
For example, suppose you use \myequation(4) to generate equation (4)
in the text.  Then you can place a % \eqno(4) on the same line
and no matter where you move the equation, things will happen
right. Similarly, if you use \Majorsection to create a section,
just stick a % Section statement very close by (e.g., on the
same line) so that if they are moved, they are moved as a unit.
Note in the default package, your macro name must end with
"section" since as before, things are done on the second pass of
Renumber Sections.

However, customizing can be very helpful in some cases.
There are three ways of customizing (the exact commands are
listed in the suceeding nodes):

INIT:
You can set RENUM Setup Hook to a macro to run after RENUM
is loaded.  This is good for universal customizing.

Local Modes setting Hook:
You can have you local modes list load Renum Setup Hook with
commands to do customization.  However, your file must be loaded
before RENUM is loaded, or you will have to issue a & Setup
RENUM Library macro.

Local Modes:
This is the preferred way.  The file must be read in AFTER RENUM
is loaded so the variables will supercede RENUMs defaults.  You
can always write your file out to disk and read it back if you
load RENUM midway in your session.  A typical list is:

^L
Local Modes:
Renumber New Section:
Renumber Section New Section:% Section
Mode:Text
Display Matching Paren:1
end:

This list would appear after the \end statement in your TEX manuscript.
RENUM ignores anything after the Local Modes: when it processes
the file so scan rules won't inadvertently get satisfied.


File: RENUM, Node: CustSect, Up: CustEx,  Next: CustEqu

Frequently used customization for sectioning:

Eliminating section numbers from equations, figures, etc.---
For simple manuscripts, you will want to use sections so you can
move sections around, delete/add sections but you don't want all
your figures, equations, and tables to be associated with a
particular section since in the final draft, all of these things
will be numbered consecutively from the beginning of the paper.
If you don't use this customization, you will have to look up
the complete (explicit) number of a figure, etc.  If you do use
the customization, RENUM will act as if all your figures, etc.
are in one giant section whose section number is null.

Renumber New Section:
Renumber Section New Section:% Section

The first line will cause RENUM to fail to find any section
separators (this is a TECO search string which always fails).
The second line will cause only Renumber Sections to work the
way it always did.


File: RENUM, Node: CustEqu, Up: CustEx, Next: CustOut

Frequently used customization for equations:

For other text formatters or even for TEX, you may want to
change the rule of how a first pass equation should be
recognized.  Say we wanted an equation to be recognized by
either "\eqn(" or by "\eqno (".
Then we would use the local modes line:

Equation Search Pass 1::s\eqn(\eqno (

The :s is a TECO search, and the  means "OR".


File: RENUM, Node: CustOut, Up: Customizing

Say you have a list of things or an outline where the index
numbers come just after (spaces and newlines may intervene) some
search string.  Then you can use:

Renumber Section New Section:<search string>

and your outline will be renumbered just like sections are
(*note headings:headings.) when you do a M-X Renumber Sections
You can refer to a section in the outline by using "section" as
usual.

Suppose you use <tab> as your search string.  Then
1. Foo
1.2 Bar in section 5.
5. Bar foo.
will be renumbered correctly.  Try this example if you are
confused.


File: RENUM, Node: CustDet, Up: Customizing,  Next: Other

The user macro in qRENUM Setup Hook (*Note Hook:  Other.)
can modify any of the values set by & Setup Renum Library.
The value of qRenumber Text Formatter contains the name of the
text formatter assumed during RENUM's initialization.

Most customization will involve copying the default values of a
few variables and making a few small changes.  The source is
located in MC:SK;RENUM >.  Or send a :BUG RENUM note explaining
what you want to do and you will be mailed the text to insert in
your init file (or have it inserted).

Often though, changes can be made without having to look at the
source since several variables contain only a text
string or number. These are:

Renumber Draft Mode1=>in draft mode
Renumber Whole File1=>ignore narrowing
Renumber Section SeparatorsText separating indexing levels
Renumber Section Default SeparatorIn case user forgets one at
the end of his new section number.
Renumber New SectionText for identifying new section--case is
significant.  Start with a <NL> if you require it
to start on a new line.
Renumber New ChapterText for identifying new chapter--case is NOT
significant.  Start with a <NL> if you require it
to start on a new line.
Renumber WhitespaceText preceding first significant character
of a figure or table or second pass equation.
Reference Output FilenameBibliography table is stored here when Renumber
References is given an arg of 1
Reference DashText for replacing consecutive numbers (references).
Used by Reference Sort Macro.
Reference Bibliography BeginText denoting start of bibliography.
Reference Bibliography EndText on the 1st line after the last reference
in the bibliography.  Should probably start with <NL>.
Reference Bibliography SeparatorText between references in the bibliography.
The exact point records are broken up is at the beginning
of the line that a search for this text would leave the
pointer.
Reference Auto TextText preceding filename to yank references from.
Must be on the same line as the last character of the
text in q$Reference Bibliography Begin$
Renumber References Default OptionsOptions to use if not specified in
file

Note that there are some variables whose existence will
over-ride the value of the default variables (and therefore are
created in the RENUM Setup Hook macro and won't be found in &
Setup RENUM Library).  These variables are listed in the
footnote (*Note variables:  HookVariables.).


File: RENUM, Node: HookVariables, Up: Top, Previous: Customizing

Variables which the user may set/create/delete in his RENUM
Setup Hook but which won't be found in the source for & Setup
RENUM Library are (<EFTS> means one of {Equation,
Figure, Table, Section}):

Renumber <EFTS> New Section  ---
Contains text identifing a new section. Overrides qRenumber New
Section when it exists. This is so separate section numbering
(or no section numbering) can be used for equations, figures and
tables.  For example, if I want the figures to have a major
section number preceding the generated number, but I want the
equations and tables to have the exact section number, I could
create Renumber Figure New Section, load it with something like
"% Figsection" and then use, e.g., % Section 1. and
% Figsection 1. at the start of major section 1 and use just
% Section 1.1 at the start of the first minor section.  The
asterisk flag preceding the section number works as before
(*Note Sectioning: Sectioning.).  You may wish to use your
own macro for  Section Search Pass 2 so the
other section headings will be looked up and renumbered.
This won't be necessary if you end your new names with
"section" (case is ignored).


File: RENUM, Node: Other, Previous: Customizing, Up: Top, Next: News

You should be able to use all of RENUM's features with any text
formatter without having to do any customization.  Send a BUG
RENUM note if this isn't possible.  However, it will be more
convenient if some things are customized for you, so RENUM has
different rules depending on what formatter you are using.

Customized routines exist for the following formatters:
<NONE>

When & Setup RENUM Library is run (which happens automatically
when the library is loaded), it tries to determine which text
formatter is being used (TEX is assumed if the formatter cannot
be identified since some setup is better than no setup) if no
argument was supplied.  If an argument is supplied, it should be
the name of a text formatter and this formatter will be assumed
(e.g., :i*TJ6MM & Setup RENUM Library).

The name of text formatter is loaded
into qRenumber Text Formatter and  the default
variables are loaded for the text formatter.  This minimizes the
amount of customization one must do.  Then qRENUM Setup Hook
is run if it exists.  This variable, set in the user's init, or
in a local modes list, should contain TECO commands to customize
the particular default variables which are loaded.

Presently, default values only exist for TEX.  If someone would
like to write a hook routine for other text formatters,
I would be happy to incorporate it into the & Setup routine.

The setup routines for a different formatter would involve
only changing the search rule for equations to make it more
convenient for the user since this is the only rule that is
really TEX oriented.  However, this can be accomplished much
easier in a local modes list (*note rules:CustEqu.).


File: RENUM, Node: News, Up: Top, Previous: Top

If you wish to be informed of new changes and new features of
RENUM, add your name to the mailing list on MC or send a bug
message to RENUM.

Summary of important news:


File: RENUM, Node: References, Up: Top, Next: Quick(r)

Using M-X Renumber References:

* Menu:

* Quick(r)::		Concise summary of usage
* Bibliographies::	Concise summary of available features
* Scan(r)::		How a reference is recognized
* AutoRef::		Automatic yanking of needed references
* Sorting::		Bibliography sorting
* All::			Things done for you all the time
* Options::		Ordinal or alphabetic renumbering and
other renumbering options
* Chapters::		How to renumber by chapter
* Info tbl::		Generation of reference statistics


File: RENUM, Node: Quick(r),  Up: References, Next: Scan(r)

Only works in final print mode (*Note Final:Draft.)

Quick summary:
---------------------------------
References:	      [foo68a, bar80a]   are examples.

Bibliography start:   <nl>\references

Auto Referencing:    "from file <filename>" appearing on the same
line as the Bibliography start.  In TEX, you
will need a % before this text so it isn't
printed.

Bibliography entry:  \ <anything> [<name>] <anything> <nl>

Bibliography End:    <nl>\vfill

Chapter sectioning:  <nl>% Chapter <optional text>

Statistics file:     use 1 M-X Renumber All or 1 M-X Renumber References.

Options text:	     "Renumber References Options <num>" must appear
in the first 1000 characters to over-ride default.

Options bits:	      +1 => Alphabetic instead of order of appearance
+2 => Don't replace any text before bibliography
+4 => Don't replace any text after bibliography

Default setting is 0.


File: RENUM, Node: Scan(r), Previous: Quick(r), Up: References, Next: AutoRef

A reference is denoted by <sp>[<letter> (a <nl> counts as a space).

A group of references is a bunch "words" with a comma after each word
except the last which must end with a "]".

For example, [foo67a, Martin-pc, Smith&Jones] will work but
[Foo bar] and [80Smith] will not.


File: RENUM, Node: AutoRef, Previous: Scan(r), Up: References, Next: Sorting

If the text "from file" (qReference Auto Text) appears on
the same line as the \references, the following filename
will be searched for the references appearing in the paper.
Don't put a \vfill at the end of this file.  Any "local"
references will be merged with the automatic references.
Don't duplicate references. For a sample file, see
MC:SK;REFERENCES >.


File: RENUM, Node: Sorting, Previous: AutoRef, Up: References, Next: All

A bibliography begining with <nl>\references (qReference Bibliography
Begin) and ending with <nl>\vfill (qReference Bibliography End)
will be sorted numerically or alphabetically depending on
whether the references in the bibliography have been changed to
numbers or left as names (*Note Options: Options.).  Unused
references will be deleted.

What constitutes a bibliographic "entity" or "record" to be
sorted depends on the contents of qReference Bibliography
Separator (default TEX value is "<NL>\").  The end of one
reference and thus the beginning of the next is gotten by
searching for this string, and then moving the pointer to the
beginning of the line.  Hence, in this case, all reference
records must begin with a "\", end with a <NL>, and have no
"<NL>\" imbedded within the record.

The default sorting routine sorts the bibliographic "records" based
on the number appearing after the first "[" in the record.  Chapter
numbers are ignored.  References left as names will be sorted
alphabetically by the name appearing between the square
brackets.  For TEX, this allows you to specify a macro
to operate on your reference; putting in quotes, changing to italics or
bold, etc.  Example:

\paperref [Foo68a] F. F. Foo| How I did it|
\JACM|6|8|1--3|Mar.|1968|
\book     [Bar80a] B. Bar   |Physics for MIT|Pergammon Press|1968|


File: RENUM, Node: All, Previous: Sorting, Up: References, Next: Options

Besides sorting (previous node) the following are done all the time:

Unused references in the bibliography are deleted.  Hence,
no new references can be defined after the start of the
bibliography.

Case is ignored.

Groups of references are numerically sorted after renumbering
and a -- (qReference Dash) is inserted when there are more
than 2 consecutive numbers, e.g., [a, b, c] becomes [1--3].
Sorting on groups of references are not done if the references
aren't changed to numbers (*Note Options: Options.)

You are informed if there are any references missing from your
bibliography.


File: RENUM, Node: Options, Previous: All, Up: References, Next: Chapters

Each file can specify certain renumbering options if the text
"Renumber References Options <num>" appears somewhere within
the first 1000 characters of the file.  The <num> should be the
number to set the options to.  If the text does not appear,
the options are set to the value of q$Renumber References Default Options$ which defaults to 0.

Bit    <Num>   Action
---   ------   ------
0	+1	off => Renumber the references in order of appearance
on  => Renumber the references alphabetically
1	+2	off => Renumber the references before the bibliography
on  => Leave the references before the bibliography
as names, but still keep track of renumbering
2	+4	off => Renumber the references after the bibliography
on  => Leave the references after the bibliography
as names, but still keep track of renumbering

Example:  Renumber References Options 6 would turn on bits 2 and
1 and leave bit 0 off since 6 is 110 in binary.  This
particular setting looks like a no-op, but it will
build a table which you can look at (*Note Table:Info table.).


File: RENUM, Node: Chapters, Previous: Options, Up: References, Next: Info tbl

You can separate your document into chapters by using
"<nl>% Chapter" (qRenumber New Chapter).  Any text
beginning with a non-blank and ending with a space or <NL>
will be inserted before the generated number.  Each chapter
is processed completely independently.

There is no such thing as an asterisk flag since each chapter is
totally independent.  Use null chapter arguments if you don't
want to insert a chapter number.


File: RENUM, Node: Info tbl, Previous: Chapters, Up: References

If Renumber References is called with an argument of 1, a file
REF TABLE (default contents of q$Reference Ouput Filename$)
is written.  The file contains the references (organized by chapter)
sorted alphabetically and numerically with a histogram of how often
each reference was referenced.  If the references are numbered
alphabetically, only one list per chapter appears.


File: RENUM, Node: Equations, Up: Top, Next: After

Using M-X Renumber Equations:

First pass scan:

"\eqno(" or "("         (case is significant)

(The "(" is provided for people who use \eqalignno).

Second pass scan:

"(" with a digit within the next 3 characters.  The ( must
be preceded by a <sp>, <nl> or -- (which is the contents of
qRenumber Whitespace) and immediately followed by a letter
or a digit.

Getting around the scan rules:

To cause things which are not really equations or references
to equations not to be mistaken for equations, you can either
insert an extra space(s) or {} in an appropriate place.  The
following are NOT equations:  \eqno ( 5);  ( 5); {}(5).  Note
that the last form is useful if you are not in math mode.
Otherwise it is more convenient just to add extra spaces which
are ignored in math mode.  Note in the first two examples, two
spaces are required: one to thwart the first pass scan, and one
to thwart the second pass scan.

See the next node to learn what happens after a number is
recognized.

File: RENUM, Node: Figures, Up: Top, Next: Tables

Using M-X Renumber Figures:

* Menu:

* Scan(f)::		How a figure is recognized
* After::		What happens next


File: RENUM, Node: Scan(f), Up: Figures, Next: After

How a "figure" to be renumbered is recognized.

First pass scan:

Examples are:
xxxFig.  A-3
fooFigs. 3, and 4
Figures 3--4
\Figure 3, 3.4-4, or C.4-5

Second pass scan:

Is same as the first pass scan only a lowercase f must
precede the capital F.  The lower case f is deleted in
final print mode.

On both passes, case is significant.

Detailed description of first pass scan (the second pass
scan is analogous):

If a digit is within 8 characters of the end of the significant
portion of the last figure renumbered, go GET-DIGIT.

Otherwise, search for anything but "f" preceding
"Fig." or "Figs." or "Figure" and search the next 5
characters for a digit.

GET-DIGIT:  move back to after a delimiter (q$Renumber Whitespace$ which is initially <sp><NL> and --).
If had to move back more than 3 characters, search
for the next likely figure.

The pointer is now at the start of something to be renumbered.


File: RENUM, Node: After, Up: Figures

After something matching a scan rule is found, the pointer is at
the start of something to be renumbered.  The end is considered
to be just before two consectutive non-digits.  This text is
looked up in a table and the appropriate things done on the
first or second pass: on the first pass, the text is added to
the table if not already there; on the second pass, if a lookup
fails, that particular text is left unchanged, the user is
notified, and the scan proceeds normally.

If the text looked up contains only digits, implicit input is
assumed and the current section number is tacked on before doing
the lookup.  The current section number is determined by the text
after "% Section " (qRenumber New Section) or the text in
qRenumber Equation New Section if this variable exists (this
is true for the figures, tables, and sections renumber macros if
you use Figure, Table, Section respectively in place of
Equation).

On output, if the section number of the renumbered text is the same
as the current section number, the section number is stripped only if
1) you are in final print mode 2) an asterisk precedes the current
section number in the section definition line.  If you don't have a
dot or a dash after the last digit in section definition line, a dot
(q$Renumber Section Default Separator$) is used for separation when
you run the renumber macros for equations, figures, and tables.


File: RENUM, Node: Tables, Previous: Figures, Up: Top, Next: Headings

Tables are handled just like Figures.

First pass:  Table or Tables
Second pass: fTable or fTables

See the previous node.


File: RENUM, Node: Headings, Up: Top

Using M-X Renumber Sections:

* Menu:

* Scan(s)::		How a section is recognized
* DotConserv::		How a section number gets renumbered


File: RENUM, Node: Scan(s), Up: Headings, Next: DotConserv

First pass scan:       "% Section "    (case is significant)
Second pass:             "section"     (case is ignored)

Examples:
\majorsection 2.3 Overview     % Section 2.3

... we saw in section 1.2 that ...

In the first example, the 2.3 before the "Overview" gets
numbered on the 2nd pass.  The result is that the two
numerical values on this line always coincide, no matter
where in the file this section is moved to.

All numbers referring to a section (NOT an equation, etc.
WITHIN a section) must be typed completely (no implicit
mode).

SUBTLE POINT: If you are a real hacker, you will wonder how
renumbering can be done on pass 1 since the scan rules of the
second pass are a subset of the scan rules of the first pass.
The reason is that when the file is processed section by
section, it is broken off after the word "Section" in the "%
Section" statement. Hence, during the second pass, the "Section"
at the end of the current boundaries doesn't meet the scan rules
since there are no digits after the word "section"--there is
nothing


File: RENUM, Node: DotConserv, Previous: Scan(s), Up: Headings

Sections are renumbered with attention paid to . and
- (q$Renumber Section Separators$) conservation.  In other
words, it renumbers things the way you would by hand.

Specifically, it counts the number of index separators (. or
-) in the next section and the section just renumbered (an
index separator is always assumed at the end of a number
even if not explicitly typed).  If they are the same, then
the last index of the previous number is bumped.  If the new
section contains more dots, a ".1" is suffixed to the
previous number.  If the new number contains less dots, the
macro moves back that many more indices, bumps the number
that is there, and clears the line while preserving the
default separator the user specified.

Examples:

Old Sequence         Renumbered Sequence
---------------      ---------------------

1.2-			1.2-
3.5			1.3
6-2.1			1.3.1
3.			2.
5-			3-
5.5			3-1

If you wish to have a particular section number accepted
at face value, just precede it by a null section number.  This
is useful if you like to skip from say 2.6 to 3.1 instead of to 3.

Section numbers beginning with an alphabetic character will not
be re-lettered.  After the first character, two non-digits signal
the end of the section name (number) as usual.  If a numbered
section appears after a lettered section, it will not get renumbered.
This is because sections are renumbered based on the last section
and if the last section was alphabetic, there are no guidelines.
This tends to be a useful feature if you have sections missing
and want your sections renumbered as you specify.  Simply insert
a % Section will a null section number before the % Section statement
which you want accepted as is.

If you don't have a dot or a dash after the last digit in section
definition line, a dot (q$Renumber Section Default Separator$)
is used for separation when you run the renumber macros for
equations, figures, and tables.  To refer to something in
another section, you must specify that section exactly:
1.2-1 is NOT the same as 1.2.1.  Of course, text after the
last digit is ignored so 1.2.1xx can refer to % Section 1.2.1-.


Tag Table:
File: RENUM, Node:  TOP272
File: RENUM, Node: Brief1608
File: RENUM, Node: Novice4229
File: RENUM, Node: Concepts12455
File: RENUM, Node: Two Pass12905
File: RENUM, Node: Implicit16573
File: RENUM, Node: Insertion17390
File: RENUM, Node: Features18428
File: RENUM, Node: FlexibleInput19217
File: RENUM, Node: Sectioning21581
File: RENUM, Node: Bibliographies24287
File: RENUM, Node: Forward26079
File: RENUM, Node: Draft28150
File: RENUM, Node: Suffix30536
File: RENUM, Node: Narrowing31073
File: RENUM, Node: Commands31628
File: RENUM, Node: Rules32581
File: RENUM, Node: Examples33718
File: RENUM, Node: Simple33979
File: RENUM, Node: Hairy34839
File: RENUM, Node: Hints44514
File: RENUM, Node: Messages45200
File: RENUM, Node: Caveats46434
File: RENUM, Node: Unsure47698
File: RENUM, Node: Lossage48868
File: RENUM, Node: Gainage49688
File: RENUM, Node: CustEx50775
File: RENUM, Node: CustGen51067
File: RENUM, Node: CustSect52842
File: RENUM, Node: CustEqu53926
File: RENUM, Node: CustDet54363
File: RENUM, Node: HookVariables56956
File: RENUM, Node: Other58259
File: RENUM, Node: News60043
File: RENUM, Node: References60282
File: RENUM, Node: Quick(r)60837
File: RENUM, Node: Scan(r)61881
File: RENUM, Node: AutoRef62250
File: RENUM, Node: Sorting62704
File: RENUM, Node: All64171
File: RENUM, Node: Options64865
File: RENUM, Node: Chapters66052
File: RENUM, Node: Info tbl66573
File: RENUM, Node: Equations67027
File: RENUM, Node: Scan(f)68294
File: RENUM, Node: After69369
File: RENUM, Node: Tables70843
File: RENUM, Node: Headings71053
File: RENUM, Node: Scan(s)71235
File: RENUM, Node: DotConserv72388

End Tag Table

; Local Modes: ::
; Auto Fill Mode:1 ::
; Find File Process Options:1 ::
; Fill Column:64 ::
