Diskussionen und Krempel (alt: Verbesserungen Doku v4)

[Andre]

[Edit]

Aktuellste deutsche Online-Hilfe zu PureBasic v4


Download auf www PureArea net (Stand Juli 2006)

[/Edit]
+++++++++++++++++++++++

Hallo Leute,

da sich nun PB v4 der Final nähert, gebe ich Euch hier nochmal die Chance für Verbesserungsvorschläge am Referenz-Handbuch zur v4.

Diese sollten Anregeungen und *konkrete* Vorschläge umfassen, welche kurzfristig noch in der v4 Final berücksichtigt werden sollten. Ich werde dann mein Bestes tun, diese noch rechtzeitig zu integrieren.

Wir Ihr also seht, nützen mir globale Vorschläge wie "zu jedem Befehl ein Beispiel hinzufügen" oder "Rechtschreibung, Grammatik, Formulierungen überarbeiten" recht wenig, da ich dies in der Kürze der Zeit ohnehin nicht umsetzen kann.

Die letzten Wochen und Monate wurde auch viel an der Doku zu PB gearbeitet - sowohl zur Integrierung der Beschreibung neuer oder geänderter Befehle als auch generell zur Verbesserung der Doku.

Mit diesem Thread bitte ich Euch um konkrete Vorschläge, die sich jeweils auf einen bestimmten Befehl beziehen und einen Textvorschlag für Änderungen / Ergänzungen beinhalten sollen.

Danke für alle konstruktiven Anregungen im voraus

[Kiffi]

> da sich nun PB v4 der Final nähert, gebe ich Euch hier nochmal die
> Chance für Verbesserungsvorschläge am Referenz-Handbuch zur v4.

Mail ist unterwegs.

Grüße ... Kiffi

[uweb]

Bevor ich los lege : Andre Du machst einen sehr guten Job !

Aber es gibt ja nichts was man nicht noch besser machen könnte.

Ich habe mich diesmal bemüht etwas *konkreter* zu sein.

Allerdings wäre ich motivierter wenn ich wüsst in wie weit meine Arbeit Sinn macht
- gegen welche Vorschläge Du Dich vielleicht schon entschieden hast.


Wenn man über die Suchfunktion in eine Seite kommt landet man immer am Anfang der Seite statt an der entsprechenden Stelle.
Bei
*konkret*
- And
- Or
- XOr
- Not
auf Variablen, Typen und Operatoren

Ich denke es sollte zumindest immer einen Link auf die übergeordnete(n) Seite(n) geben.
*konkret*
- Debugger-Schlüsselwörter in PureBasic
- Strukturen
- Select : EndSelect
- Compiler Direktiven
- Break : Continue
- Data
- Prozeduren
- Erstellung einer DLL
- Define
- Compiler Funktionen
- Dim
- If : Else : EndIf
- Andere Befehle
- Enumerations
- Import : EndImport
- Interfaces
- Macros
// ich bin jetzt im Index bis EndMacro gekommen und mache auch gerne weiter wenn Du mir 2 Fragen beantwortest :
// Gibt es einen effektiveren Weg alle Seiten abzuklappern ? (ohne Wiederholungen)
// Gibt es Seiten bei denen Du das bewust nicht gemacht hast ? (Vielleicht suche ich Dir ja gerade die unnötigerweise raus)


Richtig toll fände ich es wenn ich alle darüberliegenden Seite im Zugriff hätte.
*konkret bei allen*

Da die Hilfe sich an der Architektur von PB orientiert sind Querverweise wichtig.
Der eine sucht Menu vielleicht bei Gadget der andere vielleicht bei Window.
*konkret* - Menu-Link zu den Gadgets und zu Window

Ich denke zur besseren Übersicht sollte es auf "PureBasic - Gadget" oben eine kleinere List in der jedes Gadget aufgeführt ist geben. Die große Liste könnte so bleiben. Einiges Links wären zwar dann oben und unten aber ich denke das wäre kein Fehler. Ich hätte schnelleren Zugriff auf ein einzelnes Gadget (oben) und wäre siche alles an einer Stelle zu finden (unten).
*konkret eine Liste - jedes Gadget mit einem Link *


Ein Gadget-Beispiel ohne Eventverarbeitung finde ich nicht so toll.
Einzige Ausnahme ist ScrollAreaGadget() - dort gibt es eine Eventverarbeitung die aber nur #PB_Event_CloseWindow und die Buttons berücksichtigt.
*konkret alle Gadgets *


Bei der LinkedList habe ich zwar ein umfangreiches Beispiel ich erkenne daraus aber nicht den Vorteil gegnüber einer Tabelle - InsertElement() statt einfach nur AddElement.()
*konkret* - InsertElement() im LinkedList-Beispiel

In dem Beispiel gibt es übrigens Structure ComplexStructure. Das finde ich gut. Allerdings wird die nicht verwendet.
*konkret* - Ein Zugriff auf Field3 in *Basic oder Basic2 wäre hier hilfreich.

[Helle]

Konkret : Bezieht sich alles auf die Beispiel-Codes:
- Locate steht noch in Keyboard-Pushed, -Released, -InKey
- WindowOutput wird in Line und StopDrawing noch ohne Parameter verwendet
- evtl. Kommentare in GetCurrentEIP, GetDisASMString und GoToEIP "eindeutschen"

Gruss
Helle

Edit:
Vergessen: Bei KeyboardInkey wird bei ClearScreen und FrontColor ohne RGB (oder ein Zahlenwert) gearbeitet.

[Andre]

- Locate steht noch in Keyboard-Pushed, -Released, -InKey
- WindowOutput wird in Line und StopDrawing noch ohne Parameter verwendet

Edit:
Vergessen: Bei KeyboardInkey wird bei ClearScreen und FrontColor ohne RGB (oder ein Zahlenwert) gearbeitet.

Fixed.

@Kiffi: danke für die Mail.

@uweb: auch erstmal Danke für das Lob und die Anregungen.

Wenn man über die Suchfunktion in eine Seite kommt landet man immer am Anfang der Seite statt an der entsprechenden Stelle.

Das ist wohl ein "Feature" von .chm Dateien, und nicht ohne weiteres änderbar. Um sofort einen Befehl eingeblendet zu bekommen (z.B. beim Drücken von F1 in der PB-IDE) müsste dessen Beschreibung auf einer einzelnen Html-Seite stehen.

Ich denke es sollte zumindest immer einen Link auf die übergeordnete(n) Seite(n) geben.

Kannst Du das bitte nochmal näher erläutern?
Habe jetzt nicht verstanden, wo da ein Link hin soll...

*konkret* - Menu-Link zu den Gadgets und zu Window

Werde ich wohl noch machen.

(Ich lege selbst auch Querverweise viel Wert, habe daher auch bisher für die v4 schon etliche mehr Links von einem Befehl zu einem anderen eingebaut, wo immer dies sinnvoll erschien.

*konkret eine Liste - jedes Gadget mit einem Link *

Mal sehen - ich kenne ja den Vorschlag schon, jedes Gadget mit einem kleinen Screenshot / Icon zu ergänzen. Das ist eben nur mit dem DocMaker und dessen vorgegebener Struktur der Quelldateien nicht ohne weiteres machbar (die "Befehlsübersicht" jeder Library wird z.B. dynamisch aus den vorhandenen Befehls-Beschreibungen erstellt).

Ein Gadget-Beispiel ohne Eventverarbeitung finde ich nicht so toll.

Hm, schon klar. Weiß aber hier wirklich nicht, ob ich dies noch so kurzfristig schaffe. Wenn Du Lust hast, entsprechend erweiterte Beispiele hier zu posten?

Gleiches gilt für die anderen Beispiele.

[uweb]

Das ist wohl ein "Feature" von .chm Dateien, und nicht ohne weiteres änderbar. Um sofort einen Befehl eingeblendet zu

bekommen (z.B. beim Drücken von F1 in der PB-IDE) müsste dessen Beschreibung auf einer einzelnen Html-Seite stehen.

Da bin ich vom Gegenteil überzeugt.

test.html :

Code: Alles auswählen

<html><body>
<a href="#unten" name="oben">gehe nach unten</a> - dieser Anker ist zugleich das Ziel für oben (ein Zieltag benötigt nicht mehr als einen Namen - siehe unten)
<br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br>
Mit '#' läßt sich ein Ziel innerhalb einer Seite ansteuern.
Wenn das Ziel nicht schon sichtbar ist springt der Browser dort hin.
<br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br>
<a name="unten"></a>
<a href="#oben">gehe nach oben</a> - Hier sind Verweis und Ziel getrennt.
</body>
</html>

test.hhp (nicht komplett - deshalb Fehlermeldung - läuft aber) :

Code: Alles auswählen

[OPTIONS]
Binary Index=No
Compatibility=1.1 or later
Compiled file=test.chm
Default topic=test.html
Display compile progress=Yes
Language=0x407 Deutsch (Deutschland)

[WINDOWS]

[FILES]
test.chm

[INFOTYPES]

Ich denke es sollte zumindest immer einen Link auf die übergeordnete(n) Seite(n) geben.

Damit meinte ich : So wie Du es bei den meisten Child-Seiten von "Referenz-Handbuch - Inhaltsverzeichnis" schon gemacht hast.
Auf der "PureBasic - Gadget"-Seite gibt es unten z.B. einen Link zu "Referenz-Handbuch - Inhaltsverzeichnis".
Das finde ich gut und ich fände es schön wenn alle Seiten die einen Parent haben so einen Link hätten.
Das ist z.B. auf allen Child-Seiten von "Die PureBasic IDE" nicht der Fall.


Noch schöner fände ich es wenn

- der Link oben statt unten wäre
dann bräuchte man nicht herunter scrollen wenn man merkt, daß man auf der falschen Seite ist.

- nicht nur ein Link für den parent sondern Links für alle darüber liegenden Seiten da wären
bei ActivateGadget() z.B. <a href="...">Referenz-Handbuch - Inhaltsverzeichnis</a> / <a href="...">Gadget Inhaltsverzeichnis</a>

*konkret eine Liste - jedes Gadget mit einem Link *

Ich bin mir nun gar nicht mehr so sicher ob das wirklich konkret war.
Deshalb zur Sicherheit : Ich denke an eine kurze Linkliste "Gadgets"
wie die Befehlsübersicht vor der Befehlsübersicht.

Gadgets

ButtonGadget
ButtonImageGadget
CalendarGadget
CheckBoxGadget
ComboBoxGadget
ContainerGadget
DateGadget
EditorGadget
ExplorerComboGadget
ExplorerListGadget
ExplorerTreeGadget
Frame3DGadget
GadgetToolTip
HyperLinkGadget
IPAddressGadget
ImageGadget
ListIconGadget
ListViewGadget
MDIGadget
OptionGadget
PanelGadget
ProgressBarGadget
ScrollAreaGadget
ScrollBarGadget
SpinGadget
SplitterGadget
StringGadget
TextGadget
TrackBarGadget
TreeGadget
WebGadget

[DarkDragon]

Parse3DScripts()

-> Hier muss unbedingt rein, dass es sich nicht um GLSL/HLSL sondern um eine OGRE-Script-Sprache handelt mit der man Materials beschreiben kann, wenn das hier damit gemeint ist:

http://www.ogre3d.org/docs/manual/manual_14.html#SEC23

MfG und Frohe Ostern,
Daniel

[In_Go]

Hallo Andre!

Ich vermisse noch einige Angaben über die Deklaration bei der Übergabe von Variablen an Proceduren

Beispiel:

Declare Name ( Übergabe von mehrdimensionalen Variable)
Declare Name ( Übergabe von einfacher Strukturevariable )
Declare Name ( Übergabe von Strukturvariablen Array )
Declare Name ( Übergabe von Linked Lists )

Zu jedem der oben genannten Beispiele ein Aufruf

Zu jedem der oben genannten Beispiele ein Procedurekopf

Wie komme ich darauf?
Ich habe versucht es selbst herreuszufinden und bin auf ein Problem gestossen:

Code: Alles auswählen

Dim df.l(20) : df.l(1)=1 : df.l(2)=2 : df.l(3)=3 : df.l(4)=4                          ;Ein eindimensionales Array
Declare hohls0(df.l(1))
ai.l = df.l(1) :hohls0( df.l() ) : ar.l = df.l(1)  : Debug "Variablenübergabe    Array("+Str(ai.l)+","+Str(ar.l)+")"

a.rect   : a\left=1 : a\top=2 : a\right=3 :a\bottom=4                                ;Eine Variable die auf eine Rect Structure zeigt
Declare hohls(*b.rect)
ai.l= a\left : hohls(a) : ar.l=a\left : Debug "Variablenübergabe        Structure("+Str(ai.l)+","+Str(ar.l)+")"

Dim c.rect(20)  : c(2)\left=1 : c(2)\top=2 : c(2)\right=3 : c(2)\bottom=4   ;Ein array mit Structurezeiger
Declare hohls1( u.rect(1))
ai.l= c(2)\left
hohls1( c() )
ar.l=c(2)\left
Debug "VariablenübergabeStructureArray("+Str(ai.l)+","+Str(ar.l)+")"

NewList d.rect() :AddElement(d()) : d()\left=1 : d()\top=2 : d()\right=3 : d()\bottom=4 ; eine Liste
Declare hohls2( c())

ai.l= d()\left
hohls2( d())
ar.l=d()\left
Debug "VariablenübergabeStructureNewlist("+Str(ai.l)+","+Str(ar.l)+")"

;ai.l= c(2)\left
;hohls2( c(2) )
;ar.l=c(2)\left
;Debug "VariablenübergabeStructureArray("+Str(ai.l)+","+Str(ar.l)+")"

Procedure  hohls0(a(1 ))
a.l(1)=4
a.l(2)=3
a.l(3)=2
a.l(4)=1
EndProcedure
Procedure hohls(*b.rect)
  *B\left    =  4
  *B\top    =   3
  *B\right  = 2
  *B\bottom = 1
EndProcedure

Procedure hohls1( u.rect(1) )
  u(2)\Left      =  4
  u(2)\top      =   3
  u(2)\Right   = 2
  u(2)\bottom = 1
EndProcedure
Procedure hohls2(  v.rect() )
  v()\Left      =  4
  v()\top      =   3
  v()\Right   =   2
  v()\bottom =  1
EndProcedure

Hier tritt ein Problem bei hohls2 (Übergabe einer linked list) auf. Oder sollte es an der rect. Strukture liegen?

[ullmann]

Hallo André,

ich habe noche keine Beta installiert. Mein Hinweis bezieht sich auf die Hilfe zu V3.94.

Im Index wird der Begriff "Operatoren" nicht gefunden.

Auf der Seite der Operatoren fehlt der Operator für Zeichenfolgen-Verknüpfung.

Gruß
Rainer

[ullmann]

Hallo André,

ich habe noch keine Beta installiert. Mein Hinweis bezieht sich auf die Hilfe zu V3.94.

Die Farbtabelle in der Hilfe ist falsch oder der Compiler liefert falsche Farben.

Bsp.
Meine Farbtiefe ist auf 16 Bit eingestellt.
In der Farbtabelle in der Hilfe ist $FFFFCC ein hellgelber Farbton.

Box(100,100,50,50,$FFFFCC) liefert jedoch eine hellblaue Box.
Damit sind die Farben in der Hilfe unbrauchbar.

Box(100,100,50,50,RGB($FF,$FF,$CC)) liefert die hellgelbe Box.
Es könnte also sein, dass die Farben in der Hilfe richtig sind, so dass der oben genannte Fehler ein Compiler-Fehler ist.

Vielleicht ist aber in der Beta schon alles in bester Ordnung.

Gruß Rainer