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
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<!--Converted with LaTeX2HTML 2002-2-1 (1.70)
original version by: Nikos Drakos, CBLU, University of Leeds
* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>The forindex utilities Version 0.1</TITLE>
<META NAME="description" CONTENT="The forindex utilities Version 0.1">
<META NAME="keywords" CONTENT="forindex">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="Generator" CONTENT="LaTeX2HTML v2002-2-1">
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
<LINK REL="STYLESHEET" HREF="forindex.css">
</HEAD>
<BODY >
<P>
<P>
<P>
<H1 ALIGN="CENTER">The forindex utilities
<BR>
Version 0.1</H1>
<DIV>
<P ALIGN="CENTER"><STRONG>Guido Milanese</STRONG></P>
<P ALIGN="CENTER"><I> <TT><A NAME="tex2html1"
HREF="guido.milanese@unicatt.it">guido.milanese@unicatt.it</A></TT></I></P>
</DIV>
<P>
<P>
<H3>Abstract:</H3>
<DIV>
Making a good index is a very important part in the process
of writing a document, particularly books and manuals. Entering data
manually can be a very long process; although a certain amount of
data must be entered manually, some tasks can be performed automatically,
e.g. an index of geographical names or other trivial tasks. This task
can be achieved using the program <I>doindex</I>, that prepares
a file to be processed by <I>makeindex</I>. Another useful feature
is to remove all the <TT>\index</TT> entries in a L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X
file, obtaining a clean file with no indexing (program <I>cleanindex</I>).
The programs are written in Snobol4; the only requirement is to install
the interpreter. For Windows, a standalone file compiled with Spitbol
is also provided, and the programs can be run without the need of
an external interpreter.
</DIV>
<P>
<BR>
<H2><A NAME="SECTION00010000000000000000">
Contents</A>
</H2>
<!--Table of Contents-->
<UL>
<LI><A NAME="tex2html29"
HREF="forindex.html#SECTION00020000000000000000">1 The programs</A>
<UL>
<LI><A NAME="tex2html30"
HREF="forindex.html#SECTION00021000000000000000">1.1 The program doindex</A>
<LI><A NAME="tex2html31"
HREF="forindex.html#SECTION00022000000000000000">1.2 The program cleanindex</A>
</UL>
<BR>
<LI><A NAME="tex2html32"
HREF="forindex.html#SECTION00030000000000000000">2 Installation</A>
<UL>
<LI><A NAME="tex2html33"
HREF="forindex.html#SECTION00031000000000000000">2.1 GNU/Linux and other *nix systems</A>
<LI><A NAME="tex2html34"
HREF="forindex.html#SECTION00032000000000000000">2.2 Windows</A>
<LI><A NAME="tex2html35"
HREF="forindex.html#SECTION00033000000000000000">2.3 Windows from source</A>
<LI><A NAME="tex2html36"
HREF="forindex.html#SECTION00034000000000000000">2.4 Cygwin</A>
<LI><A NAME="tex2html37"
HREF="forindex.html#SECTION00035000000000000000">2.5 Macintosh</A>
</UL>
<BR>
<LI><A NAME="tex2html38"
HREF="forindex.html#SECTION00040000000000000000">3 Test files</A>
<LI><A NAME="tex2html39"
HREF="forindex.html#SECTION00050000000000000000">4 Bugs and TODO</A>
<LI><A NAME="tex2html40"
HREF="forindex.html#SECTION00060000000000000000">5 Acknowledgements</A>
<LI><A NAME="tex2html41"
HREF="forindex.html#SECTION00070000000000000000">6 Author, copyright, license, disclaimer</A>
</UL>
<!--End of Table of Contents-->
<P>
<H1><A NAME="SECTION00020000000000000000">
1 The programs</A>
</H1>
<P>
<H2><A NAME="SECTION00021000000000000000">
1.1 The program <I>doindex</I></A>
</H2>
<P>
The programs <I>doindex</I> reads a L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X file, using a list
file, and enters index entries in the file according to this list.
Previously entered index entries are left unchanged, making it possible
to add further indexing to an already indexed file.
<P>
The input L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X file may have extension <TT>tex</TT> or <TT>latex</TT>,
both uppercase and lowercase (not mixed as in <TT>Tex</TT>).
<P>
The list file is meant to contain all the words to be indexed. It
must have exactly the extension <TT>wls</TT>. Sub-entries are identified
with the separator character '/'. See <I>test.wls</I> as example:
<P><PRE>
animals
dogs/animals
cats
house/nouns/english/languages
sleeping@sleep
évita/Italian/foreign words
ça/French/foreign words
drücken/German/foreign words
</PRE>
No particular order in this file is required. Some users will prefer
alphabetical order, others different orders, so the programs has no
requirements concerning order/sort in this file. Entries as <TT>sleeping@sleep</TT>
use the standard <I>makeindex</I> syntax and are left unchanged.
The ``logic'' of this syntax is opposite to the internal logic
of <I>makeindex</I>, that is - I think - very clever at the stage
of typesetting an index, but not at the stage of designing an index.
``A dog is an animal'' (<TT>dog/animal</TT> in my syntax) seems
to me to be more natural than ``Among animals there are dogs''
(<TT>animals!dogs</TT> in the <I>makeindex</I> syntax). The L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X
file produced by <I>doindex</I> follows, of course, the <I>makeindex</I>
conventions.
<P>
The original L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X file is left unchanged. A new file will be written,
identified by <I>-ind</I>. For example, from <I>file.tex</I> you
will get <I>file-ind.tex</I>. Of course, you'll have to run <I>makeindex</I>
as usual.
<P>
The purpose of the program is similar to what is provided by the program
<I>ixgen</I> (<TT><A NAME="tex2html2"
HREF="http://www.iit.upco.es/~oscar/ixgen/">http://www.iit.upco.es/~oscar/ixgen/</A></TT>)
written by O<SMALL>SCAR </SMALL>L<SMALL>OPEZ</SMALL> (<TT><A NAME="tex2html3"
HREF="oscar@iit.upco.es">oscar@iit.upco.es</A></TT>), but <I>forindex</I>
was designed to be a bit more flexible.
<P>
<H2><A NAME="SECTION00022000000000000000">
1.2 The program <I>cleanindex</I></A>
</H2>
<P>
The program <I>cleanindex</I> removes <I>\index</I>
sequences from a L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X file. The program can be used e.g. if a
user is not happy with the indexing of a file and wants to start it
over again.
<P>
The input file may have extension <TT>tex</TT> or <TT>latex</TT>,
both uppercase and lowercase.
<P>
The original file is left unchanged. A new file will be written, identified
by <I>-noind</I>. For example, from <I>file.tex</I> you will get
<I>file-noind.tex</I>. In this file, lines concerning <I>makeindex</I>
will be left but commented, in order to avoid an empty <I>Contents</I>
section in the output. You can uncomment the lines as soon as you
want to reindex the file again.
<P>
<H1><A NAME="SECTION00030000000000000000">
2 Installation</A>
</H1>
<P>
<H2><A NAME="SECTION00031000000000000000">
2.1 GNU/Linux and other *nix systems</A>
</H2>
<P>
<OL>
<LI>Install <I>snobol4</I> from <TT><A NAME="tex2html4"
HREF="http://www.snobol4.org">http://www.snobol4.org</A></TT>. This
is Philip Budne's CSNOBOL implementation. You need a <TT>c</TT> compiler
to compile the interpreter; it's normally a very quick and easy process.
</LI>
<LI>Make sure <I>snobol4</I> is in your PATH or make a symbolic link.
</LI>
<LI>Copy all the files from the source directory in a suitable directory
(you do not need the <TT>bat</TT> files, provided for Windows, and
can safely remove them).
</LI>
<LI>Make executables the scripts (<I>doindex</I> and <I>cleanindex</I>
with no extensions), e.g. <TT>chmod +x doindex</TT>
</LI>
<LI>Run the scripts as follows:
<P>
<OL>
<LI>- to index a text: <TT>./doindex file.tex</TT>
</LI>
<LI>If you want to exclude words with accents: <TT>./doindex file.tex
-noacc</TT>
</LI>
<LI>- to remove <I>\index</I> sequences: <TT>./cleanindex
file.tex</TT>
</LI>
<LI>If the current directory is in your PATH, you do not need <TT>./</TT>
before the script name.
<BR>
<P>
</LI>
</OL>
</LI>
</OL>
<P>
<H2><A NAME="SECTION00032000000000000000">
2.2 Windows</A>
</H2>
<P>
The package offers exe files compiled with Spitbol (see (<TT><A NAME="tex2html5"
HREF="http://www.snobol4.com">http://www.snobol4.com</A></TT>).
Make a directory and copy all the file in the bin/windows directory.
There must be two <TT>*.exe</TT> files and the two <TT>test.*</TT>
files.
<P>
Run the programs as follows:
<P>
- to index a text: <TT>doindex file.tex</TT>
<P>
If you want to exclude words with accents: <TT>doindex file.tex
-noacc</TT>. Accents must be encoded using the <I>latin1</I> encoding
(see the list of Todo).
<P>
- to remove <TT>\index</TT> sequences: <TT>cleanindex
file.tex</TT>
<P>
<H2><A NAME="SECTION00033000000000000000">
2.3 Windows from source</A>
</H2>
<P>
Basically, follow the same directions given about GNU/Linux, but make
sure to use the <TT>bat</TT> files and to install the Windows version
of the interpreter. Before using the sources, that are in Unix format,
use a script to translate from Unix to Dos-Windows format. If you
do not have such a script, open the files with a text editor and save
the sources in Windows-Dos format. This can be done reading and saving
each file with the DOS <I>edit</I> program, with <I>vim</I> or
any other editor able to deal with different file formats. Do not
alter the files if you are not sure of what you are doing. Please
(1) do not use a word processor (as Word or similar) but a simple
text editor and (2) make sure to leave the encoding of file <I>acc.inc</I>
to <I>ISO-8859-1</I> or <I>8859-15</I>, not to plain DOS or Unicode.
<P>
<H2><A NAME="SECTION00034000000000000000">
2.4 Cygwin</A>
</H2>
<P>
I suggest to follow the same directions given for GNU/Linux, but the
EXE files provided for native Windows can be used anyway if preferred.
<P>
<H2><A NAME="SECTION00035000000000000000">
2.5 Macintosh</A>
</H2>
<P>
Not yet tested (I do not have a Mac right now). It's in the TODO list.
<P>
<H1><A NAME="SECTION00040000000000000000">
3 Test files</A>
</H1>
<P>
Please test the program on <I>test.tex</I> and <I>test.wls</I>.
The produced file will be called <I>test-ind.tex</I> if you use
<I>doindex</I>, <I>test-noind.tex</I> if you use <I>cleanindex</I>.
<P>
<H1><A NAME="SECTION00050000000000000000">
4 Bugs and TODO</A>
</H1>
<P>
The program does not support Unicode files. At this moment, most L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X
users are still using latin1, but the situation is rapidly changing.
<P>
List of features that I would like to add:
<P>
<OL>
<LI>Index also included files.
</LI>
<LI>Add typographical styles, such as italics for the most important locations
of a word.
</LI>
<LI>Add support for several indexes (particularly with class <I>memoir</I>)
</LI>
<LI>Add an option to generate a rough index for all the words.
</LI>
<LI>Add a support to index words listed with regular expressions. E.g.
<TT>read*</TT> should index <I>read</I>, <I>reads</I>, <I>reading</I>,
<I>readings</I>, all under the same heading <I>read</I>.
</LI>
<LI>Make possible to use another separator for the list file, e.g. a simple
blank or other char preferred by user.
</LI>
<LI>Test the programs on a Mac.
</LI>
<LI>Add Unicode support.
</LI>
</OL>
<P>
<H1><A NAME="SECTION00060000000000000000">
5 Acknowledgements</A>
</H1>
<P>
The program <I>ixgen</I> gave me the idea of <I>forindex</I>.
Many thanks to O<SMALL>SCAR </SMALL>L<SMALL>OPEZ</SMALL> for this very good program.
<P>
Some questions sent by C<SMALL>ARLO </SMALL>P<SMALL>ELLEGRINO</SMALL> (Modena University,
Italy) gave me the idea of transforming a very rudimentary script
into a general purpose utility. M<SMALL>AURIZIO </SMALL>L<SMALL>ORETI</SMALL> (Padua University,
Italy) sent me very useful remarks on the problems of automatical
generations of indexes, which I made use of in the introduction to
this text.
<P>
My warmest thanks to P<SMALL>HIL </SMALL>B<SMALL>UDNE</SMALL> (<TT><A NAME="tex2html6"
HREF="phil@ultimate.com">phil@ultimate.com</A></TT>)
for making his excellent CSNOBOL available. Many thanks to the community
of Snobol users, particularly to the members of the list <TT><A NAME="tex2html7"
HREF="snobol4@mercury.dsu.edu">snobol4@mercury.dsu.edu</A></TT>,
and, among them, to G<SMALL>ORDON </SMALL>P<SMALL>ETERSON</SMALL> (<TT><A NAME="tex2html8"
HREF="http://personal.terabites.com/">http://personal.terabites.com/</A></TT>),
M<SMALL>ICHAEL </SMALL>R<SMALL>ADOW</SMALL> (<TT><A NAME="tex2html9"
HREF="mikeradow@yahoo.com">mikeradow@yahoo.com</A></TT>), G<SMALL>REGORY
</SMALL>L. W<SMALL>HITE</SMALL> (<TT><A NAME="tex2html10"
HREF="glwhite@netconnect.com.au">glwhite@netconnect.com.au</A></TT>) and to R<SMALL>AFAL
</SMALL>M. S<SMALL>ULEJMAN</SMALL> (<TT><A NAME="tex2html11"
HREF="rafal@engelsinfo.de">rafal@engelsinfo.de</A></TT>) whose <I>vim</I> syntax
files are a daily blessing.
<P>
Thanks to Jim Hefferon <<TT><A NAME="tex2html12"
HREF="ftpmaint@alan.smcvt.edu">ftpmaint@alan.smcvt.edu</A></TT>> who pointed
out that the original name of the package, <I>4index</I>, was not
acceptable due to XML syntax rules.
<P>
<H1><A NAME="SECTION00070000000000000000">
6 Author, copyright, license, disclaimer</A>
</H1>
<P>
This program is Copyright © 2005
<BR>
Guido Milanese <<TT><A NAME="tex2html13"
HREF="guido.milanese@unicatt.it">guido.milanese@unicatt.it</A></TT>>
<BR>
under the terms of the GNU General Public License.
<BR>
<P>
<PRE>
This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General Public License for more details.
If you do not have a copy of the GNU General Public License write to the Free
Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
If the author of this software was too lazy to include the full GPL text along
with the code, you can find it at: http://www.gnu.org/copyleft/gpl.html.
</PRE>
<H1><A NAME="SECTION00080000000000000000">
About this document ...</A>
</H1>
<STRONG>The forindex utilities
<BR>
Version 0.1</STRONG><P>
This document was generated using the
<A HREF="http://www.latex2html.org/"><STRONG>LaTeX</STRONG>2<tt>HTML</tt></A> translator Version 2002-2-1 (1.70)
<P>
Copyright © 1993, 1994, 1995, 1996,
<A HREF="http://cbl.leeds.ac.uk/nikos/personal.html">Nikos Drakos</A>,
Computer Based Learning Unit, University of Leeds.
<BR>
Copyright © 1997, 1998, 1999,
<A HREF="http://www.maths.mq.edu.au/~ross/">Ross Moore</A>,
Mathematics Department, Macquarie University, Sydney.
<P>
The command line arguments were: <BR>
<STRONG>latex2html</STRONG> <TT>-no_subdir -split 0 -show_section_numbers /tmp/lyx_tmpdir3312NEVskb/lyx_tmpbuf0/forindex.tex</TT>
<P>
The translation was initiated by guido on 2005-01-29<HR>
<ADDRESS>
<A HREF="http://www.arsantiqua.org">Guido Milanese</A>,
2005-01-29
</ADDRESS>
</BODY>
</HTML>
|
