Pourquoi les pages de manuel n'ont-elles pas d'exemples?

Existe-t-il une raison pour laquelle la plupart des pages de manuel n'incluent pas quelques exemples courants? Ils expliquent généralement toutes les options possibles, mais cela rend encore plus difficile pour un débutant de comprendre comment il est "habituellement" utilisé.

Cela dépend des pages de manuel ... Traditionnellement, ils ont inclus une section avec des exemples - mais pour une raison qui manque généralement dans les pages de manuel sous Linux (et je suppose que d’autres utilisent des commandes GNU - qui sont la plupart du temps). Sous Solaris, par contre, presque toutes les pages de manuel incluent la section Exemple, souvent avec plusieurs exemples.

Si je devais deviner, la FSF / GNU décourage depuis longtemps l’utilisation des manpages et préfère que les utilisateurs utilisent plutôt les informations pour la documentation. infopages ont tendance à être plus complet que les pages de manuel, et en général ne comprennent des exemples. infoles pages sont aussi plus "d'actualité" - c'est-à-dire que des commandes associées (par exemple, des commandes pour trouver des fichiers) peuvent souvent être trouvées ensemble.

Une autre raison peut être que GNU et ses manpages sont utilisées sur de nombreux systèmes d’exploitation différents, qui peuvent être différents les uns des autres (après tout, il existe de nombreuses différences entre différentes distributions Linux). L'intention était peut-être que l'éditeur ait ajouté des exemples pertinents pour le système d'exploitation / distribution particulier - ce qui est évidemment rarement fait.

J'ajouterais également que les manpages n'avaient jamais été conçues pour "enseigner aux débutants". UNIX a été développé par des experts en informatique (ancien terme "hackers") et destiné à être utilisé par des experts en informatique. Les pages de manuel n'ont donc pas été conçues pour enseigner à un novice, mais pour aider rapidement un expert en informatique qui avait besoin d'un rappel pour une option obscure ou un format de fichier étrange - et cela se reflète dans la section d'une page de manuel.

man-pages sont donc destinées à

• Une référence rapide pour vous rafraîchir la mémoire; vous montrant comment appeler la commande et listant les options disponibles.
• Une description détaillée et approfondie - et généralement très technique - de tous les aspects de la commande. Il est écrit par des experts en informatique, pour d'autres experts en informatique.
• Liste des variables d'environnement et des fichiers (c'est-à-dire des fichiers de configuration) utilisés par la commande.
• Référence à d'autres documents (par exemple, livres) et à d'autres manpages - par exemple. pour le format des fichiers de configuration et des commandes associées / similaires.

Cela dit, je suis tout à fait d’accord avec vous pour dire que les manpages doivent contenir des exemples, car elles peuvent mieux expliquer cet usage que de parcourir la page de manuel elle-même. Dommage, les exemples ne sont généralement pas disponibles sur les manpages Linux ...

Exemple de la partie Exemple d'une page de manuel Solaris - zfs (1M):

(...)
EXEMPLES
     Exemple 1 Création d'une hiérarchie de système de fichiers ZFS

     Les commandes suivantes créent un système de fichiers nommé pool / home
     et un système de fichiers nommé pool / home / bob. Le point de montage
     / export / home est défini pour le système de fichiers parent et est
     hérité automatiquement par le système de fichiers enfant.

       # zfs create pool / home
       # zfs set mountpoint = / export / home pool / home
       # zfs create pool / home / bob

     Exemple 2 Création d'un instantané ZFS

     La commande suivante crée un instantané nommé hier.
     Cet instantané est monté à la demande dans le fichier .zfs / snapshot.
     répertoire situé à la racine du système de fichiers pool / home / bob.

       # zfs snapshot pool / home / bob @ hier

     Exemple 3 Création et destruction de plusieurs instantanés

     La commande suivante crée des instantanés nommés hier de
     pool / home et tous ses systèmes de fichiers descendants. Chaque
     l'instantané est monté à la demande dans le répertoire .zfs / snapshot
     à la racine de son système de fichiers. La deuxième commande détruit
     les instantanés nouvellement créés.

       # zfs snapshot -r pool / home @ hier
       # zfs destroy -r pool / home @ hier

SunOS 5.11 Dernier changement: 23 juil. 2012 51

Commandes d'administration système zfs (1M)

     Exemple 4 Désactivation et activation de la compression du système de fichiers

     La commande suivante désactive la propriété de compression pour
(...)

Cette page de manuel contient 16 (!) Exemples de ce type ... Félicitations à Solaris!
(Et j'admets que j'ai moi-même surtout suivi ces exemples, au lieu de lire toute la page de manuel de cette commande ...)

Je ne pense pas qu'il y ait une bonne réponse à cela. C'est une affaire de culture. Certaines pages de manuel ont un exemple d'utilisation. Par exemple man rsync. Vous pouvez essayer de changer la culture en écrivant à l'auteur de la page de manuel et en lui demandant d'ajouter un exemple d'utilisation ou (bien mieux) d'offrir lui-même des exemples d'utilisation. Si vous proposez à un auteur de logiciel libre un correctif, en particulier un correctif de documentation, il est environ dix mille fois plus susceptible d’obtenir le résultat souhaité qu’une simple demande.

Ça dépend:

• la plupart des programmes que vous jugeriez intéressants sont développés sur une période de temps, d'abord pour résoudre un problème, puis pour améliorer la solution. Les développeurs des programmes expliquent ce qu’ils pensaient être important de savoir (et la documentation n’était pas le problème qu’ils résolvaient).

• pour certains programmes, les développeurs préfèrent fournir des exemples de programmes ou de scripts qui montrent comment utiliser un programme (ou une bibliothèque) donné. Encore une fois, ceci est fait pour résoudre un problème: rendre le programme plus facile à tester.

  Certains exemples peuvent être basés sur des rapports de bugs d'utilisateurs et, le cas échéant, trouvent une place dans le manuel. De longs exemples sont rarement fournis dans les manuels, et de courts exemples ont le problème qu'ils tendent à être triviaux, répétitifs et ne fournissent pas vraiment à l'utilisateur autant de perspicacité qu'une description bien organisée du fonctionnement d'un programme.

• dans certains cas, vous trouverez une documentation fournie par d'autres personnes non impliquées dans le processus de développement. C'est-à-dire que les développeurs n'ont pas participé, à l'exception de l'examen de la documentation. Ce genre d’effort peut être négligé.

Si vous cherchez une alternative aux pages de manuel, vous pouvez toujours essayer les pages bro , qui ne montrent que divers exemples pour une commande, sur laquelle vous pouvez ensuite voter à partir d'une liste d'exemples soumis par la communauté. Par exemple, la commande bro tarvous donnera: