A few syntaxical/grammatical corrections to the french doc

[adesklets.git] / doc / adesklets_fr.texi

\input texinfo   @c -*-texinfo-*-
@comment %**start of header
@setfilename adesklets_fr.info
@documentlanguage fr
@include version_fr.texi
@settitle adesklets @value{VERSION}
@c @syncodeindex pg cp
@comment %**end of header
@copying
Ce manuel concerne adesklets (version @value{VERSION}, @value{UPDATED}).

Copyright @copyright{} 2004, 2005
S.Fourmanoit @email{syfou@@users.sourceforge.net}. 

Traduction française originale de Guillaume Boitel @email{g.boitel@@wanadoo.fr}, 
entièrement remise à jour et reprise par Martin 
Kirchgessner @email{martin.kirch@@gmail.com} depuis adesklets 0.4.10 

@quotation
Permission est accordée de copier, distribuer et/ou modifier ce document selon
les termes de la Licence Generale Publique GNU (GNU GPL) version 2, ou toute 
version ultérieure publiée par la Free Software Fundation. Une copie de la présente  
licence est incluse dans la section ``GNU General Public License''
@end quotation

[Cette version est une traduction complète de la documentation d'adesklets; malgré 
tout les nouveautés peuvent mettre quelques jours à être traduites, pour être sur(e)  
de ne pas les rater lisez la version originale.]
@end copying

@c Define useful weblink macro
@macro weblink{link}
@html
<a href="
@end html
\link\
@html
">\link\</a>
@end html
@end macro

@c Define weblink2 macro: a variation on the previous one
@macro weblink2{desk,link}
@html
<a href="\link\">
@end html
\desk\
@html
</a>
@end html
@end macro

@dircategory Graphics
@direntry
* adesklets in french: (adesklets_fr).      Another desklets container (in French).
@end direntry

@titlepage
@title adesklets
@subtitle pour la version @value{VERSION}, @value{UPDATED}
@author Guillaume Boitel (@email{g.boitel@@wanado.fr})
@author Martin Kirchgessner (@email{martin.kirch@@gmail.com})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top adesklets

@ifnothtml
Suivez le lien pour la version originale
(@xref{Top,Version anglaise, Contents, adesklets,}.).
@end ifnothtml
@ifhtml
@weblink2{[Version anglaise],../en/index.html}
@end ifhtml

@insertcopying
@end ifnottex

@menu
* A propos d'adesklets::
* Nouveautés::
* Installer adesklets::
* Utiliser adesklets::
* Programmation d'adesklets::
* Extension d'adesklets::
* Recherche d'aide!::
* Foire Aux Questions::
@ifhtml
* Documentation du paquetage Python::
@end ifhtml
* Documentation d'Imlib2::
* GNU Makefile pour empaqueter les desklets::
* Soumettre un desklet::
* Copier ce Manuel::
* Clé publique Open PGP::
@end menu

@noindent Une version à jour de ce document peut être trouvée en ligne:
@weblink{http://adesklets.sf.net/doc/fr/}.

@noindent Vous trouverez aussi sur le site du projet des captures d'écran, les 
paquetages des sources, les archives téléchargeables de la documentation,
et bien d'autres choses encore: @weblink{http://sf.net/projects/adesklets/}.

@node A propos d'adesklets
@chapter Qu'est-ce qu'adesklets ?

@section Réponse courte

`adesklets' est une console interactive
d'@weblink2{Imlib2,http://www.enlightenment.org/} pour le
X Window System. Il permet à des langages de script d'écrire de manière
propre et simple des applets graphiques intégrés au bureau (i.e. "desklets")
de belle apparence et légèrement interactifs.

Il peut aussi être utilisé comme un éditeur graphique en ligne de commande,
un peu comme @weblink2{ImageMagick,http://www.imagemagick.org/}, mais avec
des fonctionnalités différentes.

@section Réponse longue

@command{adesklets} signifie "another desklets [container]" (littéralement: un 
autre [conteneur] de desklets). Il a été écrit
comme une alternative à d'autres programmes tels que:

@enumerate
@item
GNOME gDesklets (@weblink{http://gdesklets.gnomedesktop.org/})
@item
KDE SuperKaramba (@weblink{http://netdragon.sourceforge.net/}).
@item
GKrellM (@weblink{http://www.gkrellm.net/})
@end enumerate

Puisque ce projet s'appelle 'a'desklets, il est encore possible, pour
commencer des projets semblables, d'utiliser l'espace de 'b' à 'z' desklets,
à l'exception de 'g' desklets, qui est déjà pris.

Plus sérieusement, tous ces programmes sont bons. Néanmoins, les deux premiers
ont des pré-requis très lourds en termes de dépendances de bibliothèques; 
de base gDesklets requiert que le bureau GNOME soit entièrement
installé (plus quelques bibliothèques spécialisées telles que gnome-python),
tandis que SuperKaramba a besoin de toutes les bibliothèques de KDE ainsi
que de l'environnement de base. Ceci se répercute sur l'exécution des autres
taches@footnote{Bien sur, c'est uniquement l'opinion de l'auteur - et ces
deux applications ont fait de gros progrès sur la gestion des ressources
de version en version.}. D'autre part, alors que GkrellM est plus léger
(bien qu'il dépende toujours de GTK+), il ne fournit pas la même qualité en
terme de "présentation" (selon les goûts de l'auteur, naturellement) ou de
" scriptabilité " par rapport aux deux autres.

De ce constat est né @command{adesklets}. Il fournit:

@itemize
@item
un cadre minimal pour des desklets X Window totalement intégrés dans le bureau,
avec quelques facilités pour gérer leur lancement, leur placement et
leur arrêt.
@item
une API de dessin générique, riche et facile d'emploi semblable à celle
de gDesklets et de SuperKaramba concernant sa qualité visuelle, grâce à la
bibliothèque Imlib2.
@item
des dépendances de bibliothèques simples, se résumant surtout à l'utilisation de la très bonne (et
rapide) bibliothèque Imlib2 pour toutes les opérations graphiques. Aucune boite
à outils de fenêtres n'est utilisée: le programme repose directement sur xlib.
@item
un interpréteur petit, léger et robuste potentiellement utilisable avec
toutes sortes de langages de scripts, grâce à une syntaxe propre, limitée et
homogène. Dans cette version @value{VERSION}, le support de Python a été fourni
séparément. Le support de Perl et Ruby serait franchement faisable, 
n'hésitez pas à contribuer afin que votre langage préféré soit 
supporté (@xref{Extension d'adesklets}.)!
@item
un usage minimal de l'espace disque, de la mémoire vive et du
processeur. Typiquement, avec la glibc-2.3.4 et le noyau Linux 2.6 sur
une architecture x86, l'unique exécutable représente moins de 130 Ko sur
le disque et prend moins de 3Mo de mémoire virtuelle par desklet, juste après
son lancement. Lorsque le desklet est lancé il n'utilise quasiment aucun 
cycle processeur (même en prenant en compte le script Python interprété).
@end itemize

Il ne fournit PAS:
@itemize
@item
une API de fenêtre sophistiquée, ni même un accès aux widgets en dehors de
menus gris nus et laids: vous ne pouvez clairement pas écrire une interface 
graphique (GUI) avec ces seuls desklets.
@item
de mécanismes compliqués (ni même de mécanismes clairs, en la matière)
pour la configuration des scripts. Les développeurs de scripts sont libres (ou
condamnés, selon la façon de voir les choses) de faire ce qu'il leur convient.
@item
un support pour tout ce qui n'est pas entièrement compatible avec un système
POSIX. Par exemple, il serait vraiment surprenant d'arriver à le compiler sur 
Cygwin.
@item
une gestion poussée des évènements utilisateurs. Le but d'@command{adesklets} est
d'être fiable et peu consommateur de ressources; seuls quelques événements - 
essentiellement relatifs au pointeur - sont utilisables via son l'API.
@end itemize

@node Nouveautés
@chapter Nouveautés

@heading Quoi de neuf pour la version 0.4.12?
C'est un correctif. Elle corrige une erreur dans le nouveau makefile 
distribué pour la documentation qui empêchait les fichiers info et 
les pages de manuel d'être installés dans des répertoires arbitraires 
vides (merci à Bart Kreska pour le patch). Elle ajoute aussi le support 
de nautilus et de KDE version 3.4.1 et supérieures, ainsi qu'un support 
préliminaire pour xffm-desktop et ROX-Filer. Elle devrait rectifier un 
vieux problème avec certains desklets qui n'arrivaient pas à terminer 
leur affichage initial. Enfin la FAQ a aussi été sensiblement enrichie.

@heading Quoi de neuf pour la version 0.4.11?
C'est un correctif. Concernant la documentation, la version française à été 
remise au niveau de l'anglaise (merci à Martin Kirchgessner 
@email{martin.kirch@@gmail.com} pour tout son travail). De plus toutes les 
sources de la documentation et les fichiers html ont étés séparés du 
paquetage principal (grâce à cela, adesklets à maintenant perdu 300Ko). 
Concernant le code, cette version contient beaucoup de petites corrections 
pour diverses plate-formes -- FreeBSD7 devrait normalement être supporté 
sans patch, le manuel du script de soumission des desklets à été ajouté 
pour satisfaire Debian. Mais le plus gros changement est probablement 
l'inclusion d'une interface optionelle basée sur le shell pour l'interpréteur, 
qui facilite l'administration d'adesklets et l'adaptation du code à 
de nouveaux gestionnaires de fenêtres.

@heading Quoi de neuf pour la version 0.4.10?
C'est un correctif. Involontairement, une modification étrange est apparue 
dans la version précedente: à cause d'elle 
le menu contextuel ne fonctionnait plus de la manière prévue (la touche 
Control devrait être enfoncée pour que le menu s'affiche). Cette version 
à annulé ce changement, et ajouté une option de configuration, 
--enable-control-on-context-menu, pour ceux qui préfèrent vraiment ce 
comportement.

@heading Quoi de neuf pour la version 0.4.9?
C'est un correctif. Elle change les définitions des macros globales pour 
qu'adekslets puisse être compilé sans problème sur FreeBSD 6.x, corrige 
une erreur lors de la suppression des options à passer au compilateur C 
relatives au débogage, et ajoute un nouveau programme de démonstration 
du threading.

@heading Quoi de neuf pour la version 0.4.8?
C'est un correctif. Elle change les définitions des macros globales pour 
qu'adekslets puisse être compilé sans problème sur FreeBSD 5.x, et 
implante la détection d'une fausse root window pour KDE, grâce à yogi77, 
du forum.

@heading Quoi de neuf pour la version 0.4.7?
C'est un correctif. Elle retire les appels à quelques fonctions 
mathématiques de C99 qui ne sont pas disponibles dans les premiers BSD, 
rendant le code plus portable. Elle ajoute aussi deux nouvelles commandes 
à l'API pour mieux contrôler le système de cache des images.

@heading Quoi de neuf pour la version 0.4.6?
C'est un correctif et une mise à jour de la documentation. Elle corrige de 
nombreux bugs mineurs dans les scripts de soumission des desklets, rend la 
structure autoconf plus portable, ajoute un nouveau script de démonstration 
dans test (widget.py), corrige quelques bugs de placement à l'écran dus à la 
routine xwindow_move_window (merci à man1ed du forum pour avoir fourni le 
patch), et enfin ajoute une nouvelle annexe contenant une version en ligne 
de la documentation d'Imlib2.

@heading Quoi de neuf pour la version 0.4.5?
C'est un correctif et une mise à jour de la documentation. Elle améliore le 
procédé de soumission des desklets en publiant le script complet de mise en 
ligne utilisé par l'auteur. Elle corrige aussi un bug du rafraichissement des 
fenêtres, qui apparait quand on utilise des images d'arrière-plan 
et des menus spécifiés par l'utilisateur; merci à ZeroDivide de l'avoir 
signalé. Quelques mises à jour et corrections de la documentation ont également 
été faites.  

@heading Quoi de neuf pour la version 0.4.4?
C'est une mise à jour de la documentation, principalement faite pour les 
auteurs de desklets. Elle inclut surtout une nouvelle annexe expliquant comment 
soumettre un desklet (avec l'aide d'un script), ainsi qu'une nouvelle sous-partie 
sur la détection des polices sur l'ensemble du système. Quelques ajouts ont 
été effectués sur la FAQ pour couvrir ce sujet.

@heading Quoi de neuf pour la version 0.4.3?
C'est une mise à jour de la documentation. Ici la plupart du travail à été 
fait part Mike Pirnat @email{exilejedi@@users.sourceforge.net}, qui a eu la 
gentillesse de corriger l'anglais déficient de l'auteur en relisant ce manuel 
d'un bout à l'autre. Merci Mike! La FAQ a aussi été largement enrichie, et 
une nouvelle annexe pour les auteurs de desklets à été ajoutée.

@heading Quoi de neuf pour la version 0.4.2?
C'est un correctif. Elle corrige un bug du paquetage Python qui l'empêchait 
de se compiler avec toutes les versions de Python inférieures à 2.4.0. Merci 
à nucular, du forum d'adesklets, de l'avoir remarqué. Elle corrige aussi un 
problème mineur concernant mmap sur ce package.  

@heading Quoi de neuf pour la version 0.4.1?
C'est un correctif. Elle sécurise l'utilisation de la classe optionelle 
@code{adesklets.ConfigFile} en changeant complètement la manière dont les 
fichiers de configurations sont importés, ce qui retire une faille de sécurité 
potentielle.

@heading Quoi de neuf pour la version 0.4.0?
C'est la sortie d'une nouvelle version mineure. L'interpreteur supporte 
maintenant l'internationalisation. Il peut maintenant travailler 
dynamiquement avec differents jeux de caractères sur les plate-formes 
supportant iconv (selon le standard UNIX98), et les affiche correctement. 
Le paquetage Python a aussi été enrichi d'une classe generique (optionelle) 
de configuration, en esperant qu'elle sera utile aux auteurs de desklets.

@heading Quoi de neuf pour la version 0.3.2?
C'est une mise à jour de la documentation. Une partie pour les 
programmeurs Python à été ajoutée, et la FAQ à été largement enrichie.

@heading Quoi de neuf pour la version 0.3.1 ?
Cette version corrige un oubli en implantant la gestion de l'interruption
des barrières temporelles (time gate) par des évènements X. Cette correction
est essentielle à la bonne marche de plusieurs effets dynamiques.

@heading Quoi de neuf pour la version 0.3.0 ?
Ceci est une nouvelle version mineure. Nous nous sommes beaucoup souciés de
la portabilité depuis les toutes premières versions d'adesklets; avec cette
version, le paquetage compile et tourne sans accroc sur FreeBSD et NetBSD 
(@xref{Portabilité}.). La gestion des évènements a également été épurée en interne,
et le paquetage Python étendu pour supporter la modification dynamique des 
évènements interceptés (voir @file{test/test_events.py}).

L'interpréteur répond maintenant aux désidérata de l'auteur, et ne devrait
pas être significativement étendu dans le futur; tout est relativement en
place pour écrire tout type de desklet, y compris des animations.

@heading Quoi de neuf pour la version 0.2.1 ?
Il s'agit de la correction d'un bug mineur du à une incompatibilité avec la 
bibliothèque GNU history. Merci à Mike Pirnat @email{exilejedi@@users.sourceforge.net} 
de l'avoir signalé.

@heading Quoi de neuf pour la version 0.2.0 ?
Ceci est une nouvelle version mineure. L'interpréteur supporte dorénavant
les variables textuelles (la substitution dynamique de chaînes, pour être précis),
ainsi que l'exécution de séquences préenregistrées de commandes sous des contraintes
précises de temps (un mode indirect d'exécution); cela donne aux desklets un moyen
de générer des animations fluides. Lancez le script de démonstration
@file{test/fading.py} du paquetage de base pour voir ces nouvelles fonctions
à l'oeuvre.

Les développeurs, quant à eux, ont maintenant accès à une plateforme complètement
réécrite d'enregistrement de rapports d'exécution de toutes session 
de l'interpréteur (à des fins de débogage).

@heading Détails
Lisez le fichier @file{ChangeLog} pour connaitre le détail des changements 
apportés.

@ifplaintext
@c Sets up a marker for automated INSTALL_FR file generation
INSTALL_BEG
@node Installer adesklets
@unnumbered Installer adesklets
@end ifplaintext
@ifnotplaintext
@node Installer adesklets
@chapter Installer adesklets
@end ifnotplaintext

@section Pré-requis pour la compilation

Pour compiler adesklets à partir des sources, vous aurez besoin de :

@itemize
@item
Un compilateur supportant le C ANSI ainsi que les macros variadiques (à peu
près toutes les versions de @weblink2{gcc,http://gcc.gnu.org} supérieures à 
la 2.7.0 devraient fonctionner, tout comme n'importe quoi d'autre sorti ces dix
dernières années)
@item
Les en-têtes@footnote{Excepté pour les compilations sans fichiers en-têtes, utiles 
pour les environnements serveurs et équivalents - lire la suite pour de plus
amples informations.} et les bibliothèques @weblink2{X11,http://www.x.org/}.
@item
Imlib2 1.1.2 ou supérieure (la plus récente sera la meilleure: allez 
la télécharger sur @weblink{http://sourceforge.net/projects/enlightenment/}).
@item
@weblink2{GNU readline,http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html}
@item
un système raisonnablement compatible POSIX
@end itemize

@noindent Les composants suivants pourront aussi être utilisés, si'ls sont 
présents sur le système:

@itemize
@item
@weblink2{fontconfig,http://www.fontconfig.org/}, pour la détection automatique 
des polices utilisables présentes dans le système
@item
@weblink2{GNU history,http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html}, 
le complément fidèle de GNU readline permettant l'enregistrement d'historiques 
de commandes
@item
@weblink2{Python,http://www.python.org} 2.3 ou supérieure, si vous désirez
le support pour Python (vous en aurez sûrement besoin: les desklets sont 
écrits avec ce langage)
@end itemize

De nombreux systèmes placent les versions de ``développement'' des librairies 
et de leurs outils dans des paquetages séparés (@command{imlib2-devel}, 
@command{readline-devel}, @command{fontconfig-devel}, @command{python-devel}, 
etc); si c'est le cas du système de destination, ces versions devront être 
utilisées plutôt que les versions ``normales''.

@section Pré-requis pour l'exécution

En plus des dépendances de compilation, l'interface optionelle d'adesklets 
basée sur le shell, installée par défaut, requiert elle-même quelques 
utilitaires, tous censés satisfaire un minimum les spécifications POSIX 
1003.2 et 1003.2a:

@itemize
@item un shell compatible @command{/bin/sh}
@item un éditeur de flux (Streaming EDitor, sed)
@item test, mkdir, rmdir, sleep, kill et ls
@end itemize

les programmes @command{xwininfo} et @command{xprop} peuvent aussi être 
utilisés, si une routine de détection de fausse fenêtre racine (fake root 
window) donnée est explicitement invoquée. Les implémentations de ces 
utilitaires de XFree86 et de X.org ont toutes les deux été testées. 
D'autres programmes seront utilisés par certaines routines de détection: 
voyez les sources de l'interface pour plus de détails.

@section Note sur la portabilité
@anchor{Portabilité}
Ce paquetage est construit en gardant la portabilité à l'esprit - toutes les
extensions spécifiques ont été évitées, et les spécifications (ANSI, SVID
3, BSD 4.3, POSIX) ont été suivies scrupuleusement. Néanmoins, tous les
développement ont été fait sur un unique système Linux: il est très probable
qu'adesklets ne compilera pas ou ne fonctionnera pas comme prévu dans
certains cas. Régler ces problèmes est important pour nous.

adesklets a été porté et testé avec succès par les développeurs sur plusieurs 
systèmes. Au moment de rendre publique la version @value{VERSION}, le paquetage 
a été compilé et utilisé avec succès sous toutes sortes de:
@itemize
@item @strong{Noyaux/systèmes}: Linux (séries 2.2, 2.4 et 2.6), FreeBSD 
      (4.10, 5, 6 et 7), NetBSD (1.6)
@item @strong{Bibliothèques C}: glibc (2.1.3 et plus), uclibc (0.8.28), si 
disponibles sur votre plate-forme
@item @strong{Compilateurs}: gcc (2.95.2, toutes versions 3, 4.0.1), 
      icc 7.0 (en paramètrant)
@end itemize

De plus adesklets est lui-même complètement indépendant de l'architecture matérielle, 
bien qu'Imlib2 soit plutôt optimisée pour x86 et amd64. Il est couramment utilisé 
par l'auteur sur des machines x86, amd64 et ppc.

Au moment où ces lignes sont écrites, adesklets est déjà intégré dans les portages 
de nombreux BSD et dans les catalogues de nombreuses distributions de Linux. 
Mentionnons notemment:

@itemize
@item Le paquetage Debian: @weblink{http://packages.debian.org/unstable/x11/adesklets}, 
maintenu par Bartosz Fenski @email{fenio@@debian.org}, 
@item Le portage FreeBSD: @weblink{http://www.freshports.org/deskutils/adesklets/}, 
maintenu par Roman Bogorodskiy @email{novel@@freebsd.org},
@end itemize

Vous avez vous-même essayé de faire tourner adesklets sur une architecture 
non citée plus haut? Faites-le nous savoir, surtout si ça n'a pas marché.

@section Téléchargement du logiciel

La version à jour du logiciel (en archive source bzipée) est disponible
 sur la page du projet sur sourceforge:
@weblink{http://sf.net/projects/adesklets/}

Vous pouvez l'extraire depuis la console avec @command{tar}. Avec la
version @value{VERSION}, la ligne de commande devrait être:
@example
tar xvjf adesklets-@value{VERSION}.tar.bz2
@end example
ou, si la version que vous avez installée de @command{tar} ne supporte pas
les filtres d'archives bzip2:
@example
bzcat adesklets-@value{VERSION}.tar.bz2 | tar xv
@end example

@section Vérification optionelle de l'intégrité du logiciel

Pour adesklets @value{VERSION},  vous pouvez également télécharger depuis 
@weblink2{sourceforge,http://sf.net/projects/adesklets/} une signature 
détachée sous forme ascii nommée @command{adesklets-@value{VERSION}.tar.bz2.asc},
que vous pourrez utiliser avec la clé publique de l'auteur 
(@pxref{Clé publique Open PGP}, en annexe) pour vous assurer de 
l'intégrité du paquetage. Par exemple, avec @command{GnuPG}
(@weblink{http://www.gnupg.org/}), vous utiliseriez la commande:

@example
gpg --verify adesklets-@value{VERSION}.tar.bz2.asc adesklets-@value{VERSION}.tar.bz2
@end example

Vous pouvez également obtenir la clé publique pour
l'adresse @email{syfou@@users.sourceforge.net}
de plusieurs serveurs de clés publiques tel @weblink{http://www.keyserver.net/} ou
encore @weblink{http://pgp.mit.edu/}. N'hésitez pas à contacter l'auteur directement
si vous désirez vous assurer plus avant de l'authenticité de cette clé.

@section Compilation et Installation:

adesklets fournit les scripts usuels autoconf/automake des paquetages GNU.

Donc, dans la plupart des cas, l'installation suit les trois étapes habituelles:

@enumerate
@item
Atteignez le répertoire contenant le code source du paquetage (avec `cd') et tapez
`./configure' pour configurer le paquetage pour votre système.  Si vous utilisez
`csh' sur une ancienne version de System V, vous devrez peut-être plutot taper
`sh ./configure' afin d'empêcher `csh' d'exécuter lui-même `configure'.

L'exécution de `configure' peut prendre du temps. Pendant qu'il s'exécute,
il écrit quelques messages qui vous informent des fonctionnalités qu'il est
en train de vérifier.
@item
Tapez `make' pour compiler le paquetage.
@item
Tapez `make install' pour installer les programmes, tous les fichiers de
données et la documentation.
@end enumerate

Vous pouvez enlever les programmes binaires et les fichiers objets du
répertoire qui contient le code source en tapant `make clean'. Pour enlever
également les fichiers que `configure' a créé (ainsi vous pourrez compiler
le paquetage pour une autre type d'ordinateur), tapez `make distclean'.

@section Compilateurs et Options:

Certains systèmes requièrent des options inhabituelles pour la compilation
ou l'édition des liens que le script `configure' ne connaît pas. Vous pouvez
donner à `configure' des valeurs initiales pour des variables en les déclarant
dans l'environnement. En utilisant un shell compatible Bourne, vous pouvez
faire cela en ligne de commande comme ceci:

@example
CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
@end example

@noindent Ou dans les systèmes dotés du programme `env', vous pouvez faire:

@example
env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
@end example

@section Fonctionnalités Optionnelles :

adesklets possède quelques fonctionnalités optionnelles que vous pouvez
installer ou non à partir du script de configuration. Tapez :

@example
./configure --help
@end example

@noindent pour une description courte et complète. En voici quelques une
intéressantes :

@itemize
@item
Vous pouvez choisir de compiler adesklets sans aucun support pour X
(@command{--without-x}).
Vous aurez une version qui n'est manifestement pas faite pour le rendu de
desklets, mais bonne pour de la manipulation d'images en ligne de commande.
@item
Vous pouvez enlever le support pour d'autres paquetages ainsi :
@command{--without-history}, @command{--without-fontconfig}
@item
L'interface du shell peut elle aussi être retirée en utilisant 
l'option: @command{--disable-frontend-shell-driver}
@end itemize


@node Utiliser adesklets

@chapter Utiliser adesklets

@ifplaintext 
INSTALL_END
@end ifplaintext

@section ... Comme un conteneur de desklets

Par lui-même, adesklets fait peu: il ne fournit que le nécessaire pour
faire plus ! Vous aurez besoin soit de lui dire quoi faire en
lui envoyant des commandes (voir la section suivante) soit d'utiliser d'autres scripts
(les desklets) qui le piloteront pour vous.

@noindent Aujourd'hui, de nombreux desklets existent: vous pouvez les 
trouver sur le site Internet d'adesklets en tant que téléchargements 
séparés: @weblink{http://adesklets.sf.net/desklets.html}.

@subsection Ajouter un nouveau desklet à votre affichage X
Pour ajouter un nouveau script de desklet, il suffit simplement de:

@enumerate
@item
Télécharger sa tarball et la désarchiver quelque part dans votre répertoire
personnel
@item
Lire le fichier README; les pré-requis ou instructions spécifiques y seront
donnés. Habituellement, vous n'aurez besoin que d'une installation
d'adesklets et d'un serveur X lancé, puis de lancer le script exécutable à
partir de votre répertoire de base.
@end enumerate

Depuis adesklets 0.4.11, les desklets en Python vous demanderont explicitement 
si vous voulez les enregistrer ou les tester. Ils supporteront également 
l'option @command{--help}, que vous pouvez utiliser pour savoir quelles sont 
les options que vous pouvez passer à l'interpréteur d'adesklets pendant des tests 
(détection de fausse fenêtre racine, etc.).

@noindent Notez bien que :

@itemize
@item
Lancer le même script plusieurs fois va en créer plusieurs instances.
@item
Sur les ordinateurs disposant de plusieurs écrans, les scripts seront affichés
sur leur écran hérité par défaut (par exemple, si vous ne faites rien
de spécial, appeler un script à partir d'un xterm sur l'écran 1 lancera le
desklet sur l'écran 1).
@end itemize

@noindent La plupart du temps, les scripts de desklets sont faits
pour fonctionner tant que vous ne leur dites pas de
s'arrêter. L'utilisateur a un contrôle total sur le démarrage, l'arrêt,
le redémarrage (quand c'est possible) et le positionnement du desklet, 
qui n'a aucun contrôle sur ces opérations.

@noindent Les quelques réglages de l'utilisateur sont stockés dans le fichier
@file{$HOME/.adesklets} de votre répertoire personnel. Habituellement, vous
n'avez pas à éditer ce fichier vous-même. Si vous le faites, assurez-vous
qu'aucune instance d'@command{adesklets} ne s'exécute en même temps.

@unnumberedsubsubsec Note concernant les polices du système

@emph{Vous pouvez sans problème passer cette partie si vous ne comptez pas 
utiliser des polices non fournies avec adeklets.}

Toutes les polices TrueType présentes sur votre système peuvent être utilisées 
avec adesklets, pourvu que votre système supporte fontconfig 
(@weblink{http://www.fontconfig.org/}) et qu'adesklets ait été compilé sans l'option
@code{--without-fontconfig} (par défaut il est compilé avec le support de 
fontconfig; @xref{Installer adesklets}.). Lors de son initialisation, 
un adesklets compilé avec fontconfig va parcourir toutes les polices 
détectées sur votre système pour identifier toutes les polices TrueType. 
Lisez la documentation de fontconfig pour savoir comment configurer 
correctement l'accès aux polices de vos logiciels 
(@xref{Foire Aux Questions}, pour quelques conseils sur le 
débogage de fontconfig). Il est aussi bon de savoir que le paquetage d'adesklets 
contient une copie de la police Bitstream's Vera; tous les utilisateurs peuvent 
donc s'attendre à ce qu'@command{adesklets} dispose toujours de cette police, 
au minimum.

@unnumberedsubsubsec Notes concernant l'internationalisation

@emph{Vous pouvez sans problème passer cette partie si vous n'envisagez pas 
d'utiliser des caractères étendus dans vos desklets.}

Si votre système supporte @command{iconv} (@xref{Installer adesklets}.), 
vous devriez pouvoir utiliser n'importe quel caractère de n'importe quel
jeu de caractères que votre système connait pour afficher du texte, que ce 
soit dans un desklet ou dans ses menus, pourvu que vous ayez les polices 
TrueType appropriées (c'est à dire des polices TrueType incluant la 
représentation de ces caractères)@footnote{Par exemple, la police 
Bitstream's Vera fournie avec @command{adesklets} contient des symboles 
pour pratiquement tous les caractères du jeu Latin-1.}.

En tout cas, en utilisant des caractères étendus (en dehors des 7 bits 
@code{ASCII}), assurez-vous que les paramètres locaux de GNU readline 
n'interfèrent pas. Ces trois paramètres devraient être configurés comme 
indiqué ci-dessous dans le fichier @file{initrc} approprié
@footnote{Veillez vous réferer à la documentation de GNU readline}:

@example
set input-meta on
set convert-meta off
output-meta on
@end example

Si vous ne voulez pas adapter vos paramètres de GNU readline, vous pouvez 
aussi utiliser l'option @code{--enable-force-extended-characters-input} du 
script @code{configure} lors de la configuration du paquetage à partir des 
sources, ainsi l'interpreteur outrepassera en interne ces trois variables 
dès qu'il le faudra.

Bien sur, vous aurez besoin de desklets utilisant ces caractères étendus. 
Au moment d'écrire ces lignes, tous les desklets en Python ne provenant pas 
de contributions les utilisent; pour ceux-là l'utilisateur peut choisir 
quel jeu de caractères utiliser en le précisant dans le fichier de 
configuration, quand il existe@footnote{si'l n'existe pas, cela signifie 
que de toute façon le desklet n'a pas besoin d'internationalisation}; 
l'utilisateur doit simplement définir correctement la ligne 'coding'
@footnote{Pour plus de détails consultez @weblink{http://python.fyxm.net/peps/pep-0263.html}.}.

Par exemple, pour utiliser les caractères ISO Latin-1, on utilisera 
quelquechose comme:

@example
# -*- coding: ISO-8859-1 -*-
@end example

à la première ou deuxième ligne du fichier de configuration d'un desklet 
en Python@footnote{Evidemment, ce fichier de configuration devra être 
enregistré en utilisant l'encodage ISO Latin-1 ou n'importe lequel de 
ses dérivés, comme l'@code{ASCII}.}.

Enfin, veillez noter que si votre plate-forme ne supporte pas iconv, 
vous devrez toujours laisser @code{ASCII} comme paramètre d'encodage, 
autrement les desklets vous renverront des erreurs fatales comme 
@code{charset conversion not compiled in}. 

@subsection Restaurer les desklets précédents sur une nouvelle session X
Invoquer @command{adesklets} sans arguments@footnote{Attention: par défaut 
depuis adesklets 0.4.11 vous @emph{devez} ajouter certaines options si 
votre gestionnaire de fenêtres utilise une fausse fenêtre racine. 
@xref{Foire Aux Questions}.}:
@example
adesklets
@end example

@noindent est suffisant pour redémarrer tous les desklets qui tournaient la
dernière fois que vous avez tué le serveur X (dans ce mode, @command{adesklets}
terminera rapidement par lui-même : il n'y a pas besoin de le lancer en
arrière-plan. adesklets n'utilise pas de démon : chaque applet créé un
interpréteur @command{adesklets} indépendant comme processus fils). 
Invoquer @command{adesklets} quand des desklets sont déjà 
lancés forcera leur arrêt avant leur redémarrage
@footnote{Les instances d'@command{adesklets} et leurs parents immédiats 
recevront alors un signal SIGKILL.}.

@noindent Si vous pensez utiliser des desklets régulièrement, vous
devriez mettre la commande @code{adesklets} quelque part dans
l'initialisation de votre session X. Je ne peux pas dire où avec précision,
puisque cela varie énormément d'un système à l'autre. Cherchez sur :
@weblink{http://www.google.com/search?q=''x window''+startup} pour une
aide générale.

Depuis adesklets 0.4.11, une interface plus complète basée sur le shell 
est à votre disposition si vous l'avez installée (ce qui se fait par 
défaut). Elle fournit un ensemble plus fonctionel d'options. Lancez 

@example
adesklets --help
@end example

Pour voir ce que vous avez au bout des doigts. Notez bien que depuis 
adesklets 0.4.11, si vous avez besoin de la détection de fausse fenêtre racine 
vous @strong{devez} normalement activer les options correctes en ligne 
de commande (@xref{Foire Aux Questions}.).

@section ... Comme un éditeur graphique en ligne de commande

Vous pouvez aussi utiliser adesklets comme un éditeur graphique en ligne de
commande. Si vous tapez dans une console:

@example
adesklets :
@end example

@noindent Vous obtiendrez quelque chose ressemblant à ceci :

@anchor{prompt}
@example
adesklets 0.1.0 (Fri Jan 28 19:09:13 EST 2005), on Linux 2.6.10
[gcc 3.4.3 20041125 (Gentoo Linux 3.4.3-r1, ssp-3.4.3-0, pie-8.7.7)]
Press TAB for hints.
0 >>> _
@end example

@noindent La dernière ligne est une invite. Elle vous dit que vous êtes prêt
à entrer la commande numéro 0. Dans adesklets @value{VERSION}, vous avez
environ 150 commandes à portée de main. Grâce à GNU readline, de nombreuses 
routines d'auto-complétion sont présentes, ce qui vous permet d'explorer 
facilement. Appuyez sur TAB pendant que vous entrez le nom d'une commande 
ou le premier argument d'une commande, et des informations utiles seront 
affichées. @xref{premiers pas,,une introduction à adesklets}, pour plus d'informations.

@node Programmation d'adesklets
@chapter Programmation d'adesklets
@section Une introduction à adesklets
@anchor{premiers pas}

Comme expliqué ci-dessus (@xref{A propos d'adesklets}.), adesklets est
principalement une console interactive d'Imlib2, avec une ou deux fonctions
supplémentaires:

@itemize
@item
Quand un affichage X est présent, la gestion automatique d'une 
fenêtre simple.
@item
Support automatique de la pseudo-transparence
@item
Gestion d'applets persistants entre sessions
@end itemize

@noindent Commençons une session interactive typique pour voir ce qui se
passe. Sous X, ouvrez un terminal et tapez:

@example
adesklets :
@end example

@noindent Comme dans la section précédente (@xref{prompt,, 'Utilisation
d'adesklets comme un éditeur graphique en ligne de commande' }.), vous obtenez
une invite. Maintenant entrez la commande '@code{images_info}'. Vous devriez
obtenir sur la sortie standard :

@example
2 images
id 0 width 1 height 1 alpha 1 filename (null)
id 1 width 1 height 1 alpha 1 filename (null)
command 0 ok: images_info
@end example

@noindent Cela signifie que vous avez deux images : l'image 0 et l'image 1,
et qu'elles ont une taille de 1x1 pixel. Ce sont les seules images que
vous ne pourrez jamais détruire ou modifier (redimensionner indépendamment, 
retourner diagonalement, etc.) comme vous le souhaitez. Qu'est-ce que c'est 
que cela?

@itemize
@item
Image 0 est l'image d'avant-plan. Par défaut, c'est la seule image qui
est affichée dans une fenêtre simple gérée par @command{adesklets}.
@item
Image 1 est l'image d'arrière-plan. Par défaut, elle contient toujours le
contenu de la fenêtre racine (le bureau) qui est sous cette fenêtre. Sans
modification de notre part, elle est toujours mise à jour lorsque l'utilisateur
la déplace, la redimensionne, lorsque le fond d'écran change, etc.
@end itemize

@noindent Mais où est cette fenêtre? Eh bien, pour l'instant, ce sont seulement des
images de 1x1 pixel, et elles ne sont pas affichées@footnote{"Mappé" dans le 
jargon d'X Window} à l'écran. Ainsi, redimensionnons les à 100x100 pixels:
tapez '@code{window_resize 100 100}'. Maintenant, si vous retapez la commande
'@code{images_info}', vous obtiendrez:
@example
2 images
id 0 width 100 height 100 alpha 1 filename (null)
id 1 width 100 height 100 alpha 1 filename (null)
command 2 ok: images_info
@end example

@noindent Vous voyez? Les images d'avant-plan et d'arrière-plan ont été
redimensionées à 100x100 pixels: de plus l'arrière-plan a été mis à jour
pour contenir la nouvelle image de fond. Maintenant, rendons cette fenêtre
visible. Tapez les deux commandes: '@code{window_reset managed}' et enfin
'@code{window_show}'.

@noindent La première commande demande à adesklets de laisser votre
gestionnaire de fenêtres "gérer" votre fenêtre (ce qui n'est pas fait par défaut): 
cela signifie que la fenêtre va être décorée, et que  vous pourrez changer sa
visibilité@footnote{Une fenêtre "non-gérée" est très utile pour les desklets: 
c'est comme si c'était une partie de la fenêtre racine puisqu'elle peut
être faite pour ne jamais être en avant-plan et pour rester affichée (mapped) 
lorsque l'on change d'espace de travail.} de façon interactive. La seconde
montre votre fenêtre de 100x100. Rien d'impressionnant: un carré noir de
100x100 avec une barre de titre et des bordures fixes.

@noindent Comme dit plus haut, seule l'image 0 (l'avant-plan) est affichée par
défaut. Maintenant, tapons : '@code{window_set_transparency 1}'. Wouah! Nous
voyons la fenêtre racine du dessous! Avec "window transparency"
activé, l'image 1 (arrière-plan) est d'abord copiée dans la fenêtre, puis
l'image 0 (avant-plan) qui est entièrement noire et transparente, est mise
par-dessus@footnote{Enfin... Pas tout à fait : il y a un buffer qui intervient 
pour la performance, mais l'opération est logiquement équivalente à
cette description.}.

@noindent Il est temps de parler des couleurs: souvenez-vous, adesklets
est une console d'Imlib2. Par conséquent, comme Imlib2@footnote{Gardez
votre documentation d'Imlib2 à proximité: c'est très utile!
@xref{Documentation d'Imlib2}.}, les couleurs sont toujours de
véritables couleurs 32 bits codées en RVBA - huit bits par canal (de 0 à
255), incluant un canal alpha pour la transparence. La conversion de palette se
fera  automatiquement si la définition de votre écran est inférieure, vous
n'avez pas à vous en occuper. Si vous tapez: '@code{context_get_color}',
vous obtiendrez:

@example
command 0 ok: context color 255 255 255 255
@end example

@noindent Imlib2 est une sorte de machine par états; en tant que tel, il utilise un 
"contexte" qui garde en mémoire une série d'attributs qui seront utilisés dans
ses opérations futures. Par exemple, nous savons maintenant que la couleur
qui sera utilisée, aussi longtemps que nous ne la modifions pas, sera un
blanc opaque (rouge=255, bleu=255, vert=255, alpha=255). Si nous tapons:
'@code{context_get_image}', il retourne:
@example
command 0 ok: context image 0
@end example

@noindent Cela signifie que toute opération que nous effectuons sur une fenêtre
sera faite directement sur l'image d'avant-plan. Dessinons un rectangle plein
semi-transparent de couleur magenta sur l'avant-plan. Les commandes seront:
'@code{context_set_color 255 0 0 200}' et '@code{image_fill_rectangle 25 25
50 50}'. Élégant, n'est-ce pas?

@noindent Si vous avez l'habitude de programmer avec Imlib2, vous avez 
du remarquer que ces dernières commandes ont l'air familières. C'est
assez normal; la plupart des fonctions C d'Imlib2 sont présentées de
la même façon dans les 'commandes' d'adesklets. Ainsi, la commande
d'adesklets  '@code{image_fill_rectangle}' suit la même sémantique que
la fonction '@code{imlib_image_fill_rectangle()}' d'Imlib2, la commande
'@code{context_set_color}' suit celle de la fonction '@code{imlib_context_set_color()}',
etc. Les deux seules différences significatives (et systématiques) sont premièrement que
partout où vous utiliserez un objet '@code{Imlib_Quelquechose}' en C, vous
utiliserez un ID entier avec adesklets, et deuxièmement dans la sémantique des fonctions
'@code{imlib_free_Quelquechose()}' où on doit préciser l'ID de l'objet 
auquel s'applique la fonction au 
lieu de libérer l'objet de ce type sélectionné dans le contexte.

@noindent Tout ceci est facile à illustrer. Chargeons la police "Vera" 
incluse dans adesklets à la taille 20pt, mettons la en police par défaut 
et écrivons 'Hello' en blanc opaque en diagonale sur l'image d'avant-plan 
en partant du coin en haut à gauche, avant de décharger la police. 
Cela devrait ressembler à:

@example
6 >>> load_font Vera/20
command 6 ok: new font 0
7 >>> context_set_font 0
command 7 ok: context_set_font 0
8 >>> context_set_direction text_to_angle
command 8 ok: context_set_direction text_to_angle
9 >>> context_set_angle 45
command 9 ok: context_set_angle 45
10 >>> context_set_color 255 255 255 255
command 10 ok: context_set_color 255 255 255 255
11 >>> text_draw 0 0 Hello
command 11 ok: text_draw 0 0 Hello
12 >>> free_font 0
command 12 ok: free_font 0
@end example

@noindent Si vous regardez votre documentation d'Imlib2, vous remarquerez
immédiatement les deux différences que l'on vient d'évoquer: toutes les
références à la police Vera/20 sont faites par un ID entier (0 ici), et
la commande '@code{free_font}', contrairement à la fonction correspondante
'@code{imlib_free_font()}', est appliquée à la police dont l'ID est donné en 
argument plutôt qu'à la police du contexte.

@noindent A partir de là, imaginons que vous voulez sauvegarder l'image résultante; 
aucun problème! Tapez: '@code{save_image out.png}', et
l'avant-plan sera sauvé dans un fichier "out.png" dans le répertoire 
courant@footnote{Pour que ça marche, il faut que votre installation d'Imlib2 
soit correctement configurée pour utiliser libpng, sinon vous
risquez de recevoir l'erreur "no loader for file format".}. Maintenant,
juste pour le plaisir, quittons adesklets, et lançons une autre session
interactive pour voir si nous pouvons recharger cette image. Tapez juste
la commande "@code{quit}" ou pressez ^D (Control D: fin de fichier), votre
nouvelle session devrait ressembler à ceci :

@example
0 >>> window_resize 100 100
command 0 ok: window_resize 100 100
1 >>> window_reset managed
command 1 ok: window_reset managed
2 >>> window_set_transparency 1
command 2 ok: window_set_transparency 1
3 >>> load_image out.png
command 3 ok: new image 2
4 >>> blend_image_onto_image 2 1 0 0 100 100 0 0 100 100
command 4 ok: blend_image_onto_image 2 1 0 0 100 100 0 0 100 100
5 >>> window_show
command 5 ok: window_show
6 >>> free_image 2
command 6 ok: free_image 2
@end example

@noindent Bien sur, nous voulions visualiser le résultat - c'est
pourquoi nous avons utilisé les commandes '@code{window_reset}',
'@code{window_set_transparency}' et '@code{window_show}': elles n'ont
pas d'autre utilité. La commande '@code{blend_image_onto_image}' vient elle 
aussi tout droit d'Imlib2; elle prend la nouvelle image 2 que l'on vient de
créer avec la troisième commande, et la met dans l'image du contexte 
(image 0 - avant-plan par défaut), à partir de ses coordonnées (0,0) et 
d'une taille de 100x100 pixels, et la met dans un rectangle partant de (0,0)
et de taille 100x100 pixels dans l'image 0. Il est finalement bon de noter
que, avec adesklets, il y a toujours une image dans le contexte d'Imlib2:
dès que vous essayez de libérer l'image courante, le contexte d'image est
réinitialisé à l'image d'avant-plan.

@noindent Voila, c'est presque la fin de cette introduction... A partir de
là vous devriez pouvoir jouer un peu avec adesklets. Si vous êtes déjà 
familier avec Imlib2 vous vous y ferez très rapidement. Sinon vous devriez 
garder la documentation d'Imlib2 sous la main. :-)

@noindent Quelques dernières astuces:

@itemize
@item
Si vous êtes fatigué de taper encore et encore, n'oubliez pas 
l'auto-complétion: 'TAB your problems away!'
@item
Si vous avez besoin d'aide sur quoi que ce soit, il existe
la commande '@code{help}'.
@item
Si vous exécutez une série de commandes, que ça ne marche pas et que tout
cet usage interactif vous fatigue:
@enumerate
@item
Utilisez la commande '@code{history}' pour enregistrer votre session courante
dans un fichier@footnote{Pour que ça marche, GNU
history doit être installé lors de la compilation d'adesklets.}.
@item
Utilisez l'option '-f' avec adesklets pour passer les commandes à partir
d'un fichier plutôt que de la console tty.
@item
Si vous essayez de visualiser quelque chose, insérez une commande
'@code{pause}' à la fin du script pour geler l'interpréteur.
@item
Tous les caractères après un dièse '#' jusqu'à la fin de la
ligne seront ignorés, ce qui vous permet d'écrire des commentaires.
@end enumerate
@end itemize

@noindent Voici un exemple:

@example
#!/usr/bin/env adesklets -f

# Rendre la fenêtre 'gérée'
#
window_reset managed

# Redimmensioner la fenêtre à 100x100 pixels
#
window_resize 100 100

# Montrer la fenêtre, puis la geler pendant 10 secondes avant de sortir
#
window_show
pause 10
@end example

@noindent Vous aurez juste besoin de rendre ce script exécutable et de le
lancer. Comme d'habitude, les résultats seront affichées sur la sortie standard.

@section Véritable programmation avec adesklets: écriture d'un script de desklet

Lorsque vous serez prêt pour un vrai travail@footnote{:-)}, vous voudrez 
surement utiliser un véritable langage de script plutôt que l'interpréteur 
rudimentaire d'@command{adesklets} que nous avons utilisé dans l'introduction;
ne serait-ce que pour pouvoir utiliser des variables.

Au moment où j'écris ces lignes (@value{UPDATED}), le support pour
Python est inclus@footnote{adesklets a été écrit pour être facilement 
utilisé depuis toutes sortes de langages interprétés; n'hésitez pas à proposer 
votre aide si vous voulez que votre langage favori soit supporté!}.

@subsection Quelques astuces pour les programmeurs

Une fonction très utile de l'interpréteur d'@command{adesklets} est sa 
capacité à produire un trace complète d'une de ses sessions (commandes, 
évènements et messages spéciaux), que ce soit sur @code{stderr} ou dans 
un fichier journal, et ce indépendemment de ce qui le contrôle. Pour se 
servir de cette fonctionalité, il faut:

@enumerate
@item Configurer le paquetage au niveau des sources en activant la trappe 
@code{--enable-debug} de @code{configure}.
@item Exporter la variable @code{ADESKLETS_LOG} dans l'environnement si la 
sortie de la session doit être enregistrée dans un fichier plutôt qu'affichée 
sur @code{stderr}@footnote{L'afficher sur @code{stderr} risque fortement de 
perturber les liens avec les langages externes, il est donc préferable de ne 
le faire que lors d'une invocation de l'interpréteur directement sur la 
console.}. Ce doit être un chemin absolu qui servira de préfixe à 
l'interpréteur qui, l'ayant hérité de l'environnement, s'en servira pour créer 
les noms complets des fichiers dans lesquels il écrira.
@end enumerate
A partir de là, il est possible de lire des journaux de session complets et 
chronologiques; utilisés correctement, ils peuvent être utiles pour débugger. 
Vous pouvez vous en servir conjointement avec la commande @code{echo} pour 
placer des marqueurs faciles à trouver.

@subsection adesklets et Python
@unnumberedsubsubsec Un exemple d'utilisation de Python
Avec Python, les choses ne sont pas très différentes de l'interpréteur. 
Les commandes ont été encapsulées dans des fonctions Python, et une classe 
publique @code{Events_handler} a été construite pour manipuler les retours 
asynchrones de l'interpréteur. Jetons un coup d'oeil sur le script 
@file{test/test.py} de l'archive source de la version @value{VERSION}:

@verbatiminclude ../test/test_fr.py

Voilà! 26 lignes de code Python, et nous avons un desklet parfaitement
fonctionnel. Je pense qu'il s'explique de lui-même; jetez un coup d'oeil à
l'aide intégrée de python à propos de @code{adesklets}, @code{adesklets.functions}
et @code{adesklets.Events_handler} pour de bonnes et complètes explications
@ifhtml
(@xref{Documentation du paquetage Python}.)
@end ifhtml
. Tout ce que nous avons fait ici c'est:

@enumerate
@item
Importer le paquetage @code{adesklets}: cela instancie automatiquement un
processus fils @command{adesklets} et configure toutes les communications. 
Si l'initialisation du paquetage termine sans provoquer d'exception, cela signifie
que l'interpréteur tourne et qu'il attend des commandes.
@item
Faire une sous-classe d'@code{adesklets.Events_handler} et redéfinir les
méthodes invoquées pour les événements qui nous intéressent (tous les autres
événements ne sont pas simplement ignorés, ils ne sont pas générés).
@item
Instancier un objet de cette classe, et le mettre en boucle infinie
@footnote{Cette dernière étape n'est pas obligatoire; le script peut
très bien continuer, mais devra alors avoir été écrit pour supporter les 
interruptions des signaux. Lisez `@code{help(adesklets.Events_handler)}' pour de
plus amples informations.}.
@end enumerate

@unnumberedsubsubsec Attention, piège: quelques détails sur les ID d'objets

Tous les objets d'adesklets (polices, images, palettes de couleurs, polygones, etc), 
sont stockés dans des piles (une pile par type d'objet). Les ID de Python ne sont 
rien d'autre que la position initale d'objets donnés dans la pile correspondante, 
et deviendront donc invalides si un objet du même type situé en-dessous est 
libéré.

Par exemple, partant d'un état vierge, il n'y a d'autre dans la pile des images 
que l'avant-plan (ID O) et l'arrière-plan (ID 1) de la fenêtre. Lorsque 
quelqu'un créé deux autres images depuis Python comme ceci:
@example
im_1 = adesklets.create_image(10,10)
im_2 = adesklets.create_image(10,10)
@end example
@noindent on a @code{im_1==2}, et @code{im_2==3}. Dès qu'on fera:
@example
adesklets.free_image(im_1)
@end example
@noindent La pile commence à s'écraser, et ce qui était l'image 3 (@code{im_2}) 
est maintenant l'image 2, et @code{im_2} est une réference invalide. Cela 
signifie clairement qu'invoquer:
@example
adesklets.free_image(im2)
@end example
@noindent génerera le message d'erreur @code{image out of range}.

@unnumberedsubsubsec Un sujet spécial: les animations

@command{adesklets} inclut maintenant aussi bien un mode d'exécution indirect 
que les variables textuelles (pour être précis, le remplacement textuel 
non-récursif). Cela signifie que les auteurs de desklets ont ce qu'il faut 
pour créer des animations précisément temporisées. Vous trouverez un exemple 
simple à suivre dans @file{test/fading.py}. Une utilisation 
plus poussée de ces fonctionalités est faite dans le desklet @code{yab}. Pour 
réaliser un animation en Python, il faut:

@enumerate
@item @strong{Enregistrer} une séquence de commandes (que nous appelerons une 
commande macro, ou macro). Avec Python, il faut passer en mode 
indirect avec la fonction @code{adesklets.start_recording()}, émettre un 
nombre indéterminé de commandes @command{adesklets}, puis repasser en mode 
normal (execution directe) avec @code{adesklets.stop_recording()}. Bien sur, 
aucune commande n'est évaluée quand l'interpréteur est en mode indirect; les 
commandes sont seulement conservées dans l'historique pour être rejouées plus 
tard. 
@item @strong{Choisir} si la séquence de commandes à rejouer peut être 
interrompue par des évènements ou pas, en utilisant la fonction 
@code{adesklets.play_set_abort_on_events()}. La méthode de haut niveau 
@code{adesklets.Events_handler::set_events()} peut aussi être utilisée pour 
choisir dynamiquement quels évènements seront rattrapés. Pour un exemple, 
voyez @file{test/test_events.py}.
@item @strong{Initialiser} les variables utilisées dans la macro 
enregistrée avec la fonction @code{adesklets.set()}, qui est très similaire 
à son homonyme du shell Bourne.
@item @strong{Lire} la macro avec la fonction @code{adesklets.play()}.
@end enumerate

Quelques remarques supplémentaires:
@itemize
@item Une temporisation précise de la séquence peut être faite par la 
commande @code{time_gate}. Elle fonctionne très simplement: à chaque 
fois qu'une macro est exécutée, adesklets enregistre à quel moment 
elle à commencé. Dès qu'une commande @code{time_gate} apparait lors 
de l'exécution, le programme attend que le nombre de secondes données 
en argument à @code{time_gate} soient écoulées. Par exemple, écrire 
@code{time_gate 0.1} dans une macro empêchera l'execution de toutes les 
commandes suivantes de la macro tant que celle-ci n'aura pas fonctionné 
pendant au moins un dixième de seconde.
@item La substitution des variables à toujours lieu juste avant l'exécution 
des commandes, indépendemment du mode d'execution (direct ou indirect). 
Toute séquence de caractères ne contenant pas d'espace précedée directement 
par un seul '$' sera remplacée par le contenu de la variable correspondante 
(configuré précedemment avec @code{set}). Si aucune variable ne correspond, 
la séquence est simplement ignorée.
@item Toutes les macros exécutées par la commande @code{play} sont, du point de 
vue du desklet qui les contrôle, élémentaires, comme toutes les autres commandes. 
En un mot, cela signifie qu'aucun évènement ne sera jamais géneré pendant 
qu'une macro est exécutée; ils apparaitront tous juste après que la commande 
@code{play} ait terminé. 
@item Comme d'habitude, l'interpréteur d'adesklets fonctionne par états pour 
les variables et les états liés au mode indirect. Vous n'avez pas à fixer le 
drapeau @code{set_abort_on_events} ou les variables à chaque fois que vous 
appelez une macro, sauf si quelquechose doit être changé depuis l'appel 
précedent.
@item La fonction de haut niveau @code{adesklets.Events_handler::set_events()} 
sert principalement à arrêter la prise en charge de certains évenements pendant 
l'exécution de la macro, ainsi la macro ne peut être interrompue que dans des 
circonstances bien précises. Bien sur, tous les évènements génerés avant l'appel 
à cette méthode ne seront pas perdus mais placés en file d'attente, et les 
méthodes d'évènements appropriées seront appelées plus tard, pourvu que les 
trappes soient en place lorsque l'exécution de la macro est terminée.
@item Avons-nous rappelé que faire tout cela depuis un endroit non protégé est 
une mauvaise idée? Eh bien, ça l'est. N'oubliez pas d'utiliser 
@code{adesklets.Events_handler::block()} et @code{adesklets.Events_handler::unblock()} 
autour de tout code relatif à une animation si vous avez instancié un objet 
d'une classe fille de @code{adesklets.Events_handler}.
@end itemize

@unnumberedsubsubsec Configuration et internationalisation

Mentionnons jute ici que depuis @command{adesklets} 0.4.0, le module 
@code{adesklets.utils} inclut maintenant une classe optionelle 
@code{ConfigFile} qui peut être facilement réutilisée par les auteurs de 
desklets pour ajouter un système de configuration facilement extensible à 
leur code@footnote{Pour en voir un exemple voyez n'importe quel desklet 
non issu de contributions.}
@ifhtml
(@xref{Documentation du paquetage Python}.)
@end ifhtml
. Par défaut, la classe prend aussi en charge l'internationalisation 
automatiquement, en sélectionnant les jeux de caractères selon les 
besoins de l'utilisateur. L'utilisation des jeux peut bien sûr être 
déterminée ou changée à tout moment en utilisant les fonctions 
@code{adesklets.get_charset()} et @code{adesklets.set_charset()}. La 
classe @code{adesklets.utils.ConfigFile} a aussi un attribut @code{charset} 
qu'on peut examiner pour connaitre les préferences de l'utilisateur. En 
utilisant cette classe on notera que le jeu de caractères 'ASCII' est 
considéré comme choix par défaut, et qu'il ne désactivera pas une éventuelle conversion.
Ainsi, les utilisateurs de plate-formes ne supportant pas iconv pourront 
toujours utiliser @command{adesklets} sans le support de l'internationalisation. 

@unnumberedsubsubsec Derniers mots

@noindent Enfin, signalons que vous pourriez avoir envie de jeter un oeil au 
code source du desklet @file{weather} disponible sur 
@weblink2{le site web du projet SourceForge,http://sourceforge.net/projects/adesklets/} pour 
voir un plus gros morceau de code Python utilisant adesklets. Il y a aussi 
quelques autres desklets de test sous le répertoire @file{test/} qui pourraient 
vous donner des idées.
@ifhtml
Vous pourriez aussi jeter un oeil au paquetage d'aide autogéneré d'@command{adesklets} 
par pydoc, inclus dans ce document (@xref{Documentation du paquetage Python}.). Dès 
que vous êtes suffisement content de votre desklet, n'hésitez pas à le partager avec 
le reste d'entre nous (ce qui serait très apprécié). Faites-en un paquetage 
(@xref{GNU Makefile pour empaqueter les desklets}.), puis soumettez-le 
(@xref{Soumettre un desklet}.).
@end ifhtml

@node Extension d'adesklets
@chapter Utiliser adesklets à partir d'autres languages

adeskets a été fait pour être facilement utilisable depuis toutes sortes 
d'environnements de langages@footnote{On parle d'environnement de langage 
parceque le problème n'est pas la syntaxe ou le paradigme utilisé 
(qu'il soit impératif, fonctionnel ou n'importe quoi d'autre), mais la 
manière dont vous pouvez gérer des opérations de base de POSIX sur les 
fichiers, les signaux, etc. (@xref{Fonctionalités requises}.). Ainsi 
un programmeur Perl 5 devrait utiliser adesklets facilement, alors qu'un 
programmeur Linux JDK devrait probablement recontrer plus de difficultés 
(sans vouloir critiquer).}. Ce chapitre explique aux développeurs comment 
l'interpréteur d'adesklets s'intègre dans le système d'une manière 
indépendante du langage.

@noindent Si vous n'êtes pas un minimum habitués aux systèmes POSIX ou que 
vous n'avez pas les notions de base sur la programmation de systèmes 
d'exploitations, ce chapitre n'est surement pas d'un grand interêt pour 
vous.

@noindent Veillez noter que le paquetage Python du répertoire 
@file{scripting/pyhton/adesklets} est un bon complément de ce que vous 
allez lire.

@section Fonctionalités requises
@anchor{Fonctionalités requises}
Si vous voulez utiliser l'interpréteur d'adesklets depuis votre langage 
favori mais qu'il n'est pas supporté à la base@footnote{Pour adesklets 
@value{VERSION}, seul Python est supporté à la base.}, vous pouvez 
toujours ajouter ce support, pourvu que votre langage comporte une 
de ces fonctionalités:

@itemize
@item Lire et écrire dans des tuyaux (pipes); ou
@item Lire et écrire depuis ou dans des fichiers sans mémoire tampon ('unbuffered files')
@end itemize

@noindent Il doit aussi pouvoir@footnote{Ceci dit, 
disposer du support d'IPC et de poll/select rendra les choses à la fois plus 
simples et plus claires. Il est aussi très utile de pouvoir bloquer des signaux.}:

@itemize
@item Rattraper des signaux IPC; ou
@item Lire des fichiers en mode non-bloquant; ou
@item Utiliser poll/select sur des fichiers
@end itemize

@noindent Enfin, il doit aussi être capable de lancer un processus fils.

@noindent Ces pré-requis sont bien minces du point de vue d'un système 
POSIX, mais précisons par souci d'exhaustivité que si votre 
environnement de langage ne remplit pas ces critères, vous pouvez quand 
même vous en servir pourvu que vous arriviez à faire en sorte que votre 
application communique de manière fiable avec un autre programme
@footnote{Qui serait en fait une interface.} qui, lui, les remplirait. 
Bien sur, ce n'est pas la situation idéale et cela doit être évité 
autant que possible.

@section Mécanisme d'initialisation

Comme vous le savez probablement (@xref{Utiliser adesklets}.), 
@command{adesklets} possède deux modes de fonctionnement, si l'on 
peut les appeler ainsi:

@enumerate
@item en tant que lanceur de desklets, si vous appelez @command{adesklets} 
sans arguments.
@item en tant qu'interpréteur, dans tous les autres cas (utilisation en 
ligne de commande intéractive ou en processus fils d'un desklet).
@end enumerate

@subsection adeskelts appelé comme un lanceur de desklets - redémarrer tous les desklets
@noindent Dans une nouvelle session X, la séquence de démarrage classique est 
à peu près la suivante:

@enumerate
@item @command{adesklets} est appelé sans arguments à partir d'un script 
d'initialisation de la session X.
@item A partir de là, la nouvelle instance d'adesklets se comporte comme 
un lanceur de desklets. Elle parcoure le fichier @file{$HOME/.adesklets}, 
puis se copie (fork) autant de fois qu'il y a de desklets à démarrer. Ensuite 
le processus lanceur termine puisqu'il n'y a pas besoin de démon ici.
@item Tous les processus copiés initialisent la variable d'environnement 
@code{ADESKLETS_ID} contenant leur propre ID entier en tant que chaine de 
caractères, puis exécutent@footnote{Avec un appel de la famille execve*; 
voir @code{man 2 execve}.} le script associé.
@item Chaque desklet se lance une instance d'@command{adesklets} en tant 
que processus fils, donnant en passant la variable @code{ADESKLETS_ID} 
sans l'alterer. Il est du devoir du desklet de s'assurer que:
@itemize
@item Les flux standards de l'interpréteur d'adesklets, @code{stdin}, 
@code{stdout} et @code{stderr}, soient redirigés séparément, de sorte que 
le processus parent puisse facilement écrire dans le @code{stdin} 
d'adesklets, et lire @code{stdout} et @code{stderr}. L'utilisation de 
tuyaux, FIFOs ou éventuellement de fichiers réguliers sont possibles.
@item les écritures vers @code{stdin} et les lectures depuis les deux 
autres flux se font toutes sans tampon.
@item le premier argument de la commande @command{adesklets} est le nom 
absolu du script du desklet.
@end itemize
@item Chaque interpréteur @command{adesklets} nouvellement créé s'initialise 
en utilisant la variable d'environnement @code{ADESKLETS_ID} et le nom 
absolu donné en premier argument de ligne de commande pour déterminer 
ses caracteristiques non-scriptables@footnote{Qui sont, nominativement, 
son écran et ses coordonnées.} à partir de @file{$HOME/.adesklets}. 
Une fois cette opération terminée, l'évènement @code{ready!} est 
géneré (@xref{Evènements}.), l'interpréteur est alors prêt à 
traiter des commandes.
@end enumerate

@subsection adesklets appelé en tant qu'interpréteur - enregistrement d'un nouveau desklet

Quand un nouveau desklet est appelé directement, la séquence de démarrage 
décrite dans la section précedente est la même, sauf que les trois 
premières étapes n'ont tout simplement pas lieu. Cela signifie que 
l'environnement @code{ADESKLETS_ID} n'est pas défini; cela permet 
au nouvel interpréteur d'@command{adesklets} de détecter qu'il 
s'agit d'un nouveau desklet, il va parcourir le fichier de configuration 
@file{$HOME/.adesklets} et allouer au desklet le premier ID disponible. 

@noindent Il faut noter que si le nom de fichier du desklet donné comme 
premier argument à l'instance fille d'@command{adesklets} est relatif ou 
si'l n'est pas lisible et exécutable par l'utilisateur courant, le 
desklet ne sera pas enregistré dans @file{$HOME/.adesklets}, et par 
conséquent ne sera pas automatiquement redémarré par le lanceur 
dans les futures nouvelles sessions X. Dans le cas où @code{stdin} 
est un terminal@footnote{Ce qui signifie que la session est 
interactive}, l'enregistrement ne se fera pas non plus.

@subsection Conséquences
Ainsi, du point de vue du script de desklet, les deux cas sont identiques, 
ce qui ne nécessite aucun traitement conditionel. Tout le travail 
d'initialisation du desklet se fait dans la quatrième étape de la 
sous-partie ci-dessus.

@noindent Si besoin, le desklet pourra utiliser la commande @code{get_id} 
pour déterminer son ID.

@section Utilisation des flux

Comme expliqué précedemment, un desklet communique avec son propre 
interpréteur adesklets via des flux sans tampons redirigés. Voyons 
ici quelles informations ils transportent.

@subsection stdin: les commandes

Sur le @code{stdin} de l'interpréteur, le desklet envoie les commande 
qu'il veut exécuter dans l'ordre dans lequel il veut les exécuter, une 
commande par ligne@footnote{Le caractère '\n' doit être placé après 
chaque commande.}. Etant donné que la lecture de ce flux est suspendue 
quand une commande est évaluée, un desklet devra géneralement attendre 
qu'une commande soit exécutée avant d'en envoyer une autre
@footnote{Ceci permet d'éviter de bloquer le processus en surchargeant 
le flux avec des commandes arbitrairement longues; bien sur, envoyer 
trois commandes de quelques centaines d'octets d'un coup n'est pas un 
problème!} (voir la section suivante).

@noindent Le format des commandes est assez simple: on a le nom d'une 
commande suivi d'arguments séparés par des espaces, tous représentés par 
du texte pur, y compris les nombres. adesklets ne se soucie pas du nombre 
d'espaces entre les arguments, pourvu qu'il y en ait au moins un. Dans le 
cas particulier des commandes où le dernier argument est une chaine de 
caractères (@code{text_draw}, par exemple), adesklets considèrera les 
premiers caractères n'étant pas des espaces comme le début de la chaine; 
le reste de la ligne, espaces inclus, sera considéré comme faisant 
partie de la chaine.

@noindent Deux fichiers, automatiquement tenus à jour avec la source 
(@file{scripting/prototypes} et @file{scripting/enums}) à partir de 
la distribution d'origine, fournissent au format texte brut (avec une 
tabulation comme séparateur) une description de toutes les commandes et 
constantes mises à disposition des desklets@footnote{Pour plus de détails 
sur le format de ces deux fichiers, cf @file{scripting/protoize.sh.in} et 
@file{scripting/enums.sh}.}. Un bon portage pour un langage particulier 
devrait être fourni avec quelques routines permettant de génerer automatiquement 
les parties pertinentes de sa propre bibliothèque à partir de ces fichiers; 
par exemple, le portage de Python comporte une fonction @code{protoize} 
dans le script @file{setup.py} de @code{distutils} pour le faire. 
Idéalement, cette routine devrait être écrite avec ce langage et un 
ensemble raisonnable de librairies@footnote{L'idée étant que la plupart 
des utilisateurs de votre portage doivent être plus ou moins capables 
de s'en servir avec l'installation de base du langage.}; si'l n'est pas 
bien adapté à cette tâche, vous devrez vous limitez à:

@itemize
@item Des scripts portables pour le shell Bourne, conforme aux standards 
POSIX 1003.2 et 1003.2a
@item Un sed (Streaming Editor) récent, compatible avec GNU sed
@footnote{De nos jours éxecuter GNU sed n'est pas un problème sur pratiquement 
n'importe quel système POSIX.}
@item Une utilisation portable de n'importe quel bc pour l'arithmetique
@end itemize

@noindent si vous voulez que votre travail soit intégré au paquetage officiel.

@subsection stdout: les résultats des commandes

L'interpréteur d'@command{adesklets} cherche fréquemment si de nouveaux 
caractères sont arrivés sur son flux @code{stdin}, et le lit si besoin. 
Dès qu'il reçoit le caractère de fin de ligne ('\n'), il arrête de lire 
et essaye d'exécuter la commande. Une fois la commande terminée (elle 
aura peut-être envoyé quelques lignes sur @code{stdout}), il envoie 
en tant que dernière entrée un message d'état de la forme suivante: 

@example
command RANG ok: MESSAGE
@end example

@noindent si la commande s'est terminée avec succès, ou:

@example
command RANG error: MESSAGE_DERREUR
@end example

@noindent @code{RANG} est l'indentifiant numérique de la commande (un entier 
non signé) qui part de zéro lorsque l'interpréteur est créé, et qui est 
automatiquement incrémenté à chaque ligne qu'il reçoit ensuite. Il est 
garanti que toutes les commandes seront exécutées dans l'ordre dans lequel 
elles ont étées données. 
@code{MESSAGE_DERREUR} est un message compréhensible, sans format particulier, 
expliquant d'où vient l'erreur. @code{MESSAGE} est également compréhensible, 
mais sera formaté de sorte qu'il peut être utilisé pour récupérer les valeurs 
de retour utiles algorithmiquement de n'importe quelles commandes. Ces valeurs 
de retour peuvent être:

@enumerate
@item un entier--l'ID de la valeur de retour (@code{create_image} et autres)
@item un couple d'entiers--le résultat numérique de la commande 
(pour @code{context_get_color} et consorts)
@item une liste de chaines--la liste ordonnée des chaines de caractères retournées 
par les commandes retournant plusieurs lignes sur @code{stdout} (@code{images_info} 
et ses semblables), la dernière ligne étant un message d'état
@item une chaine de description--une réponse textuelle en une ligne de la commande 
@item rien du tout
@end enumerate

@noindent Algorithmiquement, votre 'routine de récupération des valeurs de retour' 
devrait d'abord essayer de récupérer les entiers de @code{MESSAGE}@footnote{Tous 
les paramètres de @code{MESSAGE} sont séparés par un esapce.}. Si elle trouve un 
entier ou plus, elle devra vérifier que le message n'est pas une simple copie 
d'une commande donnée; alors la valeur de retour correspond au cinquième 
cas (cf ci-dessus). Autrement, si elle ne trouve qu'un entier, on est dans le 
premier cas; et si'l y en a plus d'un, dans le deuxième. Si aucun entier n'est 
trouvé et si'l y avait une liste de lignes envoyées à @code{stdout} avant le 
message d'état de la commande, on est dans le troisième cas. Pour le reste:  
si le message d'état diffère d'une commande donnée, cela correspond au 
quatrième cas. Sinon il faut considérer que la sortie correspond au cinquième cas. 
Cet algorithme de récupération fonctionne avec toutes les commandes listées 
dans @file{scripting/prototypes}.

@subsection stderr: les évènements
@anchor{Evènements}

Tous les autres rapports asynchrones d'évènements sont envoyés au flux 
@code{stderr} de l'interpréteur. Ils sont asynchrones par rapport au traitement 
des commandes; ils ne se produiront jamais pendant le traitement d'une 
commande (dans l'intervalle de temps entre la soumission de la commande 
complète sur @code{stdin} et la sortie de son message d'état sur 
@code{stdout}), ils peuvent être envoyés à n'importe quel autre moment
@footnote{De toute façon aucun évènement n'est jamais perdu; son apparition 
est simplement retardée.}.

@noindent Les rapports d'évènements tiennent sur une ligne, de la forme
@footnote{Toutes les autres informations sur @code{stderr} peuvent être 
ignorées sans risque.}:

@example
event: MESSAGE_DEVENEMENT
@end example

@noindent Sous la forme de Backus 
Naur@footnote{@weblink{http://fr.wikipedia.org/wiki/Forme_de_Backus_Naur}}, 
la grammaire employée pour MESSAGE_DEVENEMENT serait:

@verbatim
MESSAGE_DEVENEMENT :: ready! |
                      backgroundgrab |
                      menufire MENU_ID MENU_STR |
                      motionnotify X Y |
                      enternotify X Y |
                      leavenotify X Y |
                      buttonpress X Y BUTTON_ID |
                      buttonrelease X Y BUTTON_ID
;;
@end verbatim

@noindent où @code{MENU_ID}, @code{X}, @code{Y}, et @code{BUTTON_ID} sont tous 
des entiers supérieurs ou égaux à zéro, et @code{MENU_STR} est une chaine de 
caractères, pouvant contenir des espaces. Détaillons un peu plus tout cela:

@itemize
@item Evènement @strong{Ready}: envoyé une fois seulement, dès que l'interpréteur 
d'@command{adesklets} est prêt à traiter des commandes.
@item Evènement @strong{BackgroundGrab}: envoyé à chaque fois que l'image 
d'arrière-plan (image 1) est regénerée.
@item Evènement @strong{MenuFire}: envoyé à chaque fois qu'un utilisateur sélectionne 
un élément d'un menu qui n'est pas géré en interne par adesklets.
@item Evènement @strong{MotionNotify}: envoyé dès que le pointeur bouge dans la 
fenêtre d'un desklet.
@item @strong{EnterNotify, LeaveNotify}: envoyé dès que le curseur passe sur une 
bordure visible de la fenêtre de l'interpréteur, qu'il aille dedans ou dehors.
@item @strong{ButtonPress, ButtonRelease}: envoyé quand un bouton de la souris est 
cliqué dans la fenêtre de l'interpréteur.
@end itemize

@noindent Tous les évènements sauf 'Ready!' (nominativement: MotionNotify, 
EnterNotify, LeaveNotify, ButtonPress, ButtonRelease, BackgroundGrab et MenuFile) 
peuvent êtres masqués par le desklet. En fait, @command{adesklets} fournit au desklet 
des commandes permettant de gérer spécifiquement la création et la production des 
évènements, qui sont:
@code{event_catch}, @code{events_get_send_sigusr1}, @code{events_reset_all},
@code{event_uncatch}, @code{events_info}, @code{events_set_echo}, 
@code{events_get_echo}, @code{events_purge} et @code{events_set_send_sigusr1}.
Il faut noter que ces fonctions ne sont pas listées dans 
@file{scripting/prototypes} puisque vous ne voulez probablement pas que vos 
utilisateurs y aient accès. Vous devrez probablement démarrer une session 
interactive et jouer avec pour être sur que vous les avez bien comprises. Il est 
aussi temps de mentionner le script @file{src/adesklets_debug.sh}, qui se 
rend utile pour les expériences intéractives avec les évènements.

@noindent Il faut encore mentionner deux choses à propos des évènements:

@enumerate
@item Par défaut, les évènements ne sont pas affichés, mais stockés en interne, 
en attendant d'être purgés avec @code{event_purge}. Vous pouvez modifier cela 
avec @code{events_set_echo}.
@item Vous pouvez paramètrer un interpréteur adesklets pour qu'il envoie le 
signal SIGUSR1 à chaque fois qu'un évènement est envoyé à son processus père 
(le desklet). Cette communication entre processus est très utile puisque le signal peut être ratrappé, 
ce qui permet à la routine de gestion des évènements de ne fonctionner que 
lorsque c'est nécessaire. C'est ce qui est utilisé dans le paquetage Pyhton 
dans la classe @code{Events_handler}.
@end enumerate

@section Récuperation du signal SIGCHLD

Pourvu que votre langage le permette, vous devriez installer une sorte de 
récuperateur de SIGCHILD, ainsi vous pourrez au moins être averti si jamais 
l'interpréteur d'adesklets se termine sans raison (sans parler du cas des 
processus fils à l'état zombie)@footnote{@code{man 2 signal} est une très bonne 
réference sur les signaux.}.

@section Variables textuelles

@command{adesklets} supporte aussi l'exécution differée (mode indirect) 
et le remplacement textuel des variables. Voici comment fonctionnent les 
variables en mode indirect:

@enumerate
@item Une fois qu'une commande est entrée, elle est stockée telle quelle 
dans la liste de l'historique des commandes si on est bien dans le mode 
non-interactif de l'interpréteur et si la commande réside entre les appels 
à @code{start_recording} et @code{stop_recording})
@item Quand une macro est éxecutée (avec la commande @code{play}, 
@xref{Programmation d'adesklets}.), les variables sont substituées en une 
seule passe, et aucune réference indirecte n'est possible. La substitution 
est assez directe. On recherche dans la ligne de commande stockée toute séquence 
non-vide de caractères distincts de l'espace commançant par un seul '$'. Chaque 
séquence trouvée est remplacée par la valeur @code{$variable} correspondante, 
ou supprimée si aucune variable n'est trouvée.
@item La commande completée est exécutée.
@end enumerate


Le même mécanisme de substitution s'applique en mode d'exécution direct. Tout ceci 
implique que, avec le paquetage Python par exemple, ces deux morceaux de code sont 
équivalents:

@example
adesklets.window_resize(100,100)
@end example

et:

@example
adesklets.set('dim',100)
adesklets.window_resize('$dim','$dim')
@end example

Python étant un langage typé dynamiquement, aucune modification de notre code 
n'est nécessaire, mais d'autres langages pourraient demander plus de réflexion. 

@section Derniers mots

Maintenant vous devriez savoir quasiment tout ce qu'il faut pour intégrer adesklets 
à votre environnement de langage. Cette tache peut avoir l'air intimidante, mais un 
traducteur très propre peut être fait par un seul développeur en seulement quelques 
jours. Encore une fois, jetez un oeil à @file{src/adesklets_debug.sh}; c'est un 
traducteur (simplet) du Bourne Shell pour adesklets qui tient dans seulement 
cinquante lignes, commentaires compris.

Si jamais vous avez besoin d'aide, vous êtes encouragés à écrire (en anglais) à la 
@weblink2{mailing list 
adesklets-devel,https://lists.sourceforge.net/lists/listingo/adesklets-devel}...

Bonne programmation!

@noindent
@node Recherche d'aide!
@chapter Contribuer à adesklets

Nous avons besoin de votre aide! Vous pouvez contribuer efficacement à 
adesklets de différentes manières:
@itemize
@item
@strong{Mettre en ligne vos captures d'écran}. Vous êtes un utilisateur 
d'adesklets et pensez avoir un bureau particulièrement réussi? Partagez-le 
avec le monde, et faites-le nous savoir! Vous aiderez ainsi à faire 
connaitre le projet.
@item
@strong{Contribuer à la documentation}. Vous écrivez correctement en Allemand, 
Espagnol, Portugais, Arabe ou Swahili? Les traducteurs seront toujours les 
bienvenus, ainsi que les relecteurs, quels que soient les langues.
@item
@strong{Écrire de nouveau desklets}. adesklets est encore jeune: nous sommes 
en quête de talentueux auteurs de desklets, et nous serions
plus qu'enchantés de mettre en ligne ou de faire des liens vers votre travail.
Ne vous inquiétez pas trop des changements d'interface; l'auteur à fait des efforts 
considérables pour lui assurer une certaine stabilité, même dans les premières 
versions. Elle n'est pas non plus fixée pour toujours, mais ne devrait en tout cas 
pas gêner vos desklets sans prévenir. Actuellement, l'API subit surtout des 
corrections internes de bugs et des améliorations de sa portabilité.
@item @strong{Ajouter des interfaces pour votre langage préféré}. Contactez 
les développeurs avant de commencer quoi que ce soit pour que vous ne perdiez pas 
votre temps sur quelquechose de déjà fait; ils seront heureux de partager leur code. 
Inscrivez-vous à la @weblink2{mailing-list 
adesklets-devel,https://lists.sourceforge.net/lists/listinfo/adesklets-devel} sur 
sourceforge pour un contact direct avec eux.
@end itemize

@noindent Contactez-moi par email à @email{syfou@@users.sourceforge.net} (NdT: 
vous pouvez lui écrire en anglais comme en français).

@node Foire Aux Questions
@appendix Foire Aux Questions

Dernière mise à jour: @value{UPDATED}

@appendixsection Compiler adesklets

@subheading Le script de configuration d'adesklets dit que mon installation de Python est trop ancienne, pourtant elle ne l'est pas. Quel est le problème?

Certaines plate-formes (NetBSD, Ubuntu Linux, et probablement d'autres encore) 
altèrent parfois la version de Python, en y ajoutant des lettres, des numéros de 
version mineures, etc., ce qui empêche le script de configuration de la détecter 
correctement. Si vous êtes @strong{sûr} que la version installée est supérieure 
à la 2.3.0, vous pouvez utiliser l'option @code{--with-python-force-detection} de 
@code{configure}, ainsi le script de configuration passera la détection de version. 

@appendixsection Démarrer et arrêter des desklets

@subheading Quand j'essaie de lancer un nouveau desklet, j'obtiens l'erreur @code{ImportError: no module named adesklets} de l'interpréteur Python. Qu'est-ce qui se passe?

C'est écrit dessus: @command{python} n'arrive pas à trouver le 
paqetage @code{adesklets}; peut-être qu'il n'a pas été installé, 
ou qu'il a été installé au mauvais endroit.

@itemize
@item Reprenez depuis le début la procédure d'installation 
(@xref{Installer adesklets}.). Assurez vous que vous 
@strong{n'activez pas} l'option de configuration 
@code{--without-python-support}.
@item Re-essayez de lancer le desklet. Si cela ne marche toujours pas, 
vérifiez que le répertoire d'installation, que vous pouvez voir 
avec: @example
sed -n '/PYTHON_SITE_PKG/p' Makefile
@end example
@noindent est inclus dans: @example
echo 'import sys; print sys.path' | python
@end example

@noindent si'l ne l'est pas, vous pouvez toujours essayer de déplacer 
manuellement le répertoire d'adesklets de @code{PYTHON_SITE_PKG} vers 
un des chemins donnés par la commande précedente.
@end itemize

@subheading Quand j'essaie de démarrer un nouveau desklet, j'obtiens l'erreur @code{ADESKLETSError: adesklets process exited} de l'interpréteur Python. Qu'est-ce que c'est?

C'est une erreur génerique vous informant qu'il manque quelquechose à 
l'interpréteur de bas niveau qui est suffisamment critique pour provoquer 
une sortie. Si vous êtes chanceux vous trouverez à la fin de la ligne 
un tiret suivi d'un message décrivant ce qui ne fonctionne pas. Dans 
ce cas, et si vous avez du mal à le comprendre, allez chercher de l'aide 
en ligne. Si aucune information ne vous est donnée concernant 
l'origine de l'erreur, essayez ceci depuis un pseudo-terminal sous X:
@example
echo x_status | adesklets :
@end example
Vous devriez normalement obtenir quelquechose ressemblant à:
@example
event: ready!
command 0 ok: x_status 1 (connected to ':0.0')
@end example

Si c'est la cas, c'est probablement que vous utilisez un système 
(@weblink2{archlinux,http://www.archlinux.org/} par exemple) 
sur lequel la variable @code{PATH} de l'interpréteur Python diffère de celle 
héritée de l'environnement standard, ce qui fait que le paquetage Python 
n'arrive pas à lancer adesklets en tant que processus fils. Sur ce 
genre de systèmes, assurez-vous que vous installez @command{adesklets} 
avec l'option @code{--prefix} appropriée lors de la configuration. 
Par exemple, sur la plupart des plate-formes Linux récentes, vous 
devriez utiliser:

@example
./configure --prefix=/usr
@end example

@subheading Je ne peux lancer aucun desklet écrit en Python: j'obtiens des erreurs du récupérateur automatique de mémoire (garbage collector)!
Si vous obtenez des erreurs du type:

@example
python: Modules/gcmodule.c:275: visit_decref: Assertion `gc->gc.gc_refs != 0' failed.
Aborted
@end example

Cela signifie que le récuperateur automatique de mémoire de votre 
installation de Python est corrompu; c'est souvent du à une 
compilation utilisant des options d'optimisation incorrectes ou 
agressives. D'habitude recompiler un environnement Python solide 
provenant de @weblink{http://python.org/} résoud ce problème.

@subheading Les desklets se lancent bien en tant que root ou autre utilisateur local, mais gèlent ou se terminent avec un compte monté via NFS

Pour pouvoir fonctionner correctement, adesklets à besoin de pouvoir 
vérouiller quelques fichiers dans le répertoire @code{$HOME}: la plupart 
des problèmes avec les systèmes de fichiers en réseau sont dus à 
des installations fonctionnant à moitié qui n'arrivent pas à fournir 
ce genre de verouillage. Dans l'archive tar des sources d'adesklets vous 
trouverez un court script, @code{test/flock.py}, qui effectue un 
simple test des verrous fcntl; normalement il récupère un verrou dans 
le répertoire de travail courant, attend que l'utilisateur presse une 
touche, alors il relache le verrou et sort. Vous pouvez lancer plusieurs 
instances du script depuis le même répertoire pour vérifier que le 
verouillage fonctionne effectivement. Si ce n'est pas le cas, alors le 
faire fonctionner reviendra surement à faire fonctionner adesklets.

@subheading Tout fonctionnait bien mais j'ai essayé de mettre à jour un desklet, et je n'arrive pas à voir le nouveau. Où est l'erreur?

Il y a un mécanisme interne de blocage dans l'interpréteur qui empêche un 
utilisateur de lancer simultanément plus d'un desklet avec le même @code{ID} 
et le même nom, quelle que soit la version. Lorsque vous mettez à jour un 
desklet donné, vous devriez d'abord quitter proprement le desklet (en 
utilisant la commande @code{Quit} du menu contextuel), puis installer le 
desklet mis à jour en suivant les instructions fournies par le fichier 
@file{README}.

@subheading Argh! Le desklet X marche, mais ne se souvient pas de ses paramètres, ou bien il démarre toujours dans le coin en haut à gauche de l'écran 0 dans une nouvelle session X. Qu'est-ce que c'est? C'est lourd!

C'est très probablement lié à la manière dont vous avez démarré le 
desklet (cf @pxref{Utiliser adesklets}.). Vous devez invoquer le script 
du desklet @strong{une seule fois}. Pour toute utilisation future vous 
n'aurez qu'a éxectuer la commande:

@example
@command{adesklets}
@end example

qui se souviendra où vous aviez placé les desklets et quels desklets étaient 
lancés. N'oubliez pas d'activer les options correctes lors de l'appel à 
@command{adesklets}.

@subheading C'est exactement ce que j'ai fait, mais ce truc ne veut toujours pas redémarrer.

N'auriez-vous pas placé les desklets dans un répertoire du type 
@file{$HOME/.adesklets}? Veillez ne pas le faire. @command{adesklets} 
utilise le fichier @file{$HOME/.adesklets} pour enregistrer toutes sortes 
de paramètres des desklets lancés; créer un répertoire portant ce nom 
l'empêchera de faire son travail correctement, vous n'avez donc qu'a 
déplacer votre répertoire ailleurs (@file{$HOME/.desklets}, par exemple).

@subheading Les desklets se lancent correctement, mais ils continuent de marcher quand je termine la session X.

Normalement, les desklets sont censés s'arrêter automatiquement à la fin de la 
session. Si vous disposez de l'interface basée sur le shell (ce qui est le cas par 
défaut), vous pouvez aussi les fermer manuellement en invoquant la commande

@example
adesklets --killall
@end example

lors de la sortie de session.

@appendixsec Afficher les desklets

@subheading Où sont mes desklets? L'interpréteur d'@command{adesklets} semble être lancé correctement, mais je ne vois tout simplement rien sur mon bureau (le soi-disant problème de clignotement)!

Essayez la commande:

@example
python test/test.py
@end example

@noindent depuis le répertoire de base des sources. Si une fenêtre de 
100x100 pixels apparaît, cela signifie très probablement que vous utilisez 
un gestionnaire de fenêtres qui dessine une grosse fenêtre (dite fausse 
fenêtre racine, ``fake root window'') par dessus la fenêtre racine; 
vos desklets sont dessinés en-dessous. Parmi ces gestionnaires de 
fenêtres on trouve Nautilus, KDE, Xfce4,CDE ou E17. Pour adesklets 
@value{VERSION}, les gestionnaires de fenêtres supportés dans cette catégorie 
sont:

@itemize
@item @strong{KDE}: pour les versions 3.4.1 et supérieures (les versions 
antérieures n'ont pas été testées).
Vous devez soit activer l'option ``Centre de Contrôle -> Bureau -> 
Afficher les icones sur le bureau -> Autoriser les programmes dans la 
fenêtre du bureau''@footnote{NdT: je n'ai pas KDE donc le nom de ces menus 
est approximatif. N'hésitez pas à me donner leur nom 
précis: @email{martin.kirch@@gmail.com}}, soit 
désactiver l'option ``Afficher les icônes sur le bureau''@footnote{Merci 
à Stefan Jungcurt pour l'astuce.}.
@item @strong{Nautilus}
@item @strong{ROX-Filer}: pour l'instant il ne s'agit que d'un support 
préliminaire
@item @strong{Xfce4}
@item @strong{xffm-desktop}: pour l'instant il ne s'agit que d'un support 
préliminaire
@end itemize

Depuis adesklets 0.4.11, la méthode de détection des fausses fenêtres racine 
a changé: par défaut cela ne fait plus partie du code C@footnote{Bien que 
vous pouvez revenir à l'ancienne méthode si vous le désirez en 
utilisant @command{--enable-legacy-fake-root-window-detection} lors de 
la configuration. @xref{Installer adesklets}.}. L'interpréteur s'attend 
maintenant à ce que la variable d'environnement ADESKLETS_ROOT contienne 
le bon ID hexadécimal de la fausse fenêtre racine, si'l y en a. Vous 
pouvez bien sur la définir manuellement, mais l'interface basée sur le shell 
prendra en charge pour vous les gestionnaires de fenêtres les plus courants 
(voir la liste précedente), pourvu que vous lui demandiez de le faire. 
Essayez d'invoquer:

@example
adesklets --help
@end example

Si l'interface est installée, vous devriez voir de nombreuses options, 
notemment celles permettant d'activer une routine de détection de fausse 
fenêtre racine adaptée à un gestionnaire de fenêtres donné. Vous disposez 
aussi d'une détection ``génerique'' via l'option @command{--user}: elle 
peut fonctionner (ou pas) chez vous, selon la structure de votre 
gestionnaire de fenêtres. Enfin, veillez noter que l'interface est un 
simple script compatible sh, installé par défaut dans 
@command{$prefix/share/adesklets} -- il devrait être 
très facile de le modifier pour tout personne désirant implémenter d'autres 
méthodes de détection.

Gardez aussi à l'esprit que la détection de fausse fenêtre racine requiert 
évidemment que celle-ci existe, il est donc important que vous invoquiez 
@command{adesklets} @emph{après} l'initialisation du gestionnaire de 
fenêtre. Pour vous aider à le faire, vous avez à votre disposition l'option 
@command{-w nomduprogramme} dans l'interface du shell.

@subheading Et pour enlightenment?
adesklets fonctionnera comme prévu avec e16 tant que vous n'activez pas les 
fonctions induisant l'uilisation de fausses fenêtres racine (voir les 
questions précedentes), ce qui cache dans certains cas les desklets derrière 
la structure du gestionnaire de fenêtres. D'après l'experience de l'auteur, 
avec la version 0.16.7.2 il n'est possible de voir les desklets que dans le 
premier bureau virtuel. Ceci dit, dans le jargon d'enlightenment, les bureaux 
virtuels peuvent s'étaler sur plusieurs "écrans" (quatre, alignés 
horizontalement par défaut), ce qui permet parfaitement l'usage de plusieurs 
espaces de travail en laissant les desklets d'adesklets visibles.

e17 n'est pas supporté. Si vous y tenez vous pouvez trouver plus d'astuces à 
ce sujet sur la @weblink2{FAQ d'enlightenment, http://www.get-e.org/Main/FAQs/#48}. 
Ceci dit, e17 est fourni avec ce qu'on appelle les ``modules e17'' (engage, 
etc.), qui fonctionnnent parfaitement avec ce WM et qui remplissent les mêmes 
fonctions.

@subheading Maintenant je vois les desklets, mais la transparence foire!

Une pseudo-transparence correcte se base sur la possibilité de récupérer 
l'image de fond d'écran et d'être averti quand elle change. Il n'y a aucune 
méthode complètement fiable ni même bien établie pour le faire sur autre 
chose que la vraie fenêtre racine du protocole X11 (veuillez lire cette partie 
de la FAQ, ``Afficher les desklets'', depuis le début pour bien comprendre 
ce qui suit).

Ainsi, même en présence d'une fausse fenêtre racine, adesklets récupère 
toujours l'arrière-plan de la vraie fenêtre racine: certains gestionnaires de 
fenêtres se soucient de la synchronisation permanente entre la vraie et la 
fausse fenêtre racine, mais pas assez. adesklets fait de son mieux, quand 
c'est possible de manière portable, pour synchroniser @emph{lors de son 
initialisation} les arrières-plans mais dans certains cas supportés 
(ROX-Filer, xffm-desktop), ce n'est même pas possible. Par conséquent, si 
vous obtenez des arrières plans corrompus (pas d'arrière-plan, un arrière-plan 
incorrect ou ne reflétant pas le dernier changement effectué, alors que vous 
voyez effectivement le nouveau papier peint dans une fausse fenêtre racine), 
vous n'avez qu'à dupliquer le papier peint utilisé sur la vraie fenêtre racine, 
de préference en utilisant un afficheur de papier peint supportant la mécanisme 
ad-hoc, largement supporté, d'@weblink2{enlightenment,http://gershwin.ens.fr/vdaniel/Doc-Locale/Outils-Gnu-Linux/Eterm-0.9/#trans} pour la 
notification de changement de papier peint -- n'importe lequel des programmes 
suivants devrait fonctionner correctment: @command{Esetroot}, @command{wmsetbg}, 
@command{feh}, @command{hsetroot}, @command{chbg} ou @command{xsri}. 
En fait vous pouvez utiliser n'importe quel afficheur de papier peint pour 
changer la vraie racine, mais ensuite vous aurez peut-être à rappeler 
le lanceur d'adesklets pour profiter d'une récupération initiale du papier 
peint correcte si aucune notification n'a été envoyée.

@subheading Je ne peut pas voir les petits desklets comme xmms_bar ou asimpleclock, alors que les autres fonctionnent. Pourquoi?

Les nouveaux desklets sont toujours lancés dans le coin le plus en haut à gauche de 
l'écran, tout en bas de la pile de fenêtres. Vérifiez qu'il n'y a rien 
(barre de gnome, engage, etc) qui puisse masquer cette zone de l'écran. 
Attention! Certaines applications sont pseudo-transparentes, et peuvent 
masquer la fenêtre racine sans en avoir l'air.

@subheading J'utilise Fvwm comme gestionnaire de fenêtres. Pourquoi est-ce que je n'arrive pas à maintenir les desklets sous toutes les autres fenêtres? Ils n'arrêtent pas de se mettre au premier plan!

Allez voir la faq de Fvwm: @weblink{http://www.fvwm.org/documentation/faq/#5.11}. 
D'après de nombreux utilisateurs de Fvwm, cette option, 
@code{BugOpts RaiseOverUnmanaged on} fonctionne bien.

@appendixsec Utiliser les desklets

@subheading Le bouton 'Configure' dans le menu contextuel des desklets ne marche pas!
Pour que cela marche--tout du moins pour tous les desklets de démonstration--il faut 
que @command{xterm} soit installé, et que la variable @code{EDITOR} soit correctement 
définie dans votre environnement, comme le veut l'usage sous UNIX. Veillez remarquer 
que cela ne fait que lancer un éditeur de texte dans un terminal. Editer le fichier 
de configuration du desklet (habituellement @file{config.txt} dans le répertoire de 
base du desklet) aura le même effet.

@subheading L'élément 'Configure' du menu contextuel peut-il appeler un éditeur n'utilisant pas la console?
Oui, pourquoi pas? Depuis adesklets 0.4.13, l'interface du shell permet de 
le faire facilement: utilisez l'option @command{adesklets -e} (editeur).

@subheading Avez-vous prévu d'inclure le support d'SVG? J'aimerais utiliser une image SVG dans un de mes desklets.
Désolé, ce n'est pas prévu. Ce n'est pas 
qu'@weblink2{SVG,http://www.w3.org/Graphics/SVG/} est un mauvais format; il est même 
assez bon. Mais c'est également un format orienté vers le dessin vectoriel (et assez 
complexe), alors qu'Imlib2, sur laquelle @command{adesklets} se base entièrement, 
est complètement orientée dessin de trame. Or c'est l'utilisation d'Imlib2 qui rend 
@command{adesklets} simple, relativement rapide et peu consommateur de ressources.

Ceci dit, il n'y a aucune raison que vous n'utilisiez pas d'image SVG dans vos 
desklets, puisqu'il est assez simple de convertir des images SVG en PNG de haute 
qualité en utilisant des programmes comme @weblink2{sodipodi,http://www.sodipodi.com/}, 
@weblink2{inkscape,http://www.inkscape.org/} ou @weblink2{xsvg,http://xsvg.org/}. 
Dans un répertoire plein de SVG, sur un système GNU vous pouvez aussi utiliser 
une commande comme::
@example
ls *.svg | sed 's/\(.*\).svg/-z --file=& --export-png=\1.png --export-width=128 --export-height=128/' | xargs --max-lines=1 sodipodi
@end example
pour toutes les convertir en PNG semi-transparents de 128x128 pixels.

@subheading J'aimerais utiliser certaines polices de mon système avec adesklets, mais mes desklets n'arrivent pas à les trouver. Que dois-je faire?

D'abord, votre adesklets doit supporter fontconfig. Vérifiez-le en lisant le fichier 
config.log issu de la phase de configuration. Si vous n'avez pas gardé le log, vous 
pouvez aussi voir quelles bibliothèques dynamiques sont liées à l'interpréteur. 
Sur un système disposant des binutils GNU, vous pouvez faire quelquechose comme:
@example
ldd `which adesklets` | grep fontconfig
@end example
Si vous obtenez une réponse du genre:
@example
 libfontconfig.so.1 => /usr/lib/libfontconfig.so.1 (0x45c750000)
@end example
cela signifie que tout va bien. Autrement, vous devrez recompiler @command{adeskelts} 
à partir des sources. Ensuite, vous pouvez utiliser la commande: 
@example
echo 'list_font_path' | adesklets :
@end example
pour voir dans quels répertoires adesklets recherche les polices TrueType. Consultez 
la documentation de fontconfig si vous désirez les modifier (sur les systèmes à 
jour, @code{man 5 fonts-conf} est un bon point de départ).
De même:
@example
echo 'list_fonts' | adesklets :
@end example
Vous listera les polices actuellement disponibles... Gardez à l'esprit lorsque 
vous les testerez que le nom des polices est sensible à la casse.

Enventuellement, si vous n'arrivez pas à faire fonctionner fontconfig, une manière 
de contourner le problème est de créer des liens symboliques vers les polices que 
vous voulez utiliser dans n'importe quel répertoire listé par la commande 
@code{echo 'list_font_path' ...} ci-dessus.

@ifhtml
@node Documentation du paquetage Python
@appendix Documentation du paquetage Python

Voici quelques liens intéressants vers la documentation du paquetage 
Pyhton@footnote{NdT: elle est en anglais, certes... Mais je ne connais pas encore 
de développeur anglophobe ;-)}:

@itemize
@item @weblink2{adesklets,../pydoc/adesklets.html}
@item @weblink2{adesklets.events_handler,../pydoc/adesklets.events_handler.html}
@item @weblink2{adesklets.commands,../pydoc/adesklets.commands.html}
@item @weblink2{adesklets.utils,../pydoc/adesklets.utils.html}
@item @weblink2{adesklets.configfile,../pydoc/adesklets.configfile.html}
@end itemize

@end ifhtml

@node Documentation d'Imlib2
@appendix Documentation d'Imlib2

Carsten Haitzler (@email{raster@@rasterman.com}) a pris le temps d'écrire une 
documentation très réferencée d'Imlib2, mais pour certaines raisons (très 
probablement des problèmes de taille), elle n'est pas incluse dans le 
paquetage tar des sources d'Imlib2.@footnote{Bien qu'elle puisse être assez 
facilement refaite avec doxygen.}.
Vous pouvez 
@ifhtml
la récuperer @weblink2{ici,../imlib2}.
@end ifhtml
@ifnothtml
la lire en ligne sur @weblink{http://adesklets.sf.net/doc/imlib2/}.
@end ifnothtml


La plupart des fonctions de l'API d'Imlib2 ont des homonymes leurs 
correspondant dans @command{adesklets}. @xref{Programmation d'adesklets}, 
pour plus détails sur la transition du développement avec Imlib2 à adesklets.

@node GNU Makefile pour empaqueter les desklets
@appendix GNU Makefile pour empaqueter les desklets 

Voici un Makefile qui vous permettera d'automatiser la création de  
paquetages contenant des desklets existants ou nouveaux sur un système GNU. 
Copiez simplement le Makefile ci-dessous dans @file{GNUmakefile} dans le 
répertoire de base de votre desklet pour vous en servir. Il n'y a rien du 
tout à éditer, pourvu que le nom du répertoire de base soit de la forme 
'NOM-MAJEURE.MINEURE.REVISION', par exemple @code{beast-0.666.0}.

@verbatiminclude ../utils/GNUmakefile.desklet

@node Soumettre un desklet
@appendix Soumettre un desklet

@section Minima requis dans un paquetage de desklet
Les règles sur le contenu du paquetage d'un desklet sont maigres; les auteurs 
sont libres de faire ce qu'ils veulent. Ils ne doivent absolument respecter que 
deux choses:
@enumerate
@item Le répertoire de base de l'archive du desklet doit contenir un fichier 
@file{README} très clair@footnote{NdT: et en anglais, pour plus de 'portabilité'.} et 
tenu à jour. Il doit au moins contenir:
@itemize
@item le nom et l'adresse email de l'auteur@footnote{Ce serait surement une 
mauvaise idée que de publier votre adresse email privée ici; pour éviter 
le spam, vous devriez plutôt ouvrir un compte sur 
@weblink2{SourceForge,http://sourceforge.net/}, ou un autre fournisseur similaire 
disposant d'un bon système anti-spam.} 
@item Une courte description du desklet
@item Ses dépendances
@item Comment s'en servir
@end itemize
@item Le paquetage doit être une archive tar bzippée ne contenant qu'un seul répertoire 
source du type @code{NOM-MAJEURE.MINEURE.REVISION}, où @code{NAME} est le 
nom de base du desklet, et @code{MAJOR.MINOR.REVISION} sa version. Veillez noter 
qu'un makefile (@xref{GNU Makefile pour empaqueter les desklets}.) est aussi 
fourni pour automatiser la création de ce genre d'archive sur les systèmes GNU.
@end enumerate

@section Le script @command{adesklets_submit}

Depuis @command{adesklets} 0.4.4, les auteurs de desklets disposent d'un 
script Pyhton automatisant la soumission de leurs desklets: 
@file{utils/adesklets_submit} dans le paquetage des sources. Utilisez 
l'option de configuration @code{--with-python-install-submission-scripts} 
pour le placer dans votre répertoire @code{bindir} lors de l'installation.

@file{adesklets_submit} peut être utilisé pour:
@itemize
@item Soumettre une nouvelle description, ou une mise à jour, à inclure dans 
le @weblink2{site Internet d'adesklets,http://adesklets.sf.net/desklets.html}; 
@item Soumettre une archive bzippée du desklet pour l'ajouter aux paquetages 
de desklets de SourceForge (c'est optionel--vous pouvez choisir de l'héberger 
vous-même).
@end itemize

@section Invoquer @command{adesklets_submit}
La soumission du desklet commence par l'envoi d'un email formaté 
spécifiquement à @email{adesklets@@mailworks.org}@footnote{Il est inutile 
d'envoyer autre chose à cette adresse; tous les messages qui ne peuvent être 
interprétés par le script de réception automatique seront simplement 
supprimés. Ecrivez plutôt à @email{syfou@@users.sourceforge.net} si vous 
désirez contacter le créateur du projet (qui parle très bien français, NdT).}.
Le script @command{adesklets_submit} vous assiste dans la construction de cet 
email en utilisant le fichier de configuration @file{$HOME/.adesklets_submit} 
et des options de ligne de commande. Voici un exemple de configuration 
valide du fichier @file{$HOME/.adesklets_submit}:

@verbatiminclude ../utils/adesklets_submit.example

Il s'explique assez bien de lui-même, mais voici quelques points moins clairs:

@itemize
@item
Essayez autant que possible d'éviter les pseudonymes et les surnoms pour 
@code{author_name}, sauf si, évidemment, vous avez déjà une indentité 
virtuelle bien établie sous ce nom.
@item
@code{send_confirmation} précise si un email doit être envoyé en retour à 
l'adresse @code{author_email} dès que votre desklet est publié correctement. 
De toute façon si'l est rejeté vous serez toujours averti par email, avec 
quelques explications. Géneralement, le gérant n'essaiera pas 
de changer les données problématiques, il va seulement expliquer à l'auteur 
ce qui n'était pas bon.
@item
@emph{Verifiez deux fois} l'adresse @code{author_email}, puisque c'est la 
seule que le webmestre essaiera d'utiliser pour vous contacter, ce que les 
en-têtes disent sera ignoré. Si vous ne fournissez pas une adresse valide 
tous les messages ne pourront vous être envoyés, et toutes les nouvelles 
entrées du desklet seront rejetées.
@item
Vous pouvez sans problème utiliser adesklets_submit sans aucun contact 
préalable avec le webmestre d'adesklets (que ce soit par email, dans le 
forum avec l'adresse donnée pour l'enregistrement, ou via la mailing-list), 
mais un minimum de communication sera nécessaire avant la publication 
simplement pour vérifier votre identité et sa relation effective avec 
l'adresse email fournie.
@item
@code{desklets} est un dictionnaire de dictionnaires (un dictionnaire par 
desklet, le nom des desklets étant les clefs); toutes les données se 
réferant à des fichiers (miniatures, captures d'écran ou fichiers à 
télecharger) peuvent être soit une adresse sur un site accessible publiquement 
(de préference), soit un chemin absolu ou relatif à votre répertoire $HOME 
vers des fichiers locaux. Dans ce cas, les fichiers requis seront attachés 
en pièce jointe à l'email géneré. 
@item
Toutes les images seront rapatriées puis intégrées au site Internet 
adesklets.sf.net, vous pourrez ensuite sans problème les retirer de votre 
emplacement en ligne si vous avez fourni des URL.
@item
Si vous mettez à jour un desklet déjà en ligne, il n'y a pas besoin de 
soumettre les images @code{thumbnail} ou @code{screenshot} si elles n'ont 
pas changé; vous pouvez aussi facilement faire réference aux images 
déjà installées sur SourceForge:
@itemize
@item @code{thumbnail} est toujours stockée sous 
@code{http://adesklets.sf.net/images/NAME_thumb.[jpg|png]}
@item @code{screenshot} est toujours stockée sous 
@code{http://adesklets.sf.net/images/NAME_screen.[jpg|png]}
où @code{NAME} est le nom de votre desklet.
@end itemize
@item
En utilisant la valeur @code{host_on_sourceforge}, vous pouvez choisir 
si le paquetage de votre desklet sera hébergé sur SourceForge ou sur votre 
propre site si vous avez fourni une URL. Bien sur dans ce dernier cas 
vous devrez le maintenir à l'emplacement donné.
@item
L'image @code{thumbnail} doit être au format JPG (de préference) ou 
PNG (si vous avez @emph{vraiment} besoin de définitions plus élevées) 
et d'une dimension comprise entre 190x35 pixels et 230x110 pixels.
@item
L'image @code{screenshot} doit être un JPG (de préference) ou un 
PNG de 640x480 pixels. Elle doit mettre votre desklet en évidence, 
et donc ne pas en contenir d'autres.
@item
Vous pouvez choisir de ne pas fournir de miniature ni/ou de capture 
d'écran. Dans ce cas, par défaut, des images géneriques seront utilisées 
à la place.
@item
@code{Category} est actuellement inutilisée, et sera juste ignorée.
@item
Tous les emails pesant plus de 300KB seront rejetés par le serveur email 
du webmestre, adesklets_submit refusera donc d'en génerer. Au lieu de 
soumettre d'aussi grosses entrées, utilisez la possibilité de donner des 
URLs comme décrit ci-dessus pour alléger l'email. 
@item @command{adeskets_submit} ne vérifie pas que vous respectez toutes 
ces règles; il ne vérifie que ce qui est strictement nécessaire pour 
construire un email de soumission adapté: l'existence des entrées de 
dictionnaire, la disponibilité des fichiers, la validité des types de 
fichiers locaux... Il est de votre devoir de s'assurer que les données 
sont correctes si vous voulez éviter le rejet.
@end itemize

Par exemple, Belial Leviathan devrait d'abord vérifier les données de 
son desklet @code{beast} en faisant quelquechose comme:
@example
adesklet_submit beast
@end example

Si tout fonctionne bien, l'email de soumission résultant sera affiché sur 
@code{stdout}. A partir de là, Belial peut: 
@itemize
@item Le passer par un tuyau (pipe) à son MTA (agent de transfet d'email) 
favori pour l'envoyer à @email{adesklets@@mailworks.org}.
@item Demander à @command{adesklets_submit} de l'envoyer lui-même par 
SMTP, en utilisant les paramètres @code{smtp_host} et @code{smtp_port} 
dans son @file{$HOME/.adesklets_submit}. Pour cela, Belial devrait utiliser:
@end itemize
@example
adesklets_submit --send beast
@end example

Une dernière chose: essayez d'éviter d'envoyer des corrections mineures à 
plusieurs reprises, en particulier si vous utilisez des fichiers locaux. 
Cela va charger à la fois le server email du webmestre et son travail de gestion. 
Veillez essayer de créer une entrée valide @emph{puis} de l'envoyer, au 
lieu de patauger autrement. 

@appendixsubsec Validation approfondie d'une entrée avec @command{adesklets_checkin}
Depuis @command{adesklets} 0.4.5, vous avez aussi à votre disposition 
le script @command{adesklets_checkin}. C'est le script Python que le 
webmestre utilise pour vérifier toutes les soumissions. @emph{N'oubliez pas 
que ce script n'est fournit aux auteurs de desklets que par confort, 
pour minimiser le nombre de rejets de soumissions--les développeurs ne 
sont en aucun cas forcés de l'utiliser, et peuvent même être incapables 
de le faire, puisque ce script n'a pas été écrit avec le souci de la 
portabilité, contrairement à adesklets_submit. Lisez l'en-tête du 
script pour une liste complète des pré-requis à son exécution.}

@command{adesklets_checkin} a deux modes de fonctionnement: interactif et 
non-interactif. Seul le mode non-interactif interessera les auteurs de 
desklets. Dans ce mode, l'utilisation est franchement simple. Belial, 
par exemple, ferait:
@example
adesklets_submit beast | adesklets_checkin
@end example

Si tout fonctionne bien, le résultat serait similaire à:
@example
Validation started. Please wait.
Everything seems fine, but keep in mind a few things cannot be
verified without human intervention. See documentation for details.
@end example

Sinon, vous aurez la trace de l'exception avec quelques explications 
assez claires (espèrons-le).

@appendixsubsec Limitations d'@command{adesklets_checkin} en mode non-interactif

Voici quelques problèmes restants qu'@command{adesklets_checkin} ne 
peut pas détecter et qui doivent donc être absolument résolus 
manuellement (le webmestre en détectera la plupart, et vous aurez à 
renvoyer l'email de toute façon):
@itemize
@item
Un fichier README incomplet dans le répertoire de base (Est-ce qu'il 
contient tous les détails énumerés ci-dessus?).
@item
Le fichier README n'est plus à jour (Est-ce que son contenu reflète 
l'état actuel du desklet?).
@item
Le desklet ne peut pas fonctionner à la sortie de la boite (c'est-à-dire 
sans ou avec un minimum de configuration) alors que les pré-requis du 
fichier README et les instructions particulières sont respectés.
@end itemize    

@node Copier ce Manuel
@appendix Copier ce Manuel

@menu
* GNU General Public License::  la licence permettant de copier ce manuel.
@end menu
NdT: La licence est laissée en version originale car seule cette version à une 
valeur juridique. Néanmoins, pour en faciliter la compréhension, 
il existe des traductions disponibles sur Internet, par exemple sur 
@weblink{http://www.linux-france.org/article/these/gpl.html}.

@include gpl.texi

@node Clé publique Open PGP
@appendix Clé publique Open PGP

@verbatiminclude syfou.asc

@noindent Vous pouvez également obtenir ce certificat d'un bon nombre de serveurs
publics de clés sur Internet, tels @weblink{http://www.keyserver.net/}, ou
@weblink{http://pgp.mit.edu/}. Contactez son auteur légitime, 
Sylvain Fourmanoit, par courier électronique à l'adresse
@email{syfou@@users.sourceforge.net} pour organiser une validation plus correcte
de la clé si vous en avez besoin.

@bye