@database Def2AG @node main "Def2AG - Definitionsdateien nach AmigaGuide®" Def2AG konvertiert "Modula 2"-Definitionsdateien ins AmigaGuide®-Format. Inhalt: @{" Installation " link Installation} @{" Aufruf " link Aufruf} @{" Vorgehen " link Vorgehen} @{" ARexx " link ARexx} @{" Cross-Referenz " link Cross} @{" Copyright " link Copyright} @{" Adresse " link Adresse} @{" Geschichte " link Geschichte} Def2AG V0.98 © 1994 Fin Schuppenhauer. (Copyrighted Freeware) xi ist ein eingetragenes Warenzeichen von yi. xj © 19nn yj. @endnode @node Installation Ganz einfach: Kopiere die Datei "Def2AG" in ein Verzeichnis, das sich im Suchpfad befindet, z.B. COPY Def2AG C: Danach kopiere diese Hypertext-Anleitung in ein Verzeichnis Deiner Wahl (ich habe z.B. für .guide-Dateien ein eigenes Verzeichnis HYPER:) Wenn Du über den Editor GoldED verfügst, dann wirst Du das mitgelieferte Skript "GetM2XRef.ged" bestimmt zu schätzen wissen. Mehr dazu @{"hier" link GetM2XRef}. @endnode @node Aufruf Format: DEF2AG [FROM ] [] [XREF] [ADOC ] [QUIET] Befehlsschablone: FROM/K/A,TODIR/A,XREF/S,ADOC/K,QUIET/S Funktion: "Modula 2"-Definitionsdateien ins AmigaGuide®-Format konvertieren. Beschreibung: DEF2AG konvertiert "Modula 2"-Definitionsdateien in das Hypertext-Format von AmigaGuide®. Aus einer Verteilerdatei ("Modula-2.guide") werden die Hypertextversionen der Definitionsmoduln aufgerufen. Die Definitionsmoduln werden in gesucht. Handelt es sich dabei um ein Verzeichnis muß ein abschließendes "/" oder ein abschließender ":" mit angegeben werden. Muster sind ebenfalls zulässig. (z.B. "M2:Defs/In" würde alle Definitionsmoduln im Verzeichnis "M2:Defs/" finden, die mit "In" beginnen.) Das Schlüsselwort FROM muß unbedingt mit angegeben werden. Wird dieser Parameter weggelassen, wird in "M2:Defs/" nach Definitionsmoduln gesucht. Die erzeugten Hypertext-Dateien werden ins kopiert, oder nach "RAM:", wenn der Parameter weggelassen wird. Im Zielverzeichnis wird eine Hauptdatei "Modula-2.guide" und ein Unterverzeichnis "Modula-2" erstellt. Im Verzeichnis werden die Hypertextdateien der Definitionsmoduln und die @{"Cross-Referenz-Datei" link Cross} (siehe unten) abgelegt. Auch hier muß ein abschließender Schrägstrich oder Doppelpunkt mit angegeben werden. Mit der Option XREF wird eine @{"Cross-Referenz-Datei" link Cross} erzeugt, in der alle gefundenen Konstanten-, Typen-, Variablen- und Prozedurdeklarationen abgelegt werden. Ab Version 0.98 ist diese Datei AmigaGuide-konform. Hierbei werden dann keine Hypertext-Dateien erzeugt, sondern die Definitionsmoduln nur nach Typdefinitionen etc. durchsucht. Bei einem erneuten Aufruf (ohne die Option XREF) wird diese Datei geladen und zur Erzeugung von Links verwendet. Die Option ADOC ist nur in Verbindung mit den Definitionsmoduln sinnvoll, in denen Betriebsystemroutinen definiert sind (z.B. GraphicsL.def). Neben den anzugebenden Schlüsselwort wird ein Verzeichnis erwartet, in dem das Verzeichnis ("Autodocs") für die Hypertext-Versionen der Commodore-Autodocs stehen. Es werden dann zusätzlich Links für Prozedurbezeichner erzeugt, die auch ihr Gegenstück in den Autodocs haben. Mit der Option QUIET wird die Bildschirmausgabe unterdrückt. Beispiele: DEF2AG XREF Erzeugt die Cross-Referenz-Datei für alle Definitionsmoduln in "M2:Defs/". Im Verzeichnis "RAM:" wird das Verzeichnis "Modula-2" erzeugt und hierin die Cross-Referenz-Datei abgelegt. DEF2AG FROM M2:Defs/C HYPER: ADOC=HYPER: QUIET Es werden alle Definitionsmoduln aus "M2:Defs/" konvertiert, die mit einem "C" beginnen. Die erzeugten Dateien werden im Verzeichnis HYPER: abgelegt. Hier befindet sich auch das Verzeichnis für die Commodore-Autodocs-Guides. Die Bildschirmausgabe wird unterdrückt. @endnode @node Vorgehen "Wie erzeuge ich Hypertext-Dateien?" In Ultrakurzform: 1. @{"Cross-Referenz-Datei" link Cross} erzeugen, z.B. mit "@{"DEF2AG" link Aufruf} XREF" 2. Eigentlichen Konvertierungsvorgang starten und ggf. die Autodocs berücksichtigen: "@{"DEF2AG" link Aufruf} ADOC=HYPER:" Und jetzt etwas ausführlicher: Für die Erzeugung der Hypertext-Dateien ist es sehr zweckmäßig DEF2AG zweimal aufzurufen. Beim ersten Aufruf mit der Option XREF, also z.B. @{"DEF2AG" link Aufruf} FROM M2:Defs/ HYPER: XREF wird die @{"Cross-Referenz-Datei" link Cross} erzeugt. Diese wird beim zweiten Durchgang benötigt und erzeugt die Links für die Typbezeichner. Wenn wir z.B. eine Funktion wie ExamineFH(fh{R.D1}:d.FileHandlePtr; fib{R.D2}:d.FileInfoBlockPtr)... haben, wird ein Link für die Typbezeichner "FileHandlePtr" und "FileInfoBlockPtr" erzeugt. Werden diese angewählt, so wird die Datei geladen, in der die Typen vereinbart wurden und auf die entsprechende Stelle im Quelltext positioniert (hier würde also "DosD" geladen). Werden die vom Compiler mitgeliferten Definitionsmoduln konvertiert, sollte im zweiten Durchlauf --- z.B. @{"DEF2AG" link Aufruf} FROM M2:Defs/ HYPER: ADOC=HYPER: --- die Option ADOC mit angegeben werden, wenn Du über die Autodocs verfügst. Dann werden für die Prozedurbezeichner Links auf die Autodocs-Guides erzeugt. Im obigen Beispiel könnte dann auch "ExamineFH" selektiert werden, worauf das zugehörige Hypertext-Autodoc geladen wird und auf die Erklärung von "ExamineFH" positioniert wird. @endnode @node ARexx "Mitgelieferte ARexx-Skripte" Ab Version 0.98 gehören zum Lieferumfang von "Def2AG" auch einige ARexx-Skripte. Folgende Skripte sind derzeit vorhanden: @{"GetM2XRef.ged" link GetM2XRef} : Ein Skript für den Editor GoldED von Dietmar Eilert. @endnode @node GetM2XRef "ARexx-Skript: GetM2XRef.ged" Dieses Skript ist für den Editor GoldED gedachtet und verwendet die von "Def2AG" erzeugte @{"Cross-Referenz-Datei" link Cross}. Durch eine einfache Tastenkombination wird das Wort unter dem Cursor ermittelt und die Cross-Referenz-Datei danach durchsucht. Wird es gefunden, wird der zugehörige Hypertext geladen und auf dem Wort platziert. So kannst Du z.B. den Cursor über einen Prozedurname oder Typbezeichner platzieren und bekommst dann den entsprechenden Ausschnit aus dem Definitionsmodul angezeigt. Einbinden in GoldED: 1. Kopiere die Datei "GetM2XRef.ged" in das ARexx- Verzeichnis von GoldED: COPY GetM2XRef.ged GOLDED:ARexx 2. Starte den Editor und wähle den Menüpunkt Konfig-Tastatur. Es öffnet sich ein Fenster zur Tastatur- definition. Starte den Rekorder und drücke die Tastenkombination, die später das Skript aufrufen soll. 3. Es erscheint ein weiteres Fenster. Als einziges Kommando für diese Taste mußt Du nun "GOLDED:ARexx/GetM2XRef.ged" eintragen und "ARexx" aus dem MX-Gadget wählen. Jetzt noch "OK" und das Sichern nicht vergessen. @endnode @node Cross "Aufbau der Cross-Referenz-Datei" In der Cross-Referenz-Datei ("Modula-2/modula.xref") werden alle gefundenen Konstanten-, Typ-, Variablen und Prozedur-Definition vermerkt. Diese kann von anderen Programmen (insbesondere auch von AmigaGuide bzw. dessen Library-Funktionen) benutzt werden um zu einem Schlüsselwort die passende Hypertext-Datei zu finden. Die Cross-Referenz-Datei hat folgenden Aufbau: /* Das ist ein Kommentar. Kommentare können */ /* überall stehen. */ XREF: "keyword" "file" line type ... # keyword : Das Schlüsselwort selber. file : Name der Datei, in der das Schlüsselwort definiert ist. line : Zeilenoffset des Schlüsselwort zur Node, in der es definiert wurde. type : Die Art des Schlüsselwortes. Das kann sein 0 : Generic AmigaGuide link 1 : Describes a function 2 : Describes a command 3 : Points to an include file 4 : Describes a macro 5 : Describes a structure 6 : Describes a structure field 7 : Describes a type definition 8 : Describes a define Wie man sieht ist das stark an C-Code ausgerichtet, aber einiges kann man durchaus auch auf Modula-2 übertragen. @endnode @node Copyright DEF2AG V0.98 © 1994 Fin Schuppenhauer Das Programm, seine Dokumentation und Quelltexte stehen unter meinen Copyright, dürfen aber dennoch beliebig oft kopiert und/oder verändert werden. Lediglich mein Copyright-Hinweis darf nirgends entfernt werden und es müssen alle unten angegeben Dateien kopiert werden. Dieses Programm darf ohne Genehmigung des Autors nicht kommerziel genutzt werden. Die Benutzung erfolgt auf eigene Gefahr. Folgende Dateien sind Bestandteil dieser Veröffentlichung (die mit * markierten Dateien müssen bei Weiterverteilung mitkopiert werden): * Def2AG : Das lauffähige Programm * Def2AG.guide : Diese Dokumentation * GetM2XRef.ged : Ein @{"ARexx" link ARexx}-Skript für den Editor GoldED von Dietmar Eilert M2Guide.lha : Fertig konvertierte M2Amiga-Definitions- moduln Source.lha : Der Quelltext des Programms (ab V0.98 verfügbar) @endnode @node Adresse "Meine Anschrift" Für Fehlerhinweise, Anregungen, Postkarten und Geschenke bin ich jederzeit dankbar. Diese können an folgende Adresse gesendet werden: Fin Schuppenhauer Braußpark 10 20537 Hamburg (Germany) Oder mit E-Mail: schuppenhauer@rzdspc2.informatik.uni-hamburg.de @endnode @node Geschichte Eigentlich sollte schon die Version 0.97b für jeden zu haben sein, aber obwohl ich sie auch ins AMINET eingespeist habe, erschien es dort nie (ich bekam auch keine Mecker-Mail). Nun denn, soll also V0.98 die erste öffentliche Version werden: Version Datum Änderungen ---------------------------------------------------------------- 0.97b 12.03.94 siehe Einleitung 0.98 23.04.94 zweiter Versuch (siehe Einleitung) @endnode