WB-MakeInfo

Das Workbench-MakeInfo Paket

Version 1.0

Copyright © by Gerhard Leibrock

Mit Hilfe dieses Pakets wird das Erstellen von technischer Dokumentation im TeXInfo Format vereinfacht und beschleunigt

1 Systemanforderungen

Makeinfo funktioniert erst ab Version 2.04 oder höher des Amiga Betriebssystems.

Weiterhin benötigt man zum Betrieb von WB-MakeInfo folgende Programme:

• Cygnus Ed Professional, ein kommerzielles (kein PD oder SHAREWARE) Produkt der Firma ASDG
• ARexx, dies wird ab Version 2.0 des Betriebssystems standardmäßig mitgeliefert
• Das AmigaGuide Paket von Commodore (frei erhältlich) oder ein anderes Programm, mit dem man den erzeugten Hypertext anzeigen lassen kann
• Eine TeX Implementierung für den Amiga (Hierbei kann ich nur das PasTeX Paket empfehlen, eine fei erhältliche Software, mit der man sehr gut arbeiten kann), um mit der erzeugten .dvi Datei etwas anfangen zu können.
• Ein ASCII Text Anzeige-Programm mit dem man sich die .doc Datei ansehen kann (z.B. More von der Workbench)
• das Public Domain Make Programm “BMake” von Ben Eng oder ein hierzu kompatibles Programm (Falls Sie ein anderes Programm als das “BMake” verwenden, so sollten Sie unbedingt die datei “Do_It” im Verzeichnis “Package” editieren und die Zeile ändern, in der “BMake” aufgerufen wird, sodaß Sie an diese Stelle IHR Make Programm setzen.
• Commodore Installer Ein Programm, mit dem die Installation von Software standardisiert und erheblich komfortabler gemacht wurde. © CBM, fei erhältlich (nicht unbedingt erforderlich)
• lha kompatibler Entpacker Um das Programmpaket zu entpacken benötigen Sie einen lha kompatiblen Entpacker. Hierzu sind in der Public Domain mehrere erhältlich. z.B. “lx” von Jonathan Forbes, © 1993, Xenomiga Technology

2 Copyright

Es wird keine Garantie gegeben, daß die Programme, die hier beschrieben werden, absolut fehlerfrei sind. Sie benutzen dieses Paket auf eigene Gefahr hin. Der Autor (Gerhard Leibrock) kann auf keinen Fall für irgendwelche Schäden verantwortlich gemacht werden, die durch die Anwendung dieser Programme entstehen. Weder das hier beschriebene Paket, noch die einzelnen Programme dürfen ohne schriftliche Genehmigung des Autors in kommerziellen Programmen weitergegeben werden. Und auf keinen Fall darf das hier beschriebene Paket auf Rechnern verwendet werden, die in irgendeiner Form mit der Produktion von Waffen oder anderen militärischen Gütern zu tun haben.

3 Was ist MakeInfo?

MakeInfo wurde von den Leuten der GNU Free Software Foundation entwickelt, um das Erstellen von technischer Dokumentation zu vereinfachen.

Zur Zeit existieren 3 Hauptarten bei Computer-Dokumentationen:

Hypertext Dokumentation

Sie ist sehr leicht in der Handhabung und sicherlich eine der besten Formen elektronischer Dokumentation.

ASCII Dokumentation

Diese kann mit einfachsten Anzeigemitteln betrachtet werden, die auf den allermeisten Rechnern vorhanden sind. Man kann sie auf fast allen Druckern ohne Schwierigkeiten ausdrucken.

Dokumentation im .dvi Format

Dies ist wohl die beste Form der Dokumentation für all jene, die sich mit elektronischer Dokumentation nicht anfreunden können. Man kann sie zwar auch elektronisch betrachten, ihr Hauptvorteil liegt jedoch in der superben Qualität des Audrucks mit einem hochwertigeren Drucker. Um dies zu bewerkstelligen braucht man jedoch eine Softwareinstallation, die auf kleineren Systemen keinen Platz hat (min. 10 MB Festplatte). Mit TeX werden sehr viele Bücher und Abhandlungen geschrieben.

All diese Arten der Dokumentation sind durch die Wartung nur eines Quell-Textes verfügbar; dem TeXInfo Dokument. Das Format von TeXInfo ist relativ einfach zu lernen (Dokumentation in der Public Domain verfügbar) und bietet dem Programmierer den immensen Vorteil, daß er nur ein Format beherrschen muß, um 3 unterschiedliche Ausgaben zu erhalten. So spart man Zeit und die ist bekanntlich Geld. Menschen mit Erfahrung in TeX sollten das TeXInfo Format binnen weniger Tage beherrschen können.

4 Inhalt des Pakets

Dieses Paket enthält nur meinen (Gerhard Leibrock) Kram für die Verwendung von MakeInfo von der Workbench aus. Um MakeInfo, AmigaGuide, TeX, oder BMake zu erhalten, sollten Sie in einer Mailbox in Ihrer Nähe suchen, oder im Aminet, auf Fish Disketten oder sonstwo, wo man Public Domain oder sonstige frei verfügbare Software herbekommen könnte.

5 Warum WB-MakeInfo?

Falls Sie oft Texinfo verwenden, um Ihre Dokumentationen zu erstellen und mit der Workbench arbeiten, so ist dieses Paket genau das richtige für Sie. Sie erhalten die Macht von Texinfo kombiniert mit dem Komfort der Workbench und ARexx. Die Zeit des Schreibens wird erheblich verkürzt und Sie sparen sich die nervige Fehlersuche per Hand.
Sie kennen Texinfo nicht, arbeiten aber mit der Workbench und sie schreiben technische Dokumentation? Hier ist Ihre neue Arbeitsumgebung. Zusammen mit CEd Professional, ARexx und der Workbench ist es nun ein leichtes Texte in mehreren Formaten aus nur einer Quell-Datei zu erhalten. Sicher, sie müssen etwas Zeit in das Erlernen von TeXInfo investieren. Aber diese Zeit holen Sie hundertfach wieder herein.
Nicht überzeugt? Hmm, Starten Sie “MG-Setup” und installieren Sie das Paket irgendwohin. Nun übersetzen Sie es durch Aktivierung von “Do_It”. Sie erhalten drei(!) Dateien aus einer ursprünglichen …
Die Installation eines MakeInfo Pakets kostet 7.5 KB für jede neue Entwicklungsumgebung zusätzlich und das Paket an sich braucht 17 KB an Plattenplatz.

6 Wie verwendet man WB-MakeInfo?

Entpacken Sie das Paket irgendwohin, wo Sie gerade Platz haben. Hierzu verwenden Sie “lha”, ein Public Domain Programm, mit dem man ganze Verzeichnisse packen und wieder entpacken kann. z.B.:

(SHELL:)
  cd ram:
  lha x WBMakeInfo.lha
(jetzt Workbench:)
  RAM Disk öffnen
  Verzeichnis WBMakeInfo öffnen

Falls Sie den “Installer” von Commodore (ein fei verteilbares Programm) besitzen, so aktivieren Sie am Besten “CBM-Install”. Das Installieren geht nun fast automatisch. Besitzen Sie jedoch noch nicht dieses sehr komfortable Programm, so muessen Sie die Installation von Hand vornehmen. Hierzu lesen Sie sich am Besten die Installationsdatei durch.

Die Installation kostet Sie 30 KB. Um die mitgelieferten ARexx Skripte bestmöglich zu nutzen, sollten Sie diese in Ihrem Cygnus Ed an eine Funktionstaste binden. Haben Sie dies getan, so können Sie nun über den Druck auf eine Funktionstaste TeXInfo Dateien übersetzen und auf Fehlersuche gehen.

Achtung:

Die Entwicklungsumgebung für den CEd kann nur dazu verwendet werden, um .guide Dateien zu erzeugen. Die ist kein eigentlicher Nachteil. Sie können über die Entwicklungsumgebung die .guide Datei erzeugen lassen und bei korrektem Ablauf von der Workbench aus die .doc und .dvi Dateien (“Do_It” anklicken). Wurde die .guide Datei korrekt erzeugt (Meldung “No More Errors”), so werden auch die .dvi und .doc Datei korrekt erzeugt werden können.

Warnung:

Wenn Sie eine .texi Datei per CEd übersetzen wollen, so stellen Sie sicher, daß Sie Sie nicht gerade noch mit AmigaGuide anschauen, da dies zu einer Fehlermeldung führen wird. Dies rührt daher, daß AmigaGuide die .guide datei in Beschlag hat und Sie somit nicht neu erzeugt werden kann.

6.1 Einrichten einer .texinfo Entwicklungs-Umgebung

Starten Sie das Programm “MI-Setup” durch einen Doppelklick auf das Piktogramm. Das Programm stellt Ihnen eine einfache und sehr komfortable graphische Benutzerschnittstelle zur Verfügung, mit der Sie Ihre .texinfo Entwicklungsumgebung einrichten können:

1. Path Entweder geben Sie hier den Pfad per Hand ein, an dem die Umgebung installiert werden soll, oder Sie aktivieren den Filerequester durch Anklklicken des Gadgets mit dem Buchstaben “F”. Genauso können Sie den Filerequester durch drücken der Taste “F” aktivieren.

   Achtung:

   Die zu installierte Umgebung wird immer in ein Verzeichnis namens “Package” geschrieben. Haben Sie z.B. den Pfad “Work:Texte” angegeben, so wird dort ein Verzeichnis namens “Package” erzeugt.

2. Name of .texi file Hier geben Sie den Namen der .texi Datei an. Die Datei sollten Sie ohne ihre spätere Endung .texi angeben. Dieser Name gilt auch fuer die .doc und die .dvi Datei.

   Beispiel:

   Wenn Sie den Namen “MeinText” eingegeben haben, so werden später die Dateien mit .dvi und .doc ebenfalls “MeinText” heißen.

3. Name of .guide file Der Name des Hypertexts kann separat gewählt werden.
4. Install Installieren der Entwicklungsumgebung.
5. Forget it Programm beenden

6.1.1 Die erzeugten Piktogramme und Dateien

Nun haben Sie eine MakeInfo Entwicklungsumgebung installiert. Hierzu wurde ein Verzeichnis namens “Package” erzeugt. Wenn Sie dieses Verzeichnis von der Workbench aus öffnen, können Sie 8 Piktogramme erkennen:

Do_It

Ein Doppelklick startet die Ausführung der make-Datei “Make4Guide”. “Make4Guide”.

Make4Guide

Die Make-Datei für Ihr texinfo Dokument. Mit einem Doppelklick wird die Datei in Ihren Editor (“Ed”) geladen. Für Sie ist in der Datei eigentlich nur die 6. Zeile von Interesse; hier können Sie die Art der erzeugten Dateien festlegen: Eine .dvi Datei, eine .doc (ASCII) Datei oder eine .guide (Amigaguide format) Datei. Löschen Sie einfach den Eintrag für guide, doc oder dvi, wenn diese nicht erzeugt werden soll.

AllGuide.err

Diese Datei enthält die Fehlermeldungen. Ein Doppelklick zeigt diese an.

filename.texi

Die “Quelldatei” für Ihr Dokument. Mit einem Doppelklick laden Sie die Datei in Ihren Editor. Diese einfache Datei soll Ihnen die Erstllung eigener Dateien erleichtern.

filename.guide

Diese Datei wird die .guide Hypertext Fassung enthalten. Mit einem Doppelklick auf das Piktogramm wird es mit AmigaGuide angezeigt (SYS:UTILITIES/AMIGAGUIDE).

filename.doc

Diese Datei wird die .doc ASCII-Text Fassung enthalten. Mit einem Doppelklick auf das Piktogramm wird es mit More angezeigt (SYS:UTILITIES/MORE).

filename.dvi Diese Datei wird die .dvi TeX Fassung enthalten. Mit einem Doppelklick auf das Piktogramm wird es in ShowDVI geladen. Hierzu sollten Sie PasTeX auf Ihrem Rechner installiert haben. (SYS:UTILITIES/MORE).

Del-TeX-Trash

Dieses Piktogramm startet ein Programm, das alle durch virtex angelegten Dateien löscht, die nicht mehr nach der Erzeugung der .dvi Datei nötig sind (Löscht die temporären Dateien von virtex).

6.2 Arbeiten mit CEd und Arexx

Doppelklicken Sie auf die .texi Datei und die Datei wird in Ihren Editor geladen. Hier können Sie die Datei dann editieren und mittels Arexx Skripten “"ubersetzen”. Am besten, Sie belegen eine Funktionstaste mit dem Skript für die Übersetzung und eine andere mit dem Skript zur automatisierten Fehlersuche.

Folgende ARexx Skripte stehen Ihnen zur Verfügung:

1. Start_MGuide.ced Wir benötigt, um die Datei im Editor mittels makeinfo in eine .guide Datei zu übersetzen.
2. MGuideErr.ced Wird von “Start_MGuide.ced” verwendet, um die Arbeit mit der Fehlersuche auf ein Minimum zu reduzieren. Es kann auch von dem Benutzer selbst aktiviert werden.

Beispiel:

Ich habe bei mir das Skript “Start_MGuide.ced” auf die Funktionstaste F3 des Cygnus Ed gelegt, sd. ich den Übersetzungsvorgang einfach durch einen Druvk auf F3 aktivieren kann. Das Skript “MGuideErr.ced” habe ich auf die Taste F4 gelegt, sodaß der “Debugger” durch einen einzigen Tastendruck aktivierbar ist.

6.3 Erzeugen von .dvi oder .doc Dateien

Es ist nicht möglich über das Skript “Start_MGuide.ced” eine .dvi oder eine .doc Datei zu erzeugen. Dies wäre auch unsinnig und hätte die Entwicklung des Pakets unnötig verzögert.

Wenn Sie .dvi oder .doc Dateien erzeugen wollen, so sollten Sie zuerst mit der Entwicklungsumgebung eine lauffähige .guide Version erzeugen. So können Sie (fast) sicher sein, daß sich die anderen Versionen ebenfalls fehlerfrei erzeugen lassen.

ACHTUNG:

Bei .guide Dateien können in der Texinfo Datei bei dem @table Befehl die zweiten Argumente wie z.B. @code{} weggelassen werden. TeX quittiert Ihnen dies mit einer Fehlermeldung!

Habe Sie eine stabile Texinfo Datei erzeugt, so sollten Sie von der Workbench Oberfläche aus “Do_It” per Doppelklick starten. Diese Datei führt Ihr makefile aus und erzeugt die dort angegebenen Dateien. Voreingestellt erzeugt “Do_it” eine .guide, eine .dvi und eine .doc Datei, also alle drei Möglichkeiten. Wenn Sie das nicht möchten, so können sie die Datei “Make4Guide” durch Doppelklick in den Editor laden und dort ändern.

Suchen Sie nach der Zeile mit dem Schlüsselwort “all:”. Dort stehen guide, doc und dvi. Entfernen Sie die jeweilige Art, die Sie nicht erzeugen möchten.

7 Fehler

AmigaGuide startet nicht nach der Übersetzung

OS 3.x

Ab OS 3.0 existiert AmigaGuide nicht mehr. Seine Funktion wurde von MultiView übernommen. Ändern Sie Zeile 14 in der Datei “M4G.3”, indem Sie die Zeile “run <NIL: >NIL: sys:Utilities/AmigaGuide $(SOURCE).guide” dahingegend korrigieren, indem Sie “sys:Utilities/AmigaGuide” durch den Pfad Ihres Hypertext-Systems ersetzen.

andere OS Versionen

Der Pfad Ihres AmigaGuide stimmt nicht mit “sys:Utilities/AmigaGuide” überein, oder Sie besitzen AmigaGuide nicht. Im ersten Fall ändern Sie “M4G.1” wie oben beschreiben und im zweiten Fall sollten Sie sich mit einem PD Händler in Verbindung setzen.

Index

Table of Contents

About This Document

This document was generated on July 22, 2024 using texi2html 5.0.

The buttons in the navigation panels have the following meaning:

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

• 1. Section One
  • 1.1 Subsection One-One
    • ...
  • 1.2 Subsection One-Two
    • 1.2.1 Subsubsection One-Two-One
    • 1.2.2 Subsubsection One-Two-Two
    • 1.2.3 Subsubsection One-Two-Three     <== Current Position
    • 1.2.4 Subsubsection One-Two-Four
  • 1.3 Subsection One-Three
    • ...
  • 1.4 Subsection One-Four

This document was generated on July 22, 2024 using texi2html 5.0.