Linux / Commande apropos : trouver un manuel par mot-clé

apropos recherche un mot ou un motif dans les noms et descriptions courtes des pages de manuel, pour trouver une commande quand on connaît surtout la tâche à accomplir. Dans un environnement man-db, essayez par exemple apropos -L C copy, puis ouvrez un résultat avec man en précisant sa section ; cette recherche ne parcourt pas tout le texte des manuels.

Comprendre la recherche et lire un résultat

Les pages de manuel possèdent généralement une rubrique de nom et de description en une ligne. man-db en construit un index qu’apropos peut interroger rapidement. Les résultats dépendent donc des pages installées, de leurs descriptions, des chemins et de la langue sélectionnée.

La syntaxe générale est une notation documentaire, à adapter :

apropos [options] mot-cle...

Pour rechercher l’idée de copie dans les descriptions anglaises disponibles :

apropos -L C copy

Voici des exemples de lignes possibles, pas une garantie de sortie identique sur chaque système :

cp (1)  - copy files and directories
scp (1) - OpenSSH secure file copy

Le nom identifie la page, le nombre entre parenthèses sa section et le texte après le tiret sa description. Le numéro n’est pas une version du programme. Après avoir retenu un candidat, ouvrez sa documentation avant d’exécuter l’outil :

man 1 cp
man 1 scp

Les pages peuvent manquer ou relever d’une autre section sur votre installation. Le guide de man explique les sections et la lecture d’une page. Un résultat apropos indique une documentation enregistrée ; pour savoir ce que votre shell exécuterait réellement, utilisez séparément type -a nom ou command -v nom.

Combiner plusieurs mots sans élargir involontairement la recherche

Par défaut, un mot correspondant suffit

apropos -L C network address

Avec man-db, plusieurs arguments indépendants sont combinés par défaut comme une alternative : une entrée correspondant à network ou à address peut apparaître. Ce choix peut produire de nombreux résultats éloignés de l’intention initiale.

Exiger tous les mots avec -a

apropos -L C -a network address
apropos -L C --and user password

-a, ou --and, exige une correspondance pour chacun des mots fournis dans l’entrée considérée. Les mots ne doivent pas nécessairement apparaître côte à côte ni dans cet ordre.

Une expression entre guillemets est en revanche passée comme un seul argument :

apropos -L C 'network address'

Dans le mode par défaut, c’est un motif d’expression régulière contenant un espace. Ce n’est pas une autre écriture de -a network address. Les guillemets protègent d’abord les caractères contre l’interprétation du shell ; ils ne désactivent pas les règles de recherche d’apropos.

Choisir entre expression régulière, recherche exacte et joker

Les expressions régulières du mode par défaut

apropos -L C '^ssh'
apropos -L C 'file.*system'

Le premier motif vise le début d’un nom de page ou d’une description commençant par ssh. Il ne veut pas dire « n’importe quel mot commençant par ssh n’importe où ». Le second recherche file, puis system, avec éventuellement du texte entre les deux ; .* peut aussi correspondre à une séquence vide.

Le point, les crochets et l’astérisque ont un sens de motif. En particulier, ssh* en expression régulière ne représente pas le même motif qu’un joker de fichiers : l’astérisque répète l’élément précédent. Choisissez explicitement le mode correspondant à votre intention.

La recherche exacte avec -e

apropos -e printf

-e, ou --exact, demande une correspondance exacte du mot recherché au lieu de son interprétation comme expression régulière. La recherche porte toujours sur les noms et les descriptions ; elle ne se limite donc pas aux seuls noms de pages. Si vous connaissez déjà le nom et voulez son résumé, whatis printf est souvent plus direct.

Les jokers de style shell avec -w

apropos -w 'ssh*'
apropos -L C --wildcard '*password*'

-w, ou --wildcard, choisit les motifs de style shell. Laissez les guillemets pour que le shell ne remplace pas * par les fichiers du répertoire courant avant l’appel à apropos. Les règles de correspondance dans les descriptions ne sont pas à déduire d’une recherche de noms de fichiers ; le manuel d’apropos fourni par man-db décrit aussi l’interaction avec --exact.

Limiter les sections et conserver une description complète

apropos -L C -s 1 archive
apropos -L C -s 2,3 socket
apropos -L C --sections=5 password

La première commande privilégie les programmes utilisateur, la deuxième les appels système et fonctions de bibliothèque, la troisième les formats de fichiers. Une liste de sections peut être séparée par des virgules ou des deux-points.

Dans man-db, une section simple telle que 3 inclut aussi ses extensions, par exemple 3perl, si elles existent. Une section avec extension sélectionne plus précisément cette partie. Ce filtrage aide notamment à éviter de confondre une fonction de programmation avec une commande du shell.

Pour ne pas tronquer les descriptions à la largeur du terminal :

apropos -l -L C -a user account

-l rend la lecture ou l’enregistrement d’une description longue plus pratique. Il n’élargit pas la recherche au corps des pages.

Retrouver les principales options

Vérifiez l’implémentation avec apropos --version et ses détails avec man apropos. Ces options et les codes de retour présentés ici concernent man-db ; un autre système peut proposer des comportements différents.

Comprendre le lien avec man -k et les autres recherches

apropos -L C filesystem
man -L C -k filesystem

Dans man-db, man -k offre la recherche de type apropos. Le choix de l’interface ne change pas la nécessité de disposer des pages et de leurs index.

Un mot présent dans le corps d’un manuel peut être absent de son résumé et donc ne pas apparaître avec apropos. Inversement, un résultat pertinent sur le plan documentaire ne prouve pas que le programme soit exécutable dans votre session.

Diagnostiquer une recherche sans résultat

Vérifier le vocabulaire et la langue

apropos copier
apropos -L C copy
apropos -L C compress
apropos -L C archive

Un mot français nécessite une description correspondante dans la langue consultée. Si seuls des résumés anglais sont présents, essayez leurs termes. Simplifiez une expression trop précise et retirez temporairement un filtre de section ou -a pour voir s’il élimine les candidats attendus.

La locale C ne traduit pas les descriptions et n’installe pas une documentation manquante ; elle sélectionne la recherche dans ce contexte linguistique. Vérifiez aussi qu’une erreur de motif n’est pas confondue avec l’absence d’un sujet.

Vérifier les pages et l’index

Essayez d’ouvrir directement une page connue. Si elle fonctionne avec man mais pas dans la recherche, l’index peut être absent ou incomplet. Dans man-db, une mise à jour administrative peut être appropriée :

sudo mandb

mandb crée ou actualise les caches d’index ; il n’installe pas les pages qui manquent. Lisez ses messages, puis répétez la même recherche. Le manuel de mandb décrit aussi ses diagnostics. Une installation peut déjà actualiser les index lors des opérations de paquets ou de tâches périodiques : inutile de les reconstruire systématiquement.

Vérifier les chemins utilisés

manpath
printf '%s\n' "$MANPATH"
locale

Un chemin manuel ou une variable MANPATH personnalisée peut changer les hiérarchies consultées. -M permet d’en sélectionner temporairement pour le diagnostic, sans modifier globalement la session. Utilisez des chemins existants qui contiennent réellement les manuels et leurs index.

Distinguer absence de résultat et erreur dans un script

Dans man-db, le code 0 indique une recherche réussie, 16 aucune correspondance, 1 une erreur d’usage, de syntaxe ou de configuration et 2 une erreur de fonctionnement. Ne testez pas seulement si la sortie est vide.

Enregistrez le script complet suivant dans un nouveau fichier chercher-manuel.sh. Il attend un seul argument non vide et effectue une recherche exacte. Le code 64 est un choix de ce script pour ses propres erreurs d’arguments, distinct des codes d’apropos.

#!/usr/bin/env bash
if [ "$#" -ne 1 ] || [ -z "$1" ]; then
  printf 'Utilisation : bash chercher-manuel.sh mot-cle\n' >&2
  exit 64
fi

if apropos -e -- "$1" >/dev/null; then
  printf 'Une entrée de manuel correspond à la recherche.\n'
  exit 0
else
  query_status=$?
  case "$query_status" in
    16)
      printf 'Aucune entrée correspondante dans les index consultés.\n' >&2
      exit 16
      ;;
    *)
      printf 'Erreur de recherche : code %d\n' "$query_status" >&2
      exit "$query_status"
      ;;
  esac
fi

Exécutez-le avec Bash, sans devoir modifier les permissions du fichier :

bash chercher-manuel.sh printf
printf 'Code de retour : %s\n' "$?"

Un résultat donne le message de correspondance et le code 0. Une recherche valide mais sans entrée donne 16. Une erreur conserve le code retourné par l’outil, et ses diagnostics restent visibles sur la sortie d’erreur. L’absence du programme lui-même doit également être diagnostiquée ; elle ne signifie pas qu’aucun manuel pertinent n’existe.

Cette distinction rend l’automatisation plus lisible, mais ne transforme pas un index en inventaire complet du système. Après avoir trouvé un candidat, lisez la page et ses conditions d’utilisation avant de lancer la commande correspondante.