Alternativ zur HTML-Hilfe

Derzeit verwenden wir ein System namens AsciiDoc , mit dem wir Dokumentation in einem einfachen Text-Markup erstellen können. Daraus können wir mehrere Ausgabeformate generieren. Wir verwenden nur die Ausgabeformate pdf und chm.

Ich habe mich gefragt, ob es eine Alternative zu chm gibt. Was ich suche, ist etwas, das mit unserer Software offline verwendet werden kann (dies ist wichtig, da sich einige unserer Benutzer an sehr abgelegenen Orten befinden). Es sollte einen Index haben (es kann so einfach sein wie eine HTML-Seite mit verknüpften Begriffen), es sollte durchsuchbar sein und einen Mechanismus haben, mit dem bestimmte Einträge aus dem Code aufgerufen werden können (ähnlich wie bei der kontextsensitiven Hilfe).

Die zwei Dinge, die in diesem Fall gegen PDF sprechen, sind:

1. Kontextsensitive Hilfe ist keine Option
2. Im Allgemeinen ist das Dokument ziemlich groß
3. PDF eignet sich eher für gedruckte Dokumentationen als für kontextsensitive Hilfe

Was ich möchte, ist HTML zu verwenden. Das einzige Problem mit HTML ist, dass ich nicht herausfinden kann, wie eine Schlüsselwortsuche automatisch bereitgestellt werden kann (abgesehen von der Strg + F-Funktionalität des Browsers - ich möchte etwas offensichtlicheres). Ich kann anscheinend auch keine Methode finden, um automatisch einen Index mit Hyperlinks für Schlüsselwörter zu erstellen. Kontextsensitive Hilfe wäre aufgrund der Abschnitts-Tags einfach - ich könnte einfach die URL der Seite und des Abschnitts, die mich interessieren, an den Standardbrowser übergeben und diese Seite sollte bis zum richtigen Abschnitt geladen werden.

Meine Anforderungen klingen sehr ähnlich wie chm - sie tun es. Ich habe meine Anforderungen von chm modelliert. Der einzige Grund, warum ich chm nicht mag, ist die Art und Weise, wie der Code mit Mapiden und dergleichen interagiert. Ich würde viel lieber eine Klartextliste speichern (die automatisch für mich generiert wird), mit der mein Code auf den kontextsensitiven Teil der Dokumentation zugreifen kann.

Ich stelle mir ein Skript vor, das die HTML-Ausgabedateien durchläuft und eine Indexseite generiert, die einfach eine Liste der gefundenen Schlüsselwörter enthält. Offensichtlich sollte es einen Wortausschlussmechanismus geben, um Wörter wie: das, es ist, usw .. zu ignorieren. Dieser Teil wäre relativ einfach zu schreiben. Der zweite Teil würde eine Art Skript benötigen, um eine Datenbank mit Stichwörtern und deren Position im HTML-Text zusammenzustellen. Ich denke, dies wäre der schwierige Teil zusammen mit der Bereitstellung des Suchmechanismus innerhalb des Browsers.

Über Ideen zu Alternativen würde ich mich freuen. Ich würde gerne ein Wiki oder eine Reihe von statischen HTML-Seiten verwenden, die irgendwo auf einem Webserver gehostet werden, aber wir haben eine wichtige Anforderung an die Offline-Nutzung. Das einfache Platzieren des HTML-Codes auf dem lokalen Laufwerk bietet uns nicht die Suchanforderungen, die wir benötigen.

BEARBEITEN:

Ich entwerfe Software, die im Bergbau eingesetzt wird. Viele Minen sind sehr abgelegen und haben keinen sinnvollen Zugang zum Internet. Es ist nichts falsch mit pdf oder html oder chm (außer dass es alt wird). Wenn ich eine PDF-Datei am richtigen Ort anzeigen könnte (dh kontextsensitive Hilfe), würde ich es verwenden. Ich bin fast versucht, mein eigenes zu schreiben - im Grunde wäre es ein portables Wiki. Apropos, wenn Sie tragbares Wiki vorschlagen, müssen Sie an den Endbenutzer denken, der möglicherweise keine Erfahrung mit der Verwendung solcher Tools hat. Es muss absolut einfach sein. Das war das Schöne an chm, es ist ein Schmerz, damit zu arbeiten, aber die Endbenutzer mögen es.

Wenn Sie bereit sind, Ihre Hilfe in DocBook XML-Markup anstelle von HTML zu verfassen, unterstützt DocBook die Erstellung von WebHelp: http://wiki.docbook.org/WebHelp

Die WebHelp-Dokumentation ist auch eine Demo der Ausgabe: http://docbook.sourceforge.net/release/xsl/current/webhelp/docs/content/ch01.html

Sie erhalten ein webbasiertes HTML-Hilfeformat, das Folgendes umfasst:

• Volltextsuche mit:
  • Stemming-Unterstützung für Englisch, Französisch und Deutsch. Stemming-Unterstützung kann für andere Sprachen hinzugefügt werden, indem ein Stemmer implementiert wird.
  • Unterstützung für Chinesisch, Japanisch und Koreanisch mit Code aus der Lucene-Suchmaschine.
  • Suchmarkierung, die anzeigt, wo der gesuchte Begriff in den Ergebnissen angezeigt wird.
  • Die Suchergebnisse können kurze Beschreibungen des Ziels enthalten.
• Inhaltsverzeichnis mit ausblendbarer Inhaltsverzeichnisstruktur.
• Automatische Synchronisierung von Inhaltsbereich und Inhaltsverzeichnis.
• Inhaltsverzeichnis und Suchbereich ohne Verwendung eines Framesets implementiert.
• Eine Ant build.xml-Datei, um eine Ausgabe zu generieren.

Die Schöpfer von RoboHelp sind zu anderen Dingen übergegangen und sind zurückgekommen, um eine bessere Alternative zu finden. Schauen Sie sich MadCaps Flare an - es unterstützt eine Vielzahl von Ausgabeformaten, generiert einen Index und bietet eine Suchfunktion, die lokal (über JavaScript) funktioniert.

Wir haben Adobe RoboHelp verwendet , um verschiedene Arten der Offline- Hilfedokumentation zu erstellen . Es bietet viele Ausgabe- und Integrationsoptionen für Inhalte. Das Tolle an diesem Tool ist, dass Sie es an Nicht-Entwickler weitergeben können und großartige Inhalte mit geringem Aufwand in Ihre Lösung integrieren können.

CHM selbst ist in die Jahre gekommen, und Microsoft ist auch zu neueren Dingen übergegangen : http://msdn.microsoft.com/en-us/library/bb164608(v=vs.80).aspx

Wenn Sie jedoch wirklich vermeiden möchten, Ihre Hilfe in ein vorhandenes System umzuwandeln, und nach Möglichkeiten suchen, statische Hilfedateien zu durchsuchen und nach Schlüsselwörtern zu durchsuchen, finden Sie hier zwei Vorschläge:

• Fügen Sie dem Projekt einen kleinen HTTP-Server nur für lokale Hosts hinzu, um eine Website mit der Dokumentation bereitzustellen. Probleme bestehen darin, wann oder wie dieser HTTP-Server gestartet / gestoppt und / oder weiter ausgeführt werden kann. Eine Alternative wäre die Implementierung eines benutzerdefinierten URL-Schemas, aber dies würde Sie an einen Browser binden und ist viel mehr Arbeit ( und ich kann sagen )

• Schreiben Sie eine JavaScript-Suchmaschine. JavaScript in jedem Browser wird heutzutage ziemlich schnell und leistungsfähig. Ein Schlüsselwortindex könnte leicht in JSON gespeichert werden, und ich habe reguläre Ausdrücke für lokale Dateien mit ziemlich guten Ergebnissen ausgeführt.

Was ich suche, ist etwas, das mit unserer Software offline verwendet werden kann (dies ist wichtig, da sich einige unserer Benutzer an sehr abgelegenen Orten befinden).

Wir verwenden RoboHelp in meinem Unternehmen und wir wünschen viel Glück, dass die Hilfedateien offline verfügbar sind, da wir häufig Benutzer haben, die von Gebieten mit Netzwerkzugriff zu Gebieten ohne Netzwerkzugriff wechseln.

Es sollte durchsuchbar sein und über einen Mechanismus verfügen, mit dem bestimmte Einträge aufgerufen werden können

Wir verwenden einige Seiten in RoboHelp, um die Verwendung bestimmter Felder auf einem Bildschirm zu erläutern. Es können Pop-ups für die Felder angezeigt werden, die nach einem Klick angezeigt werden. RoboHelp hat auch eine sehr schöne Suchfunktion und einen automatisch generierten Index. Ich hatte immer viel Glück damit zu suchen. Dies ist möglicherweise kein großes Problem für Sie, aber wir können die Dokumentation von jedem aktualisieren lassen, da RoboHelp ein relativ einfach zu verwendendes Programm ist.