debhelper.fr

title: debhelper.fr(7)

text:
# debhelper.fr(7)

## NOM
debhelper - Ensemble d'outils regroupés sous le nom de debhelper

## SYNOPSIS
dh_* [-v] [-a] [-i] [-s] [--no-act] [-ppaquet] [-Npaquet] [-Ptmpdir]

## DESCRIPTION
Debhelper facilite la construction des paquets Debian. La philosophie qui sous-tend debhelper est de fournir une collection de petits outils simples et facilement compréhensibles qui seront exploités dans debian/rules pour automatiser les tâches courantes liées à la construction des paquets, d'où un travail allégé pour le responsable. Dans une certaine mesure, cela signifie également que ces outils peuvent être adaptés aux modifications éventuelles de la Charte Debian. Les paquets qui utiliseront debhelper ne nécessiteront qu'une simple reconstruction pour être conformes aux nouvelles règles.

Un fichier debian/rules typique, exploitant debhelper, appellera séquentiellement plusieurs des commandes de debhelper ou bien utilisera dh(1) pour automatiser ce processus. Des exemples de fichiers debian/rules qui exploitent debhelper se trouvent dans /usr/share/doc/debhelper/examples/

Pour créer un nouveau paquet Debian en utilisant debhelper, il suffit de copier un des fichiers d'exemple et de le modifier manuellement. Il est possible également d'essayer le paquet dh-make qui contient une commande dh_make automatisant partiellement le processus. Pour se familiariser avec ces concepts, le paquet Debian maint-guide contient un cours sur la construction d'un premier paquet avec debhelper.

## COMMANDES DE DEBHELPER
Voici la liste des commandes debhelper disponibles. Consulter leurs pages de manuel respectives pour obtenir des informations complémentaires.

dh_auto_build(1)

Construire automatiquement un paquet

dh_auto_clean(1)

Faire le ménage automatiquement après une construction de paquet

dh_auto_configure(1)

Configurer automatiquement un paquet préalablement à sa construction

dh_auto_install(1)

Lancer automatiquement make install ou équivalent

dh_auto_test(1)

Exécuter automatiquement le jeu d'essai d'un paquet

dh_bugfiles(1)

Installer les fichiers de personnalisation de rapports de bogue dans les répertoires des paquets construits

dh_builddeb(1)

Construire des paquets binaires Debian

dh_clean(1)

Nettoyer les répertoires de construction du paquet

dh_compress(1)

Compresser les fichiers dans le répertoire de construction du paquet et modifier les liens symboliques en conséquence

dh_fixperms(1)

Ajuster les droits sur les fichiers du répertoire de construction du paquet

dh_gconf(1)

Installer les fichiers par défaut de GConf et inscrit les schémas

dh_gencontrol(1)

Produire et installer le fichier de contrôle

dh_icons(1)

Update caches of Freedesktop icons

dh_installcatalogs(1)

Installer et inscrire les catalogues SGML

dh_installchangelogs(1)

Installer les journaux de suivi des modifications (changelog) dans les répertoires de construction du paquet

dh_installcron(1)

Installer les scripts cron dans etc/cron.*

dh_installdeb(1)

Installer des fichiers dans le répertoire DEBIAN

dh_installdebconf(1)

Installer les fichiers utilisés par debconf dans les répertoires de construction du paquet

dh_installdirs(1)

Créer des sous-répertoires dans le répertoire de construction du paquet

dh_installdocs(1)

Installer la documentation dans le répertoire de construction du paquet

dh_installemacsen(1)

Inscrire un paquet additionnel Emacs

dh_installexamples(1)

Installer les fichiers d'exemples dans le répertoire de construction du paquet

dh_installifupdown(1)

Installer les accroches (hooks) if-up et if-down

dh_installinfo(1)

Installer les fichiers info

dh_installinit(1)

Installer les fichiers de service « init » dans le répertoire de construction du paquet

dh_installlogcheck(1)

Installer les fichiers de règles de vérification des journaux (logcheck rulefiles) dans etc/logcheck/

dh_installlogrotate(1)

Installer les fichiers de configuration de la rotation des journaux (logrotate)

dh_installman(1)

Installer les pages de manuel dans le répertoire de construction du paquet

dh_installmenu(1)

Installer les fichiers du menu Debian dans le répertoire de construction du paquet

dh_installmime(1)

Installer les fichiers « mime » dans le répertoire de construction du paquet

dh_installmodules(1)

register kernel modules

dh_installpam(1)

Installer les fichiers de support de PAM

dh_installppp(1)

Installer les fichiers ppp.ip-up et ppp.ip-down

dh_installudev(1)

Installer les fichiers de règles udev

dh_installwm(1)

Inscrire un gestionnaire de fenêtre (window manager)

dh_installxfonts(1)

Inscrire les polices de caractères graphiques (X fonts)

dh_link(1)

Créer les liens symboliques dans le répertoire de construction du paquet

dh_lintian(1)

Installer les fichiers « override » de lintian dans le répertoire de construction du paquet

dh_listpackages(1)

Énumérer les paquets binaires que debhelper va traiter

dh_makeshlibs(1)

Créer automatiquement le fichier shlibs et exécuter dpkg-gensymbols

dh_md5sums(1)

Créer le fichier DEBIAN/md5sums

dh_movefiles(1)

Déplacer des fichiers depuis debian/tmp dans des sous-paquets

dh_perl(1)

Déterminer les dépendances Perl et fait le ménage après MakeMaker

dh_prep(1)

Faire le ménage en vue de construire un paquet Debian

dh_shlibdeps(1)

Déterminer les dépendances envers les bibliothèques partagées

dh_testdir(1)

Vérifier le répertoire avant de construire un paquet Debian

dh_testroot(1)

Vérifier que le paquet est construit par le superutilisateur (root)

dh_usrlocal(1)

Migrer les répertoires usr/local dans les scripts de maintenance du paquet

### Commandes obsolètes
Quelques commandes debhelper sont obsolètes et ne devraient plus être utilisées.

dh_desktop(1)

Obsolète, ne pas l'utiliser

dh_installmanpages(1)

ancien programme d'installation des pages de manuel (obsolète)

dh_scrollkeeper(1)

Obsolète, ne pas l'utiliser

dh_suidregister(1)

Programme d'inscription suid (obsolète)

dh_undocumented(1)

Programme de création de liens symboliques vers « undocumented.7 » (obsolète, ne pas l'utiliser)

### Autres commandes
Si le nom d'un programme commence par dh_ et qu'il n'est pas dans les listes ci-dessus, cela signifie qu'il ne fait pas partie de la suite debhelper. Cependant, il devrait tout de même fonctionner comme les autres programmes décrits dans cette page.

## FICHIERS DE CONFIGURATION DE DEBHELPER
Beaucoup de commandes de debhelper utilisent des fichiers du répertoire debian/ pour piloter leur fonctionnement. Outre les fichiers debian/changelog et debian/control, qui se trouvent dans tous les paquets, et pas seulement dans ceux qui emploient debhelper, d'autres fichiers peuvent servir à configurer le comportement des commandes spécifiques de debhelper. Ces fichiers sont, en principe, nommés debian/paquet.toto (où paquet est, bien sûr, à remplacer par le nom du paquet concerné).

Par exemple, dh_installdocs utilise un fichier appelé debian/package.docs pour énumérer les fichiers de documentation qu'il installera. Consulter les pages de manuel des différentes commandes pour connaître le détail des noms et des formats des fichiers employés. D'une façon générale, ces fichiers de configuration énumèrent les fichiers sur lesquels devra porter l'action, à raison d'un fichier par ligne. Quelques programmes de debhelper emploient des paires fichier/destination voire des formats légèrement plus compliqués.

Nota : pour le premier (ou le seul) paquet binaire énuméré dans le fichier debian/control, debhelper exploitera debian/toto quand aucun fichier debian/paquet.toto n'est présent.

Dans quelques rares cas, il peut être utile d'exploiter différentes versions de ces fichiers pour des architectures ou des systèmes d'exploitation différents. S'il existe des fichiers appelés debian/paquet.toto.ARCH ou debian/paquet.toto.OS, dans lesquels ARCH et OS correspondent respectivement au résultat de « dpkg-architecture -qDEB_HOST_ARCH » ou de « dpkg-architecture -qDEB_HOST_ARCH_OS », alors ils seront utilisés de préférence aux autres fichiers plus généraux.

En général, ces fichiers de configuration sont employés pour indiquer des listes de divers types de fichiers. Documentation, fichiers d'exemples à installer, fichiers à déplacer et ainsi de suite. Lorsque cela se justifie, dans des cas comme ceux-ci, il est possible d'employer, dans ces fichiers, les jokers (wildcard) standard de l'interpréteur de commandes (shell) (? et * et [..]). Des commentaires peuvent être ajoutés dans ces fichiers : les lignes commençant par # sont ignorées.

La syntaxe de ces fichiers est volontairement gardée très simple pour les rendre faciles à lire, comprendre et modifier. Si vous préférez la puissance et la complexité, vous pouvez rendre le fichier exécutable, et écrire un programme qui affiche n'importe quel contenu approprié à la situation. Dans ce cas, la sortie n'est plus traitée pour développer les jokers (wildcards) ou supprimer les commentaires.

## OPTIONS PARTAGÉES DE DEBHELPER
Tous les programmes de debhelper acceptent les options suivantes.

-v, --verbose

Mode verbeux : affiche toutes les commandes qui modifient le répertoire de construction du paquet.

--no-act

Empêche la construction de s'effectuer réellement. Si cette option est utilisée avec -v, le résultat sera l'affichage de ce que la commande aurait fait.

-a, --arch

Construit tous les paquets dépendants de l'architecture.

-i, --indep

Construit tous les paquets indépendants de l'architecture.

-ppaquet, --package=paquet

Construit le paquet nommé « paquet ». Cette option peut être répétée afin de faire agir debhelper sur plusieurs paquets.

-s, --same-arch

Cette option était plus intelligente que l'option -a, mais l'option -a est maintenant tout aussi intelligente.

-Npaquet, --no-package=paquet

Exclut le paquet indiqué du processus de construction, même si l'option -a, -i ou -p l'impliquait.

--remaining-packages

Exclut du processus de construction les paquets qui ont déjà été construits préalablement par cette commande debhelper (c'est-à-dire, si la commande est présente dans le journal de debhelper du paquet). Par exemple, si vous avez besoin d'invoquer la commande avec des options spéciales seulement pour certains paquets binaires, utilisez cette option lors de la dernière invocation de la commande pour construire le reste des paquets avec les options par défaut.

--ignore=fichier

Ignore le fichier indiqué. Cela peut être utilisé si debian/ contient un fichier de configuration debhelper avec une commande qui ne doit pas être pris en compte. Nota : debian/compat, debian/control, et debian/changelog ne peuvent pas être ignorés, mais il n'existe aucune raison valable de les ignorer. Par exemple, si vous récupérez en amont un fichier debian/init que vous ne voulez pas que dh_installinit installe, utilisez --ignore=debian/init

-Ptmpdir, --tmpdir=tmpdir

Utilise le répertoire tmpdir pour construire les paquets. Sinon, par défaut, le répertoire utilisé est « debian/paquet »

--mainpackage=paquet

Cette option, peu utilisée, indique à debhelper le nom du « paquet principal » pour lequel les fichiers debian/toto peuvent être utilisés à la place des fichiers habituels debian/paquet.toto. Par défaut, debhelper considère que le « paquet principal » est le premier paquet énuméré dans le fichier debian/control.

-O=option|ensemble

Cette option est utilisée par dh(1) pour passer une ou plusieurs options, indiquées par l'utilisateur, à toutes les commandes exécutées. Si la commande prend en charge l'option ou l'ensemble d'options, elle prendra effet. Si la commande n'accepte pas l'option (ou une partie de l'ensemble d'options), elle sera ignorée.

## OPTIONS COURANTES DE DEBHELPER
Certains programmes de debhelper acceptent les options ci-dessous. Consulter la page de manuel de chaque programme pour une explication complète du rôle de ces options.

-n

Ne pas modifier les scripts de maintenance du paquet (postinst, postrm, etc.).

-Xélément, --exclude=élément

Permet d'exclure un élément du traitement. Cette option peut être employée plusieurs fois afin d'exclure plusieurs éléments. L'élément est en général une partie du nom de fichier, et tous les fichier contenant le texte indiqué seront exclus.

-A, --all

Précise que les fichiers (ou autres éléments) indiqués dans la ligne de commande concernent TOUS les paquets construits et pas seulement le premier.

## OPTIONS DU PROCESSUS DE CONSTRUCTION
Les programmes debhelper dh_auto_* comportent plusieurs processus de construction et déterminent, de manière heuristique, lequel utiliser et comment. Il peut être utile de modifier ce comportement par défaut. Tous ces programmes dh_auto_* acceptent les options suivantes, typiquement passées à dh(1), qui les passe ensuite à tous les programmes dh_auto_*.

-Sprocessus de construction, --buildsystem=processus de construction

Oblige à utiliser le processus de construction indiqué au lieu de tenter de déterminer automatiquement celui qui pourrait être utilisable pour le paquet.

-Drépertoire, --sourcedirectory=répertoire

Considère que les sources du paquet sont situées dans le répertoire indiqué plutôt qu'au plus haut niveau de l'arborescence du paquet source.

-B[répertoire], --builddirectory=[répertoire]

Enable out of source building and use the specified directory as the build directory. If directory parameter is omitted, a default build directory will be chosen. Si cette option n'est pas indiquée, la construction se fera dans l'arborescence source à moins que le processus exige ou préfère le faire en dehors de cette structure. Dans ce cas, le répertoire par défaut sera utilisé même si --builddirectory n'est pas indiqué.

Même si le système préfère utiliser, pour la construction, un répertoire situé en dehors de l'arborescence source, il autorise quand même la construction dans l'arborescence source. Pour cela, il suffit d'utiliser un chemin d'accès au répertoire de construction identique au chemin d'accès au répertoire source.

--parallel, --no-parallel

Control whether parallel builds should be used if underlying build system supports them. The number of parallel jobs is controlled by the DEB_BUILD_OPTIONS environment variable ("Debian Policy, section 4.9.1") at build time. It might also be subject to a build system specific limit. If neither option are not specified, debhelper currently defaults to --parallel in compat 10 (or later) and --no-parallel otherwise.

As an optimization, dh will try to avoid passing these options to subprocesses, if they are unncessary and the only options passed. Notably this happens when DEB_BUILD_OPTIONS does not have a parallel parameter (or its value is 1).

--max-parallel=maximum

Cette option implique --parallel et permet de limiter le nombre de tâches qui pourront être lancées lors d'une compilation parallèle. Si la construction du paquet est connue pour ne fonctionner qu'avec un certain niveau de parallélisme, il est possible de le régler à la valeur maximum censée fonctionner, ou que vous souhaitez mettre en œuvre. Notably, setting the maximum to 1 is effectively the same as using --no-parallel.

--list, -l

Liste tous les processus de construction supporté par le système. Cette liste inclut à la fois les processus par défaut et les processus tiers (marqués comme tels). Cette option montre également le processus de construction automatiquement sélectionné ou celui indiqué manuellement avec l'option --buildsystem.

## NIVEAUX DE COMPATIBILITÉ
Parfois, des modifications majeures de debhelper doivent être faites et vont briser la compatibilité ascendante. Ces modifications sont nécessaires pour conserver à debhelper ses qualités de conception et d'écriture, car les besoins changent et le savoir-faire de l'auteur s'améliore. Pour éviter que de tels changements ne cassent les paquets existants, un concept de niveau de compatibilité debhelper a été introduit. On précisera à debhelper le niveau de compatibilité qu'il doit employer, ce qui modifiera son comportement de diverses manières.

Pour indiquer à debhelper le niveau de compatibilité à utiliser il faut placer un nombre dans debian/compat. Par exemple, pour exploiter la version 9 :

```
 % echo 9 > debian/compat
```

Le paquet nécessitera aussi une version de debhelper dans les dépendances de construction au moins égale au niveau de compatibilité utilisée pour la construction du paquet. Ainsi, si le paquet emploie le niveau 9 de compatibilité, debian/control devra contenir :

```
 Build-Depends: debhelper (>= 9)
```

Sauf indication contraire, toute la documentation de debhelper suppose l'utilisation du niveau de compatibilité le plus récent, et, dans la plupart des cas ne précise pas si le comportement est différent avec les niveaux de compatibilité antérieurs. De ce fait, si le niveau de compatibilité le plus récent n'est pas celui utilisé, il est fortement conseillé de lire les indications ci-dessous qui exposent les différences dans les niveaux de compatibilité antérieurs.

Les niveaux de compatibilité sont les suivants :

v1

C'est le niveau initial de compatibilité de debhelper d'où son numéro 1. Dans ce mode, debhelper emploiera debian/tmp comme répertoire de l'arborescence du premier paquet binaire énuméré dans le fichier control et « debian/paquet » pour tous les autres. Ce mode est déconseillé.

v2

Dans ce mode, debhelper emploiera uniformément « debian/paquet » comme répertoire de l'arborescence de chaque paquet construit. Ce mode est déconseillé.

v3

Ce mode fonctionne comme v2 mais avec les ajouts suivants :

- Les fichiers de configuration de debhelper acceptent les jokers * et ? lorsque cela a un sens. Pour désactiver cette substitution et utiliser ces caractères tels quels, il suffit de les préfixer avec une barre contre-oblique (backslash).

- Les scripts de maintenance du paquet (postinst et postrm) feront appel à ldconfig quand dh_makeshlibs sera lancé.

- Chaque fichier de etc/ est automatiquement marqué par dh_installdeb comme un fichier de configuration.

Ce mode est déconseillé.

v4

Les changements par rapport à la version 3 sont :

- dh_makeshlibs -V n'inclura pas la partie Debian du numéro de version dans la ligne de dépendance produite dans le fichier shlibs.

- Il est fortement conseillé de mettre le nouveau ${misc:Depends} dans debian/control pour compléter le champs ${shlibs:Depends}.

- dh_fixperms rendra exécutables tous les fichiers des répertoires bin/ et etc/init.d.

- dh_link corrigera les liens existants pour les rendre conformes à la Charte Debian.

Ce mode est déconseillé.

v5

Les changements par rapport à la version 4 sont :

- Les commentaires sont ignorés dans les fichiers de configuration de debhelper.

- dh_strip --dbg-package indique maintenant le nom du paquet qui doit recevoir les symboles de mise au point et non plus les paquets d'où proviennent ces symboles.

- dh_installdocs saute l'installation des fichiers vides.

- dh_install génère des erreurs si les jokers (wildcards) ne correspondent à rien.

v6

Les changements par rapport à la version 5 sont :

- Les commandes qui génèrent des lignes de codes de maintenance les mettront dans l'ordre inverse dans les scripts prerm et postrm.

- dh_installwm installera un lien vers une page de manuel esclave pour x-window-manager.1.gz s'il voit la page de manuel dans le répertoire usr/share/man/man1 du répertoire de construction du paquet.

- dh_builddeb, préalablement, ne supprimait pas les associations crées avec DH_ALWAYS_EXCLUDE s'il était configuré sur une liste d'éléments tels que CVS:.svn:.git. Maintenant il le fait.

- dh_installman permet d'écraser les pages de manuel existantes dans le répertoire de construction du paquet. Préalablement, il refusait en silence de le faire.

v7

Les changements par rapport à la version 6 sont :

- dh_install cherchera récursivement les fichiers dans debian/tmp s'il ne les trouve pas dans le répertoire courant (ou dans le répertoire indiqué par --sourcedir). Cela permet à dh_install d'interopérer avec dh_auto_install, qui place les fichiers dans debian/tmp, sans nécessiter de paramètres particuliers.

- dh_clean lit le répertoire debian/clean et supprime les fichiers qui y sont mentionnés.

- dh_clean supprime les fichiers *-stamp.

- dh_installchangelogs déterminera à quel fichier correspond le changelog amont si rien n'est indiqué.

v8

Les changements par rapport à la version 7 sont :

- Les commandes échoueront plutôt que de produire une alerte lorsqu'elles recevront des options inconnues.

- dh_makeshlibs va exécuter le programme dpkg-gensymbols sur toutes les bibliothèques partagées qu'il génère pour les fichiers shlibs. -X peut alors être utilisé pour exclure certaines bibliothèques. En outre, les bibliothèques rangées à des emplacements inhabituels que pkg-gensymbols n'aurait pas traitées avant qu'elles ne lui soient transmises, induisent un changement de comportement qui peut causer l'échec de la construction de certains paquets.

- dh exige que la séquence à exécuter soit indiquée en tant que premier paramètre. Tous les commutateurs doivent venir après. C'est à dire qu'il faut écrire « dh $@ --toto », et non « dh --toto $@ »

- dh_auto_* utilise préférentiellement Module::Build de Perl au lieu de Makefile.PL.

v9

C'est la version dont l'usage est recommandé. Les changements par rapport à la version 8 sont :

- Prise en charge multiarchitecture. En particulier dh_auto_configure passe les répertoires multiarchitectures à autoconf dans --libdir et --libexecdir.

- dh connaît les dépendances classiques entre les cibles de debian/rules. Donc « dh binary » exécutera toutes les cibles build, build-arch, build-indep, install, etc. présentes dans le fichier rules. Il n'est pas nécessaire de définir une cible binary avec des dépendances explicites sur les autres cibles.

- dh_strip compresse les fichiers de symboles de mise au point pour réduire la taille d'installation des paquets -dbg.

- dh_auto_configure n'inclut pas le nom du paquet source dans --libexecdir en utilisant autoconf.

- dh n'active pas --with=python-support par défaut.

- Tous les programmes debhelper dh_auto_* et dh configurent les variables d'environnement renvoyées par dpkg-buildflags, sauf si elles sont déjà configurées.

- dh_auto_configure passe les CFLAGS, CPPFLAGS et LDFLAGS de dpkg-buildflags à Makefile.PL et Build.PL de Perl.

- dh_strip place les symboles de mise au point séparés à un endroit en fonction de leur identifiant de construction (build-id).

- Les fichiers de configuration exécutables de debhelper sont exécutés et leur sortie est utilisée comme configuration.

v10

Ce niveau de compatibilité est encore en développement, à utiliser avec précaution. Les changements par rapport à la version 9 sont :

- dh_installinit will no longer install a file named debian/package as an init script.

- dh_installdocs will error out if it detects links created with --link-doc between packages of architecture "all" and non-"all" as it breaks binNMUs.

- dh no longer creates the package build directory when skipping running debhelper commands. This will not affect packages that only build with debhelper commands, but it may expose bugs in commands not included in debhelper.

- dh_installdeb no longer installs a maintainer-provided debian/package.shlibs file. This is now done by dh_makeshlibs instead.

- dh_installwm refuses to create a broken package if no man page can be found (required to register for the x-window-manager alternative).

- Debhelper will default to --parallel for all buildsystems that support parallel building. This can be disabled by using either --no-parallel or passing --max-parallel with a value of 1.

## REMARQUES

### Prise en charge de plusieurs paquets binaires
Si le paquet source produit plus d'un paquet binaire, les programmes de debhelper construiront tous les paquets binaires. Si le paquet source doit construire un paquet dépendant de l'architecture, et un paquet indépendant de l'architecture, ce comportement ne conviendra pas. En effet, il convient de construire les paquets dépendants de l'architecture dans « binary-arch » de debian/rules, et les paquets indépendants de l'architecture dans « binary-indep ».

To facilitate this, as well as give you more control over which packages are acted on by debhelper programs, all debhelper programs accept the -a, -i, -p, and -s parameters. These parameters are cumulative. If none are given, debhelper programs default to acting on all packages listed in the control file, with the exceptions below.

First, any package whose Architecture field in debian/control does not match the build architecture will be excluded ("Debian Policy, section 5.6.8").

Also, some additional packages may be excluded based on the contents of the DEB_BUILD_PROFILES environment variable and Build-Profiles fields in binary package stanzas in debian/control, according to the draft policy at <https://wiki.debian.org/BuildProfileSpec>.

### Génération automatique des scripts Debian de maintenance du paquet
Certaines commandes de debhelper produisent automatiquement des lignes de code de maintenance du paquet. Pour les inclure dans vos propres scripts de maintenance du paquet, il convient d'ajouter #DEBHELPER# à l'endroit où les lignes de code générées devront être insérées. #DEBHELPER# sera remplacé, par les lignes de code générées automatiquement, lors de l'exécution de dh_installdeb.

Si un script de maintenance n'existe pas et que debhelper doit y inclure quelque chose, alors debhelper créera le script de maintenance complètement.

Toutes les commandes de debhelper qui produisent automatiquement des lignes de code de cette façon peuvent inhiber cette production grâce à l'option -n (voir ci-dessus).

Nota : Les lignes de code insérées seront écrites dans le langage de l'interpréteur de commandes (shell). De ce fait, il est impossible de les placer directement dans un script Perl. Pour les insérer dans un script Perl, voici une solution. (S'assurer que $1, $2, etc. sont bien définis par la commande set.) :

```
  my $temp="set -e\nset -- @ARGV\n" . << 'EOF';
  #DEBHELPER#
  EOF
  if (system($temp)) {
     my $exit_code = ($? >> 8) & 0xff;
     my $signal = $? & 0x7f;
     if ($exit_code) {
         die("The debhelper script failed with error code: ${exit_code}");
     } else {
         die("The debhelper script was killed by signal: ${signal}");
     }
  }
```

### Génération automatique des diverses dépendances.
Certaines commandes de debhelper peuvent nécessiter des dépendances entre le paquet construit et d'autres paquets. Par exemple, si dh_installdebconf(1) est employé, le paquet devra dépendre de debconf. Si dh_installxfonts(1) est employé, le paquet deviendra dépendant d'une version particulière de xutils. Maintenir ces dépendances induites peut être pénible puisqu'elles découlent de la façon dont debhelper travaille. C'est pourquoi debhelper offre une solution d'automatisation.

Toutes les commandes de ce type, outre qu'elles documentent, dans leur page de manuel, les dépendances qu'elle induisent, généreront automatiquement une variable de substitution nommée ${misc:depends}. Si cette variable est exploitée dans le dossier debian/control, il sera automatiquement enrichi des dépendances induites par debhelper.

Ce processus est entièrement indépendant de ${shlibs:Depends} standard, produite par dh_makeshlibs(1), et de ${perl:Depends} produite par dh_perl(1). Il est également possible de choisir de ne pas les utiliser si les conjectures de debhelper ne correspondent pas à la réalité.

### Répertoires de construction du paquet
Par défaut, tous les programmes de debhelper supposent que le répertoire temporaire utilisé pour construire l'arborescence des fichiers d'un paquet est debian/paquet.

Parfois, il peut être souhaitable d'utiliser un autre répertoire temporaire. C'est obtenu grâce à l'attribut -P. Par exemple, dh_installdocs -Pdebian/tmp utilisera debian/tmp comme répertoire temporaire. Nota : L'usage de -P implique que les programmes de debhelper ne construisent qu'un seul paquet à la fois. De ce fait, si le paquet source génère plusieurs paquets binaires, il faudra employer également le paramètre -p pour préciser l'unique paquet binaire à construire.

### udebs
Debhelper prend en charge la construction des udebs. Pour créer un udeb avec debhelper, il faut ajouter « Package-Type: udeb » aux lignes de paquet dans debian/control. Debhelper essayera de construire des udebs, conformément aux règles de l'installateur Debian, en suffixant les fichiers de paquets générés avec .udeb, en n'installant aucune documentation dans un udeb, en omettant les scripts preinst, postrm, prerm et config, etc.

## VARIABLES D'ENVIRONNEMENT
The following environment variables can influence the behavior of debhelper. It is important to note that these must be actual environment variables in order to function properly (not simply Makefile variables). To specify them properly in debian/rules, be sure to "export" them. For example, "export DH_VERBOSE".

DH_VERBOSE

Set to 1 to enable verbose mode. Debhelper will output every command it runs. Also enables verbose build logs for some build systems like autoconf.

DH_QUIET

Set to 1 to enable quiet mode. Debhelper will not output commands calling the upstream build system nor will dh print which subcommands are called and depending on the upstream build system might make that more quiet, too. This makes it easier to spot important messages but makes the output quite useless as buildd log. Ignored if DH_VERBOSE is also set.

DH_COMPAT

Indique temporairement le niveau de compatibilité auquel debhelper doit fonctionner. Cette valeur supplante la valeur précisée dans debian/compat.

DH_NO_ACT

Mettre cette variable à 1 pour activer le mode simulation (no-act).

DH_OPTIONS

Tout ce qui est indiqué dans cette variable sera passé en argument à toutes les commandes debhelper. En utilisant dh(1), des options peuvent être passées à chaque commande debhelper, ce qui est généralement mieux que d'utiliser DH_OPTIONS.

DH_ALWAYS_EXCLUDE

Si cette variable possède une valeur, elle sera ajoutée à l'option -X de toutes les commandes qui admettent cette option. De plus, dh_builddeb fera un rm -rf quelque chose, correspondant à la valeur dans l'arbre de construction de paquet. Cela peut être utile pour construire un paquet à partir d'une arborescence CVS. Dans ce cas, le réglage de DH_ALWAYS_EXCLUDE=CVS empêchera les répertoires CVS d'interférer subrepticement dans le paquet en construction. Ou, si un paquet possède une source compressée, (maladroitement) présente dans un répertoire CVS, il peut être utile d'exporter DH_ALWAYS_EXCLUDE=CVS dans debian/rules, pour que cette variable soit prise en compte quel que soit l'endroit où le paquet est construit.

Des exclusions multiples peuvent être séparées avec des caractères deux points, comme dans DH_ALWAYS_EXCLUDE=CVS:.svn.

## VOIR AUSSI
/usr/share/doc/debhelper/examples/

Un ensemble d'exemples de fichiers debian/rules qui utilisent debhelper.

<http://joeyh.name/code/debhelper/>

Le site internet de debhelper.

## AUTEUR
Joey Hess <joeyh@debian.org>

## TRADUCTION
Valéry Perrin <valery.perrin.debian@free.fr> le 17 septembre 2005. Dernière mise à jour le 3 avril 2011.

L'équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité.

Cette traduction est gérée dynamiquement par po4a. Certains paragraphes peuvent, éventuellement, apparaître en anglais. Ils correspondent à des modifications ou des ajouts récents du mainteneur, non encore incorporés dans la traduction française.

La version originale anglaise de ce document est toujours consultable via la commande man -L en nom_du_man.

N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.


debhelper.pt

package: debhelper

title: debhelper.pt(7)

summary: a suite de ferramentas debhelper

text:
# debhelper.pt(7)

## NOME
debhelper - a suite de ferramentas debhelper

## RESUMO
dh_* [-v] [-a] [-i] [-s] [--no-act] [-ppacote] [-Npacote] [-Ptmpdir]

## DESCRIÇÃO
Debhelper é usado para ajudá-lo a compilar um pacote Debian. A filosofia por detrás de debhelper é disponibilizar uma colecção de ferramentas pequenas, simples e de fácil compreensão que são usadas em debian/rules para automatizar vários aspectos comuns da compilação de um pacote. Isto significa menos trabalho para si, o empacotador. Também significa, até certo ponto, que estas ferramentas podem ser alteradas se a política de Debian alterar, e os pacotes que as usam irão precisar apenas de uma recompilação para ficarem em conformidade com a nova política.

Um ficheiro debian/rules típico que usa debhelper irá chamar vários comandos debhelper em sequência, ou usar dh(1) para automatizar este processo. Em /usr/share/doc/debhelper/examples/ estão exemplos de ficheiros de regras que usam debhelper.

Para criar um novo pacote Debian usando o debhelper, você pode copiar um dos ficheiros de regras exemplo e editá-lo à mão. Ou pode tentar o pacote dh-make, o qual contém um comando dh_make que automatiza parcialmente o processo Para uma introdução mais gentil, o pacote Debian maint-guide contém um tutorial acerca de como fazer o seu primeiro pacote usando o debhelper.

## COMANDOS DO DEBHELPER
Aqui está a lista dos comandos debhelper que você pode usar. Veja os seus manuais para documentação adicional.

\#LISTA#

### Comandos Descontinuados
Alguns comandos debhelper estão descontinuados e não devem ser usados.

\#LISTA_DE_DESCONTINUADOS#

### Outros comandos
Se o nome dum programa começa com dh_, e o programa não está nas listas em cima, então não faz parte do pacote debhelper, mas mesmo assim deverá funcionar como os outros programas descritos nesta página.

## FICHEIROS DE CONFIGURAÇÃO DO DEBHELPER
Muitos comandos do debhelper usam ficheiros em debian/ para controlar o que fazem. Para além dos comuns debian/changelog e debian/control, que estão em todos os pacotes, e não apenas aqueles que usam debhelper, alguns ficheiros adicionais podem ser usados para configurar o comportamento de comandos debhelper específicos. Estes ficheiros são chamados tipicamente debian/pacote.foo (onde pacote é claro, é substituído pelo nome do pacote no qual se está a actuar).

Por exemplo, dh_installdocs usa ficheiros chamados debian/package.docs para listar os ficheiros de documentação que ira instalar. Veja os manuais individuais dos comandos para detalhes acerca dos nomes e formatos dos ficheiros que usam. Geralmente, estes ficheiros irão listar ficheiros onde se vai actuar, um ficheiro por linha. Alguns programas no debhelper usam pares de ficheiros e destinos ou formatos ligeiramente mais complicados.

Note que para o primeiro (ou único) pacote binário listado em <debian/control>, o debhelper irá usar debian/foo quando não existe nenhum ficheiro debian/package.foo.

Em alguns casos raros, você pode querer ter versões diferentes destes ficheiros para arquitecturas ou sistemas operativos diferentes. Se existirem ficheiros chamados debian/pacote.foo.ARCH ou debian/pacote.foo.OS, onde ARCH e OS são o mesmo que o resultado de "dpkg-architecture -qDEB_HOST_ARCH" / "dpkg-architecture -qDEB_HOST_ARCH_OS", então eles irão ser usados em preferência de outros ficheiros mais gerais.

Maioritariamente, estes ficheiros de configuração são usados para especificar listas de vários tipos de ficheiros. Documentação ou ficheiros exemplo para instalar, ficheiros para mover, e etc. Quando apropriado, em casos como estes, você pode usar caracteres "wildcard" de shell standard (classes de caracteres ? e * e [..]) nos ficheiros. Também pode meter comentários neste ficheiros; as linhas começadas com # são ignoradas.

A sintaxe destes ficheiros é mantida propositadamente simples para os tornar fáceis de ler, perceber, e modificar. Se você preferir o poder e a complexidade, pode tornar o ficheiro executável, e escrever um programa que gere um conteúdo apropriado para uma dada situação seja ela qual for. Quando o fizer, o resultado já não é mais processado para expandir wildcards ou despojar comentários.

## OPÇÕES DO DEBHELPER PARTILHADAS
As seguintes opções de linha de comandos são suportadas por todos os programas do debhelper.

-v, --verbose

Modo detalhado: mostra todos os comandos que modificam o directório de compilação de pacotes.

--no-act

Não faz nada na realidade. Se usado com -v, o resultado é que o comando mostra o que iria fazer.

-a, --arch

Actua em pacotes dependentes da arquitectura que devem ser compilados para a arquitectura de compilação.

-i, --indep

Actua em todos os pacotes independentes da arquitectura.

-ppacote, --package=pacote

Actua no pacote chamado pacote. Esta opção pode ser especifica várias vezes para fazer o debhelper operar num determinado conjunto de pacotes.

-s, --same-arch

Isto costumava ser uma versão mais inteligente da bandeira -a, mas a bandeira -a é agora igualmente inteligente.

-Npacote, --no-package=pacote

Não actua no pacote especificado mesmo se uma opção -a, -i, ou -p listarem o pacote como um em que se deverá actuar.

--remaining-packages

Não actua nos pacotes que já foram actuados antes por este comando do debhelper (isto é, se o comando estiver presente no debhelper log do pacote). Por exemplo, se você precisar de chamar o comando com opções especiais apenas para um par de pacotes binários, passe esta opção para a última chamada do comando para processar o resto dos pacotes com as definições predefinidas.

--ignore=ficheiro

Ignora o ficheiro especificado. Isto pode ser usado se debian/ conter um ficheiro de configuração de debhelper que um comando debhelper não deve usar. Note que debian/compat, debian/control, e debian/changelog não podem ser ignorados, mas também, nunca deverá existir uma razão para ignorar estes ficheiros. Por exemplo, se o autor do programa juntar um debian/init que você não quer que dh_installinit instale, use --ignore=debian/init

-Ptmpdir, --tmpdir=tmpdir

Usa tmpdir para directório de compilação de pacotes. A predefinição é debian/pacote

--mainpackage=pacote

Esta opção pouco usada muda o pacote que o debhelper considera o "pacote principal", isto é, o primeiro listado em debian/control, e aquele para o qual os ficheiros debian/foo podem ser usados em vez dos ficheiros debian/package.foo usuais.

-O=opção|bundle

Isto é usado pelo dh(1) quando se passa opções específicas do utilizador a todos os comandos que corre. Se o comando suportar a opção ou opções especificadas, irá fazer efeito. Se o comando não suportar a opção (ou alguma parte do conjunto de opções), será ignorado.

## OPÇÕES COMUNS DO DEBHELPER
As seguintes opções de linha de comandos são suportadas por alguns programas do debhelper. Veja o manual de cada programa para uma explicação completa sobre o que cada opção faz.

-n

Não modifique os scripts postinst, postrm, etc.

-Xitem, --exclude=item

Exclui um item do processamento. Esta opção pode ser usada várias vezes, para excluir mais do que uma coisa. O \fIitem\fR é tipicamente parte de um nome de ficheiro, e qualquer ficheiro que contenha o texto especificado será excluído.

-A, --all

Faz com que ficheiros ou outros itens que são especificados na linha de comandos tenham efeito em TODOS os pacotes em que se actua, e não apenas o primeiro.

## OPÇÕES DO SISTEMA DE COMPILAÇÃO
As seguintes opções de linha de comandos são suportadas por todos os comandos dh_auto_* do debhelper. Estes programas suportam uma variedade de sistemas de compilação, e normalmente determinam heurísticamente qual usar, e como os usar. Você pode usar estes opções de linha de comandos para sobrepor o comportamento predefinido. Tipicamente estas são passadas ao dh(1), o qual passa-as a todos os programas dh_auto_*.

-Ssistemacompilação, --buildsystem=sistemacompilação

Força a utilização do |<sistemacompilação> especificado, em vez de tentar auto-seleccionar um que pode ser aplicável para o pacote.

-Ddirectório, --sourcedirectory=directório

Assume que a árvore fonte do pacote original está no directório especificado em vez de estar no directório de nível de topo da árvore de pacotes fonte de Debian.

-B[directório], --builddirectory=[directório]

Activa a compilação da fonte e usa o directório especificado como o directório de compilação. Se o parâmetro directório for omitido, é escolhido o directório de compilação predefinido. Se esta opção não for especificada, a compilação será feita por predefinição na fonte a menos que o sistema de compilação requeira ou prefira a compilação da árvore de fonte. Em tal caso, será usado o directório de compilação predefinido mesmo se --builddirectory não seja especificado.

Se o sistema de compilação preferir a compilação da árvore fonte mas ainda permitir a compilação da fonte, a última pode ser re-activada ao passar-lhe um caminho para um directório de compilação que é o mesmo que o caminho para o directório fonte.

--parallel, --no-parallel

Controla se devem ser usadas compilações paralelas se o sistema de compilação o suportar. O número de trabalhos paralelos é controlado pela variável de ambiente DEB_BUILD_OPTIONS ("Debian Policy, secção 4.9.1") durante a compilação. Também pode servir como um limite específico do sistema de compilação. Se nenhuma destas opções for especificada, presentemente o debhelper usa por predefinição --parallel em modo compatibilidade 10 (ou posterior) e --no-parallel em caso contrário.

Como uma optimização, o dh irá tentar evitar passar estas opções aos sub-processos, se estas forem desnecessárias e as únicas opções a passar. De notar que isto acontece quando DEB_BUILD_OPTIONS não tem um parâmetro parallel (ou o seu valor é 1).

--max-parallel=máximo

Esta opção implica --parallel e permite mais limitação ao número de trabalhos que podem ser usados numa compilação paralela. Se a compilação do pacote é conhecida por apenas funcionar em certos níveis de concorrência, você pode definir isto para o nível máximo que é sabido funcionar, ou que deseje suportar. De notar que, definir o máximo para 1 é efectivamente o mesmo que usar --no-parallel.

--list, -l

Lista todos os sistemas de compilação suportados pelo debhelper neste sistema. A lista inclui ambos sistemas de compilação predefinidos e de terceiros (marcados como tal). Também mostra qual o sistema de compilação será seleccionado automaticamente, ou qual está especificado manualmente com a opção --buildsystem.

## NÍVEIS DE COMPATIBILIDADE
De tempos a tempos, precisam de ser feitas grandes alterações no debhelper que não compatíveis com as versões anteriores, para o manter limpo e bem construído quando as necessidades alteram e o seu autor ganha mais experiência. Para prevenir que tais grandes alterações danifiquem os pacotes existentes, foi introduzido o conceito de níveis de compatibilidade no debhelper. Você diz ao debhelper qual o nível de compatibilidade que ele deve usar, e ele modifica o seu comportamento de várias maneiras.

Diz ao debhelper qual nível de compatibilidade deve usar ao escrever um número em debian/compat. Por exemplo, para activar o modo v9:

```
  % echo 9 > debian/compat
```

O seu pacote também vai precisar de uma dependência de compilação de versão de uma versão do debhelper igual (ou maior que) ao nível de compatibilidade que o seu pacote usa. Portanto para nível de compatibilidade 9, certifique-se que debian/control tem:

```
  Build-Depends: debhelper (>= 9)
```

A menos que seja indicado o contrário, toda a documentação do debhelper assume que você está a usar o nível de compatibilidade mais recente, e na maioria dos casos não indica se o comportamento é diferente num nível de compatibilidade anterior, portanto se não está a usar o nível de compatibilidade mais recente, você é aconselhado a procurar em baixo por notas acerca do que é diferente nos níveis de compatibilidade anteriores.

Estes são os níveis de compatibilidade disponíveis:

v1

Este é o nível de compatibilidade original do debhelper, e por isso é o predefinido. Neste modo, o debhelper irá usar debian/tmp como o directório da árvore do pacote para o primeiro pacote binário listado no ficheiro de controle, enquanto usa debian/pacote para todos os outros pacotes listados no ficheiro control. Este modo está descontinuado.

v2

Neste modo, o debhelper irá consistentemente usar debian/pacote como o directório da árvore do pacote para cada pacote que é compilado. Este modo está descontinuado.

v3

Este modo funciona como v2, com as seguintes adições:

- Os ficheiros de configuração do debhelper suportam englobamentos via * e ?, onde apropriado. Para desligar isto e usar esses caracteres a cru, basta antecedê-los com uma barra invertida (backslash "").

- dh_makeshlibs faz com que os scripts postinst e postrm chamem ldconfig.

- Qualquer ficheiro em etc/ é marcado automaticamente como um conffile (ficheiro de configuração) pelo dh_installdeb.

Este modo está descontinuado.

v4

As alterações a partir de v3 são:

- dh_makeshlibs -V não irá incluir a parte Debian do número de versão na linha de dependência gerada no ficheiro shlibs.

- Você é encorajado a colocar o novo ${misc:Depends} em debian/control para suplementar o campo ${shlibs:Depends}.

- dh_fixperms irá tornar em executáveis todos os ficheiros nos directórios bin/ e em etc/init.d.

- dh_link irá corrigir os links existentes para ficarem em conformidade com a politica.

Este modo está descontinuado.

v5

As alterações a partir de v4 são:

- Comentários são ignorados nos ficheiros de configuração do debhelper.

- Agora dh_strip --dbg-package especifica o nome de um pacote onde colocar símbolos de depuração, e não os pacotes de onde tirar os símbolos.

- dh_installdocs evita a instalação de ficheiros vazios.

- dh_install resulta em erro se as "wildcards" expandirem para nada.

v6

As alterações a partir de v5 são:

- Os comandos que geram fragmentos de script de mantenedor irão ordenar os fragmentos em ordem reversa para os scripts prerm e postrm.

- dh_installwm irá instalar uma ligação escrava de manual para x-window-manager.1.gz, se vir o manual em usr/share/man/man1 no directório de compilação do pacote.

- O dh_builddeb anteriormente não apagava nada que correspondesse a DH_ALWAYS_EXCLUDE, se estivesse definida uma lista de coisas a excluir, como CVS:.svn:.git. Mas agora fá-lo.

- dh_installman permite a sobreposição de manuais existentes no directório de compilação do pacote. Nos níveis de compatibilidade anteriores recusava-se em silêncio a fazer isto.

v7

As alterações a partir de v6 são:

- dh_install, irá regressar a procurar por ficheiros em debian/tmp se não os encontrar no directório actual (ou onde você lhe disser para procurar usando --sourcedir). Isto permite ao dh_install inter-operar com o dh_auto_install, o qual instala para debian/tmp, sem precisar de nenhuns parâmetros especiais.

- dh_clean irá ler debian/clean e apagar os ficheiros listados lá.

- dh_clean irá apagar ficheiros *-stamp do nível de topo.

- dh_installchangelogs irá adivinhar qual ficheiro está no relatório de alterações da origem se nenhum for especificado.

v8

As alterações a partir de v7 são:

- Os comandos irão falhar em vez de emitirem avisos quando lhes são passadas opções desconhecidas.

- dh_makeshlibs irá correr dpkg-gensymbols em todas as bibliotecas partilhadas para as quais gera ficheiros shlibs. Portanto o -X pode ser usado para excluir bibliotecas. Também, as bibliotecas em localizações fora do habitual que o dpkg-gensymbols não tenha processado antes serão passadas para ele, uma alteração no comportamento que pode causar que alguns pacotes falhem a compilar.

- dh requer que a sequência a correr seja especificada como o primeiro parâmetro, e quaisquer switches que venham depois dela. Isto é, use dh $@ --foo", e não "dh --foo $@

- dh_auto_* prefere usar o Module::Build do Perl em preferência de Makefile.PL.

v9

Este é o modo de operação recomendado. As alterações a partir de v8 são:

- Suporte a multi-arquitectura. Em particular, dh_auto_configure passa directórios de multi-arquitectura ao autoconf em --libdir e --libexecdir.

- O dh tem conhecimento das dependências habituais entre metas em debian/rules. Por isso, o "dh binary" irá correr quaisquer metas de build, build-arch, build-indep, install, etc que existam no ficheiro de regras. Não há necessidade de definir uma meta binário explícito com dependências explícitas em outras metas.

- dh_strip comprime ficheiros de símbolos de depuração para reduzir o tamanho instalado dos pacotes -dbg.

- dh_auto_configure não inclui o nome do pacote fonte em --libexecdir quando usa autoconf.

- dh não tem por predefinição a activação de --with=python-support

- Todos os programas debhelper dh_auto_* e dh definem variáveis de ambiente listadas por dpkg-buildflags, a menos que elas estejam já definidas.

- dh_auto_configure passa as dpkg-buildflags CFLAGS, CPPFLAGS, e LDFLAGS para Makefile.PL e Build.PL de perl.

- dh_strip põe símbolos de depuração separados numa localização baseada no seu build-id.

- Os ficheiros de configuração executáveis do debhelper são corridos e os seus resultados usados como configuração.

v10

Este nível de compatibilidade ainda está aberto em desenvolvimento; use com cuidado. As alterações a partir de v9 são:

- dh_installinit não irá mais instalar um ficheiro chamado debian/pacote como um script de iniciação (init).

- O dh_installdocs irá dar erro se detectar links criados com --link-doc entre pacotes de arquitectura "all" e não-"all" porque isso faz quebrar binNMUs.

- dh já não cria o directório de compilação do pacote quando salta a execução de comandos debhelper. Isto não vai afectar pacotes que apenas compilam com comandos debhelper, mas pode expor bugs em comandos não incluídos no debhelper.

- O dh_installdeb já não instala um ficheiro debian/pacote.shlibs disponibilizado pelo mantenedor. Em vez disso, isto agora é feito pelo dh_makeshlibs.

- O dh_installwm recusa-se a criar um pacote quebrado se não encontrar nenhuma página de manual (necessário para registo para a alternativa do x-window-manager).

- Debhelper irá predefinir para --parallel em todos os sistemas de compilação que suportam compilação paralela. Isto pode ser desactivado usando --no-parallel ou passando --max-parallel com o valor de 1.

## NOTAS

### Suporte a pacotes de múltiplos binários
Se o seu pacote fonte gerar mais do que um pacote binário, os programas do debhelper, por predefinição, irão actuar em todos os pacotes binários quando correm. No caso do seu pacote fonte gerar um pacote dependente de arquitectura, e outro pacote independente da arquitectura, este não é o comportamento correcto, porque você precisa de gerar os pacotes dependentes de arquitectura na meta debian/rules binary-arch, e os pacotes independentes de arquitectura na meta debian/rules binary-indep.

Para facilitar isto, e também para lhe dar mais controle sobre em quais pacotes os programas debhelper actuam, todos os programas debhelper aceitam os parâmetros -a, -i, -p, e -s. Estes parâmetros são cumulativos. Se nenhum for usado, os programas debhelper por predefinição actuam em todos os pacotes listados no ficheiro de controle, com as excepções em baixo.

Primeiro, qualquer pacote cujo campo Architecture em debian/control não corresponda à arquitectura de compilação será excluído ("Debian Policy, secção 5.6.8").

Também, alguns pacotes adicionais podem ser excluídos com base no conteúdo da variável de ambiente DEB_BUILD_PROFILES e nos campos Build-Profiles nas estrofes de pacotes binários em debian/control, de acordo com a política proposta em <https://wiki.debian.org/BuildProfileSpec>.

### Geração automática de scripts de instalação Debian
Alguns comandos do debhelper irão gerar automaticamente partes de scripts de mantenedor Debian. Se desejar que estas coisas geradas automaticamente sejam incluídas nos sues scripts de mantenedor Debian existentes, então você precisa adicionar #DEBHELPER# aos seus scripts, no local onde o código deverá ser adicionado. #DEBHELPER# será substituído por qualquer código auto-gerado quando você correr o dh_installdeb.

Se não existir nenhum script e o debhelper precisar de adicionar algo a ele, então o debhelper irá criar o script completo.

Todos os comandos debhelper que geram código automaticamente deste modo permitem que o seja desactivado pelo parâmetro -n (ver em cima).

Note que o código inserido será código shell, portanto você não pode usá-lo directamente num script de Perl. Se desejar embebê-lo num script Perl, aqui está um modo de o fazer (note que Eu certifico-me que $1, $2, etc são definidos com o comando "set"):

```
  my $temp="set -e\nset -- @ARGV\n" . << 'EOF';
  #DEBHELPER#
  EOF
  if (system($temp)) {
     my $exit_code = ($? >> 8) & 0xff;
     my $signal = $? & 0x7f;
     if ($exit_code) {
         die("The debhelper script failed with error code: ${exit_code}");
     } else {
         die("The debhelper script was killed by signal: ${signal}");
     }
  }
```

### Geração automática de dependências variadas.
Alguns programas debhelper podem fazer com que o pacote gerado precise de depender de alguns outros pacotes. Por exemplo, se você usar o dh_installdebconf(1), o seu pacote irá geralmente depender do debconf. Ou se você usar dh_installxfonts(1), o seu pacote irá geralmente depender de uma versão particular do xutils. Acompanhar estas dependências variadas pode ser aborrecido pois elas dependem de como o debhelper faz as coisas, então o debhelper oferece um modo de automatizar isto.

Todos os comandos deste tipo, além de documentar quais dependências podem ser necessárias nos seus manuais, irão gerar automaticamente um substvar chamado ${misc:Depends}. Se você colocar esse testemunho no seu ficheiro debian/control, será expandido às dependências que o debhelper descobre que você precisa.

Isto é inteiramente independente do standard ${shlibs:Depends} gerado pelo dh_makeshlibs(1), e do ${perl:Depends} gerado pelo dh_perl(1). Você pode escolher usar qualquer um destes, se as escolhas do debhelper não corresponderem à realidade.

### Directórios de compilação de pacotes
Por predefinição, todos os programas do debhelper assumem que o directório temporário usado para montar a árvore de ficheiros num pacote é debian/pacote.

Por vezes, você pode querer usar outro directório temporário. Isto é suportado pela bandeira -P, por exemplo, "dh_installdocs -Pdebian/tmp", irá usar debian/tmp como directório temporário. Note que se você usar -P, os programas debhelper só podem actuar num pacote de cada vez. Por isso se tem um pacote que compila muitos pacotes binários, irá também precisar de usar a bandeira -p para especificar em qual pacote binário o programa debhelper irá actuar.

### udebs
Debhelper inclui suporte para udebs. Para criar um udeb com o debhelper, adicione "Package-Type: udeb" à estrofe do pacote em debian/control. O Debhelper irá tentar criar udebs em conformidade com a política do instalador debian, ao finalizar os ficheiros de pacotes gerados com .udeb, não instalando nenhuma documentação num udeb, saltando os scripts preinst, postrm, prerm, e config, etc.

## AMBIENTE
As seguintes variáveis de ambiente podem influenciar o comportamento do debhelper. É importante notar que estas que estas têm de ser mesmo variáveis de ambiente de modo a funcionarem correctamente (e não simplesmente variáveis do Makefile). Para as especificar correctamente em debian/rules, assegure-se de lhes fazer "export". Por exemplo, "export DH_VERBOSE"

DH_VERBOSE

Defina para 1 para activar o modo detalhado. O debhelper irá mostrar os resultados de cada comando que corre. Também activa relatórios de compilação detalhados para alguns sistemas de compilação como o autoconf.

DH_QUIET

Definir para 1 para activar o modo silencioso. O Debhelper não irá escrever os comandos a chamar o sistema de compilação do autor nem o dh irá escrever quais sub-comandos são chamados e dependendo do sistema de compilação do autor, poderá também tornar isso mais silencioso. Isto facilita a identificação de mensagens importantes mas torna os resultados inúteis como relatório do buildd. É ignorado se DH_VERBOSE for também definido.

DH_COMPAT

Especifica temporariamente em que nível de compatibilidade o debhelper deve correr, sobrepondo qualquer valor em debian/compat.

DH_NO_ACT

Defina para 1 para activar o modo no-act.

DH_OPTIONS

Qualquer coisa nesta variável será pre-confinada aos argumentos de linha de comandos de todos os comandos do debhelper. Quando se usa dh(1), podem-se passar opções que irão ser passadas a cada comando do debhelper, o que é geralmente melhor do que usar DH_OPTIONS.

DH_ALWAYS_EXCLUDE

Se definido, isto adiciona o valor que está definido na variável às opções -X de todos os comandos que suportam a opção -X. Ainda mais, o dh_builddeb irá fazer rm -rf a tudo o que corresponda a esse valor na sua árvore de compilação do pacote. Isto pode ser útil se você está a fazer uma compilação a partir de uma árvore fonte CVS, que no caso definindo DH_ALWAYS_EXCLUDE=CVS irá prevenir que quaisquer directórios CVS se esgueirem para o pacote que está a compilar. Ou, se um pacote tem um tarball de fonte que (não inteligentemente) inclui directórios CVS, você pode querer exportar DH_ALWAYS_EXCLUDE=CVS em debian/rules, para o fazer ter efeito onde o seu é compilado.

Várias coisas a excluir podem ser separadas com "dois pontos", como em DH_ALWAYS_EXCLUDE=CVS:.svn

## VEJA TAMBÉM
/usr/share/doc/debhelper/examples/

Um conjunto de ficheiros debian/rules exemplo que usam debhelper.

<http://joeyh.name/code/debhelper/>

Sítio web do debhelper.

## AUTOR
Joey Hess <joeyh@debian.org>

## TRADUÇÃO
Américo Monteiro

Se encontrar algum erro na tradução deste documento, por favor comunique para Américo Monteiro a_monteiro@gmx.com ou Equipa Debian de Tradução Portuguesa traduz@debianpt.org.


markdown

package: discount

title: markdown(7)

summary: The Markdown text formatting syntax

text:
# markdown(7)

## NAME
Markdown — The Markdown text formatting syntax

## DESCRIPTION

### Philosophy
Markdown is intended to be as easy-to-read and easy-to-write as is feasible.

Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it's been marked up with tags or formatting instructions. While Markdown's syntax has been influenced by several existing text-to-HTML filters -- including Setext, atx, Textile, reStructuredText, Grutatext, and EtText -- the single biggest source of inspiration for Markdown's syntax is the format of plain text email.

To this end, Markdown's syntax is comprised entirely of punctuation characters, which punctuation characters have been carefully chosen so as to look like what they mean. E.g., asterisks around a word actually look like *emphasis*. Markdown lists look like, well, lists. Even blockquotes look like quoted passages of text, assuming you've ever used email.

### Inline HTML
Markdown's syntax is intended for one purpose: to be used as a format for writing for the web.

Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags. The idea is not to create a syntax that makes it easier to insert HTML tags. In my opinion, HTML tags are already easy to insert. The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdown's formatting syntax only addresses issues that can be conveyed in plain text.

For any markup that is not covered by Markdown's syntax, you simply use HTML itself. There's no need to preface it or delimit it to indicate that you're switching from Markdown to HTML; you just use the tags.

The only restrictions are that block-level HTML elements -- e.g. <div>, <table>, <pre>, <p>, etc. -- must be separated from surrounding content by blank lines, and the start and end tags of the block should not be indented with tabs or spaces. Markdown is smart enough not to add extra (unwanted) <p> tags around HTML block-level tags.

For example, to add an HTML table to a Markdown article:

```
    This is a regular paragraph.

    <table>
        <tr>
            <td>Foo</td>
        </tr>
    </table>

    This is another regular paragraph.
```

Note that Markdown formatting syntax is not processed within block-level HTML tags. E.g., you can't use Markdown-style *emphasis* inside an HTML block.

Span-level HTML tags -- e.g. <span>, <cite>, or <del> -- can be used anywhere in a Markdown paragraph, list item, or header. If you want, you can even use HTML tags instead of Markdown formatting; e.g. if you'd prefer to use HTML <a> or <img> tags instead of Markdown's link or image syntax, go right ahead.

Unlike block-level HTML tags, Markdown syntax *is* processed within span-level tags.

### Automatic Escaping for Special Characters
In HTML, there are two characters that demand special treatment: `<` and `&`. Left angle brackets are used to start tags; ampersands are used to denote HTML entities. If you want to use them as literal characters, you must escape them as entities, e.g. `<`, and `&`.

Ampersands in particular are bedeviling for web writers. If you want to write about 'AT&T', you need to write '`AT&T`'. You even need to escape ampersands within URLs. Thus, if you want to link to:

```
    http://images.google.com/images?num=30&q=larry+bird
```

you need to encode the URL as:

```
    http://images.google.com/images?num=30&q=larry+bird
```

in your anchor tag `href` attribute. Needless to say, this is easy to forget, and is probably the single most common source of HTML validation errors in otherwise well-marked-up web sites.

Markdown allows you to use these characters naturally, taking care of all the necessary escaping for you. If you use an ampersand as part of an HTML entity, it remains unchanged; otherwise it will be translated into `&`.

So, if you want to include a copyright symbol in your article, you can write:

```
    ©
```

and Markdown will leave it alone. But if you write:

```
    AT&T
```

Markdown will translate it to:

```
    AT&T
```

Similarly, because Markdown supports inline HTML, if you use angle brackets as delimiters for HTML tags, Markdown will treat them as such. But if you write:

```
    4 < 5
```

Markdown will translate it to:

```
    4 < 5
```

However, inside Markdown code spans and blocks, angle brackets and ampersands are *always* encoded automatically. This makes it easy to use Markdown to write about HTML code. (As opposed to raw HTML, which is a terrible format for writing about HTML syntax, because every single `<` and `&` in your example code needs to be escaped.)

## Block Elements

### Paragraphs and Line Breaks
A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. (A blank line is any line that looks like a blank line -- a line containing nothing but spaces or tabs is considered blank.) Normal paragraphs should not be indented with spaces or tabs.

The implication of the "one or more consecutive lines of text" rule is that Markdown supports "hard-wrapped" Dtext paragraphs. This differs significantly from most other text-to-HTML formatters (including Movable Type's "Convert Line Breaks" option) which translate every line break character in a paragraph into a `<br />` tag.

When you *do* want to insert a `<br />` break tag using Markdown, you end a line with two or more spaces, then type return.

Yes, this takes a tad more effort to create a `<br />`, but a simplistic "every line break is a `<br />`" rule wouldn't work for Markdown. Markdown's email-style blockquoting

and multi-paragraph list items work best -- and look better -- when you format them with hard breaks.

### Headers
Markdown supports two styles of headers, Setext and atx.

Setext-style headers are ‘underlined’ using equal signs (for first-level headers) and dashes (for second-level headers). For example:

```
    This is an H1
    =============

    This is an H2
    -------------
```

Any number of underlining `=`'s or `-`'s will work.

Atx-style headers use 1-6 hash characters at the start of the line, corresponding to header levels 1-6. For example:

```
    # This is an H1

    ## This is an H2

    ###### This is an H6
```

Optionally, you may "close" atx-style headers. This is purely cosmetic -- you can use this if you think it looks better. The closing hashes don't even need to match the number of hashes used to open the header. (The number of opening hashes determines the header level.) :

```
    # This is an H1 #

    ## This is an H2 ##

    ### This is an H3 ######
```

### Blockquotes
Markdown uses email-style `>` characters for blockquoting. If you're familiar with quoting passages of text in an email message, then you know how to create a blockquote in Markdown. It looks best if you hard wrap the text and put a `>` before every line:

```
    > This is a blockquote with two paragraphs. Lorem ipsum
    > dolor sit amet, consectetuer adipiscing elit. Aliquam
    > hendrerit mi posuere lectus. Vestibulum enim wisi,
    > viverra nec, fringilla in, laoreet vitae, risus.
    >
    > Donec sit amet nisl. Aliquam semper ipsum sit amet
    > velit. Suspendisse id sem consectetuer libero luctus
    > adipiscing.
```

Markdown allows you to be lazy and only put the `>` before the first line of a hard-wrapped paragraph:

```
    > This is a blockquote with two paragraphs. Lorem ipsum
    dolor sit amet, consectetuer adipiscing elit. Aliquam
    hendrerit mi posuere lectus. Vestibulum enim wisi,
    viverra nec, fringilla in, laoreet vitae, risus.

    > Donec sit amet nisl. Aliquam semper ipsum sit amet
     velit. Suspendisse id sem consectetuer libero luctus
      adipiscing.
```

Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by adding additional levels of `>`:

```
    > This is the first level of quoting.
    >
    > > This is nested blockquote.
    >
    > Back to the first level.
```

Blockquotes can contain other Markdown elements, including headers, lists, and code blocks:

```
	> ## This is a header.
	>
	> 1.   This is the first list item.
	> 2.   This is the second list item.
	>
	> Here's some example code:
	>
	>     return shell_exec("echo $input | $markdown_script");
```

Any decent text editor should make email-style quoting easy. For example, with BBEdit, you can make a selection and choose Increase Quote Level from the Text menu.

### Lists
Markdown supports ordered (numbered) and unordered (bulleted) lists.

Unordered lists use asterisks, pluses, and hyphens -- interchangably -- as list markers:

```
    *   Red
    *   Green
    *   Blue
```

is equivalent to:

```
    +   Red
    +   Green
    +   Blue
```

and:

```
    -   Red
    -   Green
    -   Blue
```

Ordered lists use numbers followed by periods:

```
    1.  Bird
    2.  McHale
    3.  Parish
```

It's important to note that the actual numbers you use to mark the list have no effect on the HTML output Markdown produces. The HTML Markdown produces from the above list is:

```
    <ol>
    <li>Bird</li>
    <li>McHale</li>
    <li>Parish</li>
    </ol>
```

If you instead wrote the list in Markdown like this:

```
    1.  Bird
    1.  McHale
    1.  Parish
```

or even:

```
    3. Bird
    1. McHale
    8. Parish
```

you'd get the exact same HTML output. The point is, if you want to, you can use ordinal numbers in your ordered Markdown lists, so that the numbers in your source match the numbers in your published HTML. But if you want to be lazy, you don't have to.

If you do use lazy list numbering, however, you should still start the list with the number 1. At some point in the future, Markdown may support starting ordered lists at an arbitrary number.

List markers typically start at the left margin, but may be indented by up to three spaces. List markers must be followed by one or more spaces or a tab.

To make lists look nice, you can wrap items with hanging indents:

```
    *   Lorem ipsum dolor sit amet, consectetuer adipiscing
	elit. Aliquam hendrerit mi posuere lectus. Vestibulum
	enim wisi, viverra nec, fringilla in, laoreet vitae,
	risus.
    *   Donec sit amet nisl. Aliquam semper ipsum sit amet
	velit. Suspendisse id sem consectetuer libero luctus
	adipiscing.
```

But if you want to be lazy, you don't have to:

```
    *   Lorem ipsum dolor sit amet, consectetuer adipiscing
    elit. Aliquam hendrerit mi posuere lectus. Vestibulum
    enim wisi, viverra nec, fringilla in, laoreet vitae,
    risus.
    *   Donec sit amet nisl. Aliquam semper ipsum sit amet
    velit. Suspendisse id sem consectetuer libero luctus
    adipiscing.
```

If list items are separated by blank lines, Markdown will wrap the items in `<p>` tags in the HTML output. For example, this input:

```
    *   Bird
    *   Magic
```

will turn into:

```
    <ul>
    <li>Bird</li>
    <li>Magic</li>
    </ul>
```

But this:

```
    *   Bird

    *   Magic
```

will turn into:

```
    <ul>
    <li><p>Bird</p></li>
    <li><p>Magic</p></li>
    </ul>
```

List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be intended by either 4 spaces or one tab:

```
    1.  This is a list item with two paragraphs. Lorem ipsum
	dolor sit amet, consectetuer adipiscing elit. Aliquam
	hendrerit mi posuere lectus.

        Vestibulum enim wisi, viverra nec, fringilla in,
	laoreet vitae, risus. Donec sit amet nisl. Aliquam
	semper ipsum sit amet velit.

    2.  Suspendisse id sem consectetuer libero luctus
	adipiscing.
```

It looks nice if you indent every line of the subsequent paragraphs, but here again, Markdown will allow you to be lazy:

```
    *   This is a list item with two paragraphs.

        This is the second paragraph in the list item.
	You're only required to indent the first line. Lorem
	ipsum dolor sit amet, consectetuer adipiscing elit.

    *   Another item in the same list.
```

To put a blockquote within a list item, the blockquote's `>` delimiters need to be indented:

```
    *   A list item with a blockquote:

        > This is a blockquote
        > inside a list item.
```

To put a code block within a list item, the code block needs to be indented *twice* -- 8 spaces or two tabs:

```
    *   A list item with a code block:

            <code goes here>
```

It's worth noting that it's possible to trigger an ordered list by accident, by writing something like this:

```
    1986. What a great season.
```

In other words, a *number-period-space* sequence at the beginning of a line. To avoid this, you can backslash-escape the period:

```
    1986\. What a great season.
```

### Code Blocks
Pre-formatted code blocks are used for writing about programming or markup source code. Rather than forming normal paragraphs, the lines of a code block are interpreted literally. Markdown wraps a code block in both `<pre>` and `<code>` tags.

To produce a code block in Markdown, simply indent every line of the block by at least 4 spaces or 1 tab. For example, given this input:

```
    This is a normal paragraph:

        This is a code block.
```

Markdown will generate:

```
    <p>This is a normal paragraph:</p>

    <pre><code>This is a code block.
    </code></pre>
```

One level of indentation -- 4 spaces or 1 tab -- is removed from each line of the code block. For example, this:

```
    Here is an example of AppleScript:

        tell application "Foo"
            beep
        end tell
```

will turn into:

```
    <p>Here is an example of AppleScript:</p>

    <pre><code>tell application "Foo"
        beep
    end tell
    </code></pre>
```

A code block continues until it reaches a line that is not indented (or the end of the article).

Within a code block, ampersands (`&`) and angle brackets (`<` and `>`) are automatically converted into HTML entities. This makes it very easy to include example HTML source code using Markdown -- just paste it and indent it, and Markdown will handle the hassle of encoding the ampersands and angle brackets. For example, this:

```
        <div class="footer">
            © 2004 Foo Corporation
        </div>
```

will turn into:

```
    <pre><code><div class="footer">
        &copy; 2004 Foo Corporation
    </div>
    </code></pre>
```

Regular Markdown syntax is not processed within code blocks. E.g., asterisks are just literal asterisks within a code block. This means it's also easy to use Markdown to write about Markdown's own syntax.

### Horizontal Rules
You can produce a horizontal rule tag (`<hr />`) by placing three or more hyphens, asterisks, or underscores on a line by themselves. If you wish, you may use spaces between the hyphens or asterisks. Each of the following lines will produce a horizontal rule:

```
    * * *

    ***

    *****

    - - -

    ---------------------------------------
```

## Span Elements

### Links
Markdown supports two style of links: inline and reference.

In both styles, the link text is delimited by [square brackets].

To create an inline link, use a set of regular parentheses immediately after the link text's closing square bracket. Inside the parentheses, put the URL where you want the link to point, along with an *optional* title for the link, surrounded in quotes. For example:

```
    This is [an example](http://example.com/ "Title") inline link.

    [This link](http://example.net/) has no title attribute.
```

Will produce:

```
    <p>This is <a href="http://example.com/" title="Title">
    an example</a> inline link.</p>

    <p><a href="http://example.net/">This link</a> has no
    title attribute.</p>
```

If you're referring to a local resource on the same server, you can use relative paths:

```
    See my [About](/about/) page for details.
```

Reference-style links use a second set of square brackets, inside which you place a label of your choosing to identify the link:

```
    This is [an example][id] reference-style link.
```

You can optionally use a space to separate the sets of brackets:

```
    This is [an example] [id] reference-style link.
```

Then, anywhere in the document, you define your link label like this, on a line by itself:

```
    [id]: http://example.com/  "Optional Title Here"
```

That is:

- Square brackets containing the link identifier (optionally indented from the left margin using up to three spaces);

- followed by a colon;

- followed by one or more spaces (or tabs);

- followed by the URL for the link;

- optionally followed by a title attribute for the link, enclosed in double or single quotes, or enclosed in parentheses.

The following three link definitions are equivalent:

```
	[foo]: http://example.com/  "Optional Title Here"
	[foo]: http://example.com/  'Optional Title Here'
	[foo]: http://example.com/  (Optional Title Here)
```

Note: There is a known bug in Markdown.pl 1.0.1 which prevents single quotes from being used to delimit link titles.

The link URL may, optionally, be surrounded by angle brackets:

```
    [id]: <http://example.com/>  "Optional Title Here"
```

You can put the title attribute on the next line and use extra spaces or tabs for padding, which tends to look better with longer URLs:

```
    [id]: http://example.com/longish/path/to/resource/here
        "Optional Title Here"
```

Link definitions are only used for creating links during Markdown processing, and are stripped from your document in the HTML output.

Link definition names may constist of letters, numbers, spaces, and punctuation -- but they are not case sensitive. E.g. these two links:

```
	[link text][a]
	[link text][A]
```

are equivalent.

The implicit link name shortcut allows you to omit the name of the link, in which case the link text itself is used as the name. Just use an empty set of square brackets -- e.g., to link the word "Google" to the google.com web site, you could simply write:

```
	[Google][]
```

And then define the link:

```
	[Google]: http://google.com/
```

Because link names may contain spaces, this shortcut even works for multiple words in the link text:

```
	Visit [Daring Fireball][] for more information.
```

And then define the link:

```
	[Daring Fireball]: http://daringfireball.net/
```

Link definitions can be placed anywhere in your Markdown document. I tend to put them immediately after each paragraph in which they're used, but if you want, you can put them all at the end of your document, sort of like footnotes.

Here's an example of reference links in action:

```
    I get 10 times more traffic from [Google] [1] than from
    [Yahoo] [2] or [MSN] [3].

      [1]: http://google.com/        "Google"
      [2]: http://search.yahoo.com/  "Yahoo Search"
      [3]: http://search.msn.com/    "MSN Search"
```

Using the implicit link name shortcut, you could instead write:

```
    I get 10 times more traffic from [Google][] than from
    [Yahoo][] or [MSN][].

      [google]: http://google.com/        "Google"
      [yahoo]:  http://search.yahoo.com/  "Yahoo Search"
      [msn]:    http://search.msn.com/    "MSN Search"
```

Both of the above examples will produce the following HTML output:

```
    <p>I get 10 times more traffic from <a href="http://google.com/"
    title="Google">Google</a> than from
    <a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
    or
    <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>
```

For comparison, here is the same paragraph written using Markdown's inline link style:

```
    I get 10 times more traffic from
    [Google](http://google.com/ "Google") than from
    [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
    [MSN](http://search.msn.com/ "MSN Search").
```

The point of reference-style links is not that they're easier to write. The point is that with reference-style links, your document source is vastly more readable. Compare the above examples: using reference-style links, the paragraph itself is only 81 characters long; with inline-style links, it's 176 characters; and as raw HTML, it's 234 characters. In the raw HTML, there's more markup than there is text.

With Markdown's reference-style links, a source document much more closely resembles the final output, as rendered in a browser. By allowing you to move the markup-related metadata out of the paragraph, you can add links without interrupting the narrative flow of your prose.

### Emphasis
Markdown treats asterisks (`*`) and underscores (`_`) as indicators of emphasis. Text wrapped with one `*` or `_` will be wrapped with an HTML `<em>` tag; double `*`'s or `_`'s will be wrapped with an HTML `<strong>` tag. E.g., this input:

```
    *single asterisks*

    _single underscores_

    **double asterisks**

    __double underscores__
```

will produce:

```
    <em>single asterisks</em>

    <em>single underscores</em>

    <strong>double asterisks</strong>

    <strong>double underscores</strong>
```

You can use whichever style you prefer; the lone restriction is that the same character must be used to open and close an emphasis span.

Emphasis can be used in the middle of a word:

```
    un*fucking*believable
```

But if you surround an `*` or `_` with spaces, it'll be treated as a literal asterisk or underscore.

To produce a literal asterisk or underscore at a position where it would otherwise be used as an emphasis delimiter, you can backslash escape it:

```
    \*this text is surrounded by literal asterisks\*
```

### Code
To indicate a span of code, wrap it with backtick quotes (`` ` ``). Unlike a pre-formatted code block, a code span indicates code within a normal paragraph. For example:

```
    Use the `printf()` function.
```

will produce:

```
    <p>Use the <code>printf()</code> function.</p>
```

To include a literal backtick character within a code span, you can use multiple backticks as the opening and closing delimiters:

```
    ``There is a literal backtick (`) here.``
```

which will produce this:

```
    <p><code>There is a literal backtick (`) here.</code></p>
```

The backtick delimiters surrounding a code span may include spaces -- one after the opening, one before the closing. This allows you to place literal backtick characters at the beginning or end of a code span:

```
	A single backtick in a code span: `` ` ``

	A backtick-delimited string in a code span: `` `foo` ``
```

will produce:

```
	<p>A single backtick in a code span: <code>`</code></p>

	<p>A backtick-delimited string in a code span: <code>`foo`</code></p>
```

With a code span, ampersands and angle brackets are encoded as HTML entities automatically, which makes it easy to include example HTML tags. Markdown will turn this:

```
    Please don't use any `<blink>` tags.
```

into:

```
    <p>Please don't use any <code><blink></code> tags.</p>
```

You can write this:

```
    `—` is the decimal-encoded equivalent of `—`.
```

to produce:

```
    <p><code>&#8212;</code> is the decimal-encoded
    equivalent of <code>&mdash;</code>.</p>
```

### Images
Admittedly, it's fairly difficult to devise a "natural" syntax for placing images into a plain text document format.

Markdown uses an image syntax that is intended to resemble the syntax for links, allowing for two styles: inline and reference.

Inline image syntax looks like this:

```
    Alt text

    Alt text
```

That is:

- An exclamation mark: `!`;

- followed by a set of square brackets, containing the `alt` attribute text for the image;

- followed by a set of parentheses, containing the URL or path to the image, an optional `size` attribute (in width c height format) prefixed with a `=`, and an optional `title` attribute enclosed in double or single quotes.

Reference-style image syntax looks like this:

```
    ![Alt text][id]
```

Where "id" is the name of a defined image reference. Image references are defined using syntax identical to link references:

```
    [id]: url/to/image  =Optional size "Optional title attribute"
```

## Miscellaneous

### Automatic Links
Markdown supports a shortcut style for creating "automatic" links for URLs and email addresses: simply surround the URL or email address with angle brackets. What this means is that if you want to

show the actual text of a URL or email address, and also have it be

a clickable link, you can do this:

```
    <http://example.com/>
```

Markdown will turn this into:

```
    <a href="http://example.com/">http://example.com/</a>
```

Automatic links for email addresses work similarly, except that Markdown will also perform a bit of randomized decimal and hex entity-encoding to help obscure your address from address-harvesting spambots. For example, Markdown will turn this:

```
    <address@example.com>
```

into something like this:

```
    <a href="mailto:addre
    ss@example.co
    m">address@exa
    mple.com</a>
```

which will render in a browser as a clickable link to "address@example.com".

(This sort of entity-encoding trick will indeed fool many, if not most, address-harvesting bots, but it definitely won't fool all of them. It's better than nothing, but an address published in this way will probably eventually start receiving spam.)

### Backslash Escapes
Markdown allows you to use backslash escapes to generate literal characters which would otherwise have special meaning in Markdown's formatting syntax. For example, if you wanted to surround a word with literal asterisks (instead of an HTML `<em>` tag), you add backslashes before the asterisks, like this:

```
    \*literal asterisks\*
```

Markdown provides backslash escapes for the following characters:

backslash

`

backtick

*

asterisk

_

underscore

curly braces

[]

square brackets

()

parentheses

\#

hash mark

+

plus sign

-

minus sign (hyphen)

.

dot

exclamation mark

## BUGS
Markdown assumes that tabs are set to 4 spaces.

## AUTHOR
John Gruber http://daringfireball.net/

## SEE ALSO
markdown(1), markdown(3), mkd-callbacks(3), mkd-functions(3), mkd-extensions(7).

http://daringfireball.net/projects/markdown

http://docutils.sourceforge.net/mirror/setext.html

http://www.aaronsw.com/2002/atx/

http://textism.com/tools/textile/

http://docutils.sourceforge.net/rst.html

http://www.triptico.com/software/grutatxt.html

http://ettext.taint.org/doc/


mkd-extensions

title: mkd-extensions(7)

text:
# mkd-extensions(7)

## NAME
mkd-extensions — Extensions to the Markdown text formatting syntax

## DESCRIPTION
This version of markdown has been extended in a few ways by extending existing markup, creating new markup from scratch, and borrowing markup from other markup languages.

### Image dimensions
Markdown embedded images have been extended to allow specifying the dimensions of the image by adding a new argument =/height/x/width/ to the link description.

The new image syntax is

```
	alt text
```

### pseudo-protocols
Five pseudo-protocols have been added to links

id:

The alt text is marked up and written to the output, wrapped with  and .

class:

The alt text is marked up and written to the output, wrapped with  and .

raw:

The title is written -- with no further processing -- to the output. The alt text is discarded.

abbr:

The alt text is marked up and written to the output, wrapped with  and .

lang:

The alt text s marked up and written to the output, wrapped with  and .

### Pandoc headers
The markdown source document can have a 3-line Pandoc header in the format of

```
    % title
    % author(s)
    % date
```

which will be made available to the mkd_doc_title(), mkd_doc_author(), and mkd_doc_date() functions.

### Definition lists
A definition list item is defined as

```
=tag=
    description
```

(that is a =, followed by text, another =, a newline, 4 spaces of intent, and then more text.)

Alternatively, definition list items are defined as

```
tag
: description
```

(This is the format that PHP Markdown Extra uses.)

### embedded stylesheets
Stylesheets may be defined and modified in a  at the end of the line or a </style> at the beginning of a subsequent line.

Be warned that style blocks work like footnote links -- no matter where you define them they are valid for the entire document.

### alpha lists
Alphabetic lists (like regular numeric lists, but with alphabetic items) are supported. So:

```
    a. this
    b. is
    c. an alphabetic
    d. list
```

will produce:

```
    <ol type=a>
    <li>this</li>
    <li>is</li>
    <li>an alphabetic</li>
    <li>list</li>
    </ol>
```

### tables
PHP Markdown Extra tables are supported; input of the form

```
    header|header
    ------|------
     text | text
```

will produce:

```
    <table>
    <thead>
    <tr>
    <th>header</th>
    <th>header</th>
    </tr>
    </thead>
    <tbody>
    <tr>
    <td>text</td>
    <td>text</td>
    </tr>
    </tbody>
    </table>
```

The dashed line can also contain : characters for formatting; if a : is at the start of a column, it tells discount to align the cell contents to the left; if it's at the end, it aligns right, and if there's one at the start and at the end, it centers.

### strikethrough
A strikethrough syntax is supported in much the same way that ` is used to define a section of code. If you enclose text with two or more tildes, such as ~~erased text~~ it will be written as erased text. Like code sections, you may use as many ~ as you want, but there must be as many starting tildes as closing tildes.

### markdown extra-style footnotes
PHP Markdown Extra footnotes are supported. If a footnote link begins with a ^, the first use of that footnote will generate a link down to the bottom of the rendered document, which will contain a numbered footnote with a link back to where the footnote was called.

## AUTHOR
David Parsons http://www.pell.portland.or.us/~orc/

## SEE ALSO
markdown(1), markdown(3), mkd-callbacks(3), mkd-functions(3), mkd-line(3).

http://daringfireball.net/projects/markdown

http://michelf.com/projects/php-markdown


dnf.modularity

package: dnf

title: dnf.modularity(7)

summary: Modularity in DNF

text:
# dnf.modularity(7)

## NAME
dnf.modularity - Modularity in DNF

Modularity is new way of building, organizing and delivering packages. For more details see: https://docs.pagure.org/modularity/

## DEFINITIONS
modulemd

Every repository can contain modules metadata with modulemd documents. These documents hold metadata about modules such as Name, Stream or list of packages.

(non-modular) package

Package that doesn't belong to a module.

modular package

Package that belongs to a module. It is listed in modulemd under the artifacts section. Modular packages can be also identified by having %{modularitylabel} RPM header set.

(module) stream

Stream is a collection of packages, a virtual repository. It is identified with Name and Stream from modulemd separated with colon, for example "postgresql:9.6". Module streams can be active or inactive. active means the RPM packages from this stream are included in the set of available packages. Packages from inactive streams are filtered out. Streams are active either if marked as default or if they are explicitly enabled by a user action. Streams that satisfy dependencies of default or enabled streams are also considered active. Only one stream of a particular module can be active at a given point in time.

## PACKAGE FILTERING
Without modules, packages with the highest version are used by default.

Module streams can distribute packages with lower versions than available in the repositories available to the operating system. To make such packages available for installs and upgrades, the non-modular packages are filtered out when their name or provide matches against a modular package name from any enabled, default, or dependent stream. Modular source packages will not cause non-modular binary packages to be filtered out.

### Demodularized rpms
Contains names of RPMs excluded from package filtering for particular module stream. When defined in the latest active module, non-modular RPMs with the same name or provide which were previously filtered out will reappear.

## HOTFIX REPOSITORIES
In special cases, a user wants to cherry-pick individual packages provided outside module streams and make them available on along with packages from the active streams. Under normal circumstances, such packages are filtered out or rejected from getting on the system by Fail-safe mechanisms. To make the system use packages from a repository regardless of their modularity, specify module_hotfixes=true in the .repo file. This protects the repository from package filtering.

Please note the hotfix packages do not override module packages, they only become part of available package set. It's the package Epoch, Version and Release what determines if the package is the latest.

## FAIL-SAFE MECHANISMS

### Repositories with module metadata are unavailable
When a repository with module metadata is unavailable, package filtering must keep working. Non-modular RPMs must remain unavailable and must never get on the system.

This happens when:

- user disables a repository via --disablerepo or uses --repoid

- user removes a .repo file from disk

- repository is not available and has skip_if_unavailable=true

DNF keeps copies of the latest modulemd for every active stream and uses them if there's no modulemd available for the stream. This keeps package filtering working correctly.

The copies are made any time a transaction is resolved and started. That includes RPM transactions as well as any dnf module <enable|disable|reset> operations.

When the fail-safe data is used, dnf show such modules as part of @modulefailsafe repository.

### Orphaned modular packages
All packages that are built as a part of a module have %{modularitylabel} RPM header set. If such package becomes part of RPM transaction and cannot be associated with any available modulemd, DNF prevents from getting it on the system (package is available, but cannot be installed, upgraded, etc.). Packages from Hotfix repositories or Commandline repository are not affected by Fail-safe mechanisms.

## AUTHOR
See AUTHORS in DNF source distribution.

## COPYRIGHT
2012-2024, Red Hat, Licensed under GPLv2+


jw-backend-spec

package: docbook-utils

title: jw-backend-spec(7)

summary: interface between jw and its backends

text:
# jw-backend-spec(7)

## NAME
backend-spec - interface between jw and its backends

## DESCRIPTION
jw(1) calls backends like backends/html to do the "real" conversion work. The backend gets all necessary data delivered via environment variables ready to use.

This documentation describes those environment variables.

The backend is run in the directory where the output files are to be created. It should return 0 if there weren't any problem, and return a positive value otherwise.

## VARIABLES
SGML_FILE_NAME

The bare name of the source file

SGML_FILE

The full name and path of the source file

SGML_JADE

The name of the parser (usually Jade or OpenJade)

SGML_ARGUMENTS

The full argument-string for Jade or OpenJade

SGML_CATALOG_FILES

The list of catalog files needed by Jade or OpenJade

SGML_STYLESHEET

The style sheet to use

SGML_BASE_DIR

The base directory of the SGML system (default is /usr/share/sgml)

## SEE ALSO
frontend-spec(7)

## AUTHORS
Jochem Huhmann <joh@revier.com>


jw-frontend-spec

title: jw-frontend-spec(7)

summary: interface between jw and its frontends

text:
# jw-frontend-spec(7)

## NAME
frontend-spec - interface between jw and its frontends

## DESCRIPTION
jw(1) calls frontends like frontends/docbook to get the informations specific to a given input format. The frontend knows which information to return from the first command line parameter. It gets all necessary data via environment variables ready to use.

This document describes that command line parameter and those environment variables.

The frontend should return 0 if there weren't any problem, and return a positive value otherwise.

## VARIABLES
$1

The command line parameter, specifying which information to return. It can take the following values:

centralized-catalog

The frontend must return the DTD-specific centralized catalog name. Centralized catalogs normally reside in /etc/sgml and provide the location of all the catalog files useful for handling this input type (the catalog for the DTD, the catalog for the stylesheets, the catalog for the entities, ...)

style-sheet

The frontend must return the filename of the style sheet to be used for this document type and with the chosen backend.

SGML_CATALOGS_DIR

The directory where the centralized catalogs reside. It is normally /etc/sgml.

(This variable is valid only while determining the centralized catalog to use.)

SGML_BASE_DIR

The base directory of the SGML system. It is normally /usr/share/sgml.

(This variable is valid only while determining the style sheet to use.)

SGML_FILE

The name of the file to convert.

(This variable is valid only while determining the centralized catalog to use.)

SGML_TYPE

The type of the backend to use, whether it produces output files to be displayed online or to be printed out. It can take the value html or print.

(This variable is valid only while determining the style sheet to use).

SGML_STYLESHEETS

The desired custom stylesheet type, either none or default. If none, the frontend must return the file name of the style sheet provided by the system beneath the docbook-utils. If default, the frontend must return the custom stylesheet provided by the docbook-utils.

(This variable is valid only while determining the style sheet to use). SGML_XML

The metalanguage of the file to convert, either sgml or xml.

(This variable is valid only while determining the centralized catalog to use).

## SEE ALSO
backend-spec(7)

## AUTHORS
Jochem Huhmann <joh@revier.com>