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

52

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é.

man history

— Deepak Joy
source

1

J'imagine qu'ils voulaient économiser un espace disque précieux, par exemple en se débarrassant du CR. Cf. Beckett, Watt , p.8: "Un espace précieux a été sauvé [...] en évitant le pronom réflexif pléthorique après avoir été dit ."

— Peter - Réintégrer Monica

3

Une solution de contournement du problème est celle de tldr-pages.github.io , bien que je ne vois pas pourquoi ils facilitent le téléchargement de tout le contenu pour un accès hors connexion.

— Nathan Long

man jqa plus de 1000 lignes d'exemples (sur Ubuntu 16.04)

— Motte001

49

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 ...)

— Baard Kopperud
source

2

Cette dernière phrase met en évidence le problème de la présence d’exemples dans les manuels. On prend les exemples qui correspondent le mieux à ses besoins sans comprendre parfaitement les implications de l'application particulière de l'outil. Et plus tard, on peut simplement dire "je l’ai fait comme ça", mais pas vraiment pourquoi ni ce que cela voulait dire.

— Kusalananda

6

@Kusalananda Pour ma défense, j'ai lu beaucoup d'informations sur les différentes options et sur les sous-commandes dont j'ai réellement besoin - mais pas tout (encore). Il est tout simplement pas pertinent pour mon usage ... Malgré le risque d'abus, les exemples ne servent un but - et si tout ce que vous avez besoin est juste le plus l' utilisation de base d'une commande, la lecture de toutes les cloches et de sifflets sont à peine nécessaire.

— Baard Kopperud

@Kusalananda Cela peut également dépendre des commandes. La plupart des utilitaires Unix et GNU que je connais sont bien documentés, mais vous avez besoin de la documentation pour faire quoi que ce soit de sensé. Les nouvelles commandes Solaris (en particulier zfs) sont conçues assez naturellement. Par exemple, zfs destroy pool/filesystemest un usage de base et une amende pour 90% des cas d'utilisation. Les options courtes comme -rpour recursivesont plus spéciales et nécessitent une consultation avant utilisation, car elles pourraient avoir des effets secondaires non voulus.

— user121391

26

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.

— Faheem Mitha
source

7

Ç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é.

— Thomas Dickey
source

5

"Ce genre d'effort peut être négligé." Je ne suis pas sûr de ce que cela signifie.

— Faheem Mitha

La documentation n'apporte rien d'utile si elle n'est pas basée sur l'expérience.

— Thomas Dickey

En fait, une documentation non basée sur l'expérience peut apporter une contribution négative, c'est-à-dire qu'elle est tout simplement fausse.

— alephzero

Bien sûr - j'en ai parlé parce que certains des exemples qu'OP a sans aucun doute en tête tombent dans cette catégorie (je m'abstiendrai de fournir une liste sur ce forum).

— Thomas Dickey

2

@ThomasDickey. Je suis complètement en désaccord avec cette évaluation. La possibilité d'écrire un utilitaire ne vient pas nécessairement avec la capacité d'expliquer l'API à un utilisateur final. T

— Chiggsy

6

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:

— BandW2011
source