Analysenprogramm f. Exportparameter

Thomas Berger thomas at mpim-bonn.mpg.de
Mi Sep 27 19:44:25 CET 1995 

Liebe AllegrologInnen,

soeben geuploadet auf den Braunschweiger Fileserver (plana.exe im 
Verzeichnis upload) sowie per automatischer Mail zu beziehen von 
listserv at mpim-bonn.mpg.de (get perl plana.exe): 

    ANALYZE.PL

Dieses Perlscript ist geeignet:
- Zur Auswertung und Analyse von Exportparameterdateien
- Zur Versionskontrolle bzw. Testinstallation von Parameterdateien
- Zur Unterstuetzung integrierter Dokumentation von Parameterdateien
  mittels LaTeX

Warum dies ein Programm ist und nicht drei, wird eventuell aus der
enthaltenen Dokumentation ersichtlich.

Gruesse
Thomas Berger



                 K U R Z B E S C H R E I B U N G
                 -------------------------------

Voraussetzungen: 
================
 BigPerl oder aehnliches.
 Anpassen der Datei analyze.bat an die lokalen Installationsbedingungen 
 von perl.
BigPerl gibt es per anonymem ftp:
Host news.rrz.uni-koeln.de    (134.95.100.202)
    Location: /pc/msdos/gnuprogs
      FILE    -rw-rw-r--  487401 bytes  22:00 22 Oct 1994  bperl4x.zip


Was es bringt:
==============
Hier ein Auszug aus den Warnmeldungen, die entstehen, wenn man die
den aktuellen (V14a) Satz von Parameterdateien analysiert:

  34 (NMN:7): unbekanntes Kommando ----------------------------------...
  43 (NMN:16): unbekanntes Kommando ---------------------------------...
 372 (NMN:345): Sprungmarke #-u () mehrfach definiert
     (NMN:xxx): Fatal: Marke #-š existiert nicht

     (CAT:xxx): !!!: Sprungmarke #6nu fehlt

  28 (P-KURZ:14): unbekanntes Kommando li=5

 280 (COLOR:254): Anfhrungszeichen unpaarig (#8nz {C C &0 p77 ...
     (COLOR:xxx): Fatal: Marke #-Z existiert nicht
     (COLOR:xxx): Fatal: Marke #-z existiert nicht

 252 (P-WORDP:227): Unterprogramm #(G endet vor Start
     (P-WORDP:xxx): Fatal: Unterprogramm #(G startet nicht

 349 (E-MABD:334): Sprungmarke #-U () mehrfach definiert

 416 (P-DIN:391): Sprungmarke #-S () mehrfach definiert
     (P-DIN:xxx): Fatal: Marke #-Z existiert nicht
     (P-DIN:xxx): Fatal: Marke #-„ existiert nicht
     (P-DIN:xxx): !!!: Sprungmarke #39 fehlt

 424 (P-DINTEX:403): Sprungmarke #-S () mehrfach definiert
     (P-DINTEX:xxx): Fatal: Marke #-Z existiert nicht

 725 (D-1:691): Sprungmarke #-$ () mehrfach definiert

  46 (P-KARTE:13): unbekanntes Kommando fb 13 10 10 10   Kartenvorschub...
 901 (P-KARTE:864): Ende von P-KARTE: unges„ttigter Sprung zu #92i
     (P-KARTE:xxx): Fatal: Marke #-U existiert nicht


Aufrufbeispiele:
================ 
analyze -?

analyze c:\allegro\cat.api
Die Datei cat.api im Verzeichnis c:\allegro wird analysiert. 
Es wird erzeugt (im aktuellen Verzeichnis)
        cat.new     Variante von cat.api mit Headerzeilen, auch vor 
                    Includebefehlen, falls vorher die zugehoerigen 
                    .aPT-Dateien bereits analysiert worden waren.
        cat.xii     Index
        cat.xdi     Interne Merkdatei: Enthaelt den Kopf sowie 
                    Informationen fuer die Indexierung
        cat.xdb     eventuelle Fehlermeldungen und Warnungen
Im allgemeinen sollte das Script zweimal aufgerufen werden, damit
Uebereinstimmung von Index und Zeilennummern der Ausgabedatei 
gewaehrleistet ist.


Aufrufoptionen
==============
Im folgenden ist nur die Bedienung ohne die TeX-Funktionalitaet erlaeutert.

Aufruf:
analyze.pl [<Schalter>] [-i|--] <file> [<Optionen>]

    Schalter: -d[ebug  .xdb mit Debugging-Output wird erzeugt
        -i[nput ...   Dateiname fuer Quelle
        -o[utput ...  Dateipfad/Name fuer Ausgabe
        -mkd[ep       DEPEND.BAT wird erzeugt mit Aufrufen fuer Abhaengige
        -q[uick       Nur Produktion von Warnungen u. Index
        -strip[only   Statistik und Warnungen werden nicht eingehaengt
        -ind[ex       Index wird angehaengt
        -r[ecurse     Einlesen des Codes aus Includes
        -touch        Ausgabedatei mit aktuellem Datum
        -y ...        Zusaetzliche Includedatei fuer Kopf

Folgende Schalter koennen auch ueber Umgebungsvariable gesetzt werden:
  -D bzw. -P, -W ...   Daten- bzw. Programm- oder Arbeitsverzeichnis

Erzeugt: <file>.xdb    Output zum Debuggen (falls Warnungen oder -deb)
         <file>.tmp    temporaere Datei (falls -deb)
         <file>.xi?    Index (falls nicht -q)
         <file>.xd?    Interner Kurzindex zum Einfuegen am Anfang
         <file>.new    Datei mit neuem Kurzindex (falls nicht -o, -q)
         depend.bat    Abhaengigkeiten, falls -mkdep

Alle Aufrufoptionen sind im (Rahmen des Sinnvollen) miteinander kombinierbar


Funktionsweise
==============
Die Eingabedatei wird zur Ausgabedatei kopiert. 
Waehrenddessen wird ein Index der benutzten Sprungmarken, Unterprogramme,
Zwischenteile, globaler Ersetzungen, Kategorien und Anwendervariable
so wie ein (fahrlaessiger) Test auf formale Korrektheit unternommen.
Eine Kurzstatistik wird in den Kopf der Ausgabedatei eingebunden.
Bedingtes Generieren wird ueber aktive Kommentare unterstuetzt.


Was fehlt
=========
Nur Kommentare, die mindestens durch drei Leerzeichen vom Anweisungstext 
entfernt sind, werden als solche erkannt. Solche, die nur durch zwei 
Leerzeichen abgetrennt sind, werden faelschlicherweise mit analysiert.
Benutzung von Zwischenteilen wird nicht indexiert.
Der Analysemechanismus der Anweisungszeilen sollte Teilanweisungen 
analysieren, das waere intelligenter und wuerde die beiden erstgenannten 
Defizite beheben.
Es sollte die logische Verknuepfung von Optionen realisiert werden.
Dokumentation fuer die Benutzung als Codeverwaltungssystem fehlt auch.


Distribution
============
ANA.EXE ist ein selbstextrahierendes Archiv. Ins aktuelle Verzeichnis
werden analyze.pl und analyze.bat gelegt, sowie noch ein oder zwei andere
nuetzliche Perl-Scripts, die hier ohne Belang sind (vgl. Unterverzeichnis
VERSION).
Das Unterverzeichnis TEXWRAP enthaelt zusaetzliche Scripten fuer TeXniker.
Das Unterverzeichnis DEMO enthaelt die Ergebnisse, wie sie bei der Analyse
von P-NORMAL.APR und der zugehoerigen Includetabelle TEXT.APT entstanden
sind, sowie ein mit TeX produziertes Listing davon (als HP-Laserjet und
als Postscriptdatei).
Das Unterverzeichnis Version enthaelt zwei .BAT Dateien, wie man evtl.
mit MK.PL und ANALYZE.PL einen Testzyklus durchfuehren kann, wobei die
Parameterdateien aus Quellen generiert sind.
Das Verzeichnis DOC enthaelt eine etwas ausfuerhlichere Dokumentation als
ASCII, WP 5.1, WP 6.1, und als HP-Laserjet Datei.


Kleingedrucktes
===============
Es liegt wieder ein typischer Fall von Free Software unter der GNU GENERAL
PUBLIC LICENCE vor: Jeder darf sich bedienen, solange er die Copyright-Notiz 
laenger statt kuerzer macht und sagt, was er veraendert hat. Als Ausgleich 
lehnt jeder jede Verantwortung fuer Funktionalitaet ab. Genaueres ist in 
der Datei COPYING zu erfahren.

Mehr Informationen über die Mailingliste Allegro