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:
- Kontextsensitive Hilfe ist keine Option
- Im Allgemeinen ist das Dokument ziemlich groß
- 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.