INSTALLING orderrefs

INSTALLING orderrefs
====================
(Version 1.00, 2 June 2004)

John Collins
Physics Department
Penn State University
104 Davey Lab, Box 208
University Park PA 16802
U.S.A.

http://www.phys.psu.edu/~collins/
collins at phys.psu.edu

Orderrefs is a perl script to reorder the references in the
bibliography of a LaTeX document according to their order of
citation.

Orderrefs can be installed on any system that has a working
installation of perl and TeX/LaTeX. It has been developed and tested
and used on both UNIX and MS Windows; but the prerequisite software
is freely available for almost all modern operating systems and many
old ones.

On all systems, the prequisites are

a. A working installation of Perl at version 5 or higher. (See
http://www.cpan.org/ if you don't have perl installed on your
system.) This is needed to run orderrefs.

b. A working installation of TeX and LaTeX. (See http://www.ctan.org/ if
you don't have one.) Orderrefs.pl will run without TeX/LaTeX, but
there would then normally be no point in using it.

Installing on UNIX/LINUX
========================

Installation can either be made system-wide or by an individual user.
Power users can modify these as appropriate.

1. Make sure you have working installations of Perl and TeX/LaTeX.

2. Put the file orderrefs.pl in a directory for executable files.
For example, for a system-wide installation, you could put it in
/usr/local/bin. An individual user can install the file in any
suitable directory to which he/she has access.

3. Rename this file to orderrefs.

4. Make sure orderrefs is executable, e.g., by using chmod suitably.

5. (Optional) Copy the file orderrefs.1 to an appropriate directory
for man pages, e.g., /usr/local/man/man1/.

6. Test the installation: see step 8 of the instructions for
installation under MS-Windows.

Installing on MS-Windows
========================

Installation can either be made system-wide or by an individual user.
Power users can modify these as appropriate.

1. Make sure you have working installations of Perl and TeX/LaTeX.

2. If necessary, unpack the distribution. [Note: It is a good idea
to unpack the files so that they have the correct line-end
characters for MS-Windows. For example, if you use unzip on
orderrefs.zip, the command unzip -a orderrefs.zip should do the
job. If you don't do this conversion, it probably won't matter,
since much software, including perl, MikTeX and emacs, handles
MS-Windows and UNIX line ends equally well.]

3. Copy the files orderrefs.pl and orderrefs.bat to a suitable
directory (your choice). One possibility is a directory
C:\local\bin. You will need to make sure this directory in the
search path for executable files --- see the next step.

4. If the directory in the previous step is NOT already in the search
path for executable files, arrange for this:

a. Suppose this directory is named C:\local\bin, then
in Windows 95, 98 and ME, you should add a line

PATH %PATH%;C:\local\bin

to the end of the C:\AUTOEXEC.BAT file. (The last part of this
line is the full name of the directory from step 2.) This change
will take effect the next time you reboot.

b. In Windows NT (and similar systems, like Win XP), there is an
item in the Control Panel to achieve the same effect.

c. For other versions of MS-Windows, one of the above is probably
appropriate. You'll need to find out from documentation for your
system.

5. (Optional) Copy documentation file(s) to a suitable directory.
The only requirement on the directory is your convenience: some
convenient place to look up documentation. The relevant files are
orderrefs.txt which is a pure ASCII text file, and orderrefs.ps
which is a postscript file.

6. Check whether perl is in the search path for executables. (E.g., from
the MSDOS command-line prompt, try the command perl --version.) If
perl is not in the search path, then modify the first line of
orderrefs.bat (which you installed at step 2) by replacing the command
perl by the full path name for perl, e.g., C:\perl\bin\perl.exe.

7. If you made any changes to the path at step 4, you should, under
Win 95/98/ME, reboot so that the changes take effect. Under Win
NT/2000/XP, logging out and logging back in is sufficient.

8. To test the installation, start a command-line prompt window and
then:

a. Run the command

orderrefs

This should show you the version number of orderrefs, and brief
information on using it, etc. If this works, orderrefs is
accessible. If not, you will have to figure out what did not
work in the previous steps.

b. Then change to a directory where you have a good LaTeX file
that contains a bibliography. Suppose the file is paper.tex.
Run

latex paper

so that a file paper.aux is generated. (Of course, if
paper.aux already exists, and is up-to-date, you can omit this
step.)

c. Run the command

orderrefs paper

If the references are in order, you will see a message to this
effect. If not, orderrefs will create a new version of
paper.tex with correctly ordered references, and make a backup
version of the file under the name paper.tex.bak

d. If the above works, you are done. If not, you will have to figure
out what is wrong, and correct it.

9. It is possible to arrange to run orderrefs from a graphical user
interface (e.g., to right-click on the icon for a LaTeX file and
select a reorder item from the menu). You will have to figure out
how to do this from operating system documentation.

Other systems
=============

You are on your own. The instructions for UNIX/LINUX and MS-Windows
should help you to see what to do. Let me know ([email protected])
what happens, so that I can update this instructions and possibly orderrefs
as well.

Concerning portability, the only possible problem that I know of is

a. The backup files created by orderefs have names like
paper.tex.bak, which have two periods in them. Such filenames are
not allowed on some old operating systems. You will have to
modify the script to overcome this problem.