[ précédent ] [ Table des matières ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 10 ] [ 11 ] [ 12 ] [ A ] [ B ] [ C ] [ D ] [ E ] [ F ] [ G ] [ suivant ]


La Charte Debian
Chapitre 12 - La documentation


12.1 Les pages du manuel

On installera les pages de manuel sous la forme d'un source nroff, à l'emplacement approprié dans /usr/share/man. Vous utiliserez uniquement les sections 1 à 9 (voir le FHS pour plus de détails). Vous ne devez pas installer de pages « cat » préformatées.

Chaque programme, utilitaire ou fonction aura une page de manuel associée dans le même paquet. On suggère aussi que chaque fichier de configuration ait une page de manuel associée. Pour des protocoles ou des programmes secondaires, les pages de manuel sont facultatives.

L'absence de page de manuel est considérée comme un bogue et un rapport sera envoyé au système Debian de suivi de bogues (le responsable du paquet peut écrire lui-même ce rapport, s'il le souhaite). On ne doit pas fermer le rapport tant que la page de manuel n'est pas disponible [78].

Vous pouvez faire suivre une plainte concernant l'absence d'une page du manuel aux auteurs originaux, et signaler qu'un rapport de bogue a été envoyé au système Debian de suivi des bogues. Même si le projet GNU ne considère pas en général l'absence d'une page du manuel comme un bogue, nous oui. S'ils vous répondent qu'ils ne considèrent pas cela comme un bogue, laissez quand même le bogue ouvert dans notre système de suivi.

Les pages de manuel seront installées comprimées avec gzip -9.

Si une page de manuel doit être accessible via différents noms, il est préférable d'utiliser un lien symbolique plutôt que la fonctionnalité .so, mais il est inutile de bricoler les parties incriminées dans les sources originaux pour changer les .so en liens symboliques (à moins que ce soit trivial). Ne créez pas de lien physique dans les répertoires des pages du manuel et ne mettez pas de chemin absolu dans les directives .so. Le nom du fichier dans le .so d'une page du manuel sera relatif à la racine des pages (habituellement /usr/share/man). Si l'on ne crée pas de liens (liens symboliques, liens « en dur » ou des directives .so) dans le système de fichiers pour les autres noms de cette page, on ne comptera pas sur man pour trouver la page de manuel sous ces noms à partir des seuls renseignements contenus dans l'en-tête de la page[79].


12.2 Les documents « Info »

On installera les documents « Info » dans /usr/share/info. Ils seront comprimés avec gzip -9.

Votre paquet appellera install-info, dans le script postinst, appelé par exemple avec un argument configure, pour mettre à jour le fichier dir de « Info » :

     install-info --quiet --section Development Development \
     /usr/share/info/foobar.info

Il est judicieux de spécifier une section pour l'emplacement de votre programme ; cela se fait avec l'option --section. Pour déterminer la section à utiliser, vous devez consulter /usr/share/info/dir sur votre système et choisir la plus adéquate (ou créer une nouvelle section si aucune des sections actuelles n'est adaptée). Notez que l'option --section prend deux arguments ; le premier est une expression régulière pour rechercher une section existante (indépendamment de la casse), le second est utilisé pour la création d'une nouvelle section.

Vous retirerez les entrées dans le script prerm appelé avec un argument remove :

     install-info --quiet --remove /usr/share/info/foobar.info

Si install-info ne trouve pas une entrée descriptive dans le fichier Info, vous devrez en fournir une. Voir install-info(8) pour des précisions.


12.3 Documentations supplémentaires

Le responsable d'un paquet peut installer toute documentation supplémentaire qui vient avec ce paquet. Les documents texte seront placés dans le répertoire /usr/share/doc/paquet, et comprimés avec gzip -9 à moins qu'ils soient petits.

Si un paquet contient une importante documentation dont la majorité des utilisateurs du paquet n'a pas besoin, vous la mettrez dans un paquet binaire distinct. Ainsi elle ne prendra pas d'espace disque sur les machines des utilisateurs qui n'en ont pas besoin ou qui ne veulent pas l'installer.

Il est souvent judicieux de mettre les fichiers d'informations (README, changelogs, etc.) provenant du paquet source dans /usr/share/doc/paquet au sein des paquets binaires. Bien entendu, vous n'avez pas besoin de fournir les instructions de compilation et d'installation.

Aucun programme ne demandera, pour son fonctionnement, que des fichiers existent dans /usr/share/doc [80]. Tout fichier référencé par un programme et qui est utile en tant que documentation indépendante sera installé dans /usr/share/paquet/ et lié symboliquement avec /usr/share/doc/paquet/.

/usr/share/doc/paquet peut être un lien symbolique vers un autre répertoire de /usr/share/doc seulement si les deux paquets proviennent de la même source et si le premier paquet dépend du second. [81]

Les précédentes versions de Debian plaçaient toute la documentation supplémentaire dans /usr/doc/paquet. C'est maintenant /usr/share/doc/paquet, et les paquets ne doivent pas mettre de la documentation dans le répertoire /usr/doc/paquet [82].


12.4 Les formats préférés pour la documentation

L'unification de la documentation Debian se fait autour du format HTML.

Si votre paquet comprend une importante documentation dans un format balisé qui peut être converti en d'autres formats, vous livrerez si possible la version HTML dans le paquet binaire, dans le répertoire /usr/share/doc/paquet-approprié ou l'un de ses sous-répertoires [83].

Le responsable de paquet peut fournir à sa guise d'autres formats, comme PostScript.


12.5 Les informations de copyright

Chaque paquet doit être accompagné d'une copie verbatim de son copyright ainsi que de sa licence de distribution dans le fichier /usr/share/doc/paquet/copyright. Ce fichier ne doit pas être comprimé ni être un lien symbolique.

De plus, le fichier de copyright doit préciser où ont été obtenus les fichiers sources originaux (s'ils existent). Il nommera les auteurs originaux et le(s) responsable(s) Debian qui ont œuvré à la création du paquet.

Une copie du fichier installé dans /usr/share/doc/paquet/copyright sera faite dans le debian/copyright du paquet source.

/usr/share/doc/paquet peut être un lien symbolique vers un répertoire de /usr/share/doc seulement si, de deux paquets provenant tous les deux de la même source, le premier possède une relation « Depends » avec le second. Ces règles sont importantes car on doit pouvoir extraire les copyrights par des moyens automatiques.

Les paquets distribués sous la licence « UCB BSD », la licence « Artistic », la licence « GNU GPL » ou la licence « GNU LGPL » feront respectivement référence aux fichiers correspondants sous /usr/share/common-licenses,[84] plutôt que de les citer dans le fichier de copyright.

Vous ne devez pas utiliser le fichier copyright comme un fichier README général. Si votre paquet possède un tel fichier, vous l'installerez dans /usr/share/doc/paquet/README ou README.Debian ou dans un autre endroit approprié.


12.6 Exemples

On installera tous les exemples (configuration, fichiers source, autres) dans un répertoire /usr/share/doc/paquet/examples. Ces fichiers ne seront pas utilisés par un quelconque programme. Ils ne sont là qu'en tant que documentation, et pour le seul bénéfice de l'administrateur système et des utilisateurs. On installera les exemples concernant une architecture particulière dans un répertoire /usr/lib/paquet/examples et les fichiers dans /usr/share/doc/paquet/examples seront des liens symboliques. Ou bien, ce dernier répertoire sera un lien vers le premier.

Si le but d'un paquet est de fournir des exemples, les fichiers d'exemples peuvent être installés dans /usr/share/doc/paquet.


12.7 Les fichiers « Changelog »

Les paquets qui ne sont pas originaires de Debian doivent contenir, dans /usr/share/doc/paquet, une copie compressée nommée changelog.Debian.gz du fichier debian/changelog qui est dans l'arborescence des sources.

S'il existe un « changelog » original, il sera accessible comme un fichier texte, /usr/share/doc/paquet/changelog.gz. Si le « changelog » original est distribué comme un fichier HTML, il sera rendu disponible en tant que /usr/share/doc/paquet/changelog.html.gz et le changelog.gz sera produit en utilisant p. ex. lynx -dump -nolist. Si le changelog original n'est pas déjà conforme à cette convention, alors cela peut être réalisé soit en renommant ce fichier soit en créant un lien symbolique, c'est à la convenance du responsable du paquet[85].

Ces fichiers seront installés comprimés par gzip -9, car ils grossissent avec le temps même s'ils commencent petitement.

Quand un paquet a un seul changelog, utilisé à la fois comme changelog Debian et changelog original car le responsable principal est le même que le responsable Debian, on appellera simplement ce changelog : /usr/share/doc/paquet/changelog.gz. S'il y a un responsable principal mais pas de changelog source, on appellera toujours le changelog Debian : changelog.Debian.gz.

Pour des précisions sur le format et le contenu d'un fichier changelog de Debian, voyez Changelog Debian : debian/changelog, Section 4.4.


[ précédent ] [ Table des matières ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 10 ] [ 11 ] [ 12 ] [ A ] [ B ] [ C ] [ D ] [ E ] [ F ] [ G ] [ suivant ]


La Charte Debian

version 3.7.2.2

La liste de diffusion Debian-Policy