Sur OpenBSD 6.9 la blague sur tunefs(8) est encore en bas de page man de nos jours. Et les exemples de tar(1) utilisent des noms de fichier en Espéranto !
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
Des exemples seraient bienvenus pour des commandes un peu plus complexes (grep, sed, …)
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é.
Un cas que j'ai à traiter en ce moment, c'est la configuration des ports CAN sous linux en utilisant les sockets netlink. On trouve quelques infos sur SocketCAN dans la doc du noyau, il y a un peu de documentation sur netlink dans les pages de man, mais au final je n'ai pas eu d'autre choix que de tracer l'exécution de la commande ip avec strace pour voir exactement ce qu'elle fait, et reproduire les mêmes appels dans mon application. Un exemple m'aurait probablement fait gagner pas mal de temps (j'ai aussi essayé de lire le code de la commande ip, mais je me suis perdu dans plein de niveaux d'abstraction dont je n'avais pas besoin)
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
Que faudrait-il mettre comme exemples dans man ls ou man cp ou man mv par exemple ?
Des cas mettant en avant les usages typiques ou combinaisons d'options intéressantes ? ls(1), cp(1) et mv(1) ont quelques exemples sur OpenBSD. Après, ces commandes sont particulièrement simples, 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 ou se rafraîchir vite-fait la mémoire.
[…] 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
Tu es un connaisseur et tu dis « moi je préfère la pente raide parce que nanana ». Les gens comme toi et moi on a même pas besoin de ses pages de man. Les gens comme toi et moi on voit la maitrise du shell comme une finalité en soit ce n'est pas le cas de tout le monde et beaucoup de gens doivent l'utiliser pour juste répondre à un besoin de temps en temps. TextInfo est imbitable, c'est équivalent à dire à quelqu'un qui ne comprend pas une référence à judas de parcourir l'ancien et le nouveau testament, il pourra comprendre par lui même de quoi il s'agit.
Pour moi c'est se comporter comme un gatekeeper (même involontairement) c'est très difficile de se remettre dans les chaussures de quelqu'un qui découvre et qui est un peu perdu face à tout ça et si des trucs comme tldr peuvent aider des nouveaux c'est tant mieux (mais il faut savoir que ça existe etc).
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
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. À chaque projet et distributions de faire leurs choix d'être plus ou moins accueillant. D'avoir des petites roues pour apprendre le vélo, de commencer avec une draisienne ou de filer directement un monocycle (avec un peu d'entrainement ça se fait).
En vrai je ne comprends pas la résistance à un truc qui ne retire rien à personne sans autres argument que le principe de "les manpages devraient être …" (sans aucune références avec au contraire des exemples que les manpages ne suivent pas toujours ces principes) et s'appuyer sur une notion de difficulté qui est, ma foie, toute relative (j'ai aucun problème à utiliser tar, mais je dois toujours chercher pour utiliser cpio).
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
Les exemples donnés ne font qu'illustrer mon propos : c'est déjà dans le synopsis…
Il y a une différence : dans EXAMPLES seulement une partie des cas courants de la synopsis sont traités et ils sont accompagnés d'un bout de texte explicatif.
Pour le reste, oui, la section EXAMPLES peut devenir inutile pour un utilisateur expérimenté avec la commande et/ou qui a un besoin non couvert.
Je trouve personnellement cela normal.
Une page de manuel peut satisfaire les besoins de plusieurs types d'utilisateurs à des stades différents de maîtrise de la commande. Grâce à la standardisation des sections, plusieurs niveaux de lecture sont facilités sans faire perdre de temps aux utilisateurs expérimentés.
Utilisateur expérimenté nécessitant un rafraichissement de mémoire : SYNOPSIS suffit.
Utilisateur expérimenté voulant vérifier une option particulière : description détaillée de l'option (dans DESCRIPTION sur les BSDs, OPTIONS sur GNU/Linux).
Utilisateur occasionel (de cette commande) avec un besoin typique : EXAMPLES, puis le reste si insuffisant.
Utilisateur nouveau qui veut comprendre vite fait à quoi peut servir la commande avant de creuser plus loin : EXAMPLES, puis DESCRIPTION si nécessaire et s'il pense que ça peut correspondre à ce qu'il veut faire.
Utilisateur nouveau avec du temps : DESCRIPTION et EXAMPLES (dans n'importe quel ordre, au choix).
La présence d'une section EXAMPLES dans la page de manuel (plutôt qu'une cheatsheet ailleurs), outre que c'est plus pratique d'avoir les exemples dans le même document, a l'avantage d'offrir une certaine garantie de mise à jour et que les exemples proposés sont compatibles avec la version installée de la commande.
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.
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.
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
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
# Twitter
Posté par pulkomandy (site web personnel, Mastodon) . Évalué à 4.
J'anticipe parce que forcément quelqu'un va râler: c'est un fil Twitter. Merci de grouper les commentaires inutiles à ce sujet en-dessous de celui-ci.
[^] # Re: Twitter
Posté par Gil Cot ✔ (site web personnel, Mastodon) . Évalué à 1.
Ç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
[^] # Re: Twitter
Posté par barmic 🦦 . Évalué à 3.
https://threadreaderapp.com/thread/1427648667805093888.html
Sinon il faut scroller.
https://linuxfr.org/users/barmic/journaux/y-en-a-marre-de-ce-gros-troll
[^] # Re: Twitter
Posté par anaseto (site web personnel) . Évalué à 3.
Sur OpenBSD 6.9 la blague sur tunefs(8) est encore en bas de page man de nos jours. Et les exemples de tar(1) utilisent des noms de fichier en Espéranto !
[^] # Re: Twitter
Posté par Gil Cot ✔ (site web personnel, Mastodon) . Évalué à 1.
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 lsouman cpouman mvpar 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 dumanc'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
-Hvs-Ldans 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
learnouexampleque fournissent maintenant les programmes dit de cheatsheetIl 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 zipetman rsyncpour 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
[^] # Re: Twitter
Posté par pulkomandy (site web personnel, Mastodon) . Évalué à 2.
Des exemples seraient bienvenus pour des commandes un peu plus complexes (grep, sed, …)
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é.
Un cas que j'ai à traiter en ce moment, c'est la configuration des ports CAN sous linux en utilisant les sockets netlink. On trouve quelques infos sur SocketCAN dans la doc du noyau, il y a un peu de documentation sur netlink dans les pages de man, mais au final je n'ai pas eu d'autre choix que de tracer l'exécution de la commande ip avec strace pour voir exactement ce qu'elle fait, et reproduire les mêmes appels dans mon application. Un exemple m'aurait probablement fait gagner pas mal de temps (j'ai aussi essayé de lire le code de la commande ip, mais je me suis perdu dans plein de niveaux d'abstraction dont je n'avais pas besoin)
[^] # Re: Twitter
Posté par Gil Cot ✔ (site web personnel, Mastodon) . Évalué à 1.
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 ?
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
[^] # Re: Twitter
Posté par anaseto (site web personnel) . Évalué à 3.
Des cas mettant en avant les usages typiques ou combinaisons d'options intéressantes ? ls(1), cp(1) et mv(1) ont quelques exemples sur OpenBSD. Après, ces commandes sont particulièrement simples, 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 ou se rafraîchir vite-fait la mémoire.
[^] # Re: Twitter
Posté par Gil Cot ✔ (site web personnel, Mastodon) . Évalué à 1.
Les exemples donnés ne font qu'illustrer mon propos : c'est déjà dans le synopsis… Ainsi, pour moi :
n'apporte rien de plus que ce qui est marqué tout au début :
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
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
cutne me™ parlent pas tant que je n'ai pas vu les options et surtout lu :…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.
C'est ce que fait le synopsis, et c'est juste pour ça que j'utilise
manpour 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) :Par contre j'aime bien comment est présentée la notion de liste pour les drapeaux
“It is seldom that liberty of any kind is lost all at once.” ― David Hume
[^] # Re: Twitter
Posté par barmic 🦦 . Évalué à 5.
Tu es un connaisseur et tu dis « moi je préfère la pente raide parce que nanana ». Les gens comme toi et moi on a même pas besoin de ses pages de man. Les gens comme toi et moi on voit la maitrise du shell comme une finalité en soit ce n'est pas le cas de tout le monde et beaucoup de gens doivent l'utiliser pour juste répondre à un besoin de temps en temps. TextInfo est imbitable, c'est équivalent à dire à quelqu'un qui ne comprend pas une référence à judas de parcourir l'ancien et le nouveau testament, il pourra comprendre par lui même de quoi il s'agit.
Pour moi c'est se comporter comme un gatekeeper (même involontairement) c'est très difficile de se remettre dans les chaussures de quelqu'un qui découvre et qui est un peu perdu face à tout ça et si des trucs comme tldr peuvent aider des nouveaux c'est tant mieux (mais il faut savoir que ça existe etc).
https://linuxfr.org/users/barmic/journaux/y-en-a-marre-de-ce-gros-troll
[^] # Re: Twitter
Posté par Gil Cot ✔ (site web personnel, Mastodon) . Évalué à 1.
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
[^] # Re: Twitter
Posté par barmic 🦦 . Évalué à 3.
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. À chaque projet et distributions de faire leurs choix d'être plus ou moins accueillant. D'avoir des petites roues pour apprendre le vélo, de commencer avec une draisienne ou de filer directement un monocycle (avec un peu d'entrainement ça se fait).
En vrai je ne comprends pas la résistance à un truc qui ne retire rien à personne sans autres argument que le principe de "les manpages devraient être …" (sans aucune références avec au contraire des exemples que les manpages ne suivent pas toujours ces principes) et s'appuyer sur une notion de difficulté qui est, ma foie, toute relative (j'ai aucun problème à utiliser tar, mais je dois toujours chercher pour utiliser cpio).
https://linuxfr.org/users/barmic/journaux/y-en-a-marre-de-ce-gros-troll
[^] # Re: Twitter
Posté par Gil Cot ✔ (site web personnel, Mastodon) . Évalué à 1.
Nous sommes d'accord : il y a toujours apprentissage.
“It is seldom that liberty of any kind is lost all at once.” ― David Hume
[^] # Re: Twitter
Posté par anaseto (site web personnel) . Évalué à 4.
Il y a une différence : dans EXAMPLES seulement une partie des cas courants de la synopsis sont traités et ils sont accompagnés d'un bout de texte explicatif.
Pour le reste, oui, la section EXAMPLES peut devenir inutile pour un utilisateur expérimenté avec la commande et/ou qui a un besoin non couvert.
Je trouve personnellement cela normal.
Une page de manuel peut satisfaire les besoins de plusieurs types d'utilisateurs à des stades différents de maîtrise de la commande. Grâce à la standardisation des sections, plusieurs niveaux de lecture sont facilités sans faire perdre de temps aux utilisateurs expérimentés.
La présence d'une section EXAMPLES dans la page de manuel (plutôt qu'une cheatsheet ailleurs), outre que c'est plus pratique d'avoir les exemples dans le même document, a l'avantage d'offrir une certaine garantie de mise à jour et que les exemples proposés sont compatibles avec la version installée de la commande.
[^] # Re: Twitter
Posté par pulkomandy (site web personnel, Mastodon) . Évalué à 2.
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.
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.
[^] # Re: Twitter
Posté par Gil Cot ✔ (site web personnel, Mastodon) . Évalué à 1.
Attention,
--helpest 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.
“It is seldom that liberty of any kind is lost all at once.” ― David Hume
[^] # Re: Twitter
Posté par barmic 🦦 . Évalué à 2.
Quel principe ? D'ailleurs chez moi :
https://linuxfr.org/users/barmic/journaux/y-en-a-marre-de-ce-gros-troll
[^] # Re: Twitter
Posté par Gil Cot ✔ (site web personnel, Mastodon) . Évalué à 1. Dernière modification le 26 août 2021 à 22:08.
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
[^] # Re: Twitter
Posté par Anonyme . Évalué à 2.
Pour info
?s=20à la fin du lien sert à tracer comment l’URL du tweet a été partagé : https://twitter.com/_adryd/status/1429661064887738375.Suivre le flux des commentaires
Note : les commentaires appartiennent à celles et ceux qui les ont postés. Nous n’en sommes pas responsables.