Lazarus Dokumentation

[theo]

Meinte Mathias G. oder bist du in die Schweiz umgezogen ?

Mattias Gärtner schreibt sich ohne "h" dafür mit zwei "t".
http://www.lazarusforum.de/memberlist.p ... file&u=442

[Lori]

Es gibt auch hier im Forum eine Gruppe "Unterstützung Lazarusproject". Unter anderem dort wurde auch schon über Dokumentation geschrieben.

[af0815]

Nur so als Frage:

Unabhängig von dem jetzigen Inhalt, Wiki, SVN etc., wer hat sich angesehen was bei bekannten Produkten Stand der Technik ist.

Vor allen wird aktuell wieder viel über Technik dahinter diskutiert, aber noch nicht wirklich intensiv, was genau die Anwender brauchen. Vor allen weil es ja mehrer Anwendergruppen gibt, mit verschiedenen Bedürfnissen.

Mein Ansatz zur Diskussion ist:
A) Zuerst mal die Anwendergruppen definieren
B) die Bedürfnisse der Gruppen erarbeiten
C) Bestandsaufnahme Ist der verschiedenen Dokumentationen
D) Konzept wie man B und C sinnvoll ineinander überführt

Was auch klar ist, Diskutanten hat man genügend, Arbeiter dagegen findet man nicht oft. Und das ist auch eines der Probleme der Dokumentation. Hier fehlt auch, meiner Meinung nach, ein Diktator mit einer Umsetzungsarmee . Gute Projekte, und die Dokumentation ist genauso eine Projekt wie der fpc oder Lazarus, brauchen eine klare Vision (Ich sehe sie nur nicht).


--------------------------
Anwendergruppen
Einsteiger:
Benötigen Hilfe mit Beispielen, Kontext sentensiv in Lazarus, am besten mit Beispielen oder Links auf Beispiele. Schulischer Bereich, fehlende Verbindung zum Internet möglich.

Gelegenheitsprogrammierer:
Benötigt Kontext sentensiv in Lazarus, hat meist Verbindung zum Internet, findet mit Google Beispiele.

Programmierer:
Kann mit der Wiki und den derzeiten Tutorials arbeiten.

Hacker:
Benötigt fast keine Hilfe.
----------------------------

Wenn man das so definert und sich ansieht, so muss man für die ersten beiden Gruppen das definieren, der Rest kann sich ja das wissen aus den Sourcen oder über Google leicht holen. Bitte sich das bei der Diskussion mal vor Augen halten, oder Vorschläge für eine bessere Struktur machen.

[Mathias]

Meinte Mathias G. oder bist du in die Schweiz umgezogen ?

Wieso umgezogen, ich bin schon immer in der Schweiz.

[af0815]

Es gibt aktuell offensichtlich 3 Arten der Hilfe:

a) Online
b) chm basierend
c) inf basierend

b&c können aus den selben Quellen kompiliert werden, die im SVN vorhanden sind. Aktuell dürfte die inf basierende Version mehr Unterstützng haben. Sie wird auch beim fpGUI Projekt und in verschiedene Kompiler (mse, Delphi) einbindbar.

Die Hilfe ist natürlich gerade für Anfänger nicht besonders hilfreich.
Beispiel, man schreibt class und hofft auf Hilfe zur Klassenerstellung. Das Ergebnis ist aber mager.

Code: Alles auswählen

 
TClass= Class of TObject
Class of TObject

Nicht mehr und auch nicht weniger. Das hilft nicht weiter. Es würde vielmehr der Inhalt des Language Reference Guide zu class hier hinein gehören. Und das in der Sprache die derjenige spricht.

Code: Alles auswählen

6.1 Class definitions
 
The prototype declaration of a class is as follows:
 
_________________________________________________________________________________________________________
Class types
 
--        ---                 -----------------------------------
  class type  -classclfoarsswadrdefindiefitinointion-|
 
 
--                  -    ---------------------------------------
  class forward definition class
 
 
--            -----------     -----------------------------------
  class definition -      --|class  -      | --            --    -|
                packed          heritage   -component list-|end
 
 
--heritage -(- class type identifier|---------------------)------------
                             - implemented interfaces-
 
 
--implemented interfaces-|, -interface identifier-------------------------
                     --------------------
 
 
 --component list-|----------------|-----------------
                -visibility specifier--  -|field definition ---
                                   --------------
---|-------------------------------------------------------------
   ---|--const declaration part------
    | |---type declaration part----| |
    | ---variable declaration part--| |
    | -class-variable declaration part| |
    | -----method definition-----| |
    -------property definition-------|
 
 
--class variable declaration part class variable declaration part-------------
 
 
--field definition- identifier list- :- type- ;--|--------------------------
                                     -static;--
 
 
 --              -------------            ----- --
   method definition | -class-| -pfurnoccetdiounr hee haedaederr-|| ;
                  ------constructor header-----|
                  -------desctuctor header------|
-----------------------------------------------------------------
   ---| virtual----|------------- ;--|-call modifiers-;--|
    | -dynamic -- -;- abstract --|
    |---------override ---------|
    -message -|integer constant--
              --string constant---
 
 
--class visibility specifier-|-------------------------------------------
                     --|------- private --|
                     | -strict--         |
                     -|------- protected -|
                     --strict--   -------|
                     -----  public ------|
                           published
 
___________________________________________________________________
 
Remark: In MacPas mode, the Object keyword is replaced by the class keyword for compatibility with other pascal compilers available on the Mac. That means that in MacPas mode, the reserved word ’class’ in the above diagram may be replaced by the reserved word ’object’.
In a class declaration, as many private, protected, published and public blocks as needed can be used: the various blocks can be repeated, and there is no special order in which they must appear.
Methods are normal function or procedure declarations. As can be seen, the declaration of a class is almost identical to the declaration of an object. The real difference between objects and classes is in the way they are created (see further in this chapter).
The visibility of the different sections is as follows:
 
Private 
All fields and methods that are in a private block, can only be accessed in the module (i.e. unit) that contains the class definition. They can be accessed from inside the classes’ methods or from outside them (e.g. from other classes’ methods)
Strict Private 
All fields and methods that are in a strict private block, can only be accessed from methods of the class itself. Other classes or descendent classes (even in the same unit) cannot access strict private members.
Protected 
Is the same as Private, except that the members of a Protected section are also accessible to descendent types, even if they are implemented in other modules.
Strict Protected 
Is the same as Protected, except that the members of a Protected section are also accessible to other classes implemented in the same unit. Strict protected members are only visible to descendent classes, not to other classes in the same unit.
Public 
sections are always accessible.
Published 
Is the same as a Public section, but the compiler generates also type information that is needed for automatic streaming of these classes if the compiler is in the {$M+} state. Fields defined in a published section must be of class type. Array properties cannot be in a published section.
In the syntax diagram, it can be seen that a class can list implemented interfaces. This feature will be discussed in the next chapter.
Classes can contain Class methods: these are functions that do not require an instance. The Self identifier is valid in such methods, but refers to the class pointer (the VMT).
Similar to objects, if the {$STATIC ON} directive is active, then a class can contain static fields: these fields are global to the class, and act like global variables, but are known only as part of the class. They can be referenced from within the classes’ methods, but can also be referenced from outside the class by providing the fully qualified name.
For instance, the output of the following program:
 
{$mode objfpc}  
{$static on}  
type  
  cl=class  
    l : longint;static;  
  end;  
var  
  cl1,cl2 : cl;  
begin  
  cl1:=cl.create;  
  cl2:=cl.create;  
  cl1.l:=2;  
  writeln(cl2.l);  
  cl2.l:=3;  
  writeln(cl1.l);  
  Writeln(cl.l);  
end.
will be the following
 
2  
3  
3
Note that the last line of code references the class type itself (cl), and not an instance of the class (cl1 or cl2).
Remark: Like with functions and pointer types, sometimes a forward definition of a class is needed. A class forward definition is simply the name of the class, with the keyword Class, as in the following example:
 
Type  
  TClassB = Class;  
  TClassA = Class  
    B : TClassB;  
  end;  
 
  TClassB = Class  
   A : TClassA;  
  end;
When using a class forward definition, the class must be defined in the same unit, in the same section (interface/implementation). It must not necessarily be defined in the same type section.
 
.....
 

leicht gekürzt.

So wie es aussieht, ist ja die Information da, aber nicht einfach zu erreichen und nicht unbedingt in der Sprache des Anwenders.

Wie ist eure Meinung dazu ?

Quellen:
Installing chm Help
fpGUI Toolkitproject
Freepascal Online Documentation

[Euklid]

Es hat mehrere Versuchen mit wiki's gegeben, und die haben nicht wirklich mehr nützliche Dokumentation generiert. (aber ein ganze menge Zeit gegessen es zu starten)

Hmm. Also ich kann jetzt nur für diejenigen sprechen, die keine studierten Informatiker sind: Mir hat das Wiki bei ausgesprochen vielen Projekten sehr weiter geholfen. Es hat einige ausgezeichnete Artikel, die es selbst relativ unerfahrenen Programmierern wie mir ermöglichen, völlig ohne Vorwissen multithreaded zu programmieren oder externe Programme einzubinden. Kurzum: Das Wiki funktioniert und erfüllt seinen Zweck.

Man braucht sich nur den heutigen Wiki an zu sehen, das ist alles eine fragmentierten menge Artikel ist, oft ohne deutlicher Anfang oder Ende.

Da stimme ich Dir absolut zu. Aber die Lösung kann doch nicht darin bestehen, einen durchaus in vielen Bereichen funktionierenden Ansatz zu verwerfen?
Alles, was unser Wiki in meinen Augen benötigt, ist eine vernünftige Gliederung. Ohne die werden auch alle anderen Ansätze scheitern.

[mschnell]

Es gibt aktuell offensichtlich 3 Arten der Hilfe:

a) Online
b) chm basierend
c) inf basierend

b&c können aus den selben Quellen kompiliert werden, die im SVN vorhanden sind. Aktuell dürfte die inf basierende Version mehr Unterstützng haben. Sie wird auch beim fpGUI Projekt und in verschiedene Kompiler (mse, Delphi) einbindbar.

"..."
d) DocView ( -> http://forum.lazarus.freepascal.org/ind ... ic=10335.0 )

Aus den SVN-Quellen kann man auch DocView Dateien generieren (ist mir allerdings vor ein paar Jahren trotz intensiver Versuche nicht gelungen - Graeme ist dazu in der Lage). Man umgeht dabei - anscheinend - das nur für Spezialisten verwendbaren Editieren mit FPDoc.

Den Doc-View Reader kann man als "F1"-Hilfe-System (wie "inf" und/oder den "chm" Viewer) in Lazarus einbinden und ist da meiner Ansicht nach den anderen Hilfe-Viewern überlegen.

Wenn man aber ein Kapitel Hilfe-Text schreiben oder ändern möchte, ist es aber nötig ausprobieren zu können, dass es auch funktioniert (Formatierung, Verlinkung, Struktur ), bevor man es zur Freigabe durch das Team in das svn einstellt. Bei inf, chm und DocView muss man aber erst einen komplexen Generierungs-Vorgang durchgeführt werden (der wie gesagt auch nicht unbedingt erfolgreich/machbar ist.) Ich habe da aufgegeben.

Es muss auch möglich sein, ein verändertes Kapitel online (voll funktionsfähig) mit jemandem zu "teilen", damit der es prüfen kann, bevor man es ins svn stellt. All das geht vermutlich mit Wiki-Texten, nicht aber mit inf/chm/DocView.

... a) "Online" ...
Lazarus kann "inf" aus Online und Offline Quellen darstellen. DocView vermutlich auch.

-Michael

[af0815]

Es gibt aktuell offensichtlich 3 Arten der Hilfe:

a) Online
b) chm basierend
c) inf basierend

b&c können aus den selben Quellen kompiliert werden, die im SVN vorhanden sind. Aktuell dürfte die inf basierende Version mehr Unterstützng haben. Sie wird auch beim fpGUI Projekt und in verschiedene Kompiler (mse, Delphi) einbindbar.

d) DocView ( -> http://forum.lazarus.freepascal.org/ind ... ic=10335.0 )

c=d

DocView ist inf basierend. Wenn man dann den Download Links folgt kommt man auf dieselbe Seite, sprich auf fpGUI.

Die Sourcen der Dokumentation habe ich gefunden, nur noch nicht, wo die 'inf' erzeugt werden. im makefile/makefile.fpc der Dokumentation habe ich das Target noch nicht gefunden. Kann sein, das es da in fpGUI ein eigenes dafür gibt. Mal suchen.

[marcov]

Es hat mehrere Versuchen mit wiki's gegeben, und die haben nicht wirklich mehr nützliche Dokumentation generiert. (aber ein ganze menge Zeit gegessen es zu starten)

Hmm. Also ich kann jetzt nur für diejenigen sprechen, die keine studierten Informatiker sind: Mir hat das Wiki bei ausgesprochen vielen Projekten sehr weiter geholfen.

Es hat einige ausgezeichnete Artikel, die es selbst relativ unerfahrenen Programmierern wie mir ermöglichen, völlig ohne Vorwissen multithreaded zu programmieren oder externe Programme einzubinden. Kurzum: Das Wiki funktioniert und erfüllt seinen Zweck.

Ich meinte meistens nicht die heutigen Wiki, aber Wiki nutzen für die Referenz Dokumentationen. (heute ist nur IDE Hilfe Wiki)

Aber auch in heutigen Wiki gibt es viel schlechter Artikel, oft Artikel wo jeder seine eigener Meinung dazu getragen hat.

Und ja, die Referenz Dokumentation ist schwieriger für Anfänger. Für Anfänger sollte es aber Anfänger Buche geben, also zusätzlich.
Also man muss nicht versuchen die Referenz Dokumentation in Anfänger Dokumentation umzuwandeln.

Man braucht sich nur den heutigen Wiki an zu sehen, das ist alles eine fragmentierten menge Artikel ist, oft ohne deutlicher Anfang oder Ende.

Da stimme ich Dir absolut zu. Aber die Lösung kann doch nicht darin bestehen, einen durchaus in vielen Bereichen funktionierenden Ansatz zu verwerfen?

Ich verwerfe nur die Idee das Wiki Konzept mehr umfassend zu machen. Wiki ist gut für Zusatzdokumentationen (build und kurzfristig) und ein Paar lose Artikel, kann man schwieriger nutzen für Referenz Dokumentation.

Speziell Anwender müssen konsistenter Dokumentation mit Anfang und Ende haben. Wiki kompliziert das mehr dann das es das einfacher macht. Ich würde aber da mit wiki anfangen, und wenn es genügend rohes Material gibt es in ein Buch (mit anfang und Ende, nicht nur einzelne Artikel)

Alles, was unser Wiki in meinen Augen benötigt, ist eine vernünftige Gliederung. Ohne die werden auch alle anderen Ansätze scheitern.

Irgendwie eine Ordnung machen und behalten ist das großster Problem eine offener Wiki. Und Struktur ist wichtig um automatisierter Tools zu nutzen können. (zb Quellen und Dokumentation blenden wie fpdoc Dokumentation macht)

[marcov]

Einige Erklärungen

Man hat

1. fpdoc (mit html, chm, latex und INF backends) fuer die
1a FPC units Dokumentation
1b LCL und lazutils Dokumentation
Die html davon steht auch online.
2. latex für die FPC prog,ref und user Dokumentation
(generiert pdf und html, die html wird leicht modifiziert und nach CHM compiliert)
3. reine wiki (ohne eine erzwungene Struktur) für die Lazarus IDE Hilfe, und nur online.

Docview/INF ist eine alte OS/2 Schnittstelle wird meistens von Graeme (FPGUI) verwaltet wird. Es gibt kein Compiler in Pascal, noch einen portablen Compiler, nur eine sehr alter dos Kompiler (dosbox?). CHM hat eine eigene FPC Compiler, ist also einfacher in FPCs Buildprozess ein zu blenden.

Ad(3): es gab vor zehn Jahre ein Tool die der Lazarus ide Wiki Hilfe für offline Nutzung exportierte (ohne spezielle Permissionen), aber durch Engine updates und wiki Antispam plugins funktioniert das nicht mehr.

P.s. Die Chancen um für 1a+2 andere Tools zu nutzen sind sehr, sehr niedrig. Und ich denk das in 1b auch schon zu viel investiert ist. (und auch rechtlich die Möglichkeit Quellen und Dokumentation zu mixen ausnutzt).

[af0815]

P.s. Die Chancen um für 1a+2 andere Tools zu nutzen sind sehr, sehr niedrig. Und ich denk das in 1b auch schon zu viel investiert ist. (und auch rechtlich die Möglichkeit Quellen und Dokumentation zu mixen ausnutzt).

Wenn man sich intensiver mit der Dokumentaion auseinandersetzt, so sieht man das es genügend Inhalt gibt, der aber nicht beim Anwender geeignet ankommt. Es ist vollkommen klar, das es nicht andere Tools benötigt, sondern nur die Quellen des Inhaltes besser ausnutzt.

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.
Nicht nur Online, sondern auch Offline. Nur die Languagereference zB. ist ein monolitisches Latex Dokument das seinen Inhalt nicht richtig in die Struktur bekommt. Es ist folglich einmal eine Languagerefernce in chm/inf nötig. Zusätzlich ist da jetzige System IMHO nicht für Mehrsprachigkeit ausgelegt.

Das mit der Wiki wird gehen, wenn man will, ich habe vor ca. 2 Jahren versuche gemacht und Inhalt von dort bezogen. Es geht wenn man sich zuerst die Seitenübersicht holt, dann eine Seite aufruft, dann in den Editmodus schaltet und den Wikitext extrahiert, den Edit abbricht und zur nächsten Seite geht. Über ein paar Seiten hat das funktioniert, ich wollte nur nicht in die Spamfilter fallen und geblockt werden. Aktuell habe ich es nicht probiert. Ich könnte mir aber den umgekehrten Weg vorstellen, das die Wiki den Inhalt automatisch ablegt. Mal sehen ob es solche Module für die Wiki nicht schon gibt (DumpBackup ?!).

[marcov]

P.s. Die Chancen um für 1a+2 andere Tools zu nutzen sind sehr, sehr niedrig. Und ich denk das in 1b auch schon zu viel investiert ist. (und auch rechtlich die Möglichkeit Quellen und Dokumentation zu mixen ausnutzt).

Wenn man sich intensiver mit der Dokumentaion auseinandersetzt, so sieht man das es genügend Inhalt gibt, der aber nicht beim Anwender geeignet ankommt.
Es ist vollkommen klar, das es nicht andere Tools benötigt, sondern nur die Quellen des Inhaltes besser ausnutzt.

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)

Nur die Languagereference zB. ist ein monolitisches Latex Dokument das seinen Inhalt nicht richtig in die Struktur bekommt.

Komplexer Konzepte mit nur ein Wort Input finden ist nur einmal nicht einfach. Egal welches System. Aber man kann genau spezifizieren welcher Paragraf mit welches Keyword assoziiert ist.

Es ist folglich einmal eine Languagerefernce in chm/inf nötig. Zusätzlich ist da jetzige System IMHO nicht für Mehrsprachigkeit ausgelegt.

Das online System hat nie gut funktioniert. Ich weiß aber nicht warum. Aber CHM funktioniert gut, und wird heute angeraten.

Das mit der Wiki wird gehen, wenn man will, ich habe vor ca. 2 Jahren versuche gemacht und Inhalt von dort bezogen. Es geht wenn man sich zuerst die Seitenübersicht holt, dann eine Seite aufruft, dann in den Editmodus schaltet und den Wikitext extrahiert, den Edit abbricht und zur nächsten Seite geht. Über ein paar Seiten hat das funktioniert, ich wollte nur nicht in die Spamfilter fallen und geblockt werden. Aktuell habe ich es nicht probiert. Ich könnte mir aber den umgekehrten Weg vorstellen, das die Wiki den Inhalt automatisch ablegt. Mal sehen ob es solche Module für die Wiki nicht schon gibt (DumpBackup ?!).

Wenn man manuell kleine Mengen bearbeiten funktioniert fast alles.

Es ist auch gar kein frage ob es "gehen" wird, aber ob es besser und tatsächlich mehr Hilfe in guter Qualität generiert wird. Und das Glaube ich nicht.

Man versucht jetzt alles "einfach" vor zu stellen, man soll es nur in der Wiki werfen, und alles wird passieren weil es einfach ist und allen daran arbeiten können.

Fakt ist aber das Wiki System zu betreuen viel aufwendiger ist, und das jetzt schon die Wiki Autoren meistens schon COMMIT bits haben auf entweder FPC, Lazarus oder --CCR oder teilen davon.

[af0815]

Nur die Languagereference zB. ist ein monolitisches Latex Dokument das seinen Inhalt nicht richtig in die Struktur bekommt.

Komplexer Konzepte mit nur ein Wort Input finden ist nur einmal nicht einfach. Egal welches System. Aber man kann genau spezifizieren welcher Paragraf mit welches Keyword assoziiert ist.

Ich weiss, das ich noch sehr viel über das System lernen muss. Besonders wie DAS funktioniert. Das Konzept der aktuellen Hilfe ist etwas Komplex, solange es man nicht verinnerlicht hat.

[Christian]

Es ist auch gar kein frage ob es "gehen" wird, aber ob es besser und tatsächlich mehr Hilfe in guter Qualität generiert wird. Und das Glaube ich nicht.

Versteh ich nicht, im Wiki ist bisher das meisste an Hilfe zu finden oder hab ich was verpasst ?
Das Wiki generiert mehr Doku als jedes andere System. Und ich hab nicht das Gefühl als ob da jemand groß Aufwand mit der Administraion hat.

[marcov]

Versteh ich nicht, im Wiki ist bisher das meisste an Hilfe zu finden oder hab ich was verpasst ?

Ja, da hast du etwas verpasst, die meiste Hilfe ist als Quelle in fpdoc und latex Format, und wird NICHT in der Wiki gepflegt.

Das Wiki generiert mehr Doku als jedes andere System. Und ich hab nicht das Gefühl als ob da jemand groß Aufwand mit der Administraion hat.

Die meiste Doku wird von Leute wie Michael van Canneyt gemacht in fpdoc format.

Zum Beispiel: wiki über FPC rtl: http://wiki.freepascal.org/Category:RTL mit typischer Wiki meistens leere Inhalt wie: http://wiki.freepascal.org/System_unit_structure

fpdoc documentation (html backend) fpc rtl: http://www.freepascal.org/docs-html/rtl/index.html