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.
[^] # Re: Twitter
Posté par anaseto . En réponse au lien Histoire des pages de man chez Sun. É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.