summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/splitindex/install.txt
blob: 109b05f43b8717e92c969ccc12cf377ff3823711 (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
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
		SplitIndex Installation Guide

			   2016-02-18


INTRODUCTION
============

If you know how to install LaTeX packages and how to install binary
programs, just do it. If you don't know, read the following. If you
are using a system which provides a bash and gnu tools, you may try
install.sh for installation. See

    ./install.sh --help

for more information.

But you may also try the following step by step installation:

HOW TO INSTALL SplitIndex FROM A TDS-ARCHIVE
============================================

Some distributors may use a SplitIndex TDS-archive for distributing
SplitIndex.  SplitIndex TDS-archive may be installed very easily.
The SplitIndex TDS-archive has following contents:

  +- doc/
  |  +- latex/
  |  |  +- splitindex/
  |  |     +- README
  |  |     +- install.txt
  |  |     +- manifest.txt
  |  |     +- splitidx.pdf
  |  +- man/
  |     +- man1/
  |        +- splitindex.1
  +- tex/
  |  +- generic/
  |     +- splitindex/
  |        +- splitindex.tex
  |  +- latex/
  |     +- splitindex/
  |        +- splitidx.sty
  +- scripts/
  |  +- splitindex/
  |     +- splitindex.pl
  |     +- splitindex.tlu
  |     +- splitindex_main.tlu
  +- source/
     +- latex/
        +- splitindex/
           +- install.sh
           +- splitidx.dtx
           +- splitidx.ins
           +- splitindex.c
           +- splitindex.java

If you don't have such an archive, continue reading at 1st step of ``HOW TO
GENERATE THE splitidx PACKAGE''.  If you have such an archive - we will use
the file name ``splitindex.tds.zip'' in the following - you may continue 
with:

A)   Have a look where your LaTeX Distribution searchs for files. 
     With TeX Live you can ask kpathsea for this, e.g. using a unix
     shell:

	kpsexpand \$TEXMFLOCAL

     to use the local texmf tree or:

	kpsexpand \$TEXMFHOME

     to use your private texmf tree. Following uses ``<TEXMF>'' to 
     be a synonym for the texmf tree you want to use.

B)   Extract splitindex.tds.zip at <TEXMF> with all the subdirectories of
     the splitindex.tds.zip but without generating additional 
     subdirectories, e.g., using:

        cd <TEXMF>
	unzip splitindex.tds.zip

     or any other zip extraction programm.

C)   Continue with 5th or 6th step at ``HOW TO INSTALL THE EXECUTABLES''.

D)   Call the program, which is used to update the filename data
     base, e.g., texhash or mktexlsr if you are using teTeX/TeX Live.

E)   Read ``HOW TO TEST YOUR INSTALLATION'' at the end of this 
     documentation.


HOW TO GENERATE THE splitidx PACKAGE
====================================

You need this only, if you don't have a SplitIndex TDS-archive, but want
to install SplitIndex from a basic SplitIndex distribution.  If you have 
already done the SplitIndex TDS-archive installation discribed above, you
should skip this section.

1st) Process splitidx.ins with TeX or LaTeX, e.g. using the following
     input at a command shell (e.g. bash or command.com):

	latex splitidx.ins

     Maybe you'll be asked, if you want to overwrite existing files. 
     Answer this question with yes.

2nd) Have a look where your LaTeX Distribution searchs for files. 
     With TeX Live you can ask kpathsea for this, e.g. using a unix
     shell:

	kpsexpand \$TEXMFLOCAL

     to use the local texmf tree or:

	kpsexpand \$TEXMFHOME

     to use your private texmf tree. Following uses ``<TEXMF>'' to 
     be a synonym for the texmf tree you want to use.

3rd) Create folder <TEXMF>/tex/latex/splitindex (at Windows:
     <TEXMF>\tex\latex\splitindex), if it doesn't exist. Copy 
     splitidx.sty to this folder.

4th) Create folder <TEXMF>/scripts/splitindex (at Windows:
     <TEXMF>\scripts\latex\splitindex), if it doesn't exist. Copy
     splitindex.pl, splitindex.tlu and splitindex_main.tlu to this folder.

5th) Call the program, which is used to update the filename data
     base, e.g. texhash or mktexlsr if you are using teTeX/TeX Live.


HOW TO INSTALL THE EXECUTABLE
=============================

You need only one of the executables splitindex.pl or splitindex.tlu.
I recommend to use splitindex.pl, but if your system doesn't provide perl
but TeXLua, you may use splitindex.tlu instead.

To install splitindex.pl or splitindex.tlu on Windows:

5th) Rename a copy of runscript.exe into splitindex.exe and copy it
     into the binary folder of your TeX installation. You may simply search
     for runscript.exe itself to find the binary folder.

To install splitindex.pl or splitindex.tlu on Linux, OpenBSD, OS X,
OpenSolaris etc.:

6th) Copy splitindex.pl or splitindex.tlu to the binary folder of your TeX
     installation and rename it into splitindex. You may simply do a
     `which pdflatex' to find the binary folder. Make splitindex executable
     for everybody using e.g. `chmod a+x splitindex'.


HOW TO GET A REAL BINARY
========================

If you don't like scripts, you may make a real binary from the C source file
splitindex.c and install that instead of the script. If your getopt library
doesn't support long options, you may define NO_LONGOPT. In this case the code
for long options won't be compiled. I recommend to use either the perl or the
TeXLua script.


HOW TO GENERATE THE MANUAL
==========================

7th) process splitidx.dtx with LaTeX to generate the user manual of
     splitidx and SplitIndex, e.g. using the following input at a 
     command shell:

	pdflatex splitidx.dtx
	pdflatex splitidx.dtx
	mkindex splitidx
	pdflatex splitidx.dtx

     or (if you do not have the mkindex script):

	pdflatex splitidx.dtx
	pdflatex splitidx.dtx
	makeindex -s gind.ist splitidx
	makeindex -s gglo.ist -o splitidx.gls splitidx.glo
	pdflatex splitidx.dtx

     You may print the resulting splitidx.pdf.

8th) read the manual you produced at 7th step.


HOW TO TEST YOUR INSTALLATION
=============================

Use the following LaTeX source to test the installation. See
splitidx.pdf to learn to know how to do this.

\documentclass{article} %  We use \Class{article} class ...
\usepackage{splitidx} % ... and the \Package{splitidx} package
\makeindex %  And we want index generation
\usepackage{hyperref}
%  We define 4 indices:
\newindex[General Index]{idx} %  Name and shortcut of the 1st index
\newindex[Index of Animals]{ani} %  ... 2nd index
\newindex[Index of Fruits]{fru} %  ... 3rd index
\newindex[Index of Vegetables]{veg} % ... \dots\ 4th index

\begin{document}
Apples\sindex[fru]{apple} %  an entry to fru index
and oranges\sindex[fru]{orange} %  an entry to fru index
are fruits\sindex{fruits}. %  an implicite entry to idx index
Tomatos\sindex[veg]{tomato} %  an entry to veg index
are vegetables\index{vegetables}. %  an implicite entry to idx index
Cats\sindex[ani]{cat} %  an entry to ani index
are animals\sindex[idx]{animals}. %  an explicite entry to idx index

\twocolumn[%
 \section*{Indices}%
 \markboth{Indices}{Indices}%
]
\printsubindex* %  print all indices
\end{document}