Initial commit

author: Norbert Preining <norbert@preining.info> 2019-09-02 13:46:59 +0900
committer: Norbert Preining <norbert@preining.info> 2019-09-02 13:46:59 +0900
commit: e0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree: 60335e10d2f4354b0674ec22d7b53f0f8abee672 /indexing/forindex/docs
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
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}
+
author	Norbert Preining <norbert@preining.info>	2019-09-02 13:46:59 +0900
committer	Norbert Preining <norbert@preining.info>	2019-09-02 13:46:59 +0900
commit	e0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree	60335e10d2f4354b0674ec22d7b53f0f8abee672 /indexing/forindex/docs