Verwendung von fpdoc

Für Fragen rund um die Ide und zum Debugger
PascalDragon
Beiträge: 823
Registriert: Mi 3. Jun 2020, 07:18
OS, Lazarus, FPC: L 2.0.8, FPC Trunk, OS Win/Linux
CPU-Target: Aarch64 bis Z80 ;)
Wohnort: München

Re: Verwendung von fpdoc

Beitrag von PascalDragon »

braunbär hat geschrieben:
Mo 14. Dez 2020, 16:14
Ich werde mir jetzt pasdoc einmal genauer anschauen. Schön wäre es halt, wenn sich die Entwickler auf ein Tool einigen würden, mit dem dann auch die ganze Dokumentation von Free Pascal und Lazarus gebündelt wird. Da ist leider auch ein ziemlicher Wildwuchs.
Die FPC und Lazarus Entwickler sind sich hier einig: fpdoc. Was dritte machen ist nicht unter unserer Kontrolle.
FPC Compiler Entwickler

Benutzeravatar
m.fuchs
Lazarusforum e. V.
Beiträge: 2634
Registriert: Fr 22. Sep 2006, 19:32
OS, Lazarus, FPC: Winux (Lazarus 2.0.10, FPC 3.2.0)
CPU-Target: x86, x64, arm
Wohnort: Berlin
Kontaktdaten:

Re: Verwendung von fpdoc

Beitrag von m.fuchs »

braunbär hat geschrieben:
Mo 14. Dez 2020, 16:14
Schön wäre es halt, wenn sich die Entwickler auf ein Tool einigen würden, mit dem dann auch die ganze Dokumentation von Free Pascal und Lazarus gebündelt wird. Da ist leider auch ein ziemlicher Wildwuchs.
Das ist genauso unrealistisch wie die Einigung auf ein Versionskontrollsystem.
Software, Bibliotheken, Vorträge und mehr: https://www.ypa-software.de

mschnell
Beiträge: 3444
Registriert: Mo 11. Sep 2006, 10:24
OS, Lazarus, FPC: svn (Window32, Linux x64, Linux ARM (QNAP) (cross+nativ)
CPU-Target: X32 / X64 / ARMv5
Wohnort: Krefeld

Re: Verwendung von fpdoc

Beitrag von mschnell »

PascalDragon hat geschrieben:
Di 15. Dez 2020, 09:27
Die FPC und Lazarus Entwickler sind sich hier einig: fpdoc. Was dritte machen ist nicht unter unserer Kontrolle.
Wirklich ?
Ich habe da vor einiger Zeit mal mitdiskutiert, weil ich bei der (englischen) Dokumentation helfen wollte, aber nicht bei der total unklaren Ausgangslage. Da gab Bestrebungen, irgendwie ein Wiki als Master-Dolkumentation zu verwenden und daraus die verschiedenen Formate zu generieren.

-Michael
Zuletzt geändert von mschnell am Do 17. Dez 2020, 12:21, insgesamt 1-mal geändert.

Socke
Lazarusforum e. V.
Beiträge: 3158
Registriert: Di 22. Jul 2008, 19:27
OS, Lazarus, FPC: Lazarus: SVN; FPC: svn; Win 10/Linux/Raspbian/openSUSE
CPU-Target: 32bit x86 armhf
Wohnort: Köln
Kontaktdaten:

Re: Verwendung von fpdoc

Beitrag von Socke »

Soweit ich das überblicke, gibt es für verschiedene Bereiche verschiede Quellformate:
  • Dokumentation FPC (User's Guide, Programmer's Guide, Language Reference Guide): LaTeX nach HTML/PDF (und CHM?)
  • Code-Dokumentation RTL, FCL, LCL: fpdoc nach HTML/PDF/CHM
  • Anwendungsdokumentation Lazarus: Wiki (wird in Teilen auch in die CHM-Hilfe extrahiert)
MfG Socke
Ein Gedicht braucht keinen Reim//Ich pack’ hier trotzdem einen rein

marcov
Beiträge: 1100
Registriert: Di 5. Aug 2008, 09:37
OS, Lazarus, FPC: Windows ,Linux,FreeBSD,Dos (L trunk FPC trunk)
CPU-Target: 32/64,PPC(+64), ARM
Wohnort: Eindhoven (Niederlande)

Re: Verwendung von fpdoc

Beitrag von marcov »

braunbär hat geschrieben:
Mo 14. Dez 2020, 16:14
Ich werde mir jetzt pasdoc einmal genauer anschauen. Schön wäre es halt, wenn sich die Entwickler auf ein Tool einigen würden, mit dem dann auch die ganze Dokumentation von Free Pascal und Lazarus gebündelt wird. Da ist leider auch ein ziemlicher Wildwuchs.
Samt Lazarus und FPC nutzen fpdoc. Also das ist schon geeinigt auf ein Tool.

marcov
Beiträge: 1100
Registriert: Di 5. Aug 2008, 09:37
OS, Lazarus, FPC: Windows ,Linux,FreeBSD,Dos (L trunk FPC trunk)
CPU-Target: 32/64,PPC(+64), ARM
Wohnort: Eindhoven (Niederlande)

Re: Verwendung von fpdoc

Beitrag von marcov »

Socke hat geschrieben:
Di 15. Dez 2020, 11:22
LaTeX nach HTML/PDF (und CHM?)
latex->tex4ht -> Html -> CHM.

fpdoc dagegen generiert HTML spezifisch für CHM Konvertierung (ist also anders als Html fürs Web).

mschnell
Beiträge: 3444
Registriert: Mo 11. Sep 2006, 10:24
OS, Lazarus, FPC: svn (Window32, Linux x64, Linux ARM (QNAP) (cross+nativ)
CPU-Target: X32 / X64 / ARMv5
Wohnort: Krefeld

Re: Verwendung von fpdoc

Beitrag von mschnell »

Socke hat geschrieben:
Di 15. Dez 2020, 11:22
Soweit ich das überblicke, gibt es für verschiedene Bereiche verschiede Quellformate:
  • Dokumentation FPC (User's Guide, Programmer's Guide, Language Reference Guide): LaTeX nach HTML/PDF (und CHM?)
  • Code-Dokumentation RTL, FCL, LCL: fpdoc nach HTML/PDF/CHM
  • Anwendungsdokumentation Lazarus: Wiki (wird in Teilen auch in die CHM-Hilfe extrahiert)
Totaler Wildwuchs :(
-Michael

Benutzeravatar
af0815
Lazarusforum e. V.
Beiträge: 6197
Registriert: So 7. Jan 2007, 10:20
OS, Lazarus, FPC: FPC fixes Lazarus fixes per fpcupdeluxe (win,linux,raspi)
CPU-Target: 32Bit (64Bit)
Wohnort: Burgenland
Kontaktdaten:

Re: Verwendung von fpdoc

Beitrag von af0815 »

mschnell hat geschrieben:
Do 17. Dez 2020, 12:22
Totaler Wildwuchs :(
-Michael
Ich verfolge das schon lange, es ist kein Wildwuchs, sondern Evolution. Die klassisch mit Latex, automatsierten Latex und dann in Richtung fpdoc gegangen ist, weil Latex auch nicht gerade verbreitet mehr ist.
Blöd kann man ruhig sein, nur zu Helfen muss man sich wissen (oder nachsehen in LazInfos/LazSnippets).

braunbär
Beiträge: 369
Registriert: Do 8. Jun 2017, 18:21
OS, Lazarus, FPC: Windows 10 64bit, Lazarus 2.0.10, FPC 3.2.0
CPU-Target: 64Bit
Wohnort: Wien

Re: Verwendung von fpdoc

Beitrag von braunbär »

marcov hat geschrieben:
Mi 16. Dez 2020, 15:32
braunbär hat geschrieben:
Mo 14. Dez 2020, 16:14
Ich werde mir jetzt pasdoc einmal genauer anschauen. Schön wäre es halt, wenn sich die Entwickler auf ein Tool einigen würden, mit dem dann auch die ganze Dokumentation von Free Pascal und Lazarus gebündelt wird. Da ist leider auch ein ziemlicher Wildwuchs.
Samt Lazarus und FPC nutzen fpdoc. Also das ist schon geeinigt auf ein Tool.
Wenn das tatsächlich der Fall wäre, dann wäre es ja gut. Vielleicht hat ja wirklich vor ganz kurzer Zeit eien Einigung stattgefunden, und es ist nur noch nicht umgesetzt worden, das kann ich nicht beurteilen.
Tatsache ist, dass es derzeit auf FPDoc-Basis nahezu keine Dokumentation gibt, die Dokumentation findet sich im Web und in CHM Files, die offensichtlich nicht auf FPDoc basieren, weil die entsprechenden FPDoc Files sind überwiegend ziemlich leer.

PascalDragon
Beiträge: 823
Registriert: Mi 3. Jun 2020, 07:18
OS, Lazarus, FPC: L 2.0.8, FPC Trunk, OS Win/Linux
CPU-Target: Aarch64 bis Z80 ;)
Wohnort: München

Re: Verwendung von fpdoc

Beitrag von PascalDragon »

mschnell hat geschrieben:
Do 17. Dez 2020, 12:22
Socke hat geschrieben:
Di 15. Dez 2020, 11:22
Soweit ich das überblicke, gibt es für verschiedene Bereiche verschiede Quellformate:
  • Dokumentation FPC (User's Guide, Programmer's Guide, Language Reference Guide): LaTeX nach HTML/PDF (und CHM?)
  • Code-Dokumentation RTL, FCL, LCL: fpdoc nach HTML/PDF/CHM
  • Anwendungsdokumentation Lazarus: Wiki (wird in Teilen auch in die CHM-Hilfe extrahiert)
Totaler Wildwuchs :(
Das hat nichts mit Wildwuchs zu tun, sondern mit den Usecases: Der Anwendungszweck von fpdoc ist Code Dokumentation. Dafür wird es auch verwendet. Die Guides kann man damit einfach nicht umsetzen. Also wird auf etwas zurückgegriffen, dass dies kann und für sowas gedacht ist, nämlich LaTeX. Und dass für Lazarus auch aus dem Wiki Inhalte herangezogen werden ist, ist auch nur logisch, da man ansonsten wieder mehrere Quellen zu warten hat.
FPC Compiler Entwickler

Benutzeravatar
af0815
Lazarusforum e. V.
Beiträge: 6197
Registriert: So 7. Jan 2007, 10:20
OS, Lazarus, FPC: FPC fixes Lazarus fixes per fpcupdeluxe (win,linux,raspi)
CPU-Target: 32Bit (64Bit)
Wohnort: Burgenland
Kontaktdaten:

Re: Verwendung von fpdoc

Beitrag von af0815 »

Blöd kann man ruhig sein, nur zu Helfen muss man sich wissen (oder nachsehen in LazInfos/LazSnippets).

PascalDragon
Beiträge: 823
Registriert: Mi 3. Jun 2020, 07:18
OS, Lazarus, FPC: L 2.0.8, FPC Trunk, OS Win/Linux
CPU-Target: Aarch64 bis Z80 ;)
Wohnort: München

Re: Verwendung von fpdoc

Beitrag von PascalDragon »

braunbär hat geschrieben:
Do 17. Dez 2020, 13:17
Tatsache ist, dass es derzeit auf FPDoc-Basis nahezu keine Dokumentation gibt, die Dokumentation findet sich im Web und in CHM Files, die offensichtlich nicht auf FPDoc basieren, weil die entsprechenden FPDoc Files sind überwiegend ziemlich leer.
Ich kann nicht für die LCL sprechen, aber sämtliche Quellcodedokumentation, welche RTL, FCL oder Packages (als Teil vom FPC Subversion) betrifft werden nur auf Basis von fpdoc erstellt. Seit ein paar Wochen gibt es dazu auch einen täglich generierten Snapshot (Daily generated documentation enthält u.a. die RTL und FCL Units, während Daily generated package & unit overview die Packages enthält).
FPC Compiler Entwickler

Socke
Lazarusforum e. V.
Beiträge: 3158
Registriert: Di 22. Jul 2008, 19:27
OS, Lazarus, FPC: Lazarus: SVN; FPC: svn; Win 10/Linux/Raspbian/openSUSE
CPU-Target: 32bit x86 armhf
Wohnort: Köln
Kontaktdaten:

Re: Verwendung von fpdoc

Beitrag von Socke »

PascalDragon hat geschrieben:
Do 17. Dez 2020, 13:27
Seit ein paar Wochen gibt es dazu auch einen täglich generierten Snapshot
Da habe ich mir immer gewünscht ;-)

Wo ich mich da ein mal durchgeklickt habe, hätte ich schon ein paar Fragen:
  • Warum sind FCL und FCL-RES nochmals unter der Dokumentation enthalten, obwohl sie auch in den Packages enthalten sind?
  • Wo ist der Unterschied zwischen FCL und fcl-base? (außer dem Namen und dem doppelten Contennt)
  • Wie ist "RTL" definiert? In den Packages finde ich rtl-extra, rtl-unicode ... die alle einen Teil der Units enthalten. Einige Units finde ich nur in der RTL-Dokumentation aber nicht in der Packages-Dokumentation (z.B. Linux). Andere (z.B. clocale) hat in der RTL-Dokumentation einen Inhalt, in der Packages-Dokumentation ist es nur namentlich gelistet.
Als Lazarus-Anwender wäre eine durchgehende Code-Dokumentation durchaus wünschenswert; zumindest alle FPDoc-Dokumentationen sollten doch auch zusammen erstellt werden können? Gibt es diesbezüglich irgendwelche Absprachen zwischen den beiden Projekten Lazarus und FPC? Oder kocht hier jeder seine eigene Suppe?
MfG Socke
Ein Gedicht braucht keinen Reim//Ich pack’ hier trotzdem einen rein

PascalDragon
Beiträge: 823
Registriert: Mi 3. Jun 2020, 07:18
OS, Lazarus, FPC: L 2.0.8, FPC Trunk, OS Win/Linux
CPU-Target: Aarch64 bis Z80 ;)
Wohnort: München

Re: Verwendung von fpdoc

Beitrag von PascalDragon »

Socke hat geschrieben:
Do 17. Dez 2020, 16:56
  • Warum sind FCL und FCL-RES nochmals unter der Dokumentation enthalten, obwohl sie auch in den Packages enthalten sind?
Der obere Block enthält die Einträge, welche auch auf der offiziellen Seite für die Dokumentation gelistet sind. Der untere Block dient hauptsächlich dazu zu schauen, ob die Packages auch richtig geparsed werden, da die meisten davon (vor allem alles außerhalb der RTL und FCL Packages) eh nicht dokumentiert sind, da dies einfach nur Import Units sind.
Socke hat geschrieben:
Do 17. Dez 2020, 16:56
  • Wo ist der Unterschied zwischen FCL und fcl-base? (außer dem Namen und dem doppelten Contennt)
fcl-base ist ein Teil der FCL. Alle Packages mit fcl--Präfix bilden die FCL.
Socke hat geschrieben:
Do 17. Dez 2020, 16:56
  • Wie ist "RTL" definiert? In den Packages finde ich rtl-extra, rtl-unicode ... die alle einen Teil der Units enthalten. Einige Units finde ich nur in der RTL-Dokumentation aber nicht in der Packages-Dokumentation (z.B. Linux). Andere (z.B. clocale) hat in der RTL-Dokumentation einen Inhalt, in der Packages-Dokumentation ist es nur namentlich gelistet.
RTL ist alles was unter $fpcdir/rtl und unter$fpcdir/rtl-* gelistet ist.

Und wahrscheinlich hat der Generator für die Packages einfach nur nicht den korrekten Pfad zu den FPDoc XML Dateien.
Socke hat geschrieben:
Do 17. Dez 2020, 16:56
Als Lazarus-Anwender wäre eine durchgehende Code-Dokumentation durchaus wünschenswert; zumindest alle FPDoc-Dokumentationen sollten doch auch zusammen erstellt werden können? Gibt es diesbezüglich irgendwelche Absprachen zwischen den beiden Projekten Lazarus und FPC? Oder kocht hier jeder seine eigene Suppe?
Die Dokumentationen für Lazarus und FPC werden nicht zusammen erstellt, da beide Projekte unterschiedliche Release Zyklen haben und die Dokumentation sich auf das jeweilige Release bezieht.

Die LCL Dokumentation verweist jedoch korrekt auf die Dokumentation von FPC (gerade mal mit LHelp bei meinem Lazarus 2.0.10 getestet: ich konnte mich von TButton bis TObject durchhangeln).
FPC Compiler Entwickler

marcov
Beiträge: 1100
Registriert: Di 5. Aug 2008, 09:37
OS, Lazarus, FPC: Windows ,Linux,FreeBSD,Dos (L trunk FPC trunk)
CPU-Target: 32/64,PPC(+64), ARM
Wohnort: Eindhoven (Niederlande)

Re: Verwendung von fpdoc

Beitrag von marcov »

braunbär hat geschrieben:
Do 17. Dez 2020, 13:17
marcov hat geschrieben:
Mi 16. Dez 2020, 15:32
braunbär hat geschrieben:
Mo 14. Dez 2020, 16:14
Ich werde mir jetzt pasdoc einmal genauer anschauen. Schön wäre es halt, wenn sich die Entwickler auf ein Tool einigen würden, mit dem dann auch die ganze Dokumentation von Free Pascal und Lazarus gebündelt wird. Da ist leider auch ein ziemlicher Wildwuchs.
Samt Lazarus und FPC nutzen fpdoc. Also das ist schon geeinigt auf ein Tool.
Wenn das tatsächlich der Fall wäre, dann wäre es ja gut. Vielleicht hat ja wirklich vor ganz kurzer Zeit eien Einigung stattgefunden, und es ist nur noch nicht umgesetzt worden, das kann ich nicht beurteilen.
Nein, das ist schon so seit etwa 2007.
Tatsache ist, dass es derzeit auf FPDoc-Basis nahezu keine Dokumentation gibt, die Dokumentation findet sich im Web und in CHM Files, die offensichtlich nicht auf FPDoc basieren, weil die entsprechenden FPDoc Files sind überwiegend ziemlich leer.
Ich fertige die CHM files. Und die sind mit fpdoc erzeugt.

Antworten