summaryrefslogtreecommitdiff
path: root/support/orderrefs/INSTALL
blob: 48db881804e64693cfa21bb4b3c68c565f24f8b7 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
            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 (collins@phys.psu.edu)
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.