README - File IdxTool v0.2.1 ----------- Inhaltsverzeichnis ------------------------------------------/ - Übersicht - History und Changelogs - Dateien und Verzeichnisse - Anmerkungen zur Version - Installation Linux/Windows - Beispiele - Hinweise und Autoren - Lizenz -------------------------------------------------------------------------/ ========================================================================= - ÜBERSICHT ========================================================================= IdxTool ist ein kleines Konsolenprogramm das Wortindexeinträge in bestehende LaTeX Dateien einfügt. Es nutzt Wortlisten zur Auswahl der Worte, die in einen LateX-Index aufgenommen werden sollen. Dadurch kann die Erstellung von Indices für große Dokumente erheblich beschleunigt werden. IdxTool ist vollständig in C geschrieben und besteht im wesentlichen aus einem vereinfachten LaTeX-Parser. Dieser Parser entscheidet, an welchen Stellen Indexeinträge eingefügt werden müssen und wo sie zu vermeiden sind. Dafür wird nicht das gesamte Dokument eingelesen, so dass auch sehr große Dokumente auf Rechnern mit geringer Leistung bearbeitet werden können. Aus diesem Grund überschreibt IdxTool auch nicht die Originaldateien. Beim Setzen des Dokuments muss nur darauf geachtet werden, dass die richtige Datei mittels \include{ } eingebunden wird. Im Standardmodus nimmt IdxTool alle Worte, deren Länge größer als vier Buchstaben ist, in den Index auf. Alternativ kann eine Wort-Liste zur direkten Auswahl der zu indizierenden Worte benutzt werden. Diese Liste kann entweder als Ausschlussliste oder als Exklusivliste verwendet werden. Im Ausschlussmodus werden in der Liste geführten Worte nicht in den Index aufgenommen. Der Exklusivmodus hat genau die umgekehrte Funktion. Zum Erstellen der Liste kann ebenfalls auf das IdxTool zurückgegriffen werden, so dass lange Listen nicht händisch erstellt werden müssen. Die generierte Wortlist wird alphabetisch sortiert mit frei wählbaren Dateinamen abgespeichert. Als zusätzliches Feature gibt es die Möglichkeit Wortalternativen für ein entsprechendes Wort im Dokument zu verwenden. Zum Beispiel: Ontology\index{Ontology} aber auch Ontologies\index{Ontology}. Dazu muss in der Wortliste lediglich der jeweilige Eintrag angepasst werden. Download und mehr Informationen unter: >> http://lo-f.at/projekte/idxtool.html ========================================================================= - History und Changelogs ========================================================================= 18.03.2005 Release v0.2.1 + böser Bug bei der Indexierung von Listen gefixt + LaTeX Parser Bugfix beim Bindestrich (hyphen) + Korrektur der Ausgabedateinamen wenn der Benutzer keinen angibt (zwecks Scriptfähigkeit) + Programmcode überarbeitet 08.04.2004 Release v0.2.0 + Makefile angepasst; 'debugging information' entfernt; + Installation mit 'make install' möglich + kompletter Rewrite der Wortlisten-Funktionen (speedup) + verschiedene Memory-Leaks im Parser gefixed + neue Features: - Ausgabe auch auf STDOUT durch die Option '-stdout' möglich - alphabetisch sortierte Wortlisten 04.08.2003 Release v0.1.1 + kleinere Optimierungen im Code + LaTeX Parser Bugfix bei '_'-Zeichen (Unterstrich) + Portierung auf Windows 09.07.2003 Release v0.1.0-Beta + IdxTool auf lo-f.at released 10.06.2003 ersten Index mit dem IdxTool erstellt > zwischenzeitlich verschiedene Bugfixes und Erweiterungen 01.05.2003 Projektstart + TestCases erstellt + Implementierung der Parser Routinen ========================================================================= - Dateien und Verzeichnisse ========================================================================= INSTALL ... kurze Anleitung zur Installation des Tools README ... dieses File COPYING ... Lizenzbestimmungen FAQ ... die häufig gestellten Fragen TODO ... ToDo List idxtool.h ... Headerfile für das Index-Tool idxtool.c ... Quellcode Index-Tool (main) input.c ... Funktionen zum Einlesen des Input-Streams list.h ... Headerfile für die Wort-Listen Funktionen list.c ... Quellcode zu den List-Funktionen Makefile ... Makefile parser_context.h ... Headerfile für die Parserfunktionen parser_context.c ... Quellcode für den Parser texlatex.c ... ebenfalls Quellcode für den Parser config.c ... Quellcode zur Konfiguration des Parsers wordchar.c ... Quellcode für die Verarbeitung von Wörtern ========================================================================= - Anmerkungen zur Version ========================================================================= IdxTool ist noch im Beta-Stadium. Auf den Maschinen des Entwicklers läuft es allerdings bereits weitgehend stabil. Dennoch sollte besonders bei komplexen LaTeX Dokumenten mit Problemen gerechnet werden. Der Quelltext wird in der Zwischenzeit unter Debian mit dem gcc 'gcc (GCC) 3.3.5 (Debian 1:3.3.5-8)' getestet und kompiliert. Das Tool verwendet ausschließlich Funktionen der glibc, so dass es auch auf anderen Systemen lauffähig sein sollte. Eine Portierung auf Windows ist ab Release v0.1.1 erfolgt. Dabei wurde der Code jedes Releases unter Cygwin mit dem 'gcc version 3.2 20020927 (prerelease)' kompiliert und getestet. Der Entwickler selbst hat das Tool unter Windows jedoch selbst nicht in Verwendung. Bugreports und Verbesserungsvorschläge sind sowohl von Linux- als auch von Windowsanwendern jederzeit herzlich willkommen. ========================================================================= - Installation Linux/Windows ========================================================================= >> Linux: Die Installation ist einfach anhand der folgenden Schritte durchführbar. 1) $ tar xvzf idxtool-.tar.gz 2) cd idxtool- 3) make 4) make install Ein 'make install' kopiert die Datei 'idxtool' ins Verzeichnis ~/bin/ des jeweiligen $USER's, welcher die Installation durchführt. Der Pfad ~/bin sollte bei einer lokalen Installation in der $PATH Variable eingetragen sein. $ echo $PATH [...]:/home/$USER/bin:[...] Mehr Informationen zur Installation in der Datei 'INSTALL'. >> Windows: Eine Installation ist unter Windows nicht notwendig. Nach dem Download und dem Kopieren des Files 'idxtool.exe' in ein Verzeichnis welches auch durch die $PATH Variable erfasst wird, kann das Programm jederzeit durch die Eingabe des Dateinamens gestartet werden. E:\Mein_LaTeX_Projekt> idxtool ========================================================================= - Beispiele ========================================================================= $ idxtool ... Version und kurze Hilfe wird ausgegeben. $ idxtool -x index -i dokument.tex -o dokument_index.tex ... liest die Datei 'dokument.tex' und schreibt die Datei mit Indexeinträgen 'dokument_index.tex'. Es werden alle Wörter die länger als 4 Buchstaben sind im Index aufgenommen. zB Dokument\index{Dokument}. Der Indexeintrag entspricht dem Worteintrag. $ idxtool -x index -i dokument.tex -o dokument_index.tex -c 0 -v ... es werden ALLE Wörter im Index eingetragen. Zusätzlich 'verbose-output'. zB je\index{je} $ idxtool -i dokument.tex -w wort.liste ... liest die Datei 'dokument.tex' und generiert eine Wort-Liste mit dem Dateinamen 'wort.list'. Es werden dabei nur Wörter die länger als 4 Buchstaben sind in der Liste aufgenommen. Mit einem zusätzlichen '-c 0' werden ALLE Wörter in der Liste aufgenommen. $ idxtool -x index -i dokument.tex -stdout ... liest die Datei 'dokument.tex' und schreibt diese mit dem Index auf den STDOUT. Kann bei der Verwendung von Pipes in Shell-Scripts Anwendung finden. (zB: $ idxtool -x index -i $DOKUMENT -stdout > $DOKUMENT"_index") $ idxtool -x index -i dokument.tex -o dokument_index.tex -l wort.liste ... Wörter die in der Wortliste stehen, werden im Dokument mit einem Indexeintrag versehen. Sollte ein Wort welches weniger als 4 Buchstaben hat in der Wortliste stehen, wird dieses ignoriert. Somit sollte bei der Verwendung der Option '-l' immer die '-c 0' Option mit angegeben werden. Eine Negativliste erhält der User, indem er die '-s' Option setzt. Danach werden alle Wörter die nicht in der Liste vorkommen mit einem Index-Eintrag versehen. BEACHTE: Ein Alternativeintrag ist dabei nicht mehr möglich. ----------------------- Syntax der Wortliste: ----------------------- Bei der Syntax muss nur darauf geachtet werden, dass das zu indizierende Wort, unabhängig ob Black- oder Whitelist, ein Komma vor dem Zeilenumbruch aufweist. Dieses Komma trennt auch das Wort vom Alternativwort. Beispiel: Wort,Alternative Wort, Wort << wird nicht erkannt, da das Komma fehlt. WICHTIG: Es darf kein Leerzeichen zwischen dem Komma und der Alternative stehen. Wort ,Alternative ^ erlaubt Wort, Alternative ^ NICHT erlaubt Beim automatischen Generieren der Wortliste, wird das Komma automatisch gesetzt. Der Autor persönlich stellte bei der Arbeit fest, dass ein Generieren der Wortliste mit einer anschließenden Bearbeitung sich am einfachsten gestaltet um schnell ein brauchbares Ergebnis zu erzielen. ACHTUNG: Bei der Arbeit mit Wortlisten immer auf die Option '-c 0' achten, da sonst kurze Worte *vor* dem Indizierungsalgorithmus herausgefiltert werden. ========================================================================= - Hinweise und Autoren ========================================================================= Aufgrund eines Postings in de.comp.text.tex vom 08.07.2003 'Subject: Wie erstelle ich SINNVOLL einen Index?' (Message ID: <4RCOa.462$pQ2.38585@newsfep1-win.server.ntli.net>) von 'Frank' habe ich beschlossen eine Beta-Version des Tools zu releasen. Augrund von weiteren Anfragen portierte ich das Tool dann auch auf Windows. Ab Release v0.1.1 stelle ich auch ein Binary für Windows zum Download bereit. Dieses wird aus den selben Sourcen kompiliert wie die Linux Version. Die Wortlisten-Funktionen wurden ab Version v0.2.0 mit Sortier- und speziellen Suchfunktionen erweitert. Weiters wurde eine merkliche Beschleunigung bei der Listenbearbeitung sowie der Indizierung erreicht. (speedup) Die v0.2.0 enthielt einen schweren Bug beim Arbeiten mit Wortlisten. Ab v0.2.1 sollte dieser Bug behoben sein. Der MATH_MODE von LaTeX wurde nicht implementiert. Es kann daher bei Dokumenten mit Formeln zu undefinierten Indexeinträgen kommen. MATH_MODE ist derzeit untested und nicht implementiert. Soll aber in den nächsten Versionen in den Parser implementiert werden. Beim aktuellen Release handelt es sich um die dritte stabile Version. Sollte sich das Tool als nützlich erweisen, werde ich es weiter pflegen und auch weitere nützliche Features implementieren. BUG-Reports und Verbesserungsschläge an: idxtool at lo-f dot at Autor(en): Michael Valersi (michael.valersi at lo-f dot at) mit freundlicher Unterstützung von Christian Glahn (christian.glahn at lo-f dot at) ========================================================================= - Lizenz ========================================================================= IdxTool wird unter der Gnu Public License Version 2 entwickelt. /* IdxTool ... Tool zum Indizieren von LaTeX-Dokumenten * Copyright (c) 2003 mICvAL, Michael Valersi * michael.valersi at lo-f dot at * * ====================================================================== * 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. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA * 02111-1307, USA. * * ====================================================================== */ Informationen und die Lizenz unter: http://www.gnu.de/gpl-ger.html bzw unter: http://www.gnu.org/licenses/gpl.html