diff options
Diffstat (limited to 'indexing/forindex/docs/forindex.html')
-rw-r--r-- | indexing/forindex/docs/forindex.html | 457 |
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>\index</TT> entries in a L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X +file, obtaining a clean file with no indexing (program <I>cleanindex</I>). +The programs are written in Snobol4; the only requirement is to install +the interpreter. For Windows, a standalone file compiled with Spitbol +is also provided, and the programs can be run without the need of +an external interpreter. +</DIV> +<P> +<BR> + +<H2><A NAME="SECTION00010000000000000000"> +Contents</A> +</H2> +<!--Table of Contents--> + +<UL> +<LI><A NAME="tex2html29" + HREF="forindex.html#SECTION00020000000000000000">1 The programs</A> +<UL> +<LI><A NAME="tex2html30" + HREF="forindex.html#SECTION00021000000000000000">1.1 The program doindex</A> +<LI><A NAME="tex2html31" + HREF="forindex.html#SECTION00022000000000000000">1.2 The program cleanindex</A> +</UL> +<BR> +<LI><A NAME="tex2html32" + HREF="forindex.html#SECTION00030000000000000000">2 Installation</A> +<UL> +<LI><A NAME="tex2html33" + HREF="forindex.html#SECTION00031000000000000000">2.1 GNU/Linux and other *nix systems</A> +<LI><A NAME="tex2html34" + HREF="forindex.html#SECTION00032000000000000000">2.2 Windows</A> +<LI><A NAME="tex2html35" + HREF="forindex.html#SECTION00033000000000000000">2.3 Windows from source</A> +<LI><A NAME="tex2html36" + HREF="forindex.html#SECTION00034000000000000000">2.4 Cygwin</A> +<LI><A NAME="tex2html37" + HREF="forindex.html#SECTION00035000000000000000">2.5 Macintosh</A> +</UL> +<BR> +<LI><A NAME="tex2html38" + HREF="forindex.html#SECTION00040000000000000000">3 Test files</A> +<LI><A NAME="tex2html39" + HREF="forindex.html#SECTION00050000000000000000">4 Bugs and TODO</A> +<LI><A NAME="tex2html40" + HREF="forindex.html#SECTION00060000000000000000">5 Acknowledgements</A> +<LI><A NAME="tex2html41" + HREF="forindex.html#SECTION00070000000000000000">6 Author, copyright, license, disclaimer</A> +</UL> +<!--End of Table of Contents--> + +<P> + +<H1><A NAME="SECTION00020000000000000000"> +1 The programs</A> +</H1> + +<P> + +<H2><A NAME="SECTION00021000000000000000"> +1.1 The program <I>doindex</I></A> +</H2> + +<P> +The programs <I>doindex</I> reads a L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X file, using a list +file, and enters index entries in the file according to this list. +Previously entered index entries are left unchanged, making it possible +to add further indexing to an already indexed file. + +<P> +The input L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X file may have extension <TT>tex</TT> or <TT>latex</TT>, +both uppercase and lowercase (not mixed as in <TT>Tex</TT>). + +<P> +The list file is meant to contain all the words to be indexed. It +must have exactly the extension <TT>wls</TT>. Sub-entries are identified +with the separator character '/'. See <I>test.wls</I> as example: + +<P><PRE> + animals + dogs/animals + cats + house/nouns/english/languages + sleeping@sleep + évita/Italian/foreign words + ça/French/foreign words + drücken/German/foreign words +</PRE> +No particular order in this file is required. Some users will prefer +alphabetical order, others different orders, so the programs has no +requirements concerning order/sort in this file. Entries as <TT>sleeping@sleep</TT> +use the standard <I>makeindex</I> syntax and are left unchanged. +The ``logic'' of this syntax is opposite to the internal logic +of <I>makeindex</I>, that is - I think - very clever at the stage +of typesetting an index, but not at the stage of designing an index. +``A dog is an animal'' (<TT>dog/animal</TT> in my syntax) seems +to me to be more natural than ``Among animals there are dogs'' +(<TT>animals!dogs</TT> in the <I>makeindex</I> syntax). The L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X +file produced by <I>doindex</I> follows, of course, the <I>makeindex</I> +conventions. + +<P> +The original L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X file is left unchanged. A new file will be written, +identified by <I>-ind</I>. For example, from <I>file.tex</I> you +will get <I>file-ind.tex</I>. Of course, you'll have to run <I>makeindex</I> +as usual. + +<P> +The purpose of the program is similar to what is provided by the program +<I>ixgen</I> (<TT><A NAME="tex2html2" + HREF="http://www.iit.upco.es/~oscar/ixgen/">http://www.iit.upco.es/~oscar/ixgen/</A></TT>) +written by O<SMALL>SCAR </SMALL>L<SMALL>OPEZ</SMALL> (<TT><A NAME="tex2html3" + HREF="oscar@iit.upco.es">oscar@iit.upco.es</A></TT>), but <I>forindex</I> +was designed to be a bit more flexible. + +<P> + +<H2><A NAME="SECTION00022000000000000000"> +1.2 The program <I>cleanindex</I></A> +</H2> + +<P> +The program <I>cleanindex</I> removes <I>\index</I> +sequences from a L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X file. The program can be used e.g. if a +user is not happy with the indexing of a file and wants to start it +over again. + +<P> +The input file may have extension <TT>tex</TT> or <TT>latex</TT>, +both uppercase and lowercase. + +<P> +The original file is left unchanged. A new file will be written, identified +by <I>-noind</I>. For example, from <I>file.tex</I> you will get +<I>file-noind.tex</I>. In this file, lines concerning <I>makeindex</I> +will be left but commented, in order to avoid an empty <I>Contents</I> +section in the output. You can uncomment the lines as soon as you +want to reindex the file again. + +<P> + +<H1><A NAME="SECTION00030000000000000000"> +2 Installation</A> +</H1> + +<P> + +<H2><A NAME="SECTION00031000000000000000"> +2.1 GNU/Linux and other *nix systems</A> +</H2> + +<P> + +<OL> +<LI>Install <I>snobol4</I> from <TT><A NAME="tex2html4" + HREF="http://www.snobol4.org">http://www.snobol4.org</A></TT>. This +is Philip Budne's CSNOBOL implementation. You need a <TT>c</TT> compiler +to compile the interpreter; it's normally a very quick and easy process. +</LI> +<LI>Make sure <I>snobol4</I> is in your PATH or make a symbolic link. +</LI> +<LI>Copy all the files from the source directory in a suitable directory +(you do not need the <TT>bat</TT> files, provided for Windows, and +can safely remove them). +</LI> +<LI>Make executables the scripts (<I>doindex</I> and <I>cleanindex</I> +with no extensions), e.g. <TT>chmod +x doindex</TT> +</LI> +<LI>Run the scripts as follows: + +<P> + +<OL> +<LI>- to index a text: <TT>./doindex file.tex</TT> +</LI> +<LI>If you want to exclude words with accents: <TT>./doindex file.tex +-noacc</TT> +</LI> +<LI>- to remove <I>\index</I> sequences: <TT>./cleanindex +file.tex</TT> +</LI> +<LI>If the current directory is in your PATH, you do not need <TT>./</TT> +before the script name. +<BR> +<P> +</LI> +</OL> +</LI> +</OL> + +<P> + +<H2><A NAME="SECTION00032000000000000000"> +2.2 Windows</A> +</H2> + +<P> +The package offers exe files compiled with Spitbol (see (<TT><A NAME="tex2html5" + HREF="http://www.snobol4.com">http://www.snobol4.com</A></TT>). +Make a directory and copy all the file in the bin/windows directory. +There must be two <TT>*.exe</TT> files and the two <TT>test.*</TT> +files. + +<P> +Run the programs as follows: + +<P> +- to index a text: <TT>doindex file.tex</TT> + +<P> +If you want to exclude words with accents: <TT>doindex file.tex +-noacc</TT>. Accents must be encoded using the <I>latin1</I> encoding +(see the list of Todo). + +<P> +- to remove <TT>\index</TT> sequences: <TT>cleanindex +file.tex</TT> + +<P> + +<H2><A NAME="SECTION00033000000000000000"> +2.3 Windows from source</A> +</H2> + +<P> +Basically, follow the same directions given about GNU/Linux, but make +sure to use the <TT>bat</TT> files and to install the Windows version +of the interpreter. Before using the sources, that are in Unix format, +use a script to translate from Unix to Dos-Windows format. If you +do not have such a script, open the files with a text editor and save +the sources in Windows-Dos format. This can be done reading and saving +each file with the DOS <I>edit</I> program, with <I>vim</I> or +any other editor able to deal with different file formats. Do not +alter the files if you are not sure of what you are doing. Please +(1) do not use a word processor (as Word or similar) but a simple +text editor and (2) make sure to leave the encoding of file <I>acc.inc</I> +to <I>ISO-8859-1</I> or <I>8859-15</I>, not to plain DOS or Unicode. + +<P> + +<H2><A NAME="SECTION00034000000000000000"> +2.4 Cygwin</A> +</H2> + +<P> +I suggest to follow the same directions given for GNU/Linux, but the +EXE files provided for native Windows can be used anyway if preferred. + +<P> + +<H2><A NAME="SECTION00035000000000000000"> +2.5 Macintosh</A> +</H2> + +<P> +Not yet tested (I do not have a Mac right now). It's in the TODO list. + +<P> + +<H1><A NAME="SECTION00040000000000000000"> +3 Test files</A> +</H1> + +<P> +Please test the program on <I>test.tex</I> and <I>test.wls</I>. +The produced file will be called <I>test-ind.tex</I> if you use +<I>doindex</I>, <I>test-noind.tex</I> if you use <I>cleanindex</I>. + +<P> + +<H1><A NAME="SECTION00050000000000000000"> +4 Bugs and TODO</A> +</H1> + +<P> +The program does not support Unicode files. At this moment, most L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X +users are still using latin1, but the situation is rapidly changing. + +<P> +List of features that I would like to add: + +<P> + +<OL> +<LI>Index also included files. +</LI> +<LI>Add typographical styles, such as italics for the most important locations +of a word. +</LI> +<LI>Add support for several indexes (particularly with class <I>memoir</I>) +</LI> +<LI>Add an option to generate a rough index for all the words. +</LI> +<LI>Add a support to index words listed with regular expressions. E.g. +<TT>read*</TT> should index <I>read</I>, <I>reads</I>, <I>reading</I>, +<I>readings</I>, all under the same heading <I>read</I>. +</LI> +<LI>Make possible to use another separator for the list file, e.g. a simple +blank or other char preferred by user. +</LI> +<LI>Test the programs on a Mac. +</LI> +<LI>Add Unicode support. +</LI> +</OL> + +<P> + +<H1><A NAME="SECTION00060000000000000000"> +5 Acknowledgements</A> +</H1> + +<P> +The program <I>ixgen</I> gave me the idea of <I>forindex</I>. +Many thanks to O<SMALL>SCAR </SMALL>L<SMALL>OPEZ</SMALL> for this very good program. + +<P> +Some questions sent by C<SMALL>ARLO </SMALL>P<SMALL>ELLEGRINO</SMALL> (Modena University, +Italy) gave me the idea of transforming a very rudimentary script +into a general purpose utility. M<SMALL>AURIZIO </SMALL>L<SMALL>ORETI</SMALL> (Padua University, +Italy) sent me very useful remarks on the problems of automatical +generations of indexes, which I made use of in the introduction to +this text. + +<P> +My warmest thanks to P<SMALL>HIL </SMALL>B<SMALL>UDNE</SMALL> (<TT><A NAME="tex2html6" + HREF="phil@ultimate.com">phil@ultimate.com</A></TT>) +for making his excellent CSNOBOL available. Many thanks to the community +of Snobol users, particularly to the members of the list <TT><A NAME="tex2html7" + HREF="snobol4@mercury.dsu.edu">snobol4@mercury.dsu.edu</A></TT>, +and, among them, to G<SMALL>ORDON </SMALL>P<SMALL>ETERSON</SMALL> (<TT><A NAME="tex2html8" + HREF="http://personal.terabites.com/">http://personal.terabites.com/</A></TT>), +M<SMALL>ICHAEL </SMALL>R<SMALL>ADOW</SMALL> (<TT><A NAME="tex2html9" + HREF="mikeradow@yahoo.com">mikeradow@yahoo.com</A></TT>), G<SMALL>REGORY +</SMALL>L. W<SMALL>HITE</SMALL> (<TT><A NAME="tex2html10" + HREF="glwhite@netconnect.com.au">glwhite@netconnect.com.au</A></TT>) and to R<SMALL>AFAL +</SMALL>M. S<SMALL>ULEJMAN</SMALL> (<TT><A NAME="tex2html11" + HREF="rafal@engelsinfo.de">rafal@engelsinfo.de</A></TT>) whose <I>vim</I> syntax +files are a daily blessing. + +<P> +Thanks to Jim Hefferon <<TT><A NAME="tex2html12" + HREF="ftpmaint@alan.smcvt.edu">ftpmaint@alan.smcvt.edu</A></TT>> who pointed +out that the original name of the package, <I>4index</I>, was not +acceptable due to XML syntax rules. + +<P> + +<H1><A NAME="SECTION00070000000000000000"> +6 Author, copyright, license, disclaimer</A> +</H1> + +<P> +This program is Copyright © 2005 +<BR> +Guido Milanese <<TT><A NAME="tex2html13" + HREF="guido.milanese@unicatt.it">guido.milanese@unicatt.it</A></TT>> +<BR> +under the terms of the GNU General Public License. +<BR> +<P> +<PRE> +This program is free software; you can redistribute it and/or modify it under +the terms of the GNU General Public License as published by the Free Software +Foundation; either version 2 of the License, or (at your option) any later +version. + +This program is distributed in the hope that it will be useful, but WITHOUT ANY +WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A +PARTICULAR PURPOSE. See the GNU General Public License for more details. + +If you do not have a copy of the GNU General Public License write to the Free +Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +If the author of this software was too lazy to include the full GPL text along +with the code, you can find it at: http://www.gnu.org/copyleft/gpl.html. +</PRE> + +<H1><A NAME="SECTION00080000000000000000"> +About this document ...</A> +</H1> + <STRONG>The forindex utilities +<BR> +Version 0.1</STRONG><P> +This document was generated using the +<A HREF="http://www.latex2html.org/"><STRONG>LaTeX</STRONG>2<tt>HTML</tt></A> translator Version 2002-2-1 (1.70) +<P> +Copyright © 1993, 1994, 1995, 1996, +<A HREF="http://cbl.leeds.ac.uk/nikos/personal.html">Nikos Drakos</A>, +Computer Based Learning Unit, University of Leeds. +<BR> +Copyright © 1997, 1998, 1999, +<A HREF="http://www.maths.mq.edu.au/~ross/">Ross Moore</A>, +Mathematics Department, Macquarie University, Sydney. +<P> +The command line arguments were: <BR> + <STRONG>latex2html</STRONG> <TT>-no_subdir -split 0 -show_section_numbers /tmp/lyx_tmpdir3312NEVskb/lyx_tmpbuf0/forindex.tex</TT> +<P> +The translation was initiated by guido on 2005-01-29<HR> +<ADDRESS> +<A HREF="http://www.arsantiqua.org">Guido Milanese</A>, +2005-01-29 +</ADDRESS> +</BODY> +</HTML> |