Welche Hilfegenerierung verwendet ihr?

[charlytango]

Hi,

ich möchte eine komponente zur Verfügung stellen und dabei auch eine ordentliche Hilfe/Spezifikation zur Verfügung stellen.

Was nutzt ihr dazu?

fpdoc?
pasdoc?

anderes`warum?
Was sollte man benutzen macht es aber wegen des Aufwandes nicht ?

Bitte um Hilfe, es wäre meine erste Komponente die ich versuche sauber zu veröffentlichen

LG

[wp_xyz]

In TAChart habe ich mit fpdoc gearbeitet, in FPSpreadsheet mit pasdoc. Letzteres ist mir sympatischer, weil ich die Kommentare aus dem Quellcode direkt in die Hilfe übernehmen kann, was meiner Arbeitsweise entgegenkommt. Der "FPDoc Editor" dagegen hat eine eigenartige Formatierung der xml-Dateien, auf die er zumal bei jedem Speichern (das unkontrollierbar oft erfolgt) zurückgeht.

In beiden Fällen bin ich mit dem Ergebnis nicht zufrieden, denn man kann die erzeugten chm-Dateien nicht in Lazarus einbinden, so dass man, wie bei LCL, FCL einfach F1 drücken kann und so den Hilfetext zu dem Bezeichner unter dem Cursor erhält. Zumindest ist mir das noch nicht gelungen.

Und die Hilfe-Dateien sind relativ nichtssagenend, denn sie sind überladen mit leeren Einträgen (nicht physikalisch leer, sondern mit minimalem, automatisch generierten Content wie "Das ist der Constructor der Klasse XYZ"). Die wichtigeren Einträge, die man selbst geschrieben hat, sind daher zugemüllt und schwer zu finden. Und wenn man keine leeren Einträge will, muss man für jeden Sch... einen Hilfetext schreiben - womit aber die wichtigen Einträge auch wieder untergehen.

Daher habe ich es bei anderen Komponenten aufgegeben, Hilfedateien (chm) zu erstellen, und schreibe stattdessen wiki-Artikel mit der von mir gewünschten Struktur: Installation - Abstract (was macht die Komponente) - Erste Schritte (wie kann ich die Komponente anwenden) - Aufzählung und Kurzbeschreibung der wichtigsten Properties und Methoden. Und falls wirklich eine offline-Hilfe-Datei mit ausgeliefert werden soll, findest du im FPSpreadsheet-Projekt ein Skript, wie du diese wiki-Datei herunterladen und in eine chm und/oder pdf-Datei umwandeln kannst. (README.txt in fpspreadsheet/docs).

Eine Alternative zur Hilfe im wiki sind evtl. externe Hilfe-Generatoren, etwa HelpNDoc. Da kann man sich selbst die Baumstruktur der Hilfethemen definieren und die Hilfethemen selbst ähnlich wie in einer Textverarbeitung mit verschiedenen Schriftarten und eingebundenen Bildern schreiben, und alle möglichen Dateiformate erzeugen: chm, pdf, docx, ... Nachteil: das sind kommerzielle Programme, HelpNDoc gibt es in der Basis-Version zwar kostenlos, ist aber dann nur für den persönlichen Gebrauch erlaubt (es gibt 1-2x im Jahr für ein paar Tage eine stark reduzierte Vollversion für ca. 150 EUR).

Wenn jemand gern html-Seiten schreibt, wäre evtl auch chmmaker aus dem Lazarus "tools"-Verzeichnis eine Option: Man kann sich wie bei HelpNDoc den Baum der Hilfethemen zusammenstellen und kann dann die dazu vorhandenen html-Seiten einbinden. Erzeugt nur chm, wenn ich mich nicht täusche.

Apropos chm: Nachdem diese selbst unter Windows immer mehr Probleme machen und nur noch nach Freigabe durch den Benutzer angezeigt werden, ist das auch keine gute Option...

[fliegermichl]

Das wäre doch ein schönes Beispiel für den Thread Welches Programm fehlt uns noch.

[af0815]

Fpdoc kann auch nur eine Sprache. Englisch. Alles andere ist von den Entwicklern nicht akzeptiert. Info von MvC vor etlichen Jahren. Nach einigen Diskussionen über die Doku habe ich mich entschlossen fpdoc nicht einmal mehr anzusehen und auch keine fixes mehr dafür zu machen. Bei der Wiki herrschen ähnliche Zustände, vernünftige Wartbarkeit der Mehrsprachigkeit werden trotz Jahrzehnte länger Diskussion nicht einmal ignoriert. Englisch ist die einzige akzeptierte Sprache.

[Socke]

Fpdoc kann auch nur eine Sprache. Englisch. Alles andere ist von den Entwicklern nicht akzeptiert. Info von MvC vor etlichen Jahren.

Das bezieht sich aber vor allem auf Dokumentationssprache von Free Pascal und Lazarus selbst. Wenn du deine eigenen Komponenten mit Fpdoc in Deutsch dokumentieren möchtest, kannst du auch deutschen Text eingeben.

[af0815]

Fpdoc kann auch nur eine Sprache. Englisch. Alles andere ist von den Entwicklern nicht akzeptiert. Info von MvC vor etlichen Jahren.

Das bezieht sich aber vor allem auf Dokumentationssprache von Free Pascal und Lazarus selbst. Wenn du deine eigenen Komponenten mit Fpdoc in Deutsch dokumentieren möchtest, kannst du auch deutschen Text eingeben.

Eingeben ja, aber nicht mehrsprachig arbeiten. Auch wenn du jetzt die Texte in mehreren Sprachen hättest, kann fpdoc das aufgrund Designentscheidungen im "way of working" das nicht stemmen. Ist für mich für den Bau von Dokumentation somit unbrauchbar.

[af0815]

In beiden Fällen bin ich mit dem Ergebnis nicht zufrieden, denn man kann die erzeugten chm-Dateien nicht in Lazarus einbinden, so dass man, wie bei LCL, FCL einfach F1 drücken kann und so den Hilfetext zu dem Bezeichner unter dem Cursor erhält. Zumindest ist mir das noch nicht gelungen.

Mir vor Jahren schon mal. Das Geheimnis ist dabei das man ein eigens Indizierungs Dokument erzeugen und mit einbinden muss. Das ist jetzt mehr als 15 Jahre her, keine Ahnung wie ich das damals zusammengebracht habe. Ich stand damals mit MvC ein paar mal in Verbindung deswegen. Draufgekommen bin ich, weil ich damals die FPC/Lazarus Doku selbst kompilieren wollte, dabei bin ich auch über die Indexierung gestolpert. Ist aber zu lange her. Das war so um die Zeit, wo ich dem Forum beigetreten bin.

Apropos chm: Nachdem diese selbst unter Windows immer mehr Probleme machen und nur noch nach Freigabe durch den Benutzer angezeigt werden, ist das auch keine gute Option...

chm ist ja im Hintergrund verstecktes html, nachdem es MS eingestllt hat, vermutlich auch deswegen weil es als gutes Versteck für Böse funktioniert hat. Ist natürlich der Zugriff darauf zum aktiv Freigeben. MS hat das am Anfang nicht wirklich durchgesetzt, erst jetzt wo die Regeln viel strenger durchgesetzt werden fällt es auf. Auch durch die Unart unter Windows prinzipiell als Administrator zu arbeiten hat das ganze versteckt. Auf Arbeitsplätzen die als Benutzer konfiguriert waren, ist das die letzen 10 Jahren schon aufgefallen, deswegen wir das sauber als installations Produkt ausgerollt haben.

[MmVisual]

Ich schreibe seit vielen Jahrzehnte meine Doku in HTML Dateien. Einfaches HTML, keine Scripte, kein Java. Nur CSS und Bilder sind extra Dateien.

Dazu verwende ich den HtmlHelp Compiler von Microsoft, der macht eine Baumstruktur (und die CHM Datei).
Mit dazu erstelle ich eine Alias und Index Datei, die kann der HtmlHelp Compiler von MS ebenfalls verarbeiten.
Damit ist es möglich mit dem "HelpContext" eine Kontextbezogene Hilfe auf zu rufen.

Da, wie schon oben erwähnt, MS die Anzeige der CHM Datei stark einschränkt bin ich nun diesen Weg gegangen:
Alle Dateien der Hilfe packe ich mir in eine Ressource und habe mir ein TForm selbst geschrieben, links der Themen Baum und rechts die THtmlViewer Komponente.
Anhand der Baum-Datei, der Index und Alias Datei kann ich somit selbst die Kontextbezogene Hilfe aufrufen.
Der Trick dabei: Die Hilfe ist als Ressource mit in der EXE mit drin, damit ist die Hilfe immer verfügbar und passend zum Stand der EXE.

Webseite: Auf meiner Homepage verwende ich ebenfalls genau die gleiche Dateien. Dazu habe ich ein extra PHP Script geschrieben, das die Baumstruktur Datei lesen kann und den Baum im Webbrowser anzeigt.

Da die Web-Online Hilfe identisch ist mit der Hilfe in der EXE und die EXE daher die Dateinamen kennt, kann ich nun aus der EXE heraus die Web-Hilfe mit einem Google Translator Link aufrufen und somit kann jeder meine Hilfe in seine Lieblings Sprache frei übersetzen lassen.

Das Schreiben der Hilfe Webseiten hat sich seit Jahrzehnte nicht geändert, die Möglichkeiten sind nach wie vor in alle Richtungen offen und die geschriebene Hilfe ist vielfältig immer wieder weiter verwendbar. HTML ist zukunftsicher, das kann man nicht mehr aus der Welt bekommen ohne dass man das Internet neu erfindet.

Meine Empfehlung: Schreibe die Hilfe in HTML. z.B. mit dem WYSIWYG Editor "Kompozer".

Beispiel, meine Online-Doku: https://elela.de/Hilfe/Index.php?url=Index.htm
Beispiel, die CHM Datei: https://elela.de/link.php?f=Li9FbGVMYV9 ... NobQ==&n=3

[charlytango]

Fpdoc kann auch nur eine Sprache. Englisch. Alles andere ist von den Entwicklern nicht akzeptiert. Info von MvC vor etlichen Jahren.
Bei der Wiki herrschen ähnliche Zustände, vernünftige Wartbarkeit der Mehrsprachigkeit werden trotz Jahrzehnte länger Diskussion nicht einmal ignoriert. Englisch ist die einzige akzeptierte Sprache.

Das tut echt weh, ich halte das für eine Fehlentscheidung oder reine Sturheit.
Auf der einen Seite die mangelnde Verbreitung beklagen und auf der anderen Seite nichts zur Internationalisierung beitragen, besonders wenn das Wiki das automatisiert könnte.