Lazarus Dokumentation

[marcov]

Das FPDoc-System finde ich wunderbar passend, weil hier der Programmquelltext und die Benutzer-Dokumentation getrennt wird. [...]

Interessant, das empfinde ich eigentlich als Nachteil. Meiner Meinung nach, sollte die Doku immer nahe am entsprechenden Quellcode stehen. Also im Programmquellcode.

Habe ich mehrmals versucht, aber zu unpraktisch. Meistens weil die Quelldateien gigantisch dadurch Kompliziert werden, aber auch zb wenn Symbole von (.inc) File ändern (aber nicht Unit) gibt das Elend mit SVN um eine kleinen Fix in sammt Trunk und Fixes zu machen.

Deswegen benutze ich auch PasDc anstelle von FpDoc.

Kann gut Funktionieren in ein einfaches Projekt, aber ist ein Elend in ein großes, von mehrere Committers betreutes Projekt. Dokumentation sollte nicht Quellen, und Aufteilung der Quellen beeinflussen.

[marcov]

(Hier muss also Software geschrieben werden.)

Gut, starte ein neuen Thread wenn der erster Version fertig ist

[Socke]

Das FPDoc-System finde ich wunderbar passend, weil hier der Programmquelltext und die Benutzer-Dokumentation getrennt wird. [...]

Interessant, das empfinde ich eigentlich als Nachteil. Meiner Meinung nach, sollte die Doku immer nahe am entsprechenden Quellcode stehen. Also im Programmquellcode.

Habe ich mehrmals versucht, aber zu unpraktisch. Meistens weil die Quelldateien gigantisch dadurch Kompliziert werden, aber auch zb wenn Symbole von (.inc) File ändern (aber nicht Unit) gibt das Elend mit SVN um eine kleinen Fix in sammt Trunk und Fixes zu machen.

In kleineren Projekten mit einer geradlinigen Entwicklung ist das noch handhabbar, doch in RTL, FCL und LCL gibt es sehr große Units mit mehreren Tausend Zeilen Code und entsprechend vielen Symbolen.

Kannst du bitte kurz den Workflow bei der Dokumentation darstellen. Mir scheint, dass es doch große Unterschiede zwischen zwischen dem, was tatsächlich getan wird und dem was die meisten davon denken, gibt. Es geht wohl nicht nur darum, das Schreiben an sich zu strukturieren sondern auch den gesamten Workflow zu verinfachen?

Deswegen benutze ich auch PasDc anstelle von FpDoc.

Kann gut Funktionieren in ein einfaches Projekt, aber ist ein Elend in ein großes, von mehrere Committers betreutes Projekt. Dokumentation sollte nicht Quellen, und Aufteilung der Quellen beeinflussen.

Bei PasDoc und ähnlichen Formaten wie JavaDoc und PHPDoc denke ich, dass diese sehr gut in sehr sauber getrennten Dateien arbeiten. Z.b gibt es bei Java pro Datei in der Regel nur eine echte Klasse, die zu dokumentieren ist. Durch die Aufteilung des bisherigen Quelltextes gibt es in der Tat einige Schwierigkeiten, die nicht zuletzt der Umsetzung der Platformunabhängigkeit geschuldet sind.

[mschnell]

Gut, starte ein neuen Thread wenn der erster Version fertig ist

Ich denke wir haben nun die Frage "Warum immer Java" des Initiator des ursprünglichen Threads jetzt erschöpfend beantwortet.

-Michael

[af0815]

BTW: Ich habe gerade einen Build der Dokumentation in HTML unter Windows durchlaufen lassen. Es geht, ich habe allerdings eine Datei (makefile.4ht) etwas ändern müssen (ca. 4 Zeilen), da sie zu Unixspezifisch ist. Der Build ist jetzt ohne Abbruch durchgelaufen.

Für diejenigen die es auch Probieren wollen gibt ein paar Voraussetzungen
*) Ein funktionierender Compiler mit den Sourcen
*) Die Sourcen der Doku
*) Die UnixUtils
*) Funktionierende Latexumgebung (bei mir MikTex 2.9)

Hier meine aktuelle CMD Datei unter Windows 7

Code: Alles auswählen

REM Pfade setzen
set PATH=X:\Pascal\Pascal\lazarus\fpc\svn\bin\i386-win32;X:\Pascal\Pascal\UnxUtils\usr\local\wbin;%PATH%
X:
REM Löschen des Bereiches
rmdir X:\Pascal\fpcbuild\build\ /S/Q
REM Kopieren der Dateien aus dem SVNBereich
xcopy X:\Pascal\fpcbuild\fpcdocs\* X:\Pascal\fpcbuild\build\fpcdocs\* /s/e
REM Kopieren von benötigten exe
xcopy X:\Pascal\Pascal\lazarus\fpc\2.6.4\bin\i386-win32\gmkdir.exe X:\Pascal\fpcbuild\build\bin\i386-win32\ /s
xcopy X:\Pascal\Pascal\lazarus\fpc\2.6.4\bin\i386-win32\make.exe X:\Pascal\fpcbuild\build\bin\i386-win32\ /s
xcopy X:\Pascal\Pascal\lazarus\fpc\2.6.4\bin\i386-win32\gecho.exe X:\Pascal\fpcbuild\build\bin\i386-win32\ /s
ECHO Kopieren der benötigten exe fertig
cd X:\Pascal\fpcbuild\build\fpcdocs

REM Buildprozess
make html FPCSRCDIR=X:\Pascal\fpcbuild\fpcsrc\ PP=X:\Pascal\Pascal\lazarus\fpc\svn\bin\i386-win32\ppc386.exe LATEX="C:\Program Files\MiKTeX 2.9\miktex\bin\latex.exe" GINSTALL=X:\Pascal\fpcbuild\build\bin\i386-win32\gecho.exe ECHO=X:\Pascal\fpcbuild\build\bin\i386-win32\gecho.exe
 
echo zurueck mit enter
pause
exit
 

Meine aktuelle MakeFile.4ht

Code: Alles auswählen

#
# Make latex using tex4ht
#
 
HTFONTS=/usr/share/texmf/tex/generic/tex4ht/ht-fonts/
TEXEXTS=.4ct .aux .dvi .xref .4tc .idx .log .tmp .lg .idv
 
%.chk: %.tex
	rm -rf $(basename $<)
	rm -f $(addprefix $(basename $<),$(TEXEXTS))
	cp -f preamble.ts4 preamble.inc
	$(LATEX) $<
	$(LATEX) $<
	$(LATEX) $<
	$(GINSTALL) -d $(basename $<) -m755
#	edit af0815
#	for ext in $(TEXEXTS); do [ -f  ] && mv $(basename $<)$$ext $(basename $<); done || true
	mkdir $(basename $<)
	for /D %%i in ($(TEXEXTS)) do if exist $(basename $<)%%i xcopy $(basename $<)%%i $(basename $<) 
	cp -f -r ./pics $(basename $<)/pics
#      endedit
#	cp -f -r ./pics/ $(basename $<)/pics/
	cd $(basename $<) && tex4ht $<  && t4ht $< -m644
	rm -f -r $(basename $<)/pics
	rm -f $(addprefix $(basename $<)/$(basename $<),$(TEXEXTS))
	-cp $(basename $<).kwd $(basename $<)
	touch $@
 

PS: DIESER Thread handelt jetzt von der Freepscal/Lazarusdokumentation und nicht mehr von Kaffee etc.

[marcov]

Habe ich mehrmals versucht, aber zu unpraktisch. Meistens weil die Quelldateien gigantisch dadurch Kompliziert werden, aber auch zb wenn Symbole von (.inc) File ändern (aber nicht Unit) gibt das Elend mit SVN um eine kleinen Fix in sammt Trunk und Fixes zu machen.

In kleineren Projekten mit einer geradlinigen Entwicklung ist das noch handhabbar, doch in RTL, FCL und LCL gibt es sehr große Units mit mehreren Tausend Zeilen Code und entsprechend vielen Symbolen. [/quote]

Handhabbar, aber ich mag das noch immer nicht.

Kannst du bitte kurz den Workflow bei der Dokumentation darstellen. Mir scheint, dass es doch große Unterschiede zwischen zwischen dem, was tatsächlich getan wird und dem was die meisten davon denken, gibt. Es geht wohl nicht nur darum, das Schreiben an sich zu strukturieren sondern auch den gesamten Workflow zu verinfachen?

Erster Version:
1. mache ein XML mit makeskel (benutzt Parameter wie Compiler)
2. Dokumentiere es so viel wie möglich
3. Commit
4. regeneriere Docs (FPC laest lehre Nodes nicht sehen, LCL tuts)

Update: wie erster, aber gebe Parameter --update an makeskel. (siehe auch lazarus/docs/xml/updatexml.bat

Michael macht Typisch einige solche Iterationen pro FPC cyclus. Andere wie probe lesen und melden Patches an im Bugtracker.

Ich commit Patches, behelfe Fehler die ich selbst finde direkt, und arbeite von Zeit zu Zeit ans CHM backend insgesamt die CHM Generierung vor jeder Release.

Reinier arbeittete auch viel an LHelp.

[af0815]

Als Beispiel: Wenn der Benutzer F1 drückt und auf 'class' steht, so müsste dort der Inhalt aus dee Languagereference stehen oder ähnlicher Inhalt der ihm weiterhilft.

Wenn es ein Bug ins heutige System wäre, denn ist das noch kein Anlass um das System zu ändern. Aber ES FUNKTIONIERT SCHON! Hier kommt der Referenz Guide "chapter 6: CLASSES" wenn ich das mache. (mit installierter CHM hilfe, ich nutze nie online)

Ich habe jetzt auf meinem System die Dateien laut der Anleitung installiert. quelle: https://github.com/alrieckert/lazarus/b ... README.txt

Allerdings arbeitet die Hile nicht Kontextbezogen. Egal wo ich mit dem Cursor in Lazarus stehe, es wird immer die lcl im Hilfefenster angesprungen.

Code: Alles auswählen

lhelp is a program written entirely using FreePascal and the LCL to read .chm help files.
 
This is a basic HOWTO for integrating lhelp into the Lazarus IDE.
 
 
1 ) Start Lazarus
 
2 ) Install Package:
 
    In the Components Menu choose "Open Package File"
    Browse to the lazarus/components/chmhelp/packages/idehelp directory and
    open "chmhelppkg.lpk"
 
3 ) Now click "Install".
 
4 ) Restart Lazarus(if it didn't automatically)
 
5 ) Open the lhelp project in lazarus/components/chmhelp/lhelp/lhelp.lpi
    Compile lhelp.
 
6 ) Configure the paths for the lhelp:
 
    From the Tools menu choose "Options"
    Change to Help / Help options.
    Change to the "Viewers" tab and select "CHM Help Viewer"
 
    HelpEXE:
    Leave it empty to use the default: $(LazarusDir)/components/chmhelp/lhelp/lhelp(.exe)
 
    HelpFilesPath:
    This is the search path where to search for chm files.
    Default is $(LazarusDir)/docs/html;$(LazarusDir)/docs/html/lcl;$(LazarusDir)/docs/chm
 
    You can download the lcl.chm, fcl.chm, rtl.chm from
    http://sourceforge.net/projects/freepascal/files/Documentation/
    the lcl.chm, rtl.chm, fcl.chm, prog.chm from
    http://www.stack.nl/~marcov/doc-chm.zip
 
    HelpLabel Name and Tag do not need to be altered.
    The HelpLabel is the name of the named pipe that lazarus will use to communicate with lhelp.
 
7 ) Configure the Databases
 
    Choose the Databases tab.
 
    RTLUnits:
    Leave it empty to use the default: "rtl.chm://"
    FCLUnits:
    Leave it empty to use the default: "fcl.chm://"
 
    NOTE if you have only a single lcl-fcl-rtl.chm file then paths become:
    "lcl-fcl-rtl.chm://rtl/"
    "lcl-fcl-rtl.chm://fcl/"
    "lcl-fcl-rtl.chm://lcl/"
 
Now close this window and check out the integrated help :)
 
Enjoy

Mir ist unlar, was wo im Punkt 7 Eingetragen wird.

[marcov]

Ich denke das ist alt. Seit 1.2.x braucht man nur

1) chmhelp in lazarus zu installieren.
2) lhelp zu kompilieren
3) chms in docs/html zu werfen

1+2 können schon getan sein (hängen davon ab wie man Lazarus compiliert hat)

und es sollte funktionieren. (und so funktionierst für mich. Release und trunk)

[mschnell]

Michael macht ...

Ich commit Patches, behelfe Fehler die ich selbst finde direkt, und arbeite von Zeit zu Zeit ans CHM backend insgesamt die CHM Generierung vor jeder Release.

Reinier arbeittete auch viel an LHelp.

Dadurch haben wir ja tatsächlich eine funktionsfähige Hilfe. Aber leider habt ihr natürlich sehr viele andere wichtige Aufgaben.

Ich habe vor längerer Zeit (siehe englische mailing-Liste) ein Patch für die Hilfe zu "CheckSynchronize" eingereicht. Auf die Frage, wie es es schaffe, mir anzuschauen, was ich da gebastelt habe wurde ich darauf verwiesen, dass ein Update der Hilfe für die RTL erst mit dem nächsten offiziellen Release von fpc sichtbar wird. Wenn ich jetzt (svn-Version von Lazarus und fpc) "F1" auf CheckSynchronize mache, kommt immer noch der rudimentäre Text, der keine Aussage darüber macht was CheckSynchronize wirklich macht und wie man es verwenden kann.

Die Hilfe (online und downsloadable) muss kurzfrisatig unabhängig von den Software-Releases updatebar sein !!!! Die Konsistenz des Software-Systemes wird dadurch ja nicht gefährdet, aber den Usern kann es sehr nutzen.

So braucht man sich nicht zu wundern, dass es "keine Hilfetext-Schreiber gibt". (In einem Land ohne Straßen gibt es auch keine Autos.)

Natürlich ist es ein Riesen-Projekt, ein gut funktionierendes für "Laien" einsetzbares Hilefetext-Authoring System zu bauen. FPDoc ist ja vom Ansatz her vermutlich ein guter Weg, ist aber m.E. inzwischen nicht mehr zeitgemäß und die Infrastruktur wird nicht weiterentwickelt. Deshalb "FPDoc2", nicht "Wiki-Hilfe" !

IMHO ist es wegen des Multiplikations-Effekts oft sinnvoll in Tools zu investieren.

- fpc/Lazarus ist ein Tool um die Kreativität der Anwendungs-Programmierer freizusetzen.
- Die Hilfetexte sind ein Tool um die Möglichkeiten von fpc/Lazarus nutzbar zu machen
- Das Hilfetext-Authoring-System ist ein Tool um Freiwillige in die Lage zu versetzen Hilfetexte zu pflegen.

Ich sehe da einen Multiplikations-Effekt und deshalb eine Prioritäts-Erhöhung für Verbesserungen auf jeder Ebene.

-Michael

[af0815]

Die Hilfe (online und downsloadable) muss kurzfrisatig unabhängig von den Software-Releases updatebar sein !!!! Die Konsistenz des Software-Systemes wird dadurch ja nicht gefährdet, aber den Usern kann es sehr nutzen.

Das bedeuted, das der Bau der Hilfedateien so wie bei den Nightly Builds erfolgen sollte, damit es es möglich immer aktuelle Hilfe zu erhalten.

Was noch ein Problem ist, das die Hilfe NUR auf Englisch zentriert ist. Ich habe gesehen, das es auch Anfragen zu anderen Sprachen gibt (Russisch,...). Aber noch nicht wirklich eine Antwort dazu.

[marcov]

Die Hilfe (online und downsloadable) muss kurzfrisatig unabhängig von den Software-Releases updatebar sein !!!!

Ist sie auch. Es gibt nur ein paar Bedingungen und muss sich etwas Mühe geben. Man konnte in einer Mittag ein Linux VM (oder ein RPI) aufsetzen die Docs baut und zu einen Webserver hoch ladet. Ist in Vergangenheit auch schon getan. (zb Lazarus-CCR, vielleicht noch immer).

Die Konsistenz des Software-Systemes wird dadurch ja nicht gefährdet, aber den Usern kann es sehr nutzen.

Wie schon gesagt haben diverse Initiativen (täglich uploaden, Kommentar Funktionalität) nicht zur substantiell mehr Beitragen geführt.

Es ist nichts da gehen zu versuchen Dingen einfacher zu machen aber man muss deshalb vorsichtig sein gigantische Projekten zu bedenken in der Hoffnung das die zusätzliche Beitragen dieser Arbeit Kompensieren werden..

So braucht man sich nicht zu wundern, dass es "keine Hilfetext-Schreiber gibt". (In einem Land ohne Straßen gibt es auch keine Autos.)

Es gibt viele Projekten wo man freiwillig arbeiten kann um anderen Menschen zu helfen. Nur ein relativ kleine Gruppe tut das. Das ist das Kernproblem. Gelegenheit kreiert nicht automatisch Leute die mithelfen wollen. (ja mit der Mund, aber nicht wirklich).

Natürlich ist es ein Riesen-Projekt, ein gut funktionierendes für "Laien" einsetzbares Hilefetext-Authoring System zu bauen. FPDoc ist ja vom Ansatz her vermutlich ein guter Weg, ist aber m.E. inzwischen nicht mehr zeitgemäß und die Infrastruktur wird nicht weiterentwickelt.

Solch eine Unsinn?! fpdoc wird weiterentwickelt.

[mschnell]

Das bedeuted, das der Bau der Hilfedateien so wie bei den Nightly Builds erfolgen sollte, damit es es möglich immer aktuelle Hilfe zu erhalten.

Das wäre wohl nur auf den ersten Blick eine Verbesserung.
Der eigentliche Wunsch ist, dass man das Ergebnis als Online-Hilfe direkt nach dem Editiervorgang sieht. Deshalb kam der Vorschlag die Wiki-Technik als Basis zu verwenden. Da ist natürlich diverses zu berücksichtigen. Nur dem Autor (und idealer Weise vom Autor benannten oder sich dafür eintragenden dritten), sollten seine Texte direkt präsentiert werden. Anderen Usern erst nach einer Freigabe durch die "Hilfe-Reaktion" (mindestens z.B. wöchentlich).

Außerdem muss die Hilfe natürlich immer zur gerade verwendeten Version der Software passen. die notwendigen Forks muss die Infrastruktur sinnvoll verwalten. Wenn aktuell die Hilfe im "Nightly Build" upgedatet würde, würden die Verwender des offiziellen Releases der Software mit unpassenden Texten genervt.

Was noch ein Problem ist, das die Hilfe NUR auf Englisch zentriert ist. Ich habe gesehen, das es auch Anfragen zu anderen Sprachen gibt (Russisch,...). Aber noch nicht wirklich eine Antwort dazu.

Jeder Seite der Hilfe kann parallel für verschiedene Software-Versionen und in verschiedenen Sprachen existieren. Das muss die Infrastruktur (Authoring-System, "F1"-Anzeigesystem (online und offline) und Browser-Zugriff über die Website) entsprechend verwalten.

-Michael

[marcov]

Das bedeuted, das der Bau der Hilfedateien so wie bei den Nightly Builds erfolgen sollte, damit es es möglich immer aktuelle Hilfe zu erhalten.

Das wäre wohl nur auf den ersten Blick eine Verbesserung.
Der eigentliche Wunsch ist, dass man das Ergebnis als Online-Hilfe direkt nach dem Editiervorgang sieht.

Kann auch. Man kontte fpdoc modifizieren teilweise html zu generieren, und das in eine Webbrowser sichtbar zu machen.

Und das Resultat nach eine Webservice oder so zu schicken. Das ist besser dann Wiki was zu wenig Struktur hat.

VIel kann, aber wie Dokumentieren MUSS MAN WOLLEN!

[af0815]

Ich denke das ist alt. Seit 1.2.x braucht man nur

1) chmhelp in lazarus zu installieren.
2) lhelp zu kompilieren
3) chms in docs/html zu werfen

1+2 können schon getan sein (hängen davon ab wie man Lazarus compiliert hat)

und es sollte funktionieren. (und so funktionierst für mich. Release und trunk)

Ich musste die Konfigurationsdateien für Lazarus aus Benutzerverzeichnis\AppData\Local\lazarus löschen damit es geht.

Die Datein sind im chm Verzeichnis
3) chm's in Lazarusdir/doc/chm

kann natürlich sein, das auch im html gesucht wird.

Geht somit auch. Testen kann man es einfach (wie schon ein paar Posts vorher erwähnt) indem man ein neus Projekt erstellt, sich auch das Keywort class mit dem Cursor bewegt und die F1 Taste drückt. Nach kurzer Zeit öffnet sich dann die lhelp und zeigt dann dioe ref.chm mit Chapter 6 an. In der lhelp wird dann in der zweiten Zeile von unten angzeigt nach was gesucht wurd und in der Zeile darunter, was für Hilfen geladen wurden.

Für den Anwender ist das zumutbar

Inkonsequent ist für mich allerdings:
das die lcl.chm nicht im chm Pfad liegt sondern unter Lazarusdir/doc/html/lcl/
Und für die user bei der installation keine chm erzeugt wird, man aber herunterladen kann

Die Priorität dürft auf den chm liegen.

[mschnell]

Es gibt viele Projekten wo man freiwillig arbeiten kann um anderen Menschen zu helfen. Nur ein relativ kleine Gruppe tut das. Das ist das Kernproblem.

Klar. Wenn man einen Hilfetext schreiben kann braucht man ihn selber nicht, sonst könnte man ihn ja nicht schreiben. Wenn man aber Beiträge zur Software leistet, kann man das Ergebnis später auch selber nutzen.

Hilfetexte schreiben (und auch die Infrastruktur für die Hilfe zu programmieren) ist also viel "selbstloser" als an "funktionaler" Open Source Software mitzuwirken.

Vermutlich ist das das Hauptproblem warum sich Community-Software sich immer noch nicht gegen funktionsal kompatibler kommerzieller Software durchsetzen kann (keine Ahnung warum irgendjemand wirklich MS-Office, Otlook oder Internet Explorer braucht, wo es doch Libre-Office, Thunderbird und Firefox gibt...) .

Solch eine Unsinn?! fpdoc wird weiterentwickelt.

OK.
Was waren die letzten Veränderungen ?

-Michael