Lazarus Dokumentation

[mschnell]

Oder sind die Fragen schon besser im englischen Forum zu stellen ?

Die ganze Thematik haben wir (wie ich oben beschrieben habe) schon vor längerer Zeit in der englischen Mailing-Liste durchdiskutiert, als ich gerne einen Hilfetext zu "CheckSynchronize" beisteuern wollte und es mir nicht möglich war, das zu tun.

Ergebnis (genau wie hier):
- mein Text ist heute noch nicht drin (obwohl niemand was gegen den Text einzuwenden hatte)
- eine Neu-Konzeptionierung des Help-Authoring Systems ist nicht sinnvoll, weil das Team die dann notwendige Realisation nicht leisten kann.
- beste Alternative: (altes) Delphi installieren und dessen Hilfe benutzen.

-Michael

[mschnell]

Irgendwie logisch, der 'Rest' gehört nicht zu Lazarus sondern zum fpc.

Vielleicht logisch aber überhaupt nicht zielführend.

Lazarus läuft immer auf fpc. Deshalb ist klar. dass neben der Hilfe für die IDE und für LCL auch die Hilfe für die fpc-language und die rtl installiert sein und über "F1" erreichbar sein muss

Deshalb auch mittlerweile abweichende Wege die Dokumentation zu erstellen.

Was natürlich zwingend ins Chaos führt. Wenn sich das Lazarus Team weigert FPDoc zu verwenden, spricht das entweder gegen FPDoc oder gegen die Organisation des Lazarus Teams.

-Michael

[af0815]

Deshalb auch mittlerweile abweichende Wege die Dokumentation zu erstellen.

Was natürlich zwingend ins Chaos führt. Wenn sich das Lazarus Team weigert FPDoc zu verwenden, spricht das entweder gegen FPDoc oder gegen die Organisation des Lazarus Teams.

Weisst du wie die Dokumentation erstellt werden ? Das hat nichts mit fpdoc zu tun.

[marcov]

- mein Text ist heute noch nicht drin (obwohl niemand was gegen den Text einzuwenden hatte)

Was ist die Mantis Nummer?

- eine Neu-Konzeptionierung des Help-Authoring Systems ist nicht sinnvoll, weil das Team die dann notwendige Realisation nicht leisten kann.

Und de Begründung für die Notwendigkeit davon gar nicht unterschreibt.

- beste Alternative: (altes) Delphi installieren und dessen Hilfe benutzen.

Delphi's Hilfe ist nicht SO viel besser. Mindestens nicht fuer RTL und Sprache.

[marcov]

Weisst du wie die Dokumentation erstellt werden ? Das hat nichts mit fpdoc zu tun.

Mann braucht gar kein Dokumentation er zu stellen um sie mit Lazarus aus zu liefern. Man muss nur die FPC CHMs einblenden im installer.

Also dieser Fakt hat gar nichts mit Dokumentation bauen und/oder Dokumentation System zu schafften, nur mit Lazarus Release engineering.

Auf Linux ist das etwas schwieriger, weil die meiste Distributionen verlangen doc rpms/debs selbst bauen zu können. RPM und deb Packagers können die Projekten immer nutzen

[mschnell]

Was ist die Mantis Nummer?

Es ist ja wohl kaum sinnvoll jede Änderung an einem Hilfe-Text über den Bugtracker laufen zu lassen. Das würde das Verfahren ja noch weiter verlangsamen.

Ich habe den Text per Mail an jemanden weitergegeben, der ihn mit FPDoc einpflegen wollte.

Da das Ergebnis aber - auch für Benutzer der svn-Vesion von Lazarus und fpc - erst nach vielen Monaten sichtbar werden sollte (nach dem Build-Prozess für das nächste offizielle Release) habe ich die Sache aus den Augen verloren.

-Michael

[marcov]

Was ist die Mantis Nummer?

Es ist ja wohl kaum sinnvoll jede Änderung an einem Hilfe-Text über den Bugtracker laufen zu lassen. Das würde das Verfahren ja noch weiter verlangsamen.

Ich habe den Text per Mail an jemanden weitergegeben, der ihn mit FPDoc einpflegen wollte.

Da das Ergebnis aber - auch für Benutzer der svn-Vesion von Lazarus und fpc - erst nach vielen Monaten sichtbar werden sollte (nach dem Build-Prozess für das nächste offizielle Release) habe ich die Sache aus den Augen verloren.

Das ist etwas anderes als was du eher gesagt hast:

mein Text ist heute noch nicht drin

[Socke]

Was ist die Mantis Nummer?

Es ist ja wohl kaum sinnvoll jede Änderung an einem Hilfe-Text über den Bugtracker laufen zu lassen. Das würde das Verfahren ja noch weiter verlangsamen.

Ich habe den Text per Mail an jemanden weitergegeben, der ihn mit FPDoc einpflegen wollte.

Auf der Arbeit würde man sagen: Voll am Prozess vorbei
Ich hatte Mitte 2013 einen Bug erstellt; Im Februar 2014 wurde der entsprechende Eintrag in Subversion hinzugefügt. Das sind in der Tat sechs Monate Wartezeit.

[mschnell]

Und de Begründung für die Notwendigkeit davon gar nicht unterschreibt.

Aus absolut nachvollziehbaren Gründen.

Absolut nachvollziehbar ist aber auch, dass die geringe Priorität, die der Hilfe eingeräumt wird eine der Ursachen für die relativ geringe Akzeptanz des ansonsten excellenten Programmier-Systems ist.

Kommerzielle Projekte investieren vermutlich weit mehr als 50% der Kosten in alles was die Verbreitung fördert also Marketing und "ködern" neuer User durch leichten Einstig durch ausgereifte Hilfe-Funktionen.

Bei einem Projekt mit ausschließlich unbezahlten Mitarbeitern muss man sich natürlich entscheiden, ob die Priorität auf die Verbreitung an neue User oder auf die Verbesserung der Verwendbarkeit für die vorhandene User-Gemeinschaft gelegt werden soll, für die natürlich funktionale Verbesserungen wichtiger sind.

Man darf sich nachher nur nicht wundern wenn genau das passiert wofür man sich entschieden hat.

-Michael

[mschnell]

Das ist etwas anderes als was du eher gesagt hast:

mein Text ist heute noch nicht drin

Es ist vielleicht zwei Jahre her, dass ich den Text geschrieben habe.

-Michael

[af0815]

Für mich liegt die Begründung eher im Unwissen über die Hilfe.

Für Anwender/Einsteiger:
Vielleicht würde es fürs erste schon reichen, wenn auf eine Frage im Forum geantwortet wird: Verwende die Hilfe "Stell dich auf xxxx und drücke F1". So gut sollte die Hilfe sein Dazu muss aber der Inhalt auch in der Hilfe zugänglich sein. Hilfe in der Sprache als solche und auch in der Ausdrucksweise des Anwenders. Diejenigen die Fachchinesisch können, sind mit dem jetzigen ja eh zufrieden.


Für Programmierer:
Klare, verständliche Dokumentation wie die Hilfe funktioniert. (Vielleicht habe ich die Infos dazu nur nicht gefunden)

[mschnell]

"Stell dich auf xxxx und drücke F1".

xxxx = TObject (RTL) -> da kommt etwas vernünftiges
xxxx = class (Object Pascal) -> da kommt ein "Code Browser" Menü mit dem ich nichts anfangen kann. (Ich bin hier Einsteiger)
xxxx = as (Object Pascal) -> No help found
xxxx = begin (Pascal) -> ebenso
xxxx = create (eigener code) -> Auswahl zwischen verschiedenen Hierarchiestufen: Sinnvoll !

-Michael

[marcov]

xxxx = class (Object Pascal) -> da kommt ein "Code Browser" Menü mit dem ich nichts anfangen kann. (Ich bin hier Einsteiger)

Chapter 6 classes.

xxxx = as (Object Pascal) -> No help found

Funktioniert nicht in Lazarus, aber schon in textmode IDE (12.8.7 class operators). Ist ein Problem von Lazarus (der Fragt offenbar das Hilfesystem nicht um "as"). Ebenso für "is". Zu kurz?

Der Textmode IDE ist eine guter Weise um die Hilfe unabhängig van Lazarus zu testen.

xxxx = begin (Pascal) -> ebenso

13.2.1 compound statements

Fange mal an die Hilfe richtig zu installieren

Ich habe wirklich nichts anders gemacht als Package Chmhelp in der IDE installiert und die CHMs in docs/html geworfen.

Worten die mit \keywordlink{} markiert sein in ref.tex reagieren auf F1.

p.s. habe gehört das Embarcadero die Hilfe in die nächste Delphi Version auch wieder auf CHM umstellt. (kein Docviewer (aka htmlhelp2) mehr, ich nehme an weil Visual Studio jetzt htmlhelp3 nutzt, und htmlhelp2 nicht mehr gepflegt wird)

[marcov]

Für mich liegt die Begründung eher im Unwissen über die Hilfe.

Nein, im Unwillen tatsächlich damit zu wirken. Die CHM basierte Hilfe gibst schon mehrere Jahren, und wir haben hier Anfänger Frage von Regulars.

Das Bild das besteht von der Hilfe ist viele Malen schlechter als wie es wirklich ist. Mann kann grundsätzlich detail Bugs nicht von Architectur Problemen unterscheiden. Man ruft nur "neu", "modern" und "wiki".

Für Anwender/Einsteiger:
Vielleicht würde es fürs erste schon reichen, wenn auf eine Frage im Forum geantwortet wird: Verwende die Hilfe "Stell dich auf xxxx und drücke F1". So gut sollte die Hilfe sein Dazu muss aber der Inhalt auch in der Hilfe zugänglich sein. Hilfe in der Sprache als solche und auch in der Ausdrucksweise des Anwenders. Diejenigen die Fachchinesisch können, sind mit dem jetzigen ja eh zufrieden.

Ich würde schon glücklich als die Hilfe etwas komplett wäre, für eine gewisse Basissatz Klassen, und die Sprache.

[mschnell]

Chapter 6 classes.

??? Kann ich im "code Browser" nirgendwo sehen.

Der Textmode IDE ist eine guter Weise um die Hilfe unabhängig van Lazarus zu testen.

Ja. Ist für den zitierten Einsteiger aber ungeeignet.

Fange mal an die Hilfe richtig zu installieren

Ich habe nicht die "released" version installiert, sondern verwende die aktuelle und ständig veränderte Version aus dem svn. Vielleicht ist deswegen tatsächlich etwas nicht richtig installiert. Ich möchte aber auch nicht über eine nicht mehr ganz aktuelle released Version diskutieren.

-Michael