Hinweise zur Online-Hilfe

 

Dokumentversion:	1.2 (07.12.2002)
Autor:	Erstautor: U.Sacklowski, Fortschreibung durch projekt98
letzte Bearbeitung:	Günther Reinecker und Thomas Kullmann
Zustand:	in Bearbeitung

 

Diese Dokumentation ist bei Bedarf/ Erkenntnis durch die Projektmitglieder fortzuschreiben (mit Autorenhinweis).

Inhalt

1. Einführung
2. Inhalt und Struktur der Online-Hilfe aus Benutzersicht
3. Design-und Implementationsspezifik
4. Das Tool HelpScribble - allgemein und projektspezifisch
5. Online-Hilfe auf den Laborrechnern
 

1. Einführung

Neben den Benutzer-Leitfäden, die in der Physik in gedruckter Form u.a. an den Messplätzen verfügbar sein werden, wird den Benutzern noch eine Online-Hilfe bereitgestellt. Unsere Orientierung hierbei zielt auf einen geringen Umfang.

Gründe:

- Aufwand für die Erstellung der Online-Hilfe und ihre spätere Pflege gering halten,
- freie Plattenkapazität auf den Messplatzrechnern ist nur wenig verfügbar,
- die gedruckten Benutzer-Leitfäden sind eigentlich ausreichend.

Aus diesem Grund werden wir weder ein Online-Tutorial, noch eine kontextsensitive Online-Hilfe implementieren, sondern nur ein Online-Manual von geringem Umfang (nachfolgend Online-Hilfe genannt).

Das XCTL-Steuerprogramm verfügt gegenwärtig über (fast) keine Online-Hilfe. Eine solche ist nun je Anwendungsfall zu entwerfen und zu implementieren.
 

2. Inhalt und Struktur der Online-Hilfe aus Benutzersicht
 

• Die Online-Hilfe erlaubt nur eine Navigation über das Inhaltsverzeichnis. Index (bzw. Such-Funktion) werden nicht unterstützt.
• Angeboten werden
• die wichtigsten Dialog- und Mess-Fenster mit ihren Funktionen und Werten,
• ein 'Sammelsurium' weiterer Informationen. (Ausgangsmenge hierbei sind die Informationen, die in der bisherigen Online-Hilfe unter 'Suchen' bereitgestellt werden.)
• Ein Navigieren zu den Dialog- und Mess-Fenstern kann alternativ erfolgen über
• die Funktionshierarchie des Hauptfensters,
• eine alphabetisch geordnete Menge der Dialog- und Mess-Fenster.
• Die Online-Hilfe gibt es nur in textueller Form, ergänzt um die Bilder der Dialog- und Mess-Fenster.
• Die Online-Hilfe bezieht sich bei den Oberflächenobjekten (Dialog- und Mess-Fenster) nur auf die deutsche Version.

Deutsche oder englische Dialog- und Meß-Fenster?

3. Design-und Implementationsspezifik

• Die jeweilige Struktur erfolgt entsprechend den Anwendungsfällen und ist zweistufig hierarchisch. Unter den Inhaltsseiten liegen die Seiten zu den Anwendungsfällen.
• Jedes Oberflächen-Objekt ergibt ein eigenes Thema mit eigener Topic-ID.
• Tabelle.: Anwendungsfall,  Topic-ID - Bereich (aus HelpScribble):

• ACHTUNG:
• Datei- und Verzeichnisnamen müssen die 8:3-Dateinamenkonventionen erfüllen (wegen Windows 3.11) und sollten komplett groß geschrieben werden (Unix-CVS).
• Bilder:
• müssen im bmp-Format (256 farbig) sein, weil der Hilfecompiler nur .bmp akzeptiert
  Mit den aktuellen Komprimierungseinstellungen wird deren Größe, bei der Erstellung des Window-Helpfiles, jedoch stark reduziert.
• Bilder von Dialogen sollten dem Web-Repository aus dem Unterverzeichnis
      entwicklerdoku/entwicklertabelle/winressourcen
  entnommen werden. Ggf. sind die dortigen Bilder zu aktualisieren. Anschließend müssen die Bilder jedoch noch ins .bmp-Format konvertiert werden, die Dateinamen sind auf 8 Zeichen zu kürzen!
• Die anwendungsfallspezifischen Bilder sind hingegen in den genannten Verzeichnissen unterzubringen!
• In den HelpScribble-Datei selbst, sollten nur Referenzen auf Grafiken aufgenommen werden:
      {BMC <Bilddatei>} Syntax
• Context-ID's:
  • Die mit dem Dialog 'HelpScribble Context Editor' (Menüpunkt Editors -> Context File Editor) erstellte Struktur wird in der Datei SPHELP.CNT abgelegt, diese steht jedoch erst ab Win32 zur Verfügung!!!
  • Um die Context-ID's in die [MAP]-Sektion der SPHELP*.HPJ und die HELP_DEF.H zu exportieren, muss der Dialog 'Topic-Footnotes' (Menüpunkt Topic -> Footnotes) verwendet werden. Über diese ID's können die einzelnen Hilfethemen auch aus dem XCTL-System, Methode WinHelp(...) angesprochen werden.
  • Jede ID sollte mit dem Präfix "HELP_" beginnen; z.B.:
        Help_LineScan
  • ID's für Dialoge sind am Ende mit dem Suffix "Dlg" zu kennzeichnen; z.B.:
        Help_ManualAdjustmentDlg
• Keywords:
  • sind hierarchisch zu vergeben und durch Komma zu trennen, damit entsteht im Inhaltsverzeichnis eine baumähnliche Struktur; z.B.:
        Diffraktometrie
        Diffraktometrie, LineScan
        Diffraktometrie, LineScan, Tastaturbelegung
• Die aktuellsten Online-Versionen sind in unserem CVS-System unter XC010701 im Verzeichnis HELP zu finden.

Die vorliegenden Anfangsrealisierungen zeigen
• die Gesamtstruktur, Beispiele für
  -- ein Dialogfenster 'Common Settings for Drives',
• Diffraktometrie: Line- und AreaScan samt Darstellung der Messwerte
• Manuelle und Automatische Justage
• Für die Vorgehensweise bei der Erstellung einer neuen Hilfedatei siehe XC010701 -- HELP -- HOW TO BUILD.TXT.

Die Implementation von Windows-Online-Hilfen verlangt eine spezielle Syntax. Um davon zu abstrahieren, werden spezielle Tools für die Implementation von Windows-Online-Hilfen angeboten, - so auch HelpScribble.

HelpScribble unterstützt darüber hinaus bequeme Textformatierungen, einen schnellen Korrektur- make-Zyklus, vielfältige Link-Möglichkeiten u.v.a.

Für uns relevante Dateitypen sind das .hsc-File (HelpSribble-Projektfile), das .GID-File (Index-File, - obwohl wir die Index-Funktion nicht nutzen, wird es (wohl) standardmäßig angelegt) und das .hlp-File, welches schließlich aufgerufen wird, - bei uns z.B. in m_main.cpp unter DoCommandsFrame.

HelpScribble ist auf unserem Lehrstuhl-PC 'ahorn' verfügbar.

Wollen Sie dort arbeiten, müssen Sie zugelassen werden und unter e:\user ein Verzeichnis erhalten (z.B. e:\user\meier) - verantw. Uli Sacklowski.

Spezielle Hinweise zu Ablauf und Arbeit mit HelpScribble:

• Übernahme der Dateien aus dem CVS-System XC010701, Verzeichnis HELP.
• HelpScribble starten
• Projekt öffnen
• Einzelne Themen (Topics) bearbeiten, hinzufügen, löschen:

TopicBar (über View,  TopicBar herauszubekommen): auswählen,   +  hinzufügen,   -   löschen
• Textgestaltung:

Über TextBar.
• Context-ID's bearbeiten
• Links einfügen:

Help ToolBar:
Link zu Topic im gleichen Projekt:  Text markieren,  Ziel über 'Title' im Help ToolBar auswählen,  Symbol 'Link' im Help ToolBar
Link zu Topic in einem anderen Projekt:  Text markieren,   Symbol 'Special link' im Help ToolBar ,  danach in der
         Insert link - Dialogbox:
                   Link:  Other HelpScribble help file
                   File:   voller Pfad des .hlp-Files
                   Topic:  Nummer des Topics   (z.B. 9010)
                   OK
Insert bitmap:   Einfügestelle auswählen,   Symbol 'Insert bitmap' im Help ToolBar , anschließend vollen Pfad des Bildes eingeben
• Zwischendurch immer mal Projekt,  Save   und  Project,  Make,  um das Zwischenergebnis zu bewundern.
• SPHELP.HLP im EXE-Verzeichnis und HELP_DEF.H im INCLUDE\HELP-Verzeichnis platzieren.

• Den Aufruf in m_main in DoCommandsFrame entsprechend ändern.

• Zurückspielen von XC010701 in das CVS-System.
• Falls Erfolgserlebnis, dieses lauthals kundtun!!    :-)

5. Online-Hilfe auf den Laborrechnern

Für die Abarbeitung des XCTL-Steuerprogrammes muss die SPHELP.HLP in dem Verzeichnis liegen, wo sich auch die DEVELOP.EXE befindet.

Grobe Abschätzung des erforderlichen Speicherbedarfs: max. 1 MB