22.8.4 Synopsis et descriptions

Comme nous l’avons vu avant, chaque paquet dans GNU Guix contient un résumé et une description (voir Définition des paquets). Les résumés et les descriptions sont importants : ce sont eux que recherche guix package --search, et c’est une source d’informations cruciale pour aider les utilisateur·rices à déterminer si un paquet donné correspond à leurs besoins. En conséquence, il convient de prêter attention à leur contenu lorsqu’on travaille sur un paquet.

Les résumés doivent commencer par une lettre capitale et ne doit pas finir par un point. Ils ne doivent pas commencer par « a » ou « the » (« un » ou « le/la »), ce qui n’apporte généralement rien ; par exemple, préférez « File-frobbing tool » (« Outil de frobage de fichier ») à « A tool that frobs file » (« Un outil qui frobe les fichiers »). Le résumé devrait dire ce que le paquet est — p. ex. « Utilitaire du cœur de GNU (fichier, text, shell) » — ou ce à quoi il sert — p. ex. le résumé de grep est « Affiche des lignes correspondant à un motif ».

Gardez à l’esprit que le résumé doit avoir du sens pour un large public. Par exemple « Manipulation d’alignements au format SAM » peut avoir du sens pour un bioinformaticien chevronné, mais n’aidera pas ou pourra perdre une audience de non-spécialistes. C’est une bonne idée de créer un résumé qui donne une idée du domaine d’application du paquet. Dans cet exemple, cela donnerait « Manipulation d’alignements de séquences de nucléotides », ce qui devrait donner une meilleure idée à la personne qui le lit pour savoir si c’est ce qu’elle recherche.

Les descriptions devraient faire entre cinq et dix lignes. Utilisez des phrases complètes, et évitez d’utiliser des acronymes sans les introduire d’abord. Évitez les expressions commerciales comme « world-leading », « industrial-strength » et « next-generation » et évitez les superlatifs comme « the most advanced » — ils ne sont pas utiles aux personnes qui cherchent un paquet et semblent même un peu suspects. À la place, essayez d’être factuels, en mentionnant les cas d’utilisation et les fonctionnalités.

Les descriptions peuvent inclure du balisage Texinfo, ce qui est utile pour introduire des ornements comme @code ou @dfn, des listes à points ou des hyperliens (voir Overview dans GNU Texinfo). Cependant soyez prudents lorsque vous utilisez certains symboles, par exemple ‘@’ et les accolades qui sont les caractères spéciaux de base en Texinfo (voir Special Characters dans GNU Texinfo). Les commandes et outils comme guix show prennent en charge le rendu.

Les résumés et les descriptions sont traduits par des volontaires sur Weblate pour que le plus de personnes possible puissent les lire dans leur langue natale. Les interfaces les recherchent et les affichent dans la langue spécifiée par le paramètre de régionalisation actuel.

Pour permettre à xgettext de les extraire comme des chaînes traduisibles, les résumés et les descriptions doivent être des chaînes litérales. Cela signifie que vous ne pouvez pas utiliser string-append ou format pour construire ces chaînes :

(package
  ;; …
  (synopsis "Ceci est traduisible")
  (description (string-append "Ceci n'est " "*pas*" " traduisible.")))

La traduction demande beaucoup de travail, faites donc d’autant plus attention à vos résumés et descriptions lorsque vous développez un paquet car chaque changement peut demander du de travail de la part des traducteur·rices. Pour les aider, il est possible de donner des recommandations ou des instructions qu’ils et elles pourront voir en insérant des commentaires spéciaux comme ceci (voir xgettext Invocation dans GNU Gettext) :

;; TRANSLATORS: "X11 resize-and-rotate" should not be translated.
(description "ARandR is designed to provide a simple visual front end
for the X11 resize-and-rotate (RandR) extension. …")