
F: Was ist dieses ST-Guide eigentlich?
A: ST-Guide ist ein Hypertextsystem mit  diversen  Vorteilen  fr
   alle Beteiligten:
   - Programmierer: Dokumentationen im Hypertextformat werden von
     mehr Leuten gelesen, als ASCII-Dokus und deshalb mssen sich
     weniger User mit ihren Fragen an den Autor wenden
   - Programmierer: der ST-Guide darf  jedem  Programm  beigelegt
     werden, so da es leicht mglich  ist,  fr  JEDES  Programm
     eine Onlinehilfe oder Doku im  Hypertextformat  zu  liefern,
     ohne da die Anwender sich hierzu erst  um  die  Beschaffung
     oder Bezahlung der ntigen Software kmmern mten
   - Anwender: die Dokumentation kann gelesen werden, whrend das
     Programm luft, evtl. lt das  Programm  selbst  sogar  die
     fr die jeweilige Situation wichtige Seite vom ST-Guide  an-
     zeigen ('context sensitiv')
   - Anwender: die gerade bentigte Information lt sich wesent-
     lich schneller in einem Hypertext finden, als in einer ASCII
     Dokumentation
   Es gibt sicherlich viele weitere Punkte, die hier erwhnt wer-
   den knnten, aber das artet dann zu sehr in Eigenwerbung aus.


-----------------------------------------------------------------
F: Was mu ich denn jetzt anstellen, um selber einen Hypertext zu
   schreiben?
A: Erstmal die beiliegenden Dokumentationen zu HCP  und  ST-Guide
   lesen. Hypertexte sind nmlich im Prinzip wie Programme aufge-
   baut, so da es unumgnglich ist,  zumindest  die  wichtigsten
   Kommandos zu kennen, bevor ein  Hypertext  geschrieben  werden
   kann.
   Jetzt mu der gewnschte Text noch mit  den  gerade  erlernten
   Kommandos in Form eines Hypertextes aufgeschrieben werden, und
   dann mu er nur noch durch Aufruf des  hcp  bersetzt  werden,
   wonach er dann vom ST-Guide angezeigt werden kann.


-----------------------------------------------------------------
F: Ich habe keine Lust, so viel Text zu lesen, was mu  ich  denn
   mindestens wissen, um einen einfachen Hypertext zu schreiben?
A: Im Prinzip reichen die Kommandos @node, @endnode und @symbol.
   Beispiel:
   ---------
        @database <Thema des Textes>
        @author   <wer hat den Text geschrieben>
        @subject  <wo soll der Text im Katalog einsortiert werden>
        @$VER:    <Name der Datei> <Versionsnummer> <ErstellDatum>

        @node <Seitenname> [<Fenstertitel>]
        @symbol <weitere Namen dieser Seite>
        <text>
        @endnode
   Dabei ist darauf zu achten, da alle hier in <>  geschriebenen
   Begriffe durch  Anfhrungszeichen  geklammert  werden  mssen,
   wenn sie Leerzeichen enthalten, also @node "foo bar".


-----------------------------------------------------------------
F: Ich habe vorher den 1stGuide benutzt und  mchte  meine  alten
   Hypertexte jetzt auch mit dem ST-Guide  benutzen,  wie  stelle
   ich das an?
A: Hierzu gibt es Konvertierer.  Fr  1stGuide  Hilfen  wird  der
   1stConv verwendet, welcher einfach mit der Hauptdatei (die mit
   dem Inhaltsverzeichnis) als Parameter aufgerufen wird.
   Fr PureC/PurePascal Hilfen gibt es  ebenfalls  einen  Konver-
   tierer, den PC-Conv. Hierfr ist jedoch zustzlich ein  Recom-
   piler notwendig, der HELP_RC oder der HELPDISC.


-----------------------------------------------------------------
F: Welche Dateiformate werden vom ST-Guide untersttzt?
A: Der ST-Guide selber kann nur Hypertexte  (*.HYP)  sowie  ASCII
   Texte anzeigen. Hypertexte knnen allerdings Bilder enthalten,
   welche im IFF-, ICN- oder IMG-Format vorliegen  mssen.  Diese
   befinden sich jedoch direkt im Hypertext und liegen  in  einem
   speziellen Format vor, so da der ST-Guide  keine  Algorithmen
   zur Darstellung von Bilddateien enthlt.
   Aus Hypertexten heraus knnen Resourcedateien bzw.  Teile  da-
   raus angezeigt werden. Diese werden erst bei  Bedarf  geladen,
   knnen  jedoch  nicht  direkt  (d.h.  ohne  Aufruf  aus  einem
   Hypertext) angezeigt werden.
   Ebenfalls aus dem Hypertext heraus  knnen  Kommandos  an  die
   (bzw. eine) laufende  Applikation  gesendet  werden,  um  z.B.
   Musik zu spielen, ein Archiv zu ffnen, eine Diashow zu zeigen
   o.., aber all diese Dinge werde  dann  von  einer  speziellen
   Applikation und nicht vom ST-Guide erledigt.


-----------------------------------------------------------------
F: ST-Guide soll Sounds, Bewegtbilder und meinen Kaffee-Automaten
   untersttzen.
A: Keine Chance. Der ST-Guide  ist  als  reiner  Hypertext-Viewer
   ausgelegt und das wird auch  so  bleiben.  Bei  entsprechender
   Resonanz und ausreichend vielen Spenden kommen vielleicht  mal
   externe Viewermodule,  aber  direkt  eingebaut  werden  solche
   Dinge nicht (ST-Guide soll so kurz wie mglich bleiben).


-----------------------------------------------------------------
F: kann ich auch ASCII-Dateien (z.B. Headerfiles fr C) als Ver-
   weis benutzen?
A: Ja, hierzu ist (wie fr alle anderen Verweise auch) der link
   Befehl zu verwenden. Beispiel:
        ... im @{"Standard Header" link stdio.h/Main} ...
   Man beachte hierbei, da hinter dem Dateinamen IMMER der Name
   der anzuzeigenden Seite stehen mu, da ASCII-Dateien keine
   Seitennamen besitzen, wird dort als Name 'Main' benutzt.
   Falls als Name etwas anderes als  'Main'  angegeben  wird,  so
   verwendet der ST-Guide dies als Suchbegriff, die erste  Zeile,
   in der es gefunden wird, wird zur  ersten  im  Fenster  darge-
   stellten Zeile.


-----------------------------------------------------------------
F: Ich mchte gerne Abstze  im  Text  durch  Linien  voneinander
   trennen, aber mit '-----' sieht das  so  unprofessionell  aus,
   geht das eigentlich auch eleganter?
A: Natrlich. Hierzu gibts das @line-Kommando, welches frei defi-
   nierbare Linien in Hypertextseiten zeichnen kann, hier  knnen
   sogar verschiedene  Linienmuster  und  Pfeilspitzen  verwendet
   werden.


-----------------------------------------------------------------
F: Ich mchte gerne in meinen Hypertext Verweise auf ASCII-Datei-
   en einbauen und wei auch, da so etwas mit  @extern  und/oder
   @{... link ...} gemacht wird. Das Problem  ist  nun,  da  die
   ASCII-Dateien ab  einer  bestimmten  Stelle  angezeigt  werden
   sollen, also nicht vom Textanfang. Geht das?
A: Klar. Sowohl bei @extern also auch bei  link  knnen  optional
   Zeilennummern angegeben werden. Diese benutz der ST-Guide dann
   als Nummer der ersten dargestellten Zeile.
F: Fein, aber da gibt's noch ein Problem: die ASCII-Dateien  kn-
   nen sich ndern, so da die im Hypertext  angegebenen  Zeilen-
   nummern nicht mehr stimmen wrden, mu ich also  jedesmal  den
   Hypertext anpassen und neu  bersetzen,  wenn  sich  eine  der
   ASCII-Dateien ndert?
A: Nicht unbedingt.  Die  anzuzeigenden  Textstellen  knnen  vom
   ST-Guide auch direkt und automatisch beim Laden des Textes ge-
   sucht werden. Dies wird erreicht durch:
      @{<text zum Anklicken> link <ASCII-Datei>/<Seitenname>}
   Wenn <Seitenname> NICHT 'Main' ist, dann wird er im  Text  ge-
   sucht und die erste Trefferzeile wird erste Zeile im Fenster.
F: Sehr schn, da gibts dnn nur noch ein Problem: die Textstellen
   kommen in meiner ASCII-Datei alle mehrfach vor, einmal am  An-
   fang im Inhaltsverzeichnis und dann noch mal mit Beschreibung.
   Wenn jetzt immer ab Textanfang gesucht wird,  dann  wird also
   immer das "falsche" Vorkommen gefunden.
A: Sowohl @extern als auch link knnen als zustzlichen Parameter
   eine Zeilennummer bekommen. Im Zusammenhang  mit  dem  Suchbe-
   griff wird diese als Startzeile  benutzt.  Also  einfach  eine
   Nummer angegeben, die einigermaen  nahe  an  der  gewnschten
   Stelle ist, und schon geht's.


-----------------------------------------------------------------
F: Meine XIMG's werden vom Compiler nicht aktzeptiert.
A: Nachmeinen Informationen unterscheiden  sich  IMG-  und  XIMG-
   Format nur im Header. Eingene Tests mit  XIMG's  (von  1stView
   erzeugt) haben keinerlei Probleme ergeben.


-----------------------------------------------------------------
F: Wo ist die Tastaturselektierung geblieben? kann ich  die  Ver-
   weise jetzt nur noch per Maus auswhlen?
A: Nein, die Tastaturselektierung ist nach wie vor vorhanden, sie
   erscheint jedoch erst nach der ersten Bettigung von  [SHIFT-]
   TAB. Auerdem wird sie beim Scrollen nicht mehr im Fenster ge-
   halten, sondern ausgeschaltet, sobald sie nicht mehr  sichtbar
   ist. Dies hat den Vorteil, da das Scrolling nicht mehr  "ruk-
   kelt", sondern jetzt gleichmig luft.


-----------------------------------------------------------------
F: Ich finde die Handhabung des 1stGuide, jede Seite in einer ei-
   genen Datei zu haben viel besser, als alles in einer Datei  zu
   halten. Geht das mit dem ST-Guide auch?
A: Ja, natrlich. Man verwende den @include-Befehl.


-----------------------------------------------------------------
F: Wenn der ST-Guide unter MTOS von einem anderen Programm aufge-
   rufen wird, meldet MTOS einen 'privileg violation error'.  Was
   soll das?
A: Unter  MTOS  mit  entsprechendem  Prozessor  unterliegt  jeder
   Speicherbereich   einem   gewissen,   definierbaren    Schutz.
   Defaultmig darf z.B. nur das Programm selbst und das AES den
   Speicher eines laufenden Prozesses lesen/schreiben.  Wenn  ein
   solches Programm eine Meldung an  den  ST-Guide  sendet,  dann
   kopiert  das  AES  hiervon  nur  die  Zeiger  auf  Pfade   und
   Suchbegriffe, nicht jedoch  die  Strings  selbst,   d.h.   der
   Speicher, in dem sie sich  befinden,  gehrt  dem  aufrufenden
   Prozess und auch ein lesender Zugriff des  ST-Guide  wird  von
   MTOS angemeckert.

   Anhilfe:
   1. (Notlsung): Die Flags des Programmes (NICHT des  ST-Guide)
      auf private/readable setzen, hierzu eignet  sich  z.B.  das
      Programm GD_FLAGS von Gregor Duchalski.
   2. (Beste Lsung): Das aufrufende Programm  benutzt  Mxalloc()
      mit entsprechenden Parametern, um den Speicher fr  die  zu
      bergebenden Strings anzufordern.
   Nheres zu beiden Lsungen findet sich in der MTOS-Doku.


-----------------------------------------------------------------
F: ST-GUIDE liest meine [X]Environment-Variablen nicht. Wieso?
A: Weil dieses Feature aufgrund breiter  Ablehnung  und  diverser
   Probleme ausgebaut wurde. Parameter werden jetzt nur noch  aus
   der Datei ST-Guide.inf im Wurzelverzeichnis des Bootlaufwerkes
   gelesen.


-----------------------------------------------------------------
F: Der Aufruf des ST-Guide per appl_write() aus  meinem  Programm
   heraus funktioniert nicht. Woran liegt das?
A: Der  ST-Guide  kopiert  die  bergebenen  Strings  zwar,  aber
   zwischen dem Aufruf und dem  Kopieren  der  Parameter  vergeht
   eine gewisse Zeit.  Das  aufrufende  Programm  mu  daher  den
   String so anlegen, da er zumindest  noch  eine  gewisse  Zeit
   lang unverndert vorliegt, er darf also insbesondere nicht als
   lokale Variable auf dem Stack liegen. Am besten  ein  globales
   Array verwenden, dann funktioniert es auch.

   Beispiel (AV-Protokoll):
   ------------------------

   char HelpString[100];

   Help(char *pattern)
   {
       int msg[8], i;

       if ((i=appl_find("ST-GUIDE"))>=0) {
           msg[0] = VA_START;
           msg[1] = global[2];
           msg[2] = 0;
           sprintf(HelpString, "*:\\MYPROG.HYP %s", pattern);
           *(char **)&msg[3] = HelpString;
           msg[5] = 0;
           msg[6] = 0;
           msg[7] = 0;
           appl_write(i, 16, msg);
       }
   }

   Beispiel (PureC-Protokoll):
   ---------------------------

   char HelpString[100];

   Help(char *pattern)
   {
       int msg[8], i;

       if ((i=appl_find("ST-GUIDE"))>=0) {
           msg[0] = AC_HELP;
           msg[1] = global[2];
           msg[2] = 0;
           strcpy(HelpString, Pattern);
           *(char **)&msg[3] = HelpString;
           msg[5] = 0;
           msg[6] = 0;
           msg[7] = 0;
           appl_write(i, 16, msg);
       }
   }


-----------------------------------------------------------------
F: Gibt es eine Mglichkeit, in einem  Node  mit  eingeschaltetem
   Autoreferenzer ein Wort so zu maskieren, da es nicht als Re-
   ferenz erkannt wird?
A: Per @autorefoff/@autorefon fr beliebige Zeilen
        @autorefoff
        testtest nix zelenrest
        @autorefon
   wird in der Textzeile nichts markieren, davor und danach jedoch
   schon
   Per @{... ignore} fr beliebige Teile von Zeilen
   'testtest @{"nix" ignore} zeilenrest'
   wird <nix> nicht zum Verweis machen, auch wenn es ein alias/
   node/symbol mit diesem Namen gibt


-----------------------------------------------------------------
Sollte sich Ihr Problem jetzt noch nicht erledigt haben, so bitte
ich um Nachricht. Damit sie bercksichtigt werden  kann,  sollten
ihr folgende Informationen zu entnehmen sein:
1. Welche Version wird benutzt (evtl. in der Maus  OL  nachsehen,
   ob es bereits eine neuere gibt und ggfls. mit dieser noch  mal
   probieren)
2. mit welcher Komponente tritt das Problem auf
3. Wie uert es sich; diesen Punkt so  ausfhrlich  wie  mglich
   behandeln, mit Meldungen wie "der Konverter  bersetzt  meinen
   Text nicht." kann ich nichts anfangen!
   Die sicherste Methode ist hier, mir  eine  Datei  zukommen  zu
   lassen, mit der ich das Problem reproduzieren kann. Wenn  z.B.
   der HCP einen Fehler enthlt, dann hilft  mir  eine  Beispiel-
   Node, die diesen Fehler produziert, am ehesten.
4. Insbesondere bei Problemen  mit  dem  ACC  einmal  nur  dieses
   booten, also alle anderen ACC's und den  Autoordner  disablen.
   Wenn das Problem dann nicht mehr auftritt, dann durch schritt-
   weises mitbooten der anderen ACC's Auto-Prog's versuchen  her-
   auszufinden, mit welcher Kombination das Problem auftritt  und
   mir mitteilen.







