Hilfekonzept


Tip: Drücken Sie jetzt Alt+r, dann sehen Sie links die Liste der Hintergrundvariablen. Darunter z.B. #uYx Hilfe zu den Hauptfunktionen. Dazu gehört eine andere Variable: #uZx, und darin steht, was passieren soll, wenn "Hilfe zu den Hauptfunktionen" geklickt wird. Das ist das Prinzip!

Wichtig: Zu den Hilfetexten gehört die Kopfdatei HELPHEAD.RTF. Diese muß unbedingt da sein, sonst erscheinen ASCII-Hilfetexte nicht (sondern nur RTF-Texte). Gesucht wird sie zuerst auf dem Daten-, dann auf dem Programmverzeichnis. D.h. es kann datenspezifische Versionen geben, die dann vorgezogen werden. Darin kann man die Schriftart festlegen, in der die ASCII-Dateien erscheinen sollen.
In eine RTF-Hilfedatei kann man andere Textteile einbinden. Man schreibt dazu an der Stelle, wo die Einbindung hin soll: %hdateiname%. Dies hat seine Grenzen: Es ist nicht rekursiv, Variablen und FLEX-Aufrufe kann man in diese Teile nicht einbetten, die Teile müssen auf demselben Verzeichnis liegen wie die Hauptdatei. Brauchbar kann diese Technik sein, um Kopf- und Fußteile für eine Sammlung von Texten nur einmal vorhalten zu müssen. Oder um in eine statische RTF-Datei wechselnde Inhalte einzublenden, die sich aus der Situation ergeben.

Für alle Hilfetexte gilt ansonsten:

Standort der Hilfetexte: Lokal, DbDir, ProgDir\help, ProgDir\flex, ProgDir
In dieser Reihenfolge wird nach den Dateien gesucht. D.h. nutzerspezifische Versionen haben Vorrang.

Empfehlung: Nutzerspezifische Dateien: Startverzeichnis (Lokal)
Datenspezifische Hilfetexte: Datenbankverzeichnis
Allg. f. alle eigenen Datenbanken: Programmverzeichnis
Die Dateien aus Braunschweig: alle auf Programmverzeichnis\HELP

Aufruf: Jede Hilfedatei kann mit dem Befehl h name aus dem Schreibfeld heraus direkt aufgerufen werden, aber auch aus einem FLEX mit dem Befehl  help dateiname , wobei der dateiname ohne .rtf anzugeben ist. Expertentip: Wenn mit .rtf angegeben, erscheint der Text mitsamt der Steuerzeichen und ermöglicht eine Bearbeitung direkt im Anzeigefenster.


A. Hilfetexte zu den Hauptfunktionen

Diese erscheinen situationsabhängig automatisch, z.T. bei Druck auf
F1 (Dann kommt es also darauf an, wo sich im Moment von F1 der "Fokus" befindet.
Festgelegt sind folgende Dateinamen, alle vom Typ .
RTF (Angehängt wird jeweils die Sprachkennung. Von diesen Dateien liegen die Versionen GER und ENG vor.) Mehr zu  RTF-Dateien  siehe unter E.

START : Hilfeseite (gleich nach dem Start)
GENRL :
Ersatz, wenn eine Hilfeseite zur Datenbank nicht existiert (Wichtigste Funktionen)
DOKU  :
Gesamtübersicht Funktionen und Dokumentation
BUTTN :
Hilfe zu den Buttons und sonstigen Bedienelementen
EXPRT :
Export-Menü
COMMD :
wenn F1 in der Suchbefehlszeile gedrückt wird
FIND  : Zum Find-Button
FLEX  :
Zur FLEX-Makrosprache
KONFG :
wenn die CFG-Kategorienliste links zu sehen ist
MENU  :
Hilfe zu den Menüs
PRMPT :
wenn die Abfrageliste links angezeigt wird
RECRD :
wenn die Kategorien des Datensatzes im Auswahlfeld stehen
RESRV :
wenn der Hintergrundspeicher im Auswahlfeld steht
RESLT :
Hilfe zu Ergebnismengen (wenn diese im Auswahlfeld stehen)
SPCHR : "Special Characters" Sonderzeichen-Eingabe (Alt+m im Schreibfeld)
WRITE : Eingabefeld zum Eingeben/Korrigieren von Kategorien (nur a99)

Diese Dateien existieren auf Deutsch und Englisch. Die Namen sind z.B. findger.rtf und findeng.rtf
Wenn Sie den Original-RTF-Text einer solchen Datei sehen wollen, geben Sie z.B. ein
h findger.rtf 

Tip: Geben Sie ein:
Die zuletzt benutzte Hilfeseite bekommen Sie über das Kontextmenü: rechte Maustaste, dann den Punkt "Letzter Hilfetext".


B. Unterfenster-Hilfetexte

Sonderfall! Die Namen der zu den Unterfenstern gehörigen Hilfetexte beginnen alle mit HE bzw. HA und enden mit
GER oder ENG (deutsche bzw. engl. Version). Dazwischen steht der eigentliche Name der Hilfeseite, der immer aus 3 Zeichen besteht. Diese Dateien haben kein Dateityp-Suffix!
Wird eine Datei
HExxxGER nicht gefunden, sucht das Programm nach HExxx, also ohne Sprachkennung.
(
HA steht für alcarta, HE für a99. Fehlt die HE-Datei, nimmt a99 die HA-Datei.)
Wird sie immer noch nicht gefunden, wird noch nach
HExxxGER.RTF gesucht, dies also erst zuletzt.

Folgende Texte gibt es für die Unterfenster:

ASCII-Text ohne RTF. Der 3buchstabige Name muß dann mit '_' beginnen.
Diese Texte erscheinen jeweils dann, wenn F1 gedrückt wird:

für beide Programme: (mit HA (für alcarta) bzw. HE (für a99), aber a99 nimmt auch HA, wenn HE nicht da)

.._IX Index
.._BR Kurzanzeige (Brief Display)
.._VW Viewlisten-Anzeigefenster
.._CH Suchbefehls-Menü
nur A99 (d.h. nur HE...)
HE_AD Formular-Editor
HE_GR Globale Ersetzungen

Diese Texte erscheinen dann in einem eigenen Fenster (nicht im Anzeigefeld), das erst mit [Enter] oder Klick auf [OK] beseitigt werden muß, bevor man weitermachen kann.
Man bearbeitet diese Hilfetexte am besten mit dem X-Editor, doch es geht auch im Anzeigefenster.

Beispiel:  HE_ADGER 


C. Hilfetexte für den EDITOR (für die Dateneingabe und -bearbeitung)

Die Hilfetexte für das Editieren können von DOS übernommen werden (z.B. h20ger oder h2ger oder h20 oder h2). Sie erscheinen entweder im Anzeigefenster (wenn Cursor im Schreibfeld) oder im Help-Fenster (wenn gerade ein Formular benutzt wird). Ist kein geeigneter H-Text vorhanden für die aktuelle Kategorie, erscheint WRITEGER.RTF.
Diese Texte dürfen keine RTF-Texte sein, sie müssen im ASCII-Code geschrieben sein. Empfohlen wird dafür der  X-Editor , denn Notepad verwendet ANSI. Auch Microsofts DOS-Programm EDIT ist verwendbar.
Wird im Schreibfeld F1 gedrückt oder in einem Formular, dann macht das Programm folgendes: es stellt fest, welche Kategorie, z.B. #123, gerade eingegeben wird, dann sucht es zuerst nach H123, ist diese nicht da, nach H12, wenn die auch nicht existiert, nach H1. So kann man sich ein ganz detailliertes Hilfesystem anlegen (ein Text für jede einzelne Datei) oder aber nur einer für jede Kategoriegruppe.

Beispiel:  H20 


D. Registerspezifische Hilfe

für jedes Register kann man eine Hilfeseite HA_InGER für alcarta und HE_InGER für a99 anlegen. Diese sind vom Typ B., also nicht RTF, sondern simple ASCII-Texte. (n=1,2,3...). Wenn HE... fehlt, nimmt a99 ebenfalls den HA-Text. Man kann also, wenn man will, für beide Programme unterschiedliche Hilfen anbieten.
Als Minimum sollte man sich also für eine eigene Datenbank die Dateien
HA_I1 ... HA_I0 anfertigen, dann wird in jedem Fall bei jedem Register ein Text kommen.


E. Benutzergestaltete, freie RTF-Hilfeseiten

Die mächtigste der Möglichkeiten. Dieser Text, den Sie gerade lesen, ist eine solche Datei, HELP.RTF.

Wie man einen Hilfetext mit eingebauten Flips selber machen kann, behandelt die  Fortbildungslektion 13.4 

Der Dateiname ist frei. Empfohlen: bis zu 5 Buchstaben, optional GER oder ENG anhängen und verbindlich den Dateityp .RTF, z.B. flexGER.RTF.
Wenn man nicht mehrsprachig arbeiten will, kann man die Sprachkennung weglassen. Das Programm zieht die sprachspezifische Variante vor, d.h. es schaut zuerst nach nameGER.RTF, dann nach name.RTF. (Damit können auch die eigenen Hilfeseiten mehrsprachig angelegt werden)

Beispiel: Geben Sie hintereinander diese Befehle: h flex, h flexger (dann sehen Sie dasselbe) und dann
h flexger.rtf (dann sehen Sie die Steuerzeichen und die Flipzeilen).
Schreiben und bearbeiten kann man diese Dateien auch mit dem Microsoft-Programm WordPad, welches zum Windows-Zubehör gehört, notfalls auch mit WinWord, speichern aber dann mit Dateityp .RTF, nicht .DOC. (Daher haben diese Dateien ANSI-Codierung.) Wichtig: GRAFIK und TABELLEN kann man nicht einsetzen!
Schreiben und bearbeiten kann man die Dateien auch direkt im Anzeigefenster, ASCII-Dateien ebenfalls.
Abspeichern dann über das Menü "Dateien | Anzeige speichern als ...".

Aber Achtung: Vor dem Bearbeiten die Datei mit vollem Namen aufrufen (h xyz.rtf statt nur h xyz), denn sonst gehen beim Speichern die Flipzeilen verloren.
Hinweis: WinWord versagt den Dienst, wenn am Ende der RTF-Datei eine } fehlt. Eine zuviel macht dagegen nichts aus, wer also RTF außerhalb WinWord erzeugt, tut gut daran, an das Ende ruhig noch ein paar } anzuhängen, um Ärger zu vermeiden.

Wichtigstes Beispiel: dbnGER.RTF bzw. dbnENG.RTF wobei dbn der Datenbankname ist, als allgemeine Hilfeseite für Ihre Datenbank.
Standort: DbDir
Vorlage: siehe Demo-Datenbank CAT: CATGER.RTF. Erscheint bei dem Fragezeichen-Button (unten links)
help ! : Dann kommt die zur Datenbank gehörige Hilfeseite
Empfehlung: als erstes eine solche Datei für die eigene Datenbank machen. Andere Dateien können per Flip daran angeknüpft werden.
Bis auf Grafik und Tabellen kann man das meiste ausnutzen, was WordPad kann. Flips bindet man genauso ein wie oben, d.h. der Flip besteht im Text aus einer markierten Zeichenkette, der eigentliche Befehl steht auf eigener Zeile mit '?' am Anfang. Diese Zeilen werden natürlich nicht mit angezeigt. Wo diese Zeilen stehen, spielt daher keine Rolle.
Die Markierung im Text macht man mit dem Zeichen ` (Accent grave, Code 96), d.h. man setzt dieses Zeichen vor und hinter das Wort bzw. die Zeichenkette, die den Flip auslösen soll. Genau derselbe Text wie zwischen den Markierungen muß dann unten in einer mit ? beginnenden Zeile vorkommen.
Soll der Accent grave selber als einzelnes Zeichen im Text vorkommen, muß man ihn in der RTF-Datei verdoppeln. Dasselbe gilt für das Prozentzeichen.

Sonderfunktion: Wenn eine Zeile im RTF-Text mit \par _i beginnt, wobei z eine Ziffer ist, wird die Anzeige an dieser Stelle beendet, wenn der Nutzer keine Berechtigungsstufe hat, die mindestens i ist (Befehl access in der INI-Datei). So kann man sicherheitsrelevante Hilfetexte vor Unbefugten verbergen.

Flip-Einbettung
Innerhalb eines Hilfetextes können Flips eingebettet sein. Wie sieht ein solcher Flip aus?
Hier ein Beispiel aus GENRLGER.RTF:

Der`Besen`dient zum Löschen aller Ergebnismengen, Bookmarks etc.
...
(und ganz unten steht dann auf eigener Zeile:

?Besen=h besen

oder aber (in der RTF-Datei ist das meistens so):

\par ?Besen=h besen

Die zweite Form entsteht, wenn man einen RTF-Text mit WORD speichert. Beides funktioniert. Wenn ein Flip nicht funktioniert, prüfe man die Datei nicht mit WordPad, sondern z.B. mit X-Editor. Die Zeichenfolge
"\par ?" muß am Zeilenanfang stehen!

Das Wort "Besen" im Text erscheint blau und unterstrichen; wichtig ist aber nur das Steuerzeichen ` rechts und links vom Wort. Zu diesem Wort gehört der Flip "h besen", der dann die Seite "besenger.rtf" aufruft, s.u. Solche Flips werden auf die #uY/#uZ-Variablen mit den Codes ab 129 gelegt.
Hinter dem '?' muß exakt dieselbe Zeichenkette stehen wie zwischen den Begrenzungszeichen im Text (die Leerzeichen hinter \ul und \ul0 gehören zum RTF-Steuercode, nicht zum Text - so ist das bei RTF)
Hinter dem '=' kann einer der Flip-Befehle stehen oder ein FLEX-Befehl, nicht nur h ...
z.B. ...=j Xabc
das heißt: führe Sprungmarke #-X in den Anzeigeparametern aus (in #u1 steht dann "abc").
Meistens wird man aber mit x bzw. X einen FLEX angeben.

Will man einen Hilfeseiten-Aufruf in die SATZanzeige einbauen, muß der Flip z.B. so aussehen:
(Beispiele in D-WRTF.APR)

#xyz p"Information zu diesem Datensatz!" e"!" =Y~
#xyz p"h name!" e"!" =Z~
#t{ t97 t74 160 "Information zu diesem Datensatz" 160 t76 t96 }

Der Text erscheint blau und unterstrichen, 160 = unsichtbares Zeichen). Der "name" muß ohne Sprachkennung und ohne .RTF angegeben werden, z.B

... p"h hilfe!" e"!" ... für hilfeGER.RTF bzw. hilfeENG.RTF

Zum Markieren kann man entweder [ ]oder den unsichtbaren Code 160 einsetzen. In WinWord macht man diesen Code mit Shift+Strg+Leertaste. In der RTF-Datei steht dann an der Stelle   . Der Fliptext muß also genau zwischen zwei solchen Markierungen stehen.
Auch in einer
FLEX-Befehlskette können Hilfetexte aufgerufen werden, dazu dient der Befehl  help .

Einbetten von Kategorien und Nutzervariablen in Hilfetexte

Innerhalb eines Hilfetextes kann jederzeit ein Ausdruck z stehen, wobei z eine Ziffer ist. Wenn es dann die Variable #uVz gibt, wird deren Inhalt anstelle von %z eingesetzt. Dadurch kann man Satzinhalte oder anderes variables Material in Hilfesätze einbetten.
Jedoch kann man auch #nnn oder
#uxy oder %$Name in den Hilfetext schreiben (aber kein Leerzeichen zwischen und # bzw. $), um die aktuelle Kategorie #nnn bzw. die Nutzervariable #uxy bzw. die freie Variable $Name direkt in den Text einzubeziehen. [Freie Var. erst ab V25.8]
Soll etwa innerhalb eines Hilfetextes
xyz.rtf der Titel (#20) des aktuellen Satzes erscheinen, jedoch ohne Zusatz, dann macht man es z.B. so: (siehe  FLEX-Dokumentation )
x var #20(e" : ")\ins #utt\help xyz
und in
xyz.rtf muß an der betreffenden Stelle nur 2 stehen. Die Variablen #uVi können auch innerhalb der Anzeigeparameter besetzt werden oder in einem FLEX, das spielt keine Rolle.

Soll das Prozentzeichen selber als einzelnes Zeichen im Text vorkommen, muß man es in der RTF-Datei verdoppeln.


TIP zum bequemen Bearbeiten der RTF-Hilfetexte:

Man gibt im Schreibfeld ausdrücklich ein: h name.rtf (also den Namen mit .rtf) Wenn man das vergißt, verliert man die Flips, falls man beim Abspeichern das .rtf wieder an den Namen hängt!
Dann kommt die Datei name.rtf zur Anzeige, mit gelbem Hintergrund und mit sichtbaren Markierungszeichen. Dort kann man sie bearbeiten, unten sieht man auch die Flip-Zeilen (!), und über das Menü "Datei | Anzeige speichern" speichert man den Text zurück.
Wenn man nur h name gibt, also ohne .rtf, werden die Flip-Zeilen nicht sichtbar - wie es im Normalbetrieb sein soll.
Beim Abspeichern kommt es auf den Typ an: wählt man etwas anderes als .RTF, wird nur der Text gespeichert, nicht die RTF-Befehle. Das kann man nutzen, wenn man einmal nur den Textinhalt extrahieren will.
Ansonsten kann man Texte per Cut-and-Paste mit WinWord und WordPad austauschen. Dabei werden auch alle Schriftattribute übertragen, denn jene Programme verstehen ebenfalls RTF. (Mit HTML funktioniert so etwas übrigens nicht.)
Das Bearbeiten wird durch das Kontextmenü unterstützt. Drücken Sie die rechte Maustaste während die Schreibmarke sich im Anzeigefeld befindet. Dann z.B. i drücken, um Kursivschrift einzuschalten. Besonders leicht wird das Anlegen eines Flips: man markiert die gewünschte Zeichenkette, dann rechte Maustaste und f, schon werden die Begrenzungszeichen gesetzt, die Zeichenkette kopiert und am Ende des Textes mit ? davor und = dahinter hingeschrieben, jetzt braucht man nur noch hinzuschreiben, was denn passieren soll bei diesem Flip.

FLEX-Einbettung

Mit dem Muster %=x Befehlskette% und %=X FLEXdateiname...% kann man sogar FLEXe in eine Hilfedatei einbetten, und zwar werden diese dann genau in dem Moment ausgeführt, wenn dieser Teil der Datei eingelesen wird. In der Befehlskette müssen die Befehle durch das Zeichen "Accent grave" ` getrennt sein, nicht durch \.
ABER: Es klappt nur, wenn die Hilfedatei direkt mit h-Befehl oder aus einem Flip mit "h xxx" aufgerufen wird, aber NICHT, wenn sie mit "help xxx" aus einem FLEX heraus geladen wird. Denn es müßte dann ein FLEX innerhalb eines anderen FLEXes ablaufen und der erste danach weiterlaufen - das geht nicht. Wenn allerdings der help-Befehl der letzte des FLEXes ist oder ein "end" folgt, DANN klappt es trotzdem.
ExpertenTip: Wenn der FLEX als letztes den Befehl var "END" ausführt, wird das Einlesen der Hilfedatei nicht fortgesetzt und nichts angezeigt.
Als Beispiele kann man sich  adm.rtf ,  exprtger.rtf ,  dbi.rtf  und  files.rtf anschauen. Wenn man sie "normal" aufruft, also durch  h adm ,  h exprt  bzw.  h files  bzw.  h dbi , dann sieht man den Effekt.
Achtung: In Namen von #u-Variablen in solchen FLEXen keine Sonderzeichen verwenden, nur Normalbuchstaben (groß oder klein) und Ziffern.
Hinweis: Wenn ein eingebetteter FLEX läuft, ist die Schreibberechtigung abgeschaltet, d.h. es kann kein Befehl put vorkommen. Dies wäre eine potentielle Sicherheitslücke.

Sonderfall: Einbetten von Phrasen in Hilfetexte (für Strg-Tasten)
Wenn man eine Zeile der Gestalt
\par ?zzz=^pabc
in einer RTF-Hilfedatei hat, wird beim Einlesen die Phrase Strg+p mit der Zeichenkette "abc" belegt. Wenn dabei der Text abc mit "x " oder "X " anfängt, hat man einen FLEX. Beispiele dafür findet man am Ende der Datei FLEXGER.RTF. (Die Zeichen zzz sind ohne Bedeutung!)
Achtung: Wenn innerhalb "abc" ein \ vorkommt, ist dieser hier ganz normal hinzuschreiben, nicht wie sonst in RTF doppelt. Denn die Zeilen mit "\par ?" am Anfang werden nicht als RTF-Zeilen ausgewertet.


F. Hilfetexte als Datensätze

Als weitere Möglichkeit kann man einen Datensatztyp schaffen, der Hilfetexte enthält. Das ist ausführlich im Beispiel der Datenbank "Theologischer Zeitschriften-Inhaltsdienst" (Tübingen, Dr. Weisweiler) durchgeführt worden. In ca 70 solchen Hilfesätzen (jeder in deutscher und engl. Version) sind alle Hinweise zu den DOS- und Windows-Funktionen der Datenbank untergebracht. Geeignete Parametrierung ermöglicht natürlich auch hier, neben der Indexierung der Hilfesätze, Flips einzubauen, die den Nutzer dann zu anderen Hilfesätzen, zu Registerabschnitten oder zu bestimmten Datensätzen hinführen. Es ist nur eine Frage der Zeit und Phantasie, dieses Konzept beliebig auszubauen. Einmal parametriert, spart man sich dabei die Kleinarbeit, die in die RTF-Dateien manchmal zu investieren ist. (Die Datei HELPHEAD.RTF wird für diese Zwecke nicht gebraucht, sondern DISPHEAD.RTF, wie für andere Datensätze auch.)


G. "JanaS" : Das Browser-Fenster

Schließlich kann man sogar "besondere Links" für allegro-Hilfetexte und FLEX-Aufrufe in HTML-Dateien einbinden. Wirksam werden sie aber nur dann, wenn diese HTML-Texte mit dem allegro-eigenen  JanaS-Browser  angezeigt werden.
"Besondere Links" in einem JanaS-geeigneten HTML-Text sehen so aus:
href="flex:h dateiname" (damit wird a99 die Hilfedatei dateiname.rtf zeigen)

Zum Ausführen von FLEXen dienen diese Formen:
href="flex:x befehlsfolge" oder
href="flex:X flexname" (Start eines FLEXes)