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.

[charlytango]

Also: für den ersten Teil, die (Entwickler-)Dokumentation von Applikationen bzw Komponenten habe ich mich nun wegen der auch hier beschriebenen fehlenden Flexibilität gegen fpDoc entschieden. meine neue Basis wird PasDoc werden. Es kann mit Kommentaren direkt im Code dokumentiert werden und PasDoc baut daraus eine HTM Doku. Andere Formate wie HMLHelp, PDF, Latex etc sond ebenfalls möglich und können vom Entwicler selbst erzeugt werden.

Idee:

Ein zusätzliches, unabhängig installierbares Lazarus-Paket (Arbeitstitel ctPasDocHelp) das PasDoc-Dokumentation als weitere Hilfequelle neben FpDoc verfügbar macht. FpDoc wird dabei **nicht ersetzt oder deinstalliert**, sondern einfach ergänzt: Bestehende Projekte, die FpDoc verwenden, funktionieren unverändert weiter.

Geplante Funktionen

PasDoc-Hilfe im Object Inspector:
F1 auf einer Eigenschaft oder Methode zeigt die aus dem PasDoc-Kommentar generierte Hilfeseite an, direkt in der IDE. Bei mehreren gefundenen Treffern zeigt die IDE eine Auswahlliste der Hilfesysteme an.

Mehrsprachigkeit:
- Entwickler können für einzelne Bezeichner eigene, handgeschriebene
Übersetzungen als separate Dateien hinterlegen — die werden bevorzugt angezeigt.
- Fehlt eine solche manuelle Übersetzung, wird der Text automatisch per
Online-Übersetzungsdienst in die gewünschte Sprache übersetzt (frei wählbar,
unabhängig von der eingestellten IDE-Sprache).
- Bei Verbindungs- oder Übersetzungsproblemen wird trotzdem der Originaltext gezeigt
(mit dezentem Hinweis statt störendem Fehlerdialog) — es soll nie "keine Hilfe"
angezeigt werden, nur weil eine Übersetzung gerade nicht klappt.


Mitgelieferte vollständige Dokumentation:
Jede Komponentenversion/Programmversion bringt zusätzlich eine komplette, mit PasDoc erzeugte HTML-Dokumentation mit aktuell, zur jeweiligen Version passend, direkt im Browser (der kann auch übersetzen) zu öffnen. Kann mit CLI oder mit einem GUI erzeugt werden.

Einfache Einbindung langer Texte:
Über PasDocs Include-Mechanismus lassen sich ausführliche Beschreibungen aus dem Code auslagern, ohne die Quelldateien aufzublähen.

Mittelfristig denkbar
... aber noch nicht Teil des ersten Entwurfs — ist ein per Shortcut aufrufbarer kleiner PasDoc-Editor, der beim Verfassen von PasDoc-Kommentaren hilft (z. B. für alle, die die Tag-Syntax nicht auswendig kennen). Angelehnt an der Idee des Message Composers.


Das Projekt ist aktuell in der Spezifikationsphase — es gibt noch keinen Code. Bevor es
in die Umsetzung geht, würde ich mich über eure Einschätzung freuen:

- Kennt ihr bereits ähnliche Lösungen oder frühere Versuche in diese Richtung?
- Fehlt aus eurer Sicht eine wichtige Funktion, die eine PasDoc-Hilfe im Object Inspector
unbedingt haben sollte?
- Habt ihr Erfahrung mit PasDoc in größeren Lazarus-Projekten, die hier relevant wäre?

Über Feedback, Bedenken und Ideen freue ich mich sehr !


Legt los