From 640c294e08afa44ac90b14a56d07acaa6cfd8630 Mon Sep 17 00:00:00 2001 From: Date: Sun, 28 Aug 2005 17:03:23 -0400 Subject: [PATCH] Big update to the French version of adesklets' texinfo manual. adesklets french documentation has been brought back up to speed with the original version. A big thanks to Martin Kirchgessner for its hard work! --- AUTHORS | 5 +- doc/adesklets_fr.texi | 1824 ++++++++++++++++++++++++++++++++++++++++--------- site/news/033.txt | 4 + 3 files changed, 1512 insertions(+), 321 deletions(-) create mode 100644 site/news/033.txt diff --git a/AUTHORS b/AUTHORS index cdc5a5d..47b594d 100644 --- a/AUTHORS +++ b/AUTHORS @@ -6,9 +6,12 @@ Author: English Documentation proofreader, Python package adviser: Mike Pirnat -French Documentation Translator: +Original French Documentation Translator: Guillaume Boitel +Current French Documentation Translator: + Martin Kirchgessner + Debian Package Maintainer: Bartosz Fenski aka fEnIo diff --git a/doc/adesklets_fr.texi b/doc/adesklets_fr.texi index 58571aa..47c9b39 100644 --- a/doc/adesklets_fr.texi +++ b/doc/adesklets_fr.texi @@ -12,17 +12,13 @@ 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}. - -[ Ce document n'est malheureusement pas à jour. -Vous pouvez aider à la traduction? Faites-nous le savoir! ] +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 Générale publique GNU (GNU General Public -License), version 2 ou toute version ultérieure publiée par la Free Software -Foundation. Une copie de la présente licence est -incluse dans l'annexe au document intitulée "Copier ce Manuel". +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 @end copying @@ -57,6 +53,7 @@ incluse dans l'annexe au document intitul @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 @@ -82,33 +79,39 @@ Suivez le lien pour la version originale @menu * A propos d'adesklets:: * Nouveautés:: -* Installation d'adesklets:: -* Utilisation d'adesklets:: +* Installer adesklets:: +* Utiliser adesklets:: * Programmation d'adesklets:: * Extension d'adesklets:: * Recherche d'aide!:: -* Questions fréquemment posées:: +* 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:: * Index:: @end menu -@noindent Une version à jour de ce document peut être trouvée en ligne : +@noindent Une version à jour de ce document peut être trouvée en ligne: @weblink{http://adesklets.sf.net/}. @noindent Captures d'écrans, codes sources, etc. peuvent aussi être trouvés -sur la page du projet : @weblink{http://sf.net/projects/adesklets/}. +sur la page du projet: @weblink{http://sf.net/projects/adesklets/}. @node A propos d'adesklets @chapter Qu'est-ce qu'adesklets ? @section Réponse courte -@command{adesklets} `adesklets' est une console interactive +`adesklets' est une console interactive d'@weblink2{Imlib2,http://www.enlightenment.org/pages/imlib2.html} pour le système X Window. 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 interactif. +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 @@ -117,7 +120,7 @@ des fonctionnalit @section Réponse longue @command{adesklets} signifie "another desklets [container]". Il a été écrit -comme une alternative à d'autres programmes tels que : +comme une alternative à d'autres programmes tels que: @enumerate @item @@ -133,11 +136,11 @@ commencer des projets semblables, d'utiliser l'espace de 'b' à 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èque -; de base les gDesklets requiert que le bureau GNOME soit entièrement +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 base. Ceci se répercute sur l'exécution des autres +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 @@ -145,127 +148,209 @@ de version en version.}. D'autre part, alors que GkrellM est plus l 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 : +De ce constat est né @command{adesklets}. Il fournit: @itemize @item -un cadre minimal pour des desklets X Window totalement intégré dans le bureau, -avec une facilité d'emploi pour gérer leur lancement, leur placement et +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 -une dépendance très limitée de bibliothèques : utilisation de la très bonne (et +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être n'est utilisé : le programme repose directement sur xlib. +à outils de fenêtres n'est utilisée: le programme repose directement sur xlib. @item -un léger, robuste et petit interpréteur potentiellement utilisable avec +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. Dans les futurs versions, le support de Perl et Ruby sont prévus : -n'hésitez pas à contribuer afin que votre langage préféré soit supporté ! +séparément. Le support de Perl et Ruby est prévu pour les prochaines versions, +n'hésitez pas à contribuer afin que votre langage préféré soit supporté! @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 120 Ko sur -le disque et prend moins de 3Mo de mémoire virtuelle par desklet, après -initialisation, et quasiment aucun cycle de processeur (y compris ceux du -script python interprété) lorsque le desklet est lancé. - +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 : +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 application +menus gris nus et laids: vous ne pouvez clairement pas écrire une application GUI avec ces seuls desklets. @item -des mécanismes compliqués (ni même de mécanismes clairs, en la matière) -pour la configuration de script. Les développeurs de scripts sont libres (ou -condamné, selon la façon de voir les choses) de faire ce qu'il leur convient. +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, ce serait vraiment surprenant qu'il puisse être possible -de le compiler sur cygwin. +POSIX. Par exemple, il serait vraiment surprenant d'arriver à le compiler sur +Cygwin. @item -un gestionnaire avec de nombreuses fonctionnalités pour les événements -utilisateurs. @command{adesklets} vise une faible consommation de ressource -et une fiabilité ; seuls quelques événements - principalement ceux concernant -le pointeur - sont utilisables dans l'API. +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 -@unnumberedsec Quoi de neuf pour la version 0.3.1 ? +@chapter Quoi de neuf? + +@headings 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. + +@headings 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. + +@headings 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, grace à yogi77, +du forum. + +@headings 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. + +@headings 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. + +@headings 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. + +@headings 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. + +@headings 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. + +@headings 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. + +@headings 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. + +@headings 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. + +@headings 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. + +@headings 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 possibles. +est essentielle à la bonne marche de plusieurs effets dynamiques. -@unnumberedsec Quoi de neuf pour la version 0.3.0 ? +@headings 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 de adesklets; avec cette -version, le packetage compile et tourne dans accro sur FreeBSD et NetBSD -(@xref{Portabilité}.). La gestion des évènements a également été revue à l'interne, -et le packetage python étendu pour supporter la modification dynamique des +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 le plein spectre des desklets qu'il désirait couvrir, incluant -les animations. +place pour écrire tout type de desklet, y compris des animations. -@unnumberedsec Quoi de neuf pour la version 0.2.1 ? -Cette version corrige un bogue mineur quant à la compatibilité avec -les versions de la librairie GNU history incluse avec GNU readline de version -plus ancienne que 5.0. Merci à Mike Prinat pour avoir rapporté cette erreur. +@headings 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é. -@unnumberedsec Quoi de neuf pour la version 0.2.0 ? +@headings 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. Lancer le script de démonstration -@file{test/fading.py} du packetage de base pour voir ces nouvelles capacités +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). -@unnumberedsec Détails -Allez voir @file{ChangeLog} pour obtenir l'historique complète des changements +@headings Détails +Allez voir @file{ChangeLog} pour obtenir l'historique complet des changements apportés. @ifplaintext @c Sets up a marker for automated INSTALL_FR file generation INSTALL_BEG -@node Installation d'adesklets -@unnumbered Installation d'adesklets +@node Installer adesklets +@unnumbered Installer adesklets @end ifplaintext @ifnotplaintext -@node Installation d'adesklets -@chapter Installation d'adesklets +@node Installer adesklets +@chapter Installer adesklets @end ifnotplaintext @section Pré-requis pour la compilation -Pour compiler adesklets à partir des sources, vous avez besoin de : +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} à partir de -la 2.7.0 devraient fonctionner, ou n'importe quel compilateur sorti ces dix +près toutes les versions de @weblink2{gcc,http://gcc.gnu.org} supérieures à +la 2.7.0 devraient fonctionner, ou n'importe quoi d'autre sorti ces dix dernières années) @item Les entêtes@footnote{Excepté pour les compilations sans fichiers entêtes, utile 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 : vous pouvez +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} @@ -273,57 +358,66 @@ la t un système raisonnablement compatible POSIX @end itemize -@noindent Quand présents dans le système, les composantes suivantes peuvent -également être utilisées: +@noindent Les composants suivants pourront aussi être utilisés, si ils sont +présents sur le système: @itemize @item -@weblink2{fontconfig,http://www.fontconfig.org/}, pour la détections automatiques -de l'ensemble des polices utilisables présentes dans le système +@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 probablement besoin à ce niveau : +le support pour Python (vous en aurez probablement besoin à ce niveau: c'est le seul langage de script supporté pour l'instant) @end itemize @section Note sur la portabilité @anchor{Portabilité} -Ce paquetage est construit en gardant à l'esprit la portabilité - toutes les +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) sont suivies de façon scrupuleuse. Néanmoins, tous les -développement ont été fait sur un seul système Linux : il est très probable +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 -plusieurs cas. Régler ces problèmes est important pour nous. +certains cas. Régler ces problèmes est important pour nous. -@strong{Mise à jour}: adesklets a été porté et testé avec succès par les développeurs sur plusieurs systèmes. Au moment rendre publique la version @value{VERSION}, le packetage a été compilé et utilisé avec succès sous: +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: @itemize @item Linux 2.4 i386, glibc 2.1.3, gcc 2.95.2 (Debian woody) -@item Linux 2.6 i686, glibc 2.3.4, gcc 3.4.3 (Gentoo linux 2004.2) +@item Linux 2.6 i686, glibc 2.3.4, gcc 3.4.3 (Gentoo linux 2005.0) @item Linux 2.6 amd64, glibc 2.3.3, gcc 3.4.2 (Fedora core release 3) +@item Linux 2.6 amp64, glibc 2.3.4, gcc 3.4.3 (Gentoo Linux 2005.0) @item FreeBSD i386, gcc 2.95.4 (4.10-BETA) @item NetBSD i386, gcc 2.95.3 (1.6.1) @end itemize +@strong{Update}: il a été signalé que adesklets >=0.4.8 fonctionne sur +FreeBSD 5.3, mais l'auteur n'a pas eu l'occasion de le vérifier. Maintenant +qu'adesklets est dans Debian unstable, il semble qu'il compile au moins sur +tous les noyaux et architectures disponibles: allez voir +@weblink{http://packages.debian.org/unstable/x11/adesklets}. + Vous avez vous-même essayé de faire tourner adesklets sur une architecture -non citée plus haut? Laissez-nous le savoir, surtout si ça n'a pas marché. +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) peut -être trouvée sur la page du projet située sur sourceforge : +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 à partir de la console avec @command{tar}. Avec la -version @value{VERSION}, la ligne de commande devrait être : +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 : +les filtres d'archives bzip2: @example bzcat adesklets-@value{VERSION}.tar.bz2 | tar xv @end example @@ -334,7 +428,7 @@ Pour adesklets @value{VERSION}, vous pouvez @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 appendice) pour vous assurer de +(@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: @@ -346,23 +440,22 @@ Vous pouvez l'adresse @email{syfou@@users.sourceforge.net} de plusieurs serveurs de clés publics 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 l'authenticité de cette clé. +si vous désirez vous assurer plus avant de l'authenticité de cette clé. -@section Compilation et Installation : +@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 normales : +Donc, dans la plupart des cas, l'installation suit les trois étapes habituelles: @enumerate @item -`cd' dans le répertoire contenant le code source du paquetage et tapez +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 tapez -`sh ./configure' afin de prévenir la tentative de `csh' d'exécuter lui-même -`configure'. +`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, +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 @@ -373,22 +466,24 @@ donn @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 +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), taper `make distclean'. +le paquetage pour une autre type d'ordinateur), tapez `make distclean'. -@section Compilateurs et Options : +@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 +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 : +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 qui ont le programme `env', vous pouvez faire -comme cela : + +@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 @@ -396,7 +491,7 @@ env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure @section Fonctionnalités Optionnelles : adesklets possède quelques fonctionnalités optionnelles que vous pouvez -sélectionnez ou non à partir du script de configuration. Tapez : +installer ou non à partir du script de configuration. Tapez : @example ./configure --help @@ -416,9 +511,10 @@ Vous pouvez enlever le support pour d'autres paquetages ainsi : @command{--without-history}, @command{--without-fontconfig} @end itemize -@node Utilisation d'adesklets -@chapter Utilisation d'adesklets +@node Utiliser adesklets + +@chapter Utiliser adesklets @ifplaintext INSTALL_END @@ -426,28 +522,28 @@ INSTALL_END @section ... Comme un conteneur de desklets -Par lui-même, adesklets fait peu : il fournit seulement le nécessaire et -rien de plus ! Vous avez besoin soit de lui dire ce qu'il doit faire en -lui passant la commande (voir la section suivante) soit d'autres scripts +Par lui-même, adesklets fait peu: il ne fournit que le nécessaire pour +faire plus ! Vous avez 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 Pour l'instant, il y a seulement qu'un petit nombre de desklets -disponible : vous pouvez les trouvez sur la page du projet sur sourceforge en +@noindent Pour l'instant, il n'y a qu'un petit nombre de desklets +disponibles: vous pouvez les trouver sur la page du projet sur sourceforge en tant que téléchargements séparés: -@weblink{http://sf.net/projects/adesklets/} . Ils vous donneront un aperçu +@weblink{http://sf.net/projects/adesklets/}. Ils vous donneront un aperçu de ce dont @command{adesklets} est capable. @subsection Ajouter un nouveau desklet à votre affichage X -Pour ajouter un nouveau script de desklet, il suffit simplement de : +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, tout ce dont vous avez besoin sont une installation -d'adesklets et un serveur X lancé, puis de lancer le script exécutable à +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 @@ -455,56 +551,138 @@ partir de votre r @itemize @item -Lancer le même script plusieurs fois va lancer plusieurs desklets. +Lancer le même script plusieurs fois va en créer plusieurs instances. @item -Sur les ordinateurs disposant de plusieurs moniteurs, le script sera lancé -sur son écran hérité par défaut (pour l'instant, si vous ne faites rien +Sur les ordinateurs disposant de plusieurs écrans, les script 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 aussi longtemps que vous ne leur dites pas de +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 - -le desklet n'a aucun contrôle sur ces opérations. +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 -@command{.adesklets} de votre répertoire personnel. Habituellement, vous -n'avez pas à éditer ce fichier vous-même. Si vous le faite, assurez-vous -qu'aucune instance de @command{adesklets} ne s'exécute en même temps. +@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 les 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 précédents desklets sur une nouvelles session X Invoquer @command{adesklets} sans argument : @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} -sortira rapidement par lui-même : il n'est pas besoin de les lancer en -arrière-plan. adesklets n'utilise pas de démon : chaque applet va créer un -interpréteur @command{adesklets} indépendant comme un processus fils). -Invoquer @command{adesklets} de cette façon quand des desklets sont déjà -en fonction forcera leur arrêt avant leur redémarrage@footnote{Autant -les instances d'@command{adesklets} que leurs parents immédiats recevront -alors un signal SIGKILL.}. - -@noindent Si vous pensez utilisez des desklets régulièrement, vous +terminera rapidement par lui-même : il n'y a pas besoin de les 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 précédente commande @code{adesklets} quelque part dans l'initialisation de votre session X. Je ne peux pas dire où avec précision, -puisque cela change énormément de système en système. Regardez sur : -@weblink{http://www.google.com/search?q=''x window''+startup} pour une +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. @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 : +commande. Si vous tapez, dans une console: + @example adesklets : @end example -@noindent Vous obtiendrez quelque chose de similaire à ceci : - @anchor{prompt} + +@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)] @@ -514,32 +692,34 @@ Press TAB for hints. @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 au bout des doigts. Grâce à GNU readline, beaucoup -d'auto-complétements sont disponibles, ce qui vous donne une facilité -d'utilisation. Pressez TAB dans le nom d'une commande ou sur le premier -argument vous donne des informations utiles. @xref{primer,,une introduction -à adesklets}, pour plus d'information. +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{primer} +@anchor{premiers pas} Comme expliqué ci-dessus (@xref{A propos d'adesklets}.), adesklets est -principalement une console interactive d'Imlib2, avec quelques fonctionnalités -supplémentaires : +principalement une console interactive d'Imlib2, avec une ou deux fonctions +supplémentaires: @itemize @item -Quand un affichage X est présent, gestion automatique d'une simple fenêtre. +Quand un affichage X est présent, la gestion automatique d'une +fenêtre simple. @item -Support automatique pour la pseudo-transparence +Support automatique de la pseudo-transparence @item Gestion d'applets persistants entre sessions @end itemize -@noindent Commençons un session interactive typique pour voir ce qui se -passe. Sous X, ouvrez un terminal et tapez : +@noindent Commençons une session interactive typique pour voir ce qui se +passe. Sous X, ouvrez un terminal et tapez: + @example adesklets : @end example @@ -547,7 +727,8 @@ adesklets : @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 -voir en réponse sur la sortie standard : +obtenir sur la sortie standard : + @example 2 images id 0 width 1 height 1 alpha 1 filename (null) @@ -555,28 +736,28 @@ 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 : image 0 et image 1, -et quelles ont une taille de 1x1 pixel. Ceux sont les seules images que +@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 pouvez jamais détruire ni modifier comme vous le souhaitez (les -redimensionner indépendamment, les retourner diagonalement, etc. Lisez ce -qui suit pour savoir pourquoi.) +redimensionner indépendamment, les retourner diagonalement, etc.) +Qu'est-ce que c'est que cela? @itemize @item -Image 0 est l'image d'avant-plan. Par défaut, elle est la seule image qui -est affichée dans une simple fenêtre gérée par @command{adesklets}. +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) directement sous cette fenêtre : sans +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, lorsqu'il la redimensionne, lorsque le fond d'écran change, etc. +la déplace, la redimensionne, lorsque le fond d'écran change, etc. @end itemize -@noindent Mais ou sont ces fenêtres ? Pour l'instant ce sont seulement des -images de 1x1 pixel, et elles ne sont pas montrées@footnote{"Mappé" dans un -patois de X Window} à l'écran. Ainsi, redimensionnons les à 100x100 pixels : +@noindent Mais ou 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 : +'@code{images_info}', vous obtiendrez: @example 2 images id 0 width 100 height 100 alpha 1 filename (null) @@ -584,78 +765,80 @@ 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 +@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 +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être "géré" 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 construite pour ne jamais être en avant-plan et pour rester affichée +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. +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 (avant-plan) est affichée par +@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 en dessous ! Avec "window transparency" +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{Bien... Pas tout à fait : il y a un buffer qui est mise -en jeu pour la performance, mais l'opération est logiquement équivalente à +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 qu'adesklets -est une console d'Imlib2 : en conséquence, comme Imlib2@footnote{Gardez -votre documentation d'Imlib2 à proximité : c'est très utile - -@weblink{http://atmos.org/docs/imlib2/index.html} fournit une agréable -introduction, bien qu'un peu ancienne.}, les couleurs sont toujours de +@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 (transparence). La conversion de palette se -fait automatiquement si la profondeur de votre écran est inférieure, vous -n'avez pas à vous en occuper. Si vous tapez : '@code{context_get_color}', -vous obtiendrez : +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 le roi de l'état de la machine ; ainsi, il vient avec un +@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 -des opérations futures. Par exemple, nous savons maintenant que la couleur +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, bleue=255, vert=255, alpha=255). Si nous tapons : -'@code{context_get_image}', il nous retourne : +blanc opaque (rouge=255, bleue=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 -est directement fait sur l'image d'avant-plan. Dessinons un rectangle plein -semi-transparent de couleur magenta sur l'avant-plan. La commande pourra ê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 ? +50 50}'. Élégant, n'est-ce pas? -@noindent Si vous avez l'habitude de programmer avec Imlib2, vous devriez -avoir remarqué que ces dernières commandes vous sont familières. C'est -normal : la plupart des fonctions C d'Imlib2 sont présentées de +@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}' que la fonction '@code{imlib_context_set_color()}', -etc. Les deux seules différences significatives (et systématiques) sont que +'@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 entier ID avec adesklets, et dans la sémantique des fonctions -'@code{imlib_free_Quelquechose()}' on a besoin de donner un entier ID au -lieu d'un objet de ce type permettant de libérer le contexte sélectionné. +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 Illustrons cela. Chargeons la police "Vera" inclue dans adesklets -à la taille 20pt, mettons la en police par défaut, et écrivons dans un bloc -blanc opaque 'Hello' en diagonale sur l'image d'avant-plan du coin haut -gauche avant de décharger la police. Cela devrait ressembler à : +@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 @@ -675,18 +858,18 @@ 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 de dire : toutes les -références à la police Vera/20 sont faites par un entier ID (0 ici), et +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 appelée avec l'ID de la police comme argument -plutôt que le contexte de la police. - -@noindent A partir de là, imaginons que vous voulez sauver l'image résultante -; ce n'est pas un problème - tapons : '@code{save_image out.png}', et -l'avant-plan est sauvé dans un fichier "out.png" dans le répertoire de -travail courant@footnote{Pour que ça marche, vous avez besoin d'avoir une -installation d'Imlib2 proprement configuré pour utiliser libpng, ou vous -risquez de recevoir une erreur "no loader for file format".}. Maintenant, +plutôt qu'avec 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 @@ -709,58 +892,59 @@ command 5 ok: window_show command 6 ok: free_image 2 @end example -@noindent Bien sur, nous voulons visualiser le résultat - c'est -pourquoi nous avons utilisez les commandes '@code{window_reset}', -'@code{window_set_transparency}' et '@code{window_show}' : elles n'ont -pas d'autres utilités. La commande '@code{blend_image_onto_image}' vient -droit de Imlib2 aussi ; elle prend la nouvelle image 2 que l'on vient de -crée lors de la troisième commande, et la met dans un contexte d'image -(image 0 - avant-plan par défaut), à partir de ces coordonnées (0,0) pour -une taille de 100x100 pixels, et la met dans un rectangle allant de (0,0) -et de taille 100x100 pixels de 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 essayer de libérer l'image courante, le contexte d'image est -remis à l'image d'avant-plan. - -@noindent D'accord, c'est presque la fin de cette introduction. A partir de -là vous pouvez jouer avec adesklets - il est vraiment facile de l'utiliser si -vous vous êtes déjà familiarisé avec Imlib2. Sinon, votre meilleure ressource -est certainement d'avoir la documentation d'Imlib2 pas trop loin. :-) - -@noindent Quelques dernières astuces : +@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 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, et taper, n'oubliez pas l'auto-complémentation : -'TAB' vos problèmes au loin ! +Si vous êtes fatigué de taper encore et encore, n'oubliez pas +l'auto-complétion: 'TAB your problems away!' @item -Si vous voulez avoir de l'aide sur comment faire quelque chose, il existe +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 tous -cet usage interactif vous fatigue : +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 afficher votre session courante -dans un fichier@footnote{Pour que ça marche, vous avez besoin d'avoir GNU -history lorsque vous compilez adesklets.}. +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 prendre une commande à partir +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 qui se trouve après le dièse '#' jusqu'à la fin de la -ligne seront enlevés (Cela est utile pour écrire des commentaires). +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 : +@noindent Voici un exemple: @example #!/usr/bin/env adesklets -f -# Rendre la fenêtre 'géré' +# Rendre la fenêtre 'gérée' # window_reset managed @@ -775,108 +959,1108 @@ pause 10 @end example @noindent Vous aurez juste besoin de rendre ce script exécutable et de le -lancer. Comme d'habitude, les sorties 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 véritable travail@footnote{:-)}, vous pourrez -vouloir utilisé un véritable langage de script plutôt que le rudimentaire -interpréteur @command{adesklets} que nous avons utilisé dans l'introduction ; -vous ne savez jamais quand les variables sont accessibles. - -Au moment ou j'écris ces lignes (@value{UPDATED}), seul le support pour -Python est complet@footnote{adesklets a été écrit pour être facile d'usage -pour différents langages interprétés ; le futur développement inclue des -encapsulations pour Perl et Ruby - n'hésitez pas à proposer votre aide si vous -voulez accélérer les choses.}. A partir de python, les choses ne sont pas très -différentes qu'à partir 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. Jetez -un coup d'oeil sur le script @file{test/test.py} de l'archive source de la -version @value{VERSION} : +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 déjà inclus@footnote{adesklets a été écrit pour être facilement +utilisé depuis toutes sortes de langages interprétés; des interfaces +pour Perl et Ruby sont en projet - n'hésitez pas à proposer votre aide si vous +voulez accélérer les choses!}, et la mise en place de Perl 5 est en route. + +@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, ça peut être utile 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 ligne de code python, et nous avons un desklet parfaitement -fonctionnel. Je pense que cela s'explique tout seul : jetez un coup d'oeil à -l'aide intégrée de python pour @code{adesklets}, @code{adesklets.functions} -et @code{adesklets.Events_handler} pour une bonne et complète explication. En -deux mots, tout ce que nous avons fait ici c'est : +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 : -quand l'initialisation du paquetage ne retourne pas d'exception, cela signifie -que l'interpréteur tourne et est prêt à accepter des commandes. +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 des -méthodes invoquées pour les événements qui nous intéresse (tous les autres +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 mettre en boucle infinie -@footnote{Cette dernière étape n'est pas obligatoire : le script peut -très bien continuer, mais il a été écrit ainsi pour supporter les signaux -d'interruptions. Regarder `@code{help(adesklets.Events_handler)}' pour de +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 -@noindent Enfin, mentionnons que vous pouvez regarder dans le code -source du desklet @file{weather} du @weblink2{site web du projet situé sur -sourceforge,http://sourceforge.net/projects/adesklets/} pour un script python -pour adesklets plus conséquent. +@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==1}, et @code{im_2==2}. 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_1}) +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. +Ansi, 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 Utilisation d'adesklets à partir d'autres languages +@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 sopport 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émmarer tous les desklets +@noindent Dans une nouvelle session X, la séquence de démmarage 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émmaré 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 -[ Traduction en attente ] +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 -Votre aide est la bienvenue! Plusieurs avenue vous permettent de -contribuer significativement à adesklets. Vous pourriez: +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 dans sa petite +enfance: 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 de nouveaux langages}. 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} + +@section Démmarer des desklets + +@subsection 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 + +@subsection Quand j'essaie de démmarer un nouveau desklet, j'obtiens l'erreur @code{ADESKLETSError: adesklets process exited} de l'interpréteur Python. Qu'est-ce que c'est? + +Sur certains systèmes rares (@weblink2{archlinux,http://www.archlinux.org/} par exemple), +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 appropriée @code{--prefix} lors de la configuration. +Par exemple, sur la plupart des plate-formes Linux récentes, vous +devriez utiliser: + +@example +./configure --prefix=/usr +@end example + +@subsection Tout a bien fonctionné mais ensuite j'ai essayé de mettre à jour un desklet, et je n'ai jamais pu 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}. + +@subsection Argh! Le desklet X marche, mais ne se souvient pas de ses paramètres, ou bien il démmare 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émmaré 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. + +@subsection C'est exactement ce que j'ai fait, mais ce truc ne veut toujours pas redémmarer. + +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). + +@section Afficher les desklets + +@subsection Où sont mes desklets? L'interpréter d'@command{adesklets} semble être lancé correctement, mais je ne vois tout simplement rien sur mon bureau! + +Essayez la commande: + +@example +python test/test.py +@end example + +@noindent depuis le répertoire de base des sources. Si une fenêtre de 100 sur +100 pixels apparaît, ce signifie très probablement que vous utilisez un +gestionnaire de fenêtres qui dessine une grosse fenêtre par dessus la fenêtre +racine; vous desklets sont juste dessinés sous celle-ci. Parmi ces gestionnaires +de fenêtres on trouve Nautilus, KDE, Xfce4, CDE ou E17. Actuellement, Nautilus, +KDE, et Xfce4 sont pris en charge automatiquement, mais les autres ne le sont pas. + +Toute l'infrastructure nécessaire est déjà en place. Dans la plupart des cas, +seule la fonction @code{xwindow_get_root_window()} de @file{src/xwindow.c} doit +être complétée pour détecter de nouveaux gestionnaires de fenêtres. Vous pouvez +soit soumettre un patch, ou le demander sur la +@weblink2{mailing-list de développement d'adesklets,http://lists.sourceforge.net/lists/listinfo/adesklets-devel}. + +@subsection 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. + +@subsection 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. + +@section Utiliser les desklets + +@subsection 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. + +@subsection 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. + +@subsection 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 -@strong{Aider à la traduction}. Ce manuel en français n'est malheureusement -plus à jour. Si vous êtes un locuteur francophone lisant bien l'anglais, -votre aide serait très appréciée pour maintenir ce document. -@item -@strong{Poster en ligne vos captures d'écran}. Vous êtes un utilisateur -de adesklets et pensez avoir un bureau spécialement réussi? Partager-le -avec le monde, et laissez-le nous savoir; vous en aiderez ainsi d'autres -à entendre parler du projet. -@item -@strong{Écrire de nouveau desklets}. adesklets est encore en petite -enfance : nous sollicitons les talentueux compositeurs de desklets, et nous serions -plus qu'enchanté de poster ou de faire des liens vers leur travail en la matière. -Qu'il ne s'inquiète pas des changements d'interface : nous avons apassé -beaucoup de temps à y réfléchir, et si on ne peut garantir la stabilité absolue -de l'API, même pour une version si précoce, il devrait malgré tout rester -relativement fixe; nous nous attendons en fait bien davantage à résoudre -des bogues et à apporter des changements internes relatifs à la portabilité -qu'à toute autre chose. -@item @strong{Ajouter des interfaces pour de nouveau langages}. Contactez -les développeurs avant de commencer question de ne pas perdre de temps si quelque -chose de déjà écrit: ils seront heureux de partager leur code avec vous. -Inscrivez-vous à la @weblink2{liste d'envois -adesklets-devel,https://lists.sourceforge.net/lists/listinfo/adesklets-devel} sur sourceforge pour un accès direct à ceux-là. +@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 -@noindent Contactez-moi par email à @email{syfou@@users.sourceforge.net}. +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 -@node Questions fréquemment posées -@appendix Questions fréquemment posées +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. + +@subsection 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 -[ Traduction en attente ] +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 (esperons-le). + +@subsection 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:: Licence sous laquelle copier ce manuel. +* 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 diff --git a/site/news/033.txt b/site/news/033.txt new file mode 100644 index 0000000..36a992c --- /dev/null +++ b/site/news/033.txt @@ -0,0 +1,4 @@ +@Sun Aug 28 20:59:26 UTC 2005@ +Updated French documentation + +adesklets french documentation has been brought back up to speed with the original version. A big thanks to Martin Kirchgessner for its hard work! -- 2.11.4.GIT