Gil Cot ✔ a écrit 6119 commentaires

Merci beaucoup : c'est bien plus clair maintenant (même si je suis loin de prétendre à la maîtrise.) La référence est très intéressante à lire (mais il faut du temps pour arriver à digérer la chose.)

Merci aussi pour ton retour d'expérience. Comme quoi, il peut être mieux d'inclure toute la police pour avoir un document plus exploitable …sauf si on sait qu'on va traiter des pages individuelles et qu'on en a les moyens.

“It is seldom that liberty of any kind is lost all at once.” ― David Hume

J'aurais du y penser plus tôt et faire ce procès…
Je suppose sinon qu'ils vont produire la preuve ADN ?

“It is seldom that liberty of any kind is lost all at once.” ― David Hume

Enfin une réponse qui explique bien l'utilité éventuelle de cette section. Le seul hic, c'est que dans les quelques commandes parcourues, je n'ai pas trouvé les exemples pertinents mais juste redondants du synopsis.

Concernant le dernier paragraphe, les exemples des cas les plus courants ne sont pas supposés changer avec l'ajout d'option et les options présentes ne devraient pas changer de signification d'une version à une autre. Mais j'entends le point, vu que tout est possible.

Pour les cheatsheet, il y en a en fait de différentes formes pour différents besoins. Ceux que j'aime bien utiliser sont ceux pour lesquels les références sont locales (et non les trucs sur Internet) et personnalisables/adaptables : ceci permet de distribuer de façon facile (plus facile/rapide que les manpages —perso j'en écris, mais dans ce cas je suis souvent le seul à pouvoir les mettre à jour sans compter que je ne suis pas éternel ni ne suis toujours au service de la même entreprise) des mémos pour des scripts maison et/ou des procédures à suivre pour certaines opérations etc.

“It is seldom that liberty of any kind is lost all at once.” ― David Hume

Surtout que si tu as juste besoin de retrouver le nom d'une option, tu trouveras ta réponse plus vite dans le --help de la commande plutôt que dans sa page de man.

Attention, --help est propre aux implémentations GNU… et les devs qui veulent reprendre le principe. Il n'y a pas les options longues dans les implémentations BSD…

Sinon, cette option affiche normalement les options les plus courantes (et dans le principe n'est pas supposé faire plus d'un écran –une vingtaine de lignes) sur une ligne, alors que dans la page complète chaque option est plus détaillée (cette option est donc une sorte de résumé) Donc on est d'accord sur le reste.

Ce qui permet d'avoir une page de man un peu plus détaillée pour les gens qui ne connaîssent pas du tout la commande ou qui ont besoin de détails plus précis.

C'est dommage si la page de man ne dit pas plus de choses que le --help.

“It is seldom that liberty of any kind is lost all at once.” ― David Hume

lire/utiliser les manpages s'apprend

Il y a des gens qui prennent des cours de langues alors qu'il est tout à fait possible d'apprendre simplement en immersion total, même sans aucun notion préalable.

Nous sommes d'accord : il y a toujours apprentissage.

“It is seldom that liberty of any kind is lost all at once.” ― David Hume

Non, pas une préférence pour la pente raide mais juste que j'ai appris à faire du vélo : lire/utiliser les manpages s'apprend (et pareil pour textinfo que je trouve pourtant bien fait même si je reste au vieux man par habitude.) Désolé de n'avoir pas découvert de la même façon que d'autres et de donner l'impression de gatekeeper.

J'ai mentionné les programmes dit cheatsheet (dont tldr fait parti) si tu remontes plus haut. Les besoins et les cibles ne sont pas les mêmes et aujourd'hui il y a une certaine variété de deux roues (la moto, le vélo classique ou à moteur électrique ou pas, et j'en passe)

“It is seldom that liberty of any kind is lost all at once.” ― David Hume

En effet, aucune banque ne pourra crècher la redevance.
Mais il peut faire plus soft en s'attaquant à une marque de javel qui lave même pas les péchés…

“It is seldom that liberty of any kind is lost all at once.” ― David Hume

Prête pas le flan à Socrate…

“It is seldom that liberty of any kind is lost all at once.” ― David Hume

Œufs et rats, de quoi attirer aussi des serpents non ?
Et peut-être aussi maître Renart ma poule.

“It is seldom that liberty of any kind is lost all at once.” ― David Hume

Les arbres dans (la cour) des usines c'est bien : ça humanise l'univers de l'ouvrier. ->[]

“It is seldom that liberty of any kind is lost all at once.” ― David Hume

Des exemples seraient bienvenues pour des commandes un peu plus complexes (grep, sed, …)

Je répondais dans un autre commentaire que je™ ne les trouve pas toujours utiles même si OpenBSD par exemple s'efforce d'en mettre, alors que chez AT&T ce n'était pas le cas (je n'ai pas vérifié mais c'est ce que mentionne le tweet : Sun avait suivi l'autre voie avant de revirer vers l'originale comme le fait Linux sur ce point, perdant du coup les sections d'exemples.)
Il se trouve que les exemples que tu mentionnes ont déjà des pages fort longues et ont fait couler de l'encre (au sens où il existe des livres de centaines de pages dont la moitié est fait d'exemples.) Peut-être qu'il aurait fallu des manpages dédiés aux exemples dans ce cas ?

On en trouve pas mal dans la documentation de Linux proprement dit (epoll, par exemple) et des APIs de systemd (sd_notify, les APIs pour récupérer les logs de journalctl). Dans ces cas là il n'y a en général aucune autre documentation disponible, et quand la page de man n'existe pas ou ne donne pas d'exemple, ça devient vite compliqué.

Oui, ma réponse faisait surtout référence aux rayons 1, 4, 5 et 7. Sous Linux, ou plus précisément pour les outils GNU, la tendance est d'avoir une page (de man) minimaliste pour faire office de mémento, et d'avoir un manuel utilisateur plus complet accessible en ligne (sur le site du projet) ou localement avec le système TextInfo. Là c'est effectivement assez riche pour rivaliser avec les équivalents papier O'reilly et autres.

Pour les rayons 2, 3 et souvent 4, (cas de epoll que tu cites) il y a en effet la plupart du temps les modèles types de code …qui pour ne sont pas toujours juste des exemples (dans le sens que je crois comprendre du post tweeter qui serait des trucs à copier-coller tel-quels.)
Mais je te rejoins sur le fait que la manpage doit être systématique pour eux (comme au bon vieux temps…)

“It is seldom that liberty of any kind is lost all at once.” ― David Hume

[…] mv(1) ont quelques exemples sur OpenBSD. Après, ces commandes sont particulièrement simples, […]

Les exemples donnés ne font qu'illustrer mon propos : c'est déjà dans le synopsis… Ainsi, pour moi :

mv -f foo bar

n'apporte rien de plus que ce qui est marqué tout au début :

mv [-fiv] source target

mais il y en a d'autres (chmod, find, cut, paste) où je trouve que ça peut être une porte d'entrée utile pour guider notre lecture du reste de la page de manuel …

Sous OpenBSD toujours, il y a une section d'exemples aussi pour cut, paste, find, chmod, etc.
Mais pour moi™, ça aide autant que d'aller copier des commandes sur le net sans trop comprendre… En prenant la cas du changement de permission de fichier, je préfère savoir que la forme est

chmod   [-h] [-R [-H | -L | -P]] mode file

et comprendre comment trouver le mode qui me convient en suivant la recette donnée (il se trouve qu'avec le pot que j'ai, ce qu'il me faut est rarement ce qui dans les exemples qui du coup sont inutiles en plus d'être redondants.)
De même, les exemples de cut ne me™ parlent pas tant que je n'ai pas vu les options et surtout lu :

List is a comma or whitespace separated set of numbers and/or number ranges. 
Number ranges consist of a number, a dash (‘-’), and a second number which 
select the fields or columns from the first number to the second, inclusive. 
Numbers or number ranges may be preceded by a dash, which selects all fields 
or columns from 1 to the first number. Numbers or number ranges may be 
followed by a dash, which selects all fields or columns from the last number 
to the end of the line. Numbers and number ranges may be repeated, 
overlapping, and in any order. It is not an error to select fields or columns 
not present in the input line.

…or une fois que j'ai ces informations, les exemples donnés ne me servent plus à rien, voir ne sont pas ceux que j'aurais choisi.

… ou se rafraîchir vite-fait la mémoire.

C'est ce que fait le synopsis, et c'est juste pour ça que j'utilise man pour des commandes simples/basiques (j'avais marqué que ça me permet de retrouver l'ordre des arguments positionnels, mais j'ai oublié d'indiquer que ça me montre la liste des bascules disponibles) Pour cette raison, je pesterai plutôt contre les formulations de type wtf suivant (ça fait vraiment doc bâclée où on a juste copié-collé le modèle sans faire le taf) :

cut OPTION... [FILE]...

Par contre j'aime bien comment est présentée la notion de liste pour les drapeaux

Use one, and only one of -b, -c or -f. Each LIST is made up of one range, or 
many ranges separated by commas. Selected input is written in the same order 
that it is read, and is written exactly once. Each range is one of:

N
    N'th byte, character or field, counted from 1 
N-
    from N'th byte, character or field, to end of line 
N-M
    from N'th to M'th (included) byte, character or field 
-M
    from first to M'th (included) byte, character or field

“It is seldom that liberty of any kind is lost all at once.” ― David Hume

bah voilà, c'est l'exploitation gratos du modèle qui est dénoncé.
au fait on avait pensé à rétribuer bébé guigoz ? et les bébés evian ?

“It is seldom that liberty of any kind is lost all at once.” ― David Hume

J'ai lu en diagonale, et je pense que tu utilise une version de FF assez récente …qui ne fait pas appel à une extension d'un lecteur externe mais à son traitement interne de type pdfjs (pour lequel le problème ne se pose pas)

“It is seldom that liberty of any kind is lost all at once.” ― David Hume

La sienne utilisait du bicarbonate bio…

“It is seldom that liberty of any kind is lost all at once.” ― David Hume

me rappelle les échanges ci et là sans oublier divers autres soucis

“It is seldom that liberty of any kind is lost all at once.” ― David Hume

C'est ça l'OpenSource : les deux schémas (par soi ou mutualisé par un artisan) sont possibles car la recette disponible, et on peut voir et contre-carrer les dérives (si le prix n'est plus en rapport avec les ingrédients et l'infrastructure mise en place on saura avoir des alternatives) Cela n'est plus possible avec du propriétaire cadenassé (remplaçons pain par coca-cola pour voir.) Étrangement c'est difficile à comprendre pour nos énarques qui parlent de souveraineté. (à moins qu'ils y voient un truc nébuleux comme les pseudo-démocraties qu'ils incarnent)

“It is seldom that liberty of any kind is lost all at once.” ― David Hume

Ce qu'elle dit c'est justement que si le noyau Linux était écrit en C normalisé, n'importe quel compilateur respectant ce standard ferait l'affaire. Là c'est écrit pour GCC, tout comme les gens de petit mou écrivent pour leur compilo maison. Dans les deux cas on perd l'interopérabilité que permet la norme.

Ceci dit je suis d'accord qu'on peut être ouvert (par une normalisation) et pourtant pas libre, et que les deux notions sont orthogonales (c'est ça qui ne paraît pas évident pour tout le monde.)

“It is seldom that liberty of any kind is lost all at once.” ― David Hume

Merci beaucoup : c'est bien plus clair !

Du coup, pour en revenir au sujet, une section EXEMPLES (je traduis en français) fait rarement sens pour être systématisé… Je vais de préciser un peu mon propos.

Que faudrait-il mettre comme exemples dans man ls ou man cp ou man mv par exemple ? Comme elle dit à un moment, on apprend à travers un livre (ou aujourd'hui un site interactif, ou généralement accompagné de quelqu'un) pour surtout pratiquer. Et tous les cas qu'on va pratiquer se ramènent au synopsis de la commande ; que faut-il de plus ? (question sérieuse) Perso, le premier usage que j'ai du man c'est pour m'assurer/remémorer l'ordre des arguments.

Mon second usage est pour trouver la bascule qui va bien. Là, j'aime bien qu'il y ait la liste dans une section dédiée. Normalement la description de chacune devrait se suffire. Là aussi, je ne vois pas ce qu'une section d'exemples ferait en plus : les fois où j'en ai vu, ça me semblait toujours trivial et surtout il n'y a pas l'exemple qui correspond à ce que je recherchais, mais on ne peut illustrer toutes les combinaisons de bascules possibles… Non, le mieux reste encore qu'au niveau de chaque option il y ait le rappel des options conflictuelles les mentions de combinaisons problématiques. (par exemple -H vs -L dans le traitement des liens symboliques.)
Elle compare, à juste titre, avec un dictionnaire, et dit elle-même que ce n'est pas l'outil adéquat pour apprendre… On dirait qu'elle cherche une commande learn ou example que fournissent maintenant les programmes dit de cheatsheet

Il y a d'autres sections que j'aime bien consulter quand j'écris des scripts parce-qu'il faut comprendre quelles variables d'environnement vont influer et quels sont les bogues et/ou limitations connues. Ces mêmes sections sont utiles en dehors du scripting, quand l'on veut personnaliser son environnement de travail. Je ne vois pas comment une section d'exemples peut remplacer cela ou ce que cela apportera de plus.
Enfin, des exemples bien sentis sont glissés ci et là (voir par exemple man zip et man rsync pour ce qui me vient en tête de suite) et il n'est pas besoin d'avoir une section dédiée qui n'apporterait rien.

“It is seldom that liberty of any kind is lost all at once.” ― David Hume

ou manger les pommes avec les protéines incluses ?

“It is seldom that liberty of any kind is lost all at once.” ― David Hume

Ça se lit comment ? Je ne vois pas l'histoire des pages du manuel du Soleil mais juste une question parmi plusieurs éparpillées.

“It is seldom that liberty of any kind is lost all at once.” ― David Hume

Merci (je comprends mieux)

“It is seldom that liberty of any kind is lost all at once.” ― David Hume

PS : Je n'ai que plussoyé ; faut croire que tout le monde ne fonctionne pas pseudo…

“It is seldom that liberty of any kind is lost all at once.” ― David Hume

C'est quoi « crtl + zut » ? (question pour ma culture)

“It is seldom that liberty of any kind is lost all at once.” ― David Hume

Le clavier normal (qwert) fait bien l'affaire pour les parenthèses. Et Emacs est dans la continuité des environnements LISP (c'est son langage d'extension), d'où le commentaire.

“It is seldom that liberty of any kind is lost all at once.” ― David Hume