summaryrefslogtreecommitdiff
path: root/indexing/forindex/docs
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /indexing/forindex/docs
Initial commit
Diffstat (limited to 'indexing/forindex/docs')
-rw-r--r--indexing/forindex/docs/forindex.html457
-rw-r--r--indexing/forindex/docs/forindex.lyx922
-rw-r--r--indexing/forindex/docs/forindex.pdfbin0 -> 351370 bytes
-rw-r--r--indexing/forindex/docs/forindex.tex250
4 files changed, 1629 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>
diff --git a/indexing/forindex/docs/forindex.lyx b/indexing/forindex/docs/forindex.lyx
new file mode 100644
index 0000000000..1b4146aa0d
--- /dev/null
+++ b/indexing/forindex/docs/forindex.lyx
@@ -0,0 +1,922 @@
+#LyX 1.3 created this file. For more info see http://www.lyx.org/
+\lyxformat 221
+\textclass article
+\begin_preamble
+\usepackage{url}
+\end_preamble
+\language english
+\inputencoding latin1
+\fontscheme default
+\graphics default
+\paperfontsize default
+\spacing single
+\papersize a4paper
+\paperpackage a4
+\use_geometry 0
+\use_amsmath 0
+\use_natbib 0
+\use_numerical_citations 0
+\paperorientation portrait
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\defskip medskip
+\quotes_language english
+\quotes_times 2
+\papercolumns 1
+\papersides 1
+\paperpagestyle default
+
+\layout Title
+
+The forindex utilities
+\newline
+ Version 0.1
+\layout Author
+
+Guido Milanese
+\newline
+
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+url{guido.milanese@unicatt.it}
+\end_inset
+
+
+\layout Standard
+
+
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+thispagestyle{empty}
+\end_inset
+
+
+\layout Date
+
+January 2005
+\layout Abstract
+\noindent
+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
+\family sans
+doindex
+\family default
+, that prepares a file to be processed by
+\family sans
+makeindex
+\family default
+.
+ Another useful feature is to remove all the
+\family typewriter
+
+\backslash
+index
+\family default
+ entries in a LaTeX file, obtaining a clean file with no indexing (program
+
+\family sans
+cleanindex
+\family default
+).
+ 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.
+
+\layout Standard
+
+
+\begin_inset LatexCommand \tableofcontents{}
+
+\end_inset
+
+
+\layout Section
+
+The programs
+\layout Subsection
+
+The program
+\family sans
+doindex
+\layout Standard
+
+The programs
+\family sans
+doindex
+\family default
+ reads a LaTeX 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.
+\layout Standard
+
+The input LaTeX file may have extension
+\family typewriter
+tex
+\family default
+ or
+\family typewriter
+latex
+\family default
+, both uppercase and lowercase (not mixed as in
+\family typewriter
+Tex
+\family default
+).
+\layout Standard
+
+The list file is meant to contain all the words to be indexed.
+ It must have exactly the extension
+\family typewriter
+wls
+\family default
+.
+ Sub-entries are identified with the separator character '/'.
+ See
+\family sans
+test.wls
+\family default
+ as example:
+\layout Quote
+
+
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+begin{verbatim}
+\newline
+ animals
+\newline
+ dogs/animals
+\newline
+ cats
+\newline
+ house/nouns/english/languages
+\newline
+ sleeping@sleep
+\newline
+ évita/Italian/foreign words
+\newline
+ ça/French/foreign words
+\newline
+ drücken/German/foreign words
+\newline
+
+\backslash
+end{verbatim}
+\end_inset
+
+
+\layout Standard
+
+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
+\family typewriter
+sleeping@sleep
+\family default
+ use the standard
+\family sans
+makeindex
+\family default
+ syntax and are left unchanged.
+ The
+\begin_inset Quotes eld
+\end_inset
+
+logic
+\begin_inset Quotes erd
+\end_inset
+
+ of this syntax is opposite to the internal logic of
+\family sans
+makeindex
+\family default
+, that is -- I think -- very clever at the stage of typesetting an index,
+ but not at the stage of designing an index.
+
+\begin_inset Quotes eld
+\end_inset
+
+A dog is an animal
+\begin_inset Quotes erd
+\end_inset
+
+ (
+\family typewriter
+dog/animal
+\family default
+ in my syntax) seems to me to be more natural than
+\begin_inset Quotes eld
+\end_inset
+
+Among animals there are dogs
+\begin_inset Quotes erd
+\end_inset
+
+ (
+\family typewriter
+animals!dogs
+\family default
+ in the
+\family sans
+makeindex
+\family default
+ syntax).
+ The LaTeX file produced by
+\family sans
+doindex
+\family default
+ follows, of course, the
+\family sans
+makeindex
+\family default
+ conventions.
+\layout Standard
+
+The original LaTeX file is left unchanged.
+ A new file will be written, identified by
+\family sans
+-ind
+\family default
+.
+ For example, from
+\family sans
+file.tex
+\family default
+ you will get
+\family sans
+file-ind.tex
+\family default
+.
+ Of course, you'll have to run
+\family sans
+makeindex
+\family default
+ as usual.
+\layout Standard
+
+The purpose of the program is similar to what is provided by the program
+
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+mbox{
+\end_inset
+
+
+\family sans
+ixgen
+\family default
+
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+}
+\end_inset
+
+ (
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+url{http://www.iit.upco.es/~oscar/ixgen/}
+\end_inset
+
+) written by
+\shape smallcaps
+Oscar Lopez
+\shape default
+ (
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+url{oscar@iit.upco.es}
+\end_inset
+
+), but
+\family sans
+forindex
+\family default
+ was designed to be a bit more flexible.
+\layout Subsection
+
+The program
+\family sans
+cleanindex
+\layout Standard
+
+The program
+\family sans
+cleanindex
+\family default
+ removes
+\family sans
+
+\backslash
+index
+\family default
+ sequences from a LaTeX 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.
+\layout Standard
+
+The input file may have extension
+\family typewriter
+tex
+\family default
+ or
+\family typewriter
+latex
+\family default
+, both uppercase and lowercase.
+\layout Standard
+
+The original file is left unchanged.
+ A new file will be written, identified by
+\family sans
+-noind
+\family default
+.
+ For example, from
+\family sans
+file.tex
+\family default
+ you will get
+\family sans
+file-noind.tex
+\family default
+.
+ In this file, lines concerning
+\family sans
+makeindex
+\family default
+ will be left but commented, in order to avoid an empty
+\emph on
+Contents
+\emph default
+ section in the output.
+ You can uncomment the lines as soon as you want to reindex the file again.
+\layout Section
+
+Installation
+\layout Subsection
+
+GNU/Linux and other *nix systems
+\layout Enumerate
+
+Install
+\family sans
+snobol4
+\family default
+ from
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+url{http://www.snobol4.org}
+\end_inset
+
+.
+ This is Philip Budne's CSNOBOL implementation.
+ You need a
+\family typewriter
+c
+\family default
+ compiler to compile the interpreter; it's normally a very quick and easy
+ process.
+
+\layout Enumerate
+
+Make sure
+\family sans
+snobol4
+\family default
+ is in your PATH or make a symbolic link.
+
+\layout Enumerate
+
+Copy all the files from the source directory in a suitable directory (you
+ do not need the
+\family typewriter
+bat
+\family default
+ files, provided for Windows, and can safely remove them).
+
+\layout Enumerate
+
+Make executables the scripts (
+\family sans
+doindex
+\family default
+ and
+\family sans
+cleanindex
+\family default
+ with no extensions), e.g.
+
+\family typewriter
+chmod +x doindex
+\layout Enumerate
+
+Run the scripts as follows:
+\begin_deeper
+\layout Enumerate
+
+-- to index a text:
+\family typewriter
+./doindex file.tex
+\layout Enumerate
+
+If you want to exclude words with accents:
+\family typewriter
+./doindex file.tex --noacc
+\layout Enumerate
+
+-- to remove
+\family sans
+
+\backslash
+index
+\family default
+sequences:
+\family typewriter
+./cleanindex file.tex
+\layout Enumerate
+
+If the current directory is in your PATH, you do not need
+\family typewriter
+./
+\family default
+ before the script name.
+\newline
+
+\end_deeper
+\layout Subsection
+
+Windows
+\layout Standard
+
+The package offers exe files compiled with Spitbol (see (
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+url{http://www.snobol4.com}
+\end_inset
+
+).
+ Make a directory and copy all the file in the bin/windows directory.
+ There must be two
+\family typewriter
+*.exe
+\family default
+ files and the two
+\family typewriter
+test.*
+\family default
+ files.
+\layout Standard
+
+Run the programs as follows:
+\layout Standard
+
+-- to index a text:
+\family typewriter
+doindex file.tex
+\layout Standard
+
+If you want to exclude words with accents:
+\family typewriter
+doindex file.tex -noacc
+\family default
+.
+ Accents must be encoded using the
+\family sans
+latin1
+\family default
+ encoding (see the list of Todo).
+\layout Standard
+
+-- to remove
+\family typewriter
+
+\backslash
+index
+\family default
+ sequences:
+\family typewriter
+cleanindex file.tex
+\layout Subsection
+
+Windows from source
+\layout Standard
+
+Basically, follow the same directions given about GNU/Linux, but make sure
+ to use the
+\family typewriter
+bat
+\family default
+ 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
+\family sans
+edit
+\family default
+ program, with
+\family sans
+vim
+\family default
+ 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
+\family sans
+acc.inc
+\family default
+ to
+\family sans
+ISO-8859-1
+\family default
+ or
+\family sans
+8859-15
+\family default
+, not to plain DOS or Unicode.
+\layout Subsection
+
+Cygwin
+\layout Standard
+
+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.
+\layout Subsection
+
+Macintosh
+\layout Standard
+
+Not yet tested (I do not have a Mac right now).
+ It's in the TODO list.
+\layout Section
+
+Test files
+\layout Standard
+
+Please test the program on
+\family sans
+test.tex
+\family default
+ and
+\family sans
+test.wls
+\family default
+.
+ The produced file will be called
+\family sans
+test-ind.tex
+\family default
+ if you use
+\family sans
+doindex
+\family default
+,
+\family sans
+test-noind.tex
+\family default
+ if you use
+\family sans
+cleanindex
+\family default
+.
+\layout Section
+
+Bugs and TODO
+\layout Standard
+
+The program does not support Unicode files.
+ At this moment, most LaTeX users are still using latin1, but the situation
+ is rapidly changing.
+\layout Standard
+
+List of features that I would like to add:
+\layout Enumerate
+
+Index also included files.
+
+\layout Enumerate
+
+Add typographical styles, such as italics for the most important locations
+ of a word.
+
+\layout Enumerate
+
+Add support for several indexes (particularly with class
+\family sans
+memoir
+\family default
+)
+\layout Enumerate
+
+Add an option to generate a rough index for all the words.
+
+\layout Enumerate
+
+Add a support to index words listed with regular expressions.
+ E.g.
+
+\family typewriter
+read*
+\family default
+ should index
+\emph on
+read
+\emph default
+,
+\emph on
+reads
+\emph default
+,
+\emph on
+reading
+\emph default
+,
+\emph on
+readings
+\emph default
+, all under the same heading
+\emph on
+read
+\emph default
+.
+
+\layout Enumerate
+
+Make possible to use another separator for the list file, e.g.
+ a simple blank or other char preferred by user.
+
+\layout Enumerate
+
+Test the programs on a Mac.
+
+\layout Enumerate
+
+Add Unicode support.
+
+\layout Section
+
+Acknowledgements
+\layout Standard
+
+The program
+\family sans
+ixgen
+\family default
+ gave me the idea of
+\family sans
+forindex
+\family default
+.
+ Many thanks to
+\shape smallcaps
+Oscar Lopez
+\shape default
+ for this very good program.
+\layout Standard
+
+Some questions sent by
+\shape smallcaps
+Carlo Pellegrino
+\shape default
+ (Modena University, Italy) gave me the idea of transforming a very rudimentary
+ script into a general purpose utility.
+
+\shape smallcaps
+Maurizio Loreti
+\shape default
+ (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.
+\layout Standard
+
+My warmest thanks to
+\shape smallcaps
+Phil Budne
+\shape default
+ (
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+url{phil@ultimate.com}
+\end_inset
+
+) for making his excellent CSNOBOL available.
+ Many thanks to the community of Snobol users, particularly to the members
+ of the list
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+url{snobol4@mercury.dsu.edu}
+\end_inset
+
+, and, among them, to
+\shape smallcaps
+Gordon Peterson
+\shape default
+ (
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+url{http://personal.terabites.com/}
+\end_inset
+
+),
+\shape smallcaps
+Michael Radow
+\shape default
+ (
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+url{mikeradow@yahoo.com}
+\end_inset
+
+),
+\shape smallcaps
+Gregory L.
+ White
+\shape default
+ (
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+url{glwhite@netconnect.com.au}
+\end_inset
+
+) and to
+\shape smallcaps
+Rafal M.
+ Sulejman
+\shape default
+ (
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+url{rafal@engelsinfo.de}
+\end_inset
+
+) whose
+\family sans
+vim
+\family default
+ syntax files are a daily blessing.
+\layout Standard
+
+Thanks to Jim Hefferon <
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+url{ftpmaint@alan.smcvt.edu}
+\end_inset
+
+> who pointed out that the original name of the package,
+\family sans
+ 4index
+\family default
+, was not acceptable due to XML syntax rules.
+\layout Section
+
+Author, copyright, license, disclaimer
+\layout Standard
+
+This program is Copyright
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+copyright{}
+\end_inset
+
+ 2005
+\newline
+ Guido Milanese <
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+url{guido.milanese@unicatt.it}
+\end_inset
+
+>
+\newline
+ under the terms of the GNU General Public License.
+\newline
+
+\layout Standard
+
+
+\size footnotesize
+
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+begin{verbatim}
+\newline
+This program is free software; you can redistribute it and/or modify it under
+\newline
+the terms of the GNU General Public License as published by the Free Software
+\newline
+Foundation; either version 2 of the License, or (at your option) any later
+\newline
+version.
+\newline
+
+\newline
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
+\newline
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+\newline
+PARTICULAR PURPOSE. See the GNU General Public License for more details.
+\newline
+
+\newline
+If you do not have a copy of the GNU General Public License write to the Free
+\newline
+Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+\newline
+
+\newline
+If the author of this software was too lazy to include the full GPL text along
+\newline
+with the code, you can find it at: http://www.gnu.org/copyleft/gpl.html.
+\newline
+
+\backslash
+end{verbatim}
+\end_inset
+
+
+\the_end
diff --git a/indexing/forindex/docs/forindex.pdf b/indexing/forindex/docs/forindex.pdf
new file mode 100644
index 0000000000..a481edd84b
--- /dev/null
+++ b/indexing/forindex/docs/forindex.pdf
Binary files differ
diff --git a/indexing/forindex/docs/forindex.tex b/indexing/forindex/docs/forindex.tex
new file mode 100644
index 0000000000..9ccb59ab94
--- /dev/null
+++ b/indexing/forindex/docs/forindex.tex
@@ -0,0 +1,250 @@
+% Forindex documentation
+% Version 0.1
+% January 2005
+% Guido Milanese - guido.milanese@unicatt.it
+
+\documentclass[a4paper,english]{article}
+\usepackage[T1]{fontenc}
+\usepackage[latin1]{inputenc}
+\IfFileExists{url.sty}{\usepackage{url}}
+ {\newcommand{\url}{\texttt}}
+\usepackage{babel}
+
+\begin{document}
+
+\title{The forindex utilities\\
+Version 0.1}
+
+
+\author{Guido Milanese\\
+\url{guido.milanese@unicatt.it}}
+
+
+\thispagestyle{empty}
+\date{January 2005}
+\maketitle
+\begin{abstract}
+\noindent{}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 \textsf{doindex}, that prepares a file to be processed by
+\textsf{makeindex}. Another useful feature is to remove all the
+\texttt{\textbackslash{}index} entries in a \LaTeX{} file, obtaining a
+clean file with no indexing (program \textsf{cleanindex}). 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.
+\end{abstract}
+
+\tableofcontents
+
+\section{The programs}
+\subsection{The program \textsf{doindex}}
+The programs \textsf{doindex} reads a \LaTeX{} 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.
+
+The input \LaTeX{} file may have extension \texttt{tex} or \texttt{latex},
+both uppercase and lowercase (not mixed as in \texttt{Tex}).
+
+The list file is meant to contain all the words to be indexed. It must have
+exactly the extension \texttt{wls}. Sub-entries are identified with the separator
+character '/'. See \textsf{test.wls} as example:
+
+
+\begin{quote}
+ \begin{verbatim}
+ animals
+ dogs/animals
+ cats
+ house/nouns/english/languages
+ sleeping@sleep
+ évita/Italian/foreign words
+ ça/French/foreign words
+ drücken/German/foreign words
+ \end{verbatim}
+\end{quote}
+
+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 \texttt{sleeping@sleep} use the
+standard \textsf{makeindex} syntax and are left unchanged. The ``logic'' of this
+syntax is opposite to the internal logic of \textsf{makeindex}, 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'' (\texttt{dog/animal} in my syntax)
+seems to me to be more natural than ``Among animals there are dogs''
+(\texttt{animals!dogs} in the \textsf{makeindex} syntax). The \LaTeX{} file produced
+by \textsf{doindex} follows, of course, the \textsf{makeindex} conventions.
+
+The original \LaTeX{} file is left unchanged. A new file will be written,
+identified by \textsf{-ind}. For example, from \textsf{file.tex} you will get
+\textsf{file-ind.tex}. Of course, you'll have to run \textsf{makeindex} as usual.
+
+The purpose of the program is similar to what is provided by the program
+\mbox{\textsf{ixgen}} (\url{http://www.iit.upco.es/~oscar/ixgen/})
+written by \textsc{Oscar Lopez} (\url{oscar@iit.upco.es}), but \textsf{forindex} was
+designed to be a bit more flexible.
+
+\subsection{The program \textsf{cleanindex}}
+
+The program \textsf{cleanindex} removes \textsf{\textbackslash{}index}
+sequences from a \LaTeX{} 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.
+
+The input file may have extension \texttt{tex} or \texttt{latex},
+both uppercase and lowercase.
+
+The original file is left unchanged. A new file will be written, identified
+by \textsf{-noind}. For example, from \textsf{file.tex} you will get
+\textsf{file-noind.tex}. In this file, lines concerning \textsf{makeindex} will
+be left but commented, in order to avoid an empty \emph{Contents} section in the
+output. You can uncomment the lines as soon as you want to reindex the file
+again.
+
+\section{Installation}
+
+\subsection{GNU/Linux and other {*}nix systems}
+
+\begin{enumerate}
+ \item Install \textsf{snobol4} from \url{http://www.snobol4.org}. This is Philip Budne's
+ CSNOBOL implementation. You need a \texttt{c} compiler to compile the
+ interpreter; it's normally a very quick and easy process.
+\item Make sure \textsf{snobol4} is in your PATH or make a symbolic link.
+\item Copy all the files from the source directory in a suitable directory (you
+ do not need the \texttt{bat} files, provided for Windows, and can safely remove
+ them).
+\item Make executables the scripts (\textsf{doindex} and \textsf{cleanindex}
+with no extensions), e.g. \texttt{chmod +x doindex}
+\item Run the scripts as follows:
+
+\begin{enumerate}
+\item -- to index a text: \texttt{./doindex file.tex}
+\item If you want to exclude words with accents: \texttt{./doindex file.tex
+-{}-noacc}
+\item -- to remove \textsf{\textbackslash{}index }sequences: \texttt{./cleanindex
+file.tex}
+\item If the current directory is in your PATH, you do not need \texttt{./}
+before the script name.\\
+
+\end{enumerate}
+\end{enumerate}
+
+\subsection{Windows}
+
+The package offers exe files compiled with Spitbol (see
+(\url{http://www.snobol4.com}). Make a directory and copy all the file in the
+bin/windows directory. There must be two \texttt{{*}.exe} files and the two
+\texttt{test.{*}} files.
+
+Run the programs as follows:
+
+-- to index a text: \texttt{doindex file.tex}
+
+If you want to exclude words with accents: \texttt{doindex file.tex -noacc}.
+Accents must be encoded using the \textsf{latin1} encoding (see the list of
+Todo).
+
+-- to remove \texttt{\textbackslash{}index} sequences: \texttt{cleanindex
+file.tex}
+
+\subsection{Windows from source}
+
+Basically, follow the same directions given about GNU/Linux, but make sure to
+use the \texttt{bat} 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 \textsf{edit} program, with
+\textsf{vim} 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 \textsf{acc.inc} to \textsf{ISO-8859-1} or
+\textsf{8859-15}, not to plain DOS or Unicode.
+
+\subsection{Cygwin}
+
+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.
+
+\subsection{Macintosh}
+Not yet tested (I do not have a Mac right now). It's in the TODO list.
+
+\section{Test files}
+Please test the program on \textsf{test.tex} and \textsf{test.wls}.
+The produced file will be called \textsf{test-ind.tex} if you use
+\textsf{doindex}, \textsf{test-noind.tex} if you use \textsf{cleanindex}.
+
+\section{Bugs and TODO}
+The program does not support Unicode files. At this moment, most
+\LaTeX{} users are still using latin1, but the situation is rapidly changing.
+
+List of features that I would like to add:
+
+\begin{enumerate}
+\item Index also included files.
+\item Add typographical styles, such as italics for the most important
+locations of a word.
+\item Add support for several indexes (particularly with class \textsf{memoir})
+\item Add an option to generate a rough index for all the words.
+\item Add a support to index words listed with regular expressions.
+E.g. \texttt{read{*}} should index \emph{read}, \emph{reads},
+\emph{reading}, \emph{readings},
+all under the same heading \emph{read}.
+\item Make possible to use another separator for the list file, e.g. a simple
+blank or other char preferred by user.
+\item Test the programs on a Mac.
+\item Add Unicode support.
+\end{enumerate}
+
+\section{Acknowledgements}
+The program \textsf{ixgen} gave me the idea of \textsf{forindex}. Many thanks to
+\textsc{Oscar Lopez} for this very good program.
+
+Some questions sent by \textsc{Carlo Pellegrino} (Modena University, Italy) gave
+me the idea of transforming a very rudimentary script into a general purpose
+utility. \textsc{Maurizio Loreti} (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.
+
+My warmest thanks to \textsc{Phil Budne} (\url{phil@ultimate.com}) for making
+his excellent CSNOBOL available. Many thanks to the community of Snobol users,
+particularly to the members of the list \url{snobol4@mercury.dsu.edu}, and,
+among them, to \textsc{Gordon Peterson} (\url{http://personal.terabites.com/}),
+\textsc{Michael Radow} (\url{mikeradow@yahoo.com}), \textsc{Gregory L. White}
+(\url{glwhite@netconnect.com.au}) and to \textsc{Rafal M. Sulejman}
+(\url{rafal@engelsinfo.de}) whose \textsf{vim} syntax files are a daily
+blessing.
+
+Thanks to Jim Hefferon <\url{ftpmaint@alan.smcvt.edu}> who pointed out that the
+original name of the package,\textsf{ 4index}, was not acceptable due to XML syntax
+rules.
+
+\section{Author, copyright, license, disclaimer}
+
+This program is Copyright \copyright{} 2005\\
+Guido Milanese <\url{guido.milanese@unicatt.it}>\\
+under the terms of the GNU General Public License.\\
+
+\footnotesize{}
+ \begin{verbatim}
+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.
+\end{verbatim}
+\normalsize{}
+\end{document}
+