;-----------------------------------------------------------------------
;-                             TXT2STG.TTP                             -
;-                                                                     -
;-         Erzeugung eines STG-Quelltextes fr das Hypertext-          -
;-            system ST-Guide auf Basis eines ASCII-Textes             -
------------------------------------------------------------------------
TXT2STG.TTP, ein Tool fr ST-Guide

 Willkommen
 Status TXT2STG.TTP
 Das Programmpaket
 Aufbau eines Hypertext-Sources
 Aufruf TXT2STG.TTP
 Tips & Hinweise
 Versionsgeschichte TXT2STG.TTP

 --> APPEND.TTP
 --> STGALIAS.TTP

------------------------------------------------------------------------
Willkommen

Willkommen zu Gregis Wunderwelt der Hypertext-Bearbeitung. Ziel war es,
die Erstellung eines Hypertextes fr ST-Guide mglichst einfach und
bersichtlich zu gestalten, ohne die teils kryptischen 'link' Kommandos
usw. des ST-Guide per Hand eintragen zu mssen. Das hier vorliegende
'System' gestattet diese relativ einfache Erzeugung von Hypertexten.

Dabei wird aus einem 'Quelltext' im ASCII-Format eine STG-Datei erzeugt,
die nur noch mit dem HCP.TTP behandelt werden mu. Voraussetzung ist
allerdings, da der Autoreferenzer des ST-Guide eingeschaltet bleibt.

Ein weiterer Vorteil dieses Systems: Der Quelltext bleibt lesbar und
kann somit z.B. als reine ASCII-Anleitung einem Programm beigelegt
werden. Schlielich gibt es (zu meiner berraschung) Menschen, die
den ST-Guide nicht mgen...

------------------------------------------------------------------------
Status TXT2STG.TTP

Alle in diesem Paket enthaltenen Programme sind Freeware und drfen
auch getrennt weitergegeben werden, sofern Programm und Dokumentation
zusammenbleiben.

Ich bernehme keine Garantie fr die Funktionsfhigkeit und Verwendbar-
keit der Programme, nehmt sie wie sie sind! Fr Anregungen oder Bugre-
ports habe ich aber ein offenes Ohr (oder auch zwei, oder drei...?).

Meine Adresse:

 Gregor Duchalski, Im Wiescherfeld 21, D-44627 Herne
 eMail: Gregor_Duchalski@do.maus.ruhr.de (Mausnetz)

------------------------------------------------------------------------
Das Programmpaket

 TXT2STG.TTP    Das Programm. Erzeugt aus einem ASCII-Text (Format s.u.)
                einen STG-Text.
 TXT2STG.TXT    Dieser Text. Dient gleichzeitig als Beispiel fr einen
                Sourcetext!

 APPEND.TTP     Zusatztool, hngt eine Datei an eine andere dran. Wird
                bentigt, um mehrere getrennte Hypertext-Sourcedateien
                zu verketten.
 APPEND.TXT     Die Dokumentation dazu. Ebenfalls als Hypertext-Source-
                verwendbar.

 MAKE_HYP.MUP   Ein Beispiel-Batch fr die Mupfel von Gemini, der
                automatisch aus den drei Dokumentationen TXT2STG.TXT,
                APPEND.TXT und STGALIAS.TXT einen Hypertext mit dem
                Namen TXT2STG.HYP erzeugt. Natrlich mssen die Pfade
                hier angepat werden.

------------------------------------------------------------------------
Aufbau eines Hypertext-Sources

-> Vorweg: Dieser Text ist gleichzeitig ein Beispiel fr so einen
   Source. Also einfach mal auf das TTP schmeien und gucken, was
   passiert...

-> Ein Screen _mu_ mit einer Zeile beginnen, die am Anfang mindestens
   drei '-' enthlt. Die Zeile selbst wird aber ignoriert, die darauf-
   folgende Zeile wird als Titel des Screens interpretiert.
   Der Screentitel wird automatisch verdoppelt und beim zweiten Mal in
   Fettschrift dargestellt. Dies kann ber eine Kommandozeilenoption
   konfiguriert werden (-> Aufruf TXT2STG).
   Danach sollte noch eine Leerzeile folgen.

   Damit ggf. die Kapitelverweise funktionieren, sollten Hauptkapitel
   mit einer Reihe von mehr als 50 '-' beginnen. Alle Unterpunkte
   sollten dann genau <=50 '-' lang sein.

-> Mit ; beginnende Zeilen werden ignoriert, sind also REMs. Folgt als
   2. Zeichen ein '-' so wird versucht, den Rest der Zeile als Kommando-
   zeilenoptionen zu deuten. Auf diese Weise knnen also bestimmte
   Optionen direkt im Text ein- oder ausgeschaltet werden! Beispiel:

   ;-n
   _Text 1_
   ;-n
   _Text 2_

   'Text 1' wrde hierbei nicht unterstrichen dargestellt werden, da
   die Attributkonvertierung (s.u.) ber die Option -n abgeschaltet
   wurde. 'Text 2' wird unterstrichen, da die Konvertierung wieder
   aktiviert wurde.

-> Attribute: Die Schriftattributte fett, hell, kursiv und unterstrichen
   knnen gesetzt werden. Dazu sind die Textstellen mit Zeichen einzu-
   grenzen:
   * --> fett
   _ --> unterstrichen
   / --> kursiv

   Beispiel: *Fettschrift*
         --> @{B}Fettschrift@{0}

   Diese Art der Kennzeichnung ist brigens aus der DF-Szene bernom-
   men. Kombinationen (z.B. fett+unterstrichen) sind momentan noch
   nicht mglich.

   Die Attributkonvertierung kann ber die Option -n global
   abgeschaltet werden.

-> Ignore: Damit bestimmte Textteile nicht vom Autoreferenzierer des
   ST-Guide erfat werden, mssen diese normalerweise mit @{"" ignore}
   geklammert werden. TXT2STG wandelt von '' eingeschlossende Text-
   stellen automatisch in dieses Konstrukt um.

   Beispiel: Das ist ein schlechtes Beispiel
         --> Das ist ein @{"schlechtes" ignore} Beispiel

   Vorteil: Der Quelltext bleibt lesbarer.

-> ber die Textvariable $DATE kann das aktuelle Tagesdatum in den
   Text eingetragen werden.
   Beispiel: @$VER: 2.00 ($DATE)
         --> @$VER: 2.00 (17.07.94)

   Diese Ersetzung wird aus Geschwindigkeitsgrnden nur einmal
   vorgenommen.
   
-> Das war's auch schon fast. Normale, mit '@' eingeleitete ST-Guide-
   Kommandos knnen jederzeit und berall gesetzt werden.

-> Nochmal: Mit '---' beginnende Zeilen sind wichtig und fest an einen
   Screen gebunden! Sollen Striche lediglich zur optischen Unterteilung
   eingesetzt werden, so ist das Kommentarzeichen ; voranzustellen!

---------------------------------------------------------------------------
Aufruf TXT2STG.TTP

 TXT2STG Quelltext [Zieltext] ...
     ... [-a{BIU}] [-t{Programmname}] [-w{min. Breite}] [-x{Zeilen}] ...
     ... [-l{Textzeilen}] [-c{Kapitel}] [-n]

 Wird der Zieltext weggelassen, so wird der Name des Quelltextes bis zum
 '.' bernommen und 'STG' angehangen.

 Beispiel: TXT2STG TEST.TXT
       --> Erzeugt die Datei TEST.STG

 Folgende Optionen knnen angegeben werden:
 Option -a
 Option -t
 Option -w
 Option -x
 Option -l
 Option -c
 Option -n

 Hinweis: Wenn dieser Text mit dem TTP bearbeitet wird und keine
 Option angegeben wurde, wird zu Demonstrationszwecken automatisch
 '-aUI -t -cOberbegriff:~' gesetzt!

 Hinweis 2: Die Optionen knnen auch direkt im Quelltext angegeben
 werden, siehe Aufbau eines Hypertextes.

--------------------------------------------------
Option -a
 -a{BIU}

 Textattribut, das fr den verdoppelten Titel eines Screens verwendet
 werden soll. Ohne Angabe dieser Option wird dafr Fettschrift benutzt,
 ansonsten werden die Buchstaben danach als Attribut verwendet. '-a'
 ohne weitere Angaben schaltet die Verdoppelung des Titels aus! Damit
 werden ggf. nachfolgende Optionen ungltig.  

 Beispiele: TXT2STG TEST.TXT -aI
        --> Verdoppelt den Titel und schreibt ihn kursiv

            TXT2STG TEST.TXT -aBI
        --> Verdoppelt den Titel und schreibt ihn kursiv-fett

            TXT2STG TEST.TXT -a
        --> Schaltet die Screenverdoppelung aus

--------------------------------------------------
Option -t
 -t{Programmname}

 Erzeugt sogn. 'Spezialtitel'. Dabei wird der Titel des Screens wie
 gehabt verdoppelt, aber zustzlich ein beliebiger Text rechtsbndig
 eingetragen. Dabei kann es sich z.B. um den Namen des Programms
 handeln, zu dem der Hypertext gehrt. Das wrde dann z.B. so
 aussehen:

 Einleitung                                              TXT2STG
 ---------------------------------------------------------------

 Wird 'Programmname' nicht angegeben, wird der Name des Zieltextes
 verwendet.

 Die Breite des Spezialtitels richtet sich nach der lngsten Zeile
 eines Screens, die fr jeden Screen neu bestimmt wird.

--------------------------------------------------
Option -w
 -w{min. Breite}

 Setzt die minimale Breite des Spezialtitels (Option -t).
 Sinnvoll sind z.B. 50 Zeichen, das ist auch die Voreinstellung.

--------------------------------------------------
Option -x
 -x{Zeilen}

 Normalerweise wird der 'verdoppelte' Titel des Screens direkt als
 erste Zeile eingefgt. Mit dieser Option kann eine zustzliche
 Anzahl Leerzeilen bestimmt werden, die davorgesetzt werden.
   
--------------------------------------------------
Option -l
 -l{Textzeilen}

 TXT2STG.TTP verwaltet den zu bearbeitenden Text nicht dynamisch. Vor-
 eingestellt knnen Texte mit bis zu 3000 Zeilen bearbeitet werden.
 Sollte das nicht ausreichen, kann dieser Wert mit dieser Option erhht
 werden. Der Grund, warum dies nicht automatisch gemacht wird:
 Geschwindigkeit. Je grer der Maximalwert, desto lnger dauert die
 Konvertierung.

--------------------------------------------------
Option -c
 -c{Text}

 Erzeugt automatisch in der letzten Zeile eines Screens einen Verweis
 auf das bergeordnetet Kapitel. Dieser kann von einem spezifizierbaren
 'Text' (z.B. "Oberbegriff:") eingeleitet werden. Soll dieser Begriff
 Leerzeichen enthalten, so ist dafr der Platzhalter '~' einzufgen
 (z.B. "Kapitel:~~~~").

 TXT2STG erkennt ein bergeordnetes Kapitel daran, da an der 52. Stelle
 ein '-' steht. Beispiel:

 -----------------------------------------------------------------------
 Oberkapitel

  ->Unterkapitel 1
  ->Unterkapitel 2
 ----------------------
 Unterkapitel 1
 ----------------------
 Unterkapitel 2

 Ein Screen, der also keinen Verweis erhalten soll, mu daher selbst
 als 'Oberbegriff' definiert sein.

 Vor dem Verweis wird ggf. eine Leerzeile eingefgt.

--------------------------------------------------
Option -n
 -n

 Schaltet die Attribut-Konvertierung (siehe
 Aufbau eines Hypertext-Sources) global ab.

------------------------------------------------------------------------
Tips & Hinweise

 -TXT2STG zeigt die Zeilenanzahl des geladenen Textes an und die Zeile,
  die es gerade bearbeitet. Da eine Reihe von Zeilen eingefgt werden
  mssen, ist die endgltige Zeilenzahl also hher als die des Ur-
  sprungstextes. Dabei handelt es sich also um ein Feature.

------------------------------------------------------------------------
Versionsgeschichte TXT2STG.TTP

Version Datum           nderungen

0.94    18.07.94        -Es knnen Textattribute erzeugt werden.
                        -REM auf ';' gendert.

        20.07.94        -Die Titelverdoppelung kann abgeschaltet und
                         konfiguriert werden.

        21.07.94        -Spezialtitel eingebaut und weitere Optionen
                         hinzugefgt.

0.95    23.07.94        -Option '-c' eingefhrt.

                        -Attributerkennung gendert, es wird jetzt nicht
                         mehr geprft, ob sich vor und nach den Kennun-
                         gen Leerzeichen befinden.

                        -Maximalbreite bei Spezialtiteln jetzt 72 Zei-
                         chen, auerdem wird bei der Breitenbestimmung
                         jetzt versucht, mit '@' eingeleitete Kommandos
                         nicht zu bercksichtigen.

        25.07.94        -Ausgabe der aktuellen Zeile jetzt nur noch
                         bei einem neuen Hilfsscreen -> schneller.

        31.07.94        -ARGV-bergabe wird untersttzt.

0.96    04.09.94        -Attributerkennung: Vor dem einleitenden Attr.
                         mu jetzt wieder ein Space stehen.

        18.09.94        -Die Autoreferenzierung eines verdoppelten
                         Screentitels wird jetzt immer explizit
                         verhindert. Die Option -r entfllt somit.

        06.10.94        -Das Verhindern einer Autoreferenzierung eines
                         verdoppelten Screentitels sollte jetzt wirklich
                         immer funktionieren.

        23.10.94        -Attributkonvertierung fr Hellschrift
                         (mit '') rausgenommen.

                        -Attributkonvertierung kann mit der Option -n
                         in der Kommandozeile abgeschaltet werden.

                        -Von '' eingeschlossene Textstellen werden
                         jetzt zu {"" ignore} gewandelt.

                        -Kommandozeilen-Optionen knnen jetzt auch
                         direkt im Text gesetzt werden.

;-----------------------------------------------------------------------
