---
title: "Une man page peut-elle être sa propre antisèche ?"
locale: "fr"
url: "https://irz.fr/fr/articles/man-pages-own-cheatsheet-fr"
markdown_url: "https://irz.fr/fr/articles/man-pages-own-cheatsheet-fr.md"
category: "tech"
tags: ["CLI", "documentation", "Unix", "open source", "apprentissage"]
published_at: "2026-08-24T10:45:00.000Z"
author: "Camille Morel"
translation: "https://irz.fr/en/articles/man-pages-own-cheatsheet-en.md"
---

# Une man page peut-elle être sa propre antisèche ?

Julia Evans a demandé aux gens leurs man pages préférées, puis a tenté d'en réécrire une. L'exercice tient du reverse engineering : chaque convention de rangement dit quelque chose du programme.

Julia Evans l'avoue sans détour : elle oublie toujours le nom de l'option `-l` de grep, et la retrouver dans la man page lui prend, selon ses mots, une éternité.[1](https://jvns.ca/blog/2026/02/18/man-pages/) Partant de ce petit échec quotidien, elle a posé une question simple sur son blog : est-ce que la man page pourrait embarquer sa propre antisèche ? Avant d'écrire quoi que ce soit, elle avait demandé à ses abonnés Mastodon leurs pages man préférées, et le résultat mérite le détour.[1](https://jvns.ca/blog/2026/02/18/man-pages/)

## L'alphabet déborde

Le problème de départ tient en deux lignes de SYNOPSIS. Celle de `ls` liste `[-@ABCFGHILOPRSTUWabcdefghiklmnopqrstuvwxy1%,]`, celle de `grep` n'est guère mieux : quand une page énumère presque tout l'alphabet, le résumé d'utilisation ne résume plus rien.[1](https://jvns.ca/blog/2026/02/18/man-pages/)

La contrainte est réelle, pas cosmétique. Une man page tient dans un terminal, en ASCII, sur environ 80 colonnes, et doit rester lisible dans un pager sans images ni liens cliquables. Dans un cadre aussi serré, la manière dont on range l'information devient une décision de conception à part entière. C'est exactement ce que montrent les exemples relevés par Evans : cinq outils ont trouvé cinq réponses différentes au même problème « comment retrouver l'option vite ».

## Le résumé détourné

La réponse de rsync est celle qui a le plus surpris Evans. Le SYNOPSIS reste minimal :

```
rsync [OPTION...] SRC... [DEST]
```

et toute la complexité migre vers une section OPTION SUMMARY, absente de la plupart des autres pages : une ligne par option, `--verbose, -v   increase verbosity`, puis plus loin la section OPTIONS habituelle avec les descriptions complètes.[1](https://jvns.ca/blog/2026/02/18/man-pages/)[2](https://download.samba.org/pub/rsync/rsync.1) Nous avons vérifié dans la page publiée par Samba : cette structure existe bien telle quelle, synopsis court d'un côté, résumé d'une ligne de l'autre.[2](https://download.samba.org/pub/rsync/rsync.1)

> **Deux façons de survivre au SYNOPSIS**
> - grep empile les options dans le synopsis jusqu'à épuiser l'alphabet, sans hiérarchie visible.: Tout montrer
> - rsync garde un synopsis court et reporte le détail dans un résumé d'une ligne par option.: Déplacer
> Pages man grep et rsync ; le résumé détaillé d'Evans porte sur le cas grep.

## Ranger par intention

strace prend le problème par un autre bout : sa section OPTIONS est organisée par familles, General, Startup, Tracing, Filtering, plutôt que par ordre alphabétique.[3](https://man7.org/linux/man-pages/man1/strace.1.html) On y cherche moins « l'option qui commence par e » que « ce qui filtre quoi », et la structure suit.

C'est ce qui a poussé Evans à tenter l'exercice inverse sur grep : produire un OPTIONS SUMMARY groupé par catégories, DISPLAY, HOW TO MATCH, WHICH FILES TO SEARCH, MISC, et publier le brouillon tel quel.[1](https://jvns.ca/blog/2026/02/18/man-pages/)[4](https://gist.github.com/jvns/9f5966633875a4758e0d947a5b4dbdcf) Elle juge l'exercice sur un point unique : arriver à retrouver `-l` vite, parce que c'est précisément cette option qui se dérobe.

> L'essai grep
> **Réécrire, c'est décider**
> - Parcourir les options réelles de la page existante.: Lire
> - Trier par intention : affichage, correspondance, fichiers, divers.: Regrouper
> - Une ligne par option, sans perdre le sens.: Condenser
> - Relire chaque drapeau contre le manuel officiel.: Vérifier
> Les quatre gestes de l'exercice ; le quatrième est celui qui manque le plus souvent.

## Une coquille au passage

Ce dernier geste mérite qu'on s'y attarde, parce que le brouillon d'Evans l'illustre malgré elle. Dans sa version réécrite, l'option de contexte avant apparaît sous la forme `--before-context-num`. Le manuel GNU donne `--before-context=NUM`.[4](https://gist.github.com/jvns/9f5966633875a4758e0d947a5b4dbdcf)[5](https://www.gnu.org/software/grep/manual/grep.html) Un tiret au lieu d'un signe égal, rien de grave dans un brouillon expérimental, mais le genre de détail qui casse un copier-coller.

C'est la partie la plus intéressante de l'exercice : réécrire une documentation ne produit pas automatiquement une meilleure documentation. Ça produit une hypothèse, qu'il faut retester contre l'original. L'écriture révèle ce qu'on a compris, et parfois ce qu'on a compris de travers.

## L'exemple d'abord

Autre consensus des personnes interrogées par Evans : les pages avec exemples gagnent. Les man pages OpenBSD en ont une réputation solide, et leur page `tail` se termine par les deux usages exacts qu'Evans dit employer.[1](https://jvns.ca/blog/2026/02/18/man-pages/)[6](https://man.openbsd.org/tail) La page GNU du même outil n'a pas de section exemples du tout, ce qui n'est pas un oubli isolé : Evans rappelle que le projet GNU préfère entretenir ses manuels « info » et cite la page coreutils affirmant que ses man pages ne sont plus maintenues. Elle refuse d'aller plus loin sur ce terrain, qu'elle juge politique.[1](https://jvns.ca/blog/2026/02/18/man-pages/)[7](https://man7.org/linux/man-pages/man1/tail.1.html)

curl pousse la logique plus loin encore : chaque option de la page man possède son exemple, et côté source, chaque option vit dans son propre fichier avec un champ `Example`. Celui de `--cert` montre du même coup qu'il faut songer à ajouter `--key` : `curl --cert certfile --key keyfile $URL`.[8](https://curl.se/docs/manpage.html)[9](https://github.com/curl/curl/blob/master/docs/cmdline-opts/cert.md) Et quand la matière s'y prête, la page entière peut devenir une table scannable : `man ascii`, citée par plusieurs répondants, aligne octal, décimal, hexadécimal et caractère en colonnes, ce qui explique probablement son statut de page préférée.[1](https://jvns.ca/blog/2026/02/18/man-pages/) Perl fait un peu tout cela à la fois avec `perlcheat`, une man page qui assume être une antisèche, syntaxe comprise.[10](https://perldoc.perl.org/perlcheat)

## Clair et vrai

Ces bricolages ont un arrière-plan sérieux. En janvier, Evans racontait avoir retroussé les manches sur les pages man de Git, `git add`, `git checkout`, `git push`, `git pull`, avec une méthode explicite : environ 80 lecteurs testeurs recrutés sur Mastodon, chargés de signaler ce qui les bloquait vraiment, termes incompris, phrases confuses, contradictions entre sections.[11](https://jvns.ca/blog/2026/01/08/a-data-model-for-git/) Son bilan mérite d'être retenu par quiconque écrit de la doc : il n'est pas facile d'écrire des choses à la fois claires et vraies. Certaines phrases sont restées volontairement floues, parce que démêler tous les détails, par exemple ceux de `push.default`, aurait été un projet à part entière.[11](https://jvns.ca/blog/2026/01/08/a-data-model-for-git/)

Autrement dit, la question d'Evans sur les man pages n'est pas une question de style. Chaque solution relevée, résumé détourné chez rsync, familles chez strace, exemples chez curl et OpenBSD, table chez `man ascii`, antisèche chez Perl, répond au même souci de rendre l'outil trouvable, et chacune trahit ce que les mainteneurs ont décidé de protéger en priorité : la brièveté, la recherche par intention, le premier contact réussi ou la consultation rapide.

## La contrainte comme terrain

Il existe déjà des contournements hors man page : tldr.sh maintient une base d'exemples communautaires, le shell fish génère ses complétions directement depuis les pages man, et des navigateurs de documentation comme Dash ajoutent une table des matières à la version HTML.[1](https://jvns.ca/blog/2026/02/18/man-pages/)[12](https://tldr.sh) Mais ces outils contournent la contrainte au lieu de la travailler.

Ce que l'exercice d'Evans suggère, c'est qu'on peut faire l'inverse : prendre la contrainte comme un terrain d'étude. Elle-même a continué après ce billet de février, en publiant en mars des sections d'exemples pour les man pages de `tcpdump` et `dig`.[13](https://jvns.ca/blog/2026/03/10/examples-for-the-tcpdump-and-dig-man-pages/) Réécrire une man page, fût-ce dans un fichier jetable, oblige à décider où va chaque option, donc à deviner comment les mainteneurs pensent l'outil, puis à confronter cette lecture à la réalité du programme. Du reverse engineering appliqué à la documentation, avec un bénéfice immédiat : on repart en connaissant son outil un cran mieux, même quand le brouillon finit à la corbeille.

Et si le doute subsiste sur la valeur de l'exercice, il reste l'argument massue d'Evans elle-même : sa propre astuce pour retrouver une option consiste à chercher `^ *-a` dans le pager, une regex qu'elle oublie systématiquement.[1](https://jvns.ca/blog/2026/02/18/man-pages/) Entre une astuce qu'on oublie et une page qu'on réécrit, le choix est vite fait.

## References

1. [Julia Evans, Notes on clarifying man pages, 18 février 2026](https://jvns.ca/blog/2026/02/18/man-pages/)
2. [Page man rsync (rsync.1, samba.org)](https://download.samba.org/pub/rsync/rsync.1)
3. [Page man strace (man7.org)](https://man7.org/linux/man-pages/man1/strace.1.html)
4. [Julia Evans, brouillon d'un OPTIONS SUMMARY pour grep (gist)](https://gist.github.com/jvns/9f5966633875a4758e0d947a5b4dbdcf)
5. [Manuel GNU grep (GNU Project)](https://www.gnu.org/software/grep/manual/grep.html)
6. [Page man tail (OpenBSD)](https://man.openbsd.org/tail)
7. [Page man tail (GNU coreutils, man7.org)](https://man7.org/linux/man-pages/man1/tail.1.html)
8. [Page man curl (curl.se)](https://curl.se/docs/manpage.html)
9. [curl, docs/cmdline-opts/cert.md (dépôt curl)](https://github.com/curl/curl/blob/master/docs/cmdline-opts/cert.md)
10. [perlcheat, antisèche Perl intégrée aux man pages](https://perldoc.perl.org/perlcheat)
11. [Julia Evans, A data model for Git (and other docs updates), 8 janvier 2026](https://jvns.ca/blog/2026/01/08/a-data-model-for-git/)
12. [tldr.sh, base communautaire d'exemples](https://tldr.sh)
13. [Julia Evans, Examples for the tcpdump and dig man pages, 10 mars 2026](https://jvns.ca/blog/2026/03/10/examples-for-the-tcpdump-and-dig-man-pages/)