summaryrefslogtreecommitdiff
path: root/indexing/forindex/docs/forindex.html
diff options
context:
space:
mode:
Diffstat (limited to 'indexing/forindex/docs/forindex.html')
-rw-r--r--indexing/forindex/docs/forindex.html457
1 files changed, 457 insertions, 0 deletions
diff --git a/indexing/forindex/docs/forindex.html b/indexing/forindex/docs/forindex.html
new file mode 100644
index 0000000000..900796d4bb
--- /dev/null
+++ b/indexing/forindex/docs/forindex.html
@@ -0,0 +1,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>&#92;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>&#92;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>&#92;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>&#92;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 &lt;<TT><A NAME="tex2html12"
+ HREF="ftpmaint@alan.smcvt.edu">ftpmaint@alan.smcvt.edu</A></TT>&gt; 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 &#169; 2005
+<BR>
+Guido Milanese &lt;<TT><A NAME="tex2html13"
+ HREF="guido.milanese@unicatt.it">guido.milanese@unicatt.it</A></TT>&gt;
+<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 &#169; 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 &#169; 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>