[v4] Corrections & Améliorations de la doc FR

Archive.
comtois
Messages : 5186
Inscription : mer. 21/janv./2004 17:48
Contact :

Message par comtois »

nico a écrit :Ce serait bien de mentionner la commande ici
j'ai mis ça
- toutes les commandes de la bibliothèque @LibraryLink "window" "Window" (sauf @Link "Window/StickyWindow" "StickyWindow()").

Pour ce qui est de Position, c'est vrai que c'est expliqué mais le terme ne correspond pas, c'est un identifiant.
Dans l'exemple c'est bien un numéro et ça fonctionne, que veux-tu dire par identifiant ?

Code : Tout sélectionner

AddGadgetItem(0, #FenetreFille, "Fenêtre fille")

[EDIT]
Ok je viens de te relire
en général un identifiant dans l'aide à un # qui le repère.
Non ça c'est un numéro !!
Relis la page Numéros et identifiants

extrait de la page
Dans ce manuel, les numéros s'écrivent sous la forme #Numéro
http://purebasic.developpez.com/
Je ne réponds à aucune question technique en PV, utilisez le forum, il est fait pour ça, et la réponse peut profiter à tous.
nico
Messages : 3702
Inscription : ven. 13/févr./2004 0:57

Message par nico »

Dans l'exemple oui mais pas dans la description; je parle du mot position qui me gêne.


Les exemples qui sont mis avec les descriptions ne servent à rien du tout pour moi, ce qui m'a intéressé avec Pure ce sont les exemples généralistes qui renvoient vers la page de code concernées, comme Gadget.pb par exemple , mais un seul exemple pour tous les gadgets, qu'est-ce que tu veux faire avec ça quand tu débutes.

Il faudrait des exemples pour chaque Gadget avec des liens en bas de la page de la description et cela pour tout les Gadgets:
OS Supportés

Windows, Linux, MacOS X

Exemple 1
Exemple 2 etc...
J'ai galéré comme tout le monde quand j'ai commencé Pure parce qu'il n'y a quasiment pas d'exemple, et on voit régulièrement des débutants qui ne s'en sortent pas et qui demandent des Tuts à cause de ça!

C'est mon point de vue!
comtois
Messages : 5186
Inscription : mer. 21/janv./2004 17:48
Contact :

Message par comtois »

ben moi j'apprécie ces petits exemples simples, pour débuter c'est mieux de ne pas être noyer dans un code :)

Mais je suis d'accord avec toi , des exemples plus complexes et variés seraient aussi très utiles.
Même quand Fred propose un code sur le forum il ne le met pas dans le répertoire example :?

Je pense aux exemples 3D shadow, et CameraProjection. idem pour les exemples avec Ode ,il y a bien un zip qui est proposé sur le forum , mais celui qui découvre PureBasic ne sera pas au courant de son existence.

Il y a effectivement un gros travail dans ce domaine et ce serait bien que Fred donne son avis, et il faudrait se concerter avec André car ça concerne les 3 docs.

Pour tout te dire je pense que le répertoire examples devrait être découpé en sous répertoire portant le nom de chaque bibliothèque et on devrait trouver dans chacun de ces répertoires des exemples recoupant l'ensemble des commandes de la biblio.
http://purebasic.developpez.com/
Je ne réponds à aucune question technique en PV, utilisez le forum, il est fait pour ça, et la réponse peut profiter à tous.
comtois
Messages : 5186
Inscription : mer. 21/janv./2004 17:48
Contact :

Message par comtois »

j'ai modifié la fonction AddGadgetItem(), en gras la partie ajoutée, ça ira comme ça ?
Pour le @Link "MDIGadget" "MDIGadget()" le paramètre 'Position' indique le numéro de la #Fenetre pour la nouvelle fenêtre MDI. @ReferenceLink "purebasic_objects" "#PB_Any" peut être utilisé, auquel cas la valeur de retour sera le nouveau numéro défini automatiquement par PureBasic. Le paramètre 'Options' peut servir à spécifier les options de la nouvelle fenêtre MDI (voir @Link "Window/OpenWindow" "OpenWindow()"). Les constantes @ConstantColor "#PB_Window_BorderLess", @ConstantColor "#PB_Window_ScreenCentered" et @ConstantColor #PB_Window_WindowCentered" ne sont pas supportées par les fenêtre MDI.

Autrement dit, pour le @Link "MDIGadget" "MDIGadget()" la syntaxe peut se présenter ainsi :
AddGadgetItem(#MDI, #Fenetre, Titre$ [, ImageID [, Options]])

Et pour l'aide du MDI , j'ai modifié la phrase suivante.
En complément des commandes de la bibliothèque @LibraryLink "window" "Window" (sauf @Link "Window/StickyWindow" "StickyWindow()"),
les commandes suivantes sont disponibles pour agir sur le gadget:
http://purebasic.developpez.com/
Je ne réponds à aucune question technique en PV, utilisez le forum, il est fait pour ça, et la réponse peut profiter à tous.
nico
Messages : 3702
Inscription : ven. 13/févr./2004 0:57

Message par nico »

Personnellement, je trouve que c'est beaucoup mieux! :)
comtois
Messages : 5186
Inscription : mer. 21/janv./2004 17:48
Contact :

Message par comtois »

J'ai une petite question .
André a fait quelques ajouts dans la page variables, mais ces modifs sont en html , dans la partie existante il y a par exemple le mot résultat qui est écrit résultat, je suppose que c'est la syntaxe du html, mais si moi j'écris résultat et que je lance DocMaker , le mot s'affiche correctement, mais peut-être que ça ne sera pas le cas avec tous les navigateurs ? ou maintenant tous les navigateurs savent afficher les accents ?

bref c'est grave docteur si je mets résultat à la place de résultat ?

Je pose cette question parce que ça me simplifierait la vie d'écrire normalement les ajouts d'andré plutôt que d'avoir à gérer les accents(je peux prendre modèle sur ce qui est déjà fait sur la page, mais bon c'est chiant).
http://purebasic.developpez.com/
Je ne réponds à aucune question technique en PV, utilisez le forum, il est fait pour ça, et la réponse peut profiter à tous.
Dräc
Messages : 526
Inscription : dim. 29/août/2004 0:45

Message par Dräc »

comtois a écrit :bref c'est grave docteur si je mets résultat à la place de résultat ?
Dès lors qu’il en a déjà par ailleurs, où est le problème ?

Sinon, j’ai rencontré une inversion de mots dans la deuxième phrase de la description de ExamineDirectory():
Examine un répertoire et crée une liste qui peut être ensuite affichée avec les fonctions NextDirectoryEntry() et DirectoryEntryName(). #Repertoire est Si #PB_Any est utilisé pour le paramètre '#Repertoire', le numéro du nouveau répertoire sera renvoyé dans 'Resultat'. Si Resultat = 0, le répertoire n'a pu être examiné.
comtois
Messages : 5186
Inscription : mer. 21/janv./2004 17:48
Contact :

Message par comtois »

C'est pas un problème insurmontable, mais si c'est pas indispensable j'aimerais bien me passer d'avoir à écrire de cette façon
<td><font face="Arial" size="2">NOT est une inversion logique (binaire). Vous devez &ecirc;tre familiaris&eacute; avec les nombres binaires pour utiliser cet op&eacute;rateur. Le r&eacute;sultat de cet op&eacute;rateur est une inversion bit &agrave; bit de la valeur RHS. La valeur de chaque bit est fix&eacute;e comme indiqu&eacute; dans la table ci-dessous. Cet op&eacute;rateur ne peut &ecirc;tre utilis&eacute; avec une variable de type chaine.<br>
Ce n'est pas très naturel et ça demande un effort supplémentaire :)

Pour le é , je sais ce qu'il faut mettre , et pour le î du chaîne ? je regarderai à l'occasion , peut-être &icirc;

Ca m'emmerde tellement cette écriture en html que ça fait plusieurs semaines que je remets pour faire ces modifs :?
Surtout que c'est pas des infos capitales.

Mais comme il ne me reste plus que ça pour être à jour par rapport aux dernières modifs de la doc anglaise... je vais prendre mon courage à deux mains pour la semaine prochaine.


[EDIT]
Et pour ExamineDirectory() je l'avais déjà corrigé en regardant le débat sur le forum anglais au sujet d'un bug concernant cette commande :)
@Description
Examine un répertoire et crée une liste qui peut être ensuite affichée avec les fonctions @Link "NextDirectoryEntry" "NextDirectoryEntry()" et @Link "DirectoryEntryName" "DirectoryEntryName()".
@LineBreak
@LineBreak
Si @ReferenceLink "purebasic_objects" "#PB_Any" est utilisé pour le paramètre '#Repertoire', le numéro du nouveau répertoire sera renvoyé dans 'Resultat'. Si Resultat = 0, le répertoire n'a pu être examiné.
http://purebasic.developpez.com/
Je ne réponds à aucune question technique en PV, utilisez le forum, il est fait pour ça, et la réponse peut profiter à tous.
Avatar de l’utilisateur
Jacobus
Messages : 1559
Inscription : mar. 06/avr./2004 10:35
Contact :

Message par Jacobus »

Salut Comtois

Je viens de trouver ça dans ma doc, une inversion dans les commandes
Read à la place de Write
WritePreferenceString()


Syntaxe

WritePreferenceString(Clef$, Valeur$)
Description

Ecrit la paire Clef$, Valeur sous la forme : 'Clef$ = Valeur' dans le fichier préférences préalablement créé avec CreatePreferences() ou ouvert avec OpenPreferences(). Si la 'Clef$' existe déjà, alors sa valeur est remplacée.

Pour écrire une valeur dans un type particulier, les commandes suivantes peuvent être utilisées:

ReadPreferenceDouble() <----- !!
ReadPreferenceFloat() <----- !!
ReadPreferenceLong() <----- !!
ReadPreferenceQuad() <----- !!
Ma version est celle livrée avec PB4, je ne l'ai pas changé depuis.
Quand tous les glands seront tombés, les feuilles dispersées, la vigueur retombée... Dans la morne solitude, ancré au coeur de ses racines, c'est de sa force maturité qu'il renaîtra en pleine magnificence...Jacobus.
nico
Messages : 3702
Inscription : ven. 13/févr./2004 0:57

Message par nico »

Tiens Comtois, un petite page avec les accents:

http://www.designvegetal.com/gadrat/cou ... cents.html



Sinon, pourquoi tu ne fais pas un petit prog qui te changera les accents en code Html, comme ça c'est plus simple à écrire et surtout à relire!
comtois
Messages : 5186
Inscription : mer. 21/janv./2004 17:48
Contact :

Message par comtois »

@Nico , merci pour le lien.
Pour les accents , je vais effectivement écrire normalement , et ensuite faire un simple rechercher / Remplacer ,c'est pas la mort .
Disons que ça m'avait gonflé parce que j'avais merdé une première fois avec les balises , mais ça va mieux je me suis ressaisi :)

@Jacobus ,c'est fait .

@Dräc, j'ai intégré ton texte sur les pointeurs, si tu pouvais reprendre cette partie aussi , ça serait bien , ça permettrait de rester dans l'esprit de ce que tu as fait :)
The "String" structure looks like this:
Code:
Structure String
s.s
EndStructure


So when doing *Struct.String, you actually have a pointer (the structure pointer)
to a pointer (the s.s) to a string (the actual data)
Doing "@String$" however returns the pointer to the actual data.
This is a fundamental difference to the other basic types, where the variable data
is actually stored inside the structure, and that is why it will not work with strings.

This one illustrates it:
Code:
String$ = "Hello World"
*Pointer = @String$ ; get pointer to string data
*Struct.String = @*Pointer ; get pointer to pointer to string data
Debug *Struct\s ; now it displays


The best solution to this problem really depends on what you need to do with the string.

If you need to compare the string data to something else, the best thing
is to use commands like CompareMemoryString()/MemoryStringLength(),
which can operate on pointers, so you have no overhead at all.

If what you need is to copy the string from the pointer into a normal
PB variable, PeekS() is a good thing to use, as it is almost as fast as
a normak string copy like "a$ = b$".
Je ne sais plus qui m'avait suggéré de mettre le lien de la doc dans ma signature , je viens de refaire un essai , et ça passe , c'est le premier lien dans ma signature.

Je viens de mettre en ligne la dernière version de la doc , elle comporte les petits trucs mentionnés plus haut. et la page variables n'est pas terminée , ça sera pour la semaine prochaine , donc ceux qui n'ont pas l'adsl vous pouvez attendre je sortirai une autre version dans une semaine.
http://purebasic.developpez.com/
Je ne réponds à aucune question technique en PV, utilisez le forum, il est fait pour ça, et la réponse peut profiter à tous.
comtois
Messages : 5186
Inscription : mer. 21/janv./2004 17:48
Contact :

Message par comtois »

Je propose d'ajouter ce complément au sujet des pointeurs et des chaines.
Pointeurs et chaînes de caractères.

La structure "String" se présente ainsi:

Code : Tout sélectionner

@Code:
  Structure String
    s.s
  EndStructure
@EndCode
Aussi en faisant *Struct.String, vous obtenez un pointeur (pointeur de la structure) vers un pointeur (le s.s) qui pointe vers les données réelles d'une chaîne.

"@Texte$" renvoie le pointeur vers les données de la chaîne "Texte$".

C'est une différence fondamentale avec les autres types de variables, où les données des variables sont stockées réellement à l'intérieur de la structure.

@Example
@Code
Texte$ = "Hello World"
*Pointeur = @Texte$ ; Pointeur vers les données de la chaîne
*Struct.String = @*Pointeur ; Pointeur vers le pointeur des données de la chaîne
Debug *Struct\s ; Maintenant on peut afficher la chaîne
@EndCode

Ce qui revient à faire :

Code : Tout sélectionner

@Code
  Debug PeekS(@Texte$)
  ;ou 
  Debug PeekS(*Pointeur)
@EndCode

Toutes les critiques seront les bienvenues
http://purebasic.developpez.com/
Je ne réponds à aucune question technique en PV, utilisez le forum, il est fait pour ça, et la réponse peut profiter à tous.
Dräc
Messages : 526
Inscription : dim. 29/août/2004 0:45

Message par Dräc »

comtois a écrit :@Dräc, j'ai intégré ton texte sur les pointeurs, si tu pouvais reprendre cette partie aussi , ça serait bien , ça permettrait de rester dans l'esprit de ce que tu as fait :)
Oui, tu as raison, j’ai commencé, je veux bien continuer cette page.
Cependant, vu qu’il s’agit de la Doc officielle, je suis un peu préoccupé par deux points :
- Est-ce que Fred a validé mes digressions sur ce thème? (entre autre :))
- Ne risque t’on pas d’avoir une doc Française différente de celle plus officielle Anglaise?
Parce que là, on commence sèrieusement à dériver de la simple correction…


Bon ! Sinon, revenons à nos moutons :
Vous le savez, le pointeur est une notion fondamentale mais délicate au début.
D’autre part, les chaînes sont des variables gérées différemment des autres.
Aussi comprendre la combinaison des pointeurs et des chaînes de caractères est loin d’etre immédiat.

Cela nécessite un minimum d’explications et je vous soumets donc la proposition suivante :

Pointeurs et chaînes de caractères
Toutes les variables ont une taille fixe en mémoire (1 octet pour un Byte, 4 octets pour un Long, etc…) sauf les chaînes de caractères dont la longueur peut changer.
N’ayant donc pas de longueur fixe, l’espace mémoire alloué à une chaîne de caractères varie.

C’est pour cette raison qu’à l’intérieur des structures, les chaînes de caractères sont gérées différemment des autres variables.

En effet, lors de la compilation, le compilateur ne connaît pas la taille des chaînes de caractères qui seront utilisées.
C’est pour cela que les champs d’une structure faisant référence à une chaîne de caractères se contentent de ne stocker que l’adresse mémoire où réside la chaîne de caractères et non la chaîne elle-même.
Donc les champs d’une structure faisant référence à une chaîne de caractères sont en fait des pointeurs vers des chaînes de caractères.
C’est pour cela, entre autre, que SizeOf(String) retourne une taille de 4 octets pour une compilation 32 bits.

Aussi l’écriture suivante est incorrecte:

Code : Tout sélectionner

Texte$ = "Bonjour"
*Pointeur.String = @Texte$
Debug *Pointeur\s
car *Pointeur\s cherche à lire la chaîne de caractères qui réside à l’adresse écrite en *Pointeur.
Or cette adresse n’existe pas car *Pointeur pointe la chaîne de caractères et non une zone mémoire contenant une adresse!

Pour bien faire ici, il faut pouvoir donner au champ \s de la structure String, l’adresse de la chaîne de caractères.
Exemple :

Code : Tout sélectionner

Texte$ = "Bonjour"
*Texte = @Texte$ ;*Texte a pour valeur l’adresse où réside la chaîne de caractères en mémoire
*Pointeur.String = @*Texte
Debug *Pointeur\s

[Fin de mon exposé]

4 remarques, si vous me le permettez :

1- Je ne suis pas d’accord avec l’intro actuelle sur les pointeurs : elle dit qu’un pointer est une variable de type Long, ce qui est faux !
Pourquoi ne pas reprendre, par exemple, ce que j’avais proposé la derniere fois ? A savoir :
L'utilisation des pointeurs est possible en plaçant une * devant le nom d’une variable.
Une telle variable est de type pointeur ou plus simplement un pointeur.

Un pointeur est une variable dont la valeur contient une adresse mémoire.

Un pointeur est généralement associé avec une structure.
2- Justement pour éviter certaines maladresses de codage, je pense qu’il serait judicieux d’indiquer à l’utilisateur qu’à chaque fois que l’on veut stoker une adresse, il faut le faire avec un pointeur meme si, sur un processeur 32 bits, un long peut contenir une adresse.
Si tel n’est pas le cas, le jour ou l’on compile en 64bits, ca risque de ne marcher et l’utilisateur risque lui de passer du temps à trouver le pb…

Je propose donc la phrase suivante que je verrais bien placée juste après celle mentionnant que PureBasic ne permet pas encore de créer des exécutables 64 bits :

A chaque fois qu’une adresse mémoire doit être stockée, il faut le faire par l’intermédiaire d’un pointeur. Ceci garanti (le jour où PureBasic permettra aussi une compilation 64bits), que l’adresse sera correctement représentée lors de la compilation du code que ce soit par un processeur 32 bits comme par un processeur 64 bits par exemple.

3- Maintenant qu’il y a l’explication sur les chaînes de caractères, il faut mettre au pluriel le sous titre:
Notions sur les pointeurs en PureBasic

4- De même, il me semble qu’il serait plus claire de mettre des sous-sous titre (vous me suivez ?)
Par exemple :
  • Pointeurs et taille mémoire
    Pointeurs et structures
    Pointeurs et chaînes de caractères

5- Enfin, dans le premier exemple donné pour les structures, peut-on permuter Nom et Prenom, svp? (non parce que là, j’en dors pas la nuit)

Code : Tout sélectionner

  MesAmis(0)\Nom = "Durand"
  MesAmis(0)\Prenom = "Michel" 
  MesAmis(0)\Age = 32
Dernière modification par Dräc le mer. 28/juin/2006 1:16, modifié 2 fois.
comtois
Messages : 5186
Inscription : mer. 21/janv./2004 17:48
Contact :

Message par comtois »

Dräc a écrit :- Est-ce que Fred a validé mes digressions sur ce thème? (entre autre :))
A mon avis il a d'autres chats à fouetter :)
S'il y a le moindre doute, j'espère qu'il y aura toujours quelqu'un pour le signaler et dans ce cas il sera toujours temps de contacter Fred pour qu'il arbitre.
- Ne risque t’on pas d’avoir une doc Française différente de celle plus officielle Anglaise?
Parce que là, on commence sèrieusement à dériver de la simple correction…
Je mettrai une note dans le mail pour indiquer pour s'agit d'un supplément d'information pour qu'André prenne en compte la modif.
Alors effectivement il peut y avoir quelques différences , mais dans l'ensemble on colle quand même avec la doc anglaise.
Et puis c'est des informations importantes, alors il ne faut pas hésiter à les ajouter :)
Cela nécessite un minimum d’explications et je vous soumets donc la proposition suivante :
J'attends un peu pour laisser le temps aux autres de réagir à ta proposition avant de la reprendre.
Sinon petite faute dans l'exemple
*Pointeur.String = @*Texte
1- Je ne suis pas d’accord avec l’intro actuelle sur les pointeurs : elle dit qu’un pointer est une variable de type Long, ce qui est faux !
C'est vrai , je vais le corriger.
2- Je propose donc la phrase suivante que je verrais bien placée juste après celle mentionnant que PureBasic ne permet pas encore de créer des exécutables 64 bits :

A chaque fois qu’une adresse mémoire doit être stockée, il faut le faire par l’intermédiaire d’un pointeur. Ceci garanti (le jour où PureBasic permettra aussi une compilation 64bits), que l’adresse sera correctement représentée lors de la compilation du code que ce soit par un processeur 32 bits comme par un processeur 64 bits par exemple.
Plutôt 'il faut le faire', je mettrais nous vous conseillons ou un truc dans le style, c'est un conseil qu'on donne pas une obligation :)
Mais sinon oui c'est une bonne suggestion.
4- De même, il me semble qu’il serait plus clair de mettre des sous-sous titre (vous me suivez ?)
Pas trop , je comprendrai mieux quand je me replongerai dans la doc peut-être ?
5- Enfin, dans le premier exemple donné pour les structures, peut-on permuter Nom et Prenom, svp? (non parce que là, j’en dors pas la nuit)
Durand c'est pas un prénom ? en tout cas je suis sûr que Michel ça peut être un nom :)

Mais pour préserver ton sommeil , je vais sûrement faire la correction :)
http://purebasic.developpez.com/
Je ne réponds à aucune question technique en PV, utilisez le forum, il est fait pour ça, et la réponse peut profiter à tous.
nico
Messages : 3702
Inscription : ven. 13/févr./2004 0:57

Message par nico »

Je trouve les explications de Dräc pertinentes et bien adaptées au discours sur les pointeurs quelque peu difficile à appréhender.
Répondre