Perché le pagine man non hanno esempi?

C'è un motivo per cui la maggior parte delle pagine man non include alcuni esempi comuni? Di solito spiegano tutte le possibili opzioni, ma ciò rende ancora più difficile per un principiante capire come viene "normalmente" utilizzato.

Dipende dalle pagine man ... Tradizionalmente, hanno incluso una sezione con esempi - ma per qualche ragione che di solito manca dalle pagine man sotto Linux (e presumo che altri utilizzino i comandi GNU - che sono la maggior parte in questi giorni). Su Solaris, d'altra parte, quasi tutte le pagine man includono la sezione Esempio, spesso con diversi esempi.

Se dovessi indovinare, FSF / GNU ha a lungo scoraggiato l'uso delle manpagine e preferisce invece agli utenti utilizzare le informazioni per la documentazione. infopagine tendono ad essere più completo rispetto pagine man, e di solito non includono esempi. infole pagine sono anche più "attuali", ovvero i comandi correlati (ad es. comandi per la ricerca di file) sono spesso reperibili insieme.

Un altro motivo potrebbe essere che GNU e le sue manpagine sono utilizzate su molti sistemi operativi diversi che possono differire l'uno dall'altro (dopo tutto ci sono molte differenze solo tra diverse distro Linux). L'intenzione potrebbe essere che l'editore abbia aggiunto esempi rilevanti per il particolare sistema operativo / distro, cosa che ovviamente viene fatta raramente.

Vorrei anche aggiungere che le manpagine non sono mai state pensate per "insegnare ai principianti". UNIX è stato sviluppato da esperti di computer (vecchio termine "hacker") e destinato ad essere utilizzato da esperti di computer. Le pagine man non sono state quindi create per insegnare a un principiante, ma per aiutare rapidamente un esperto di computer che aveva bisogno di un promemoria per qualche oscura opzione o strano formato di file - e questo si riflette nel modo in cui una pagina man è sezionata.

man-pagine sono quindi intese come

• Un rapido riferimento per rinfrescare la memoria; mostrandoti come chiamare il comando e elencando le opzioni disponibili.
• Una descrizione profonda e completa - e di solito molto tecnica - di tutti gli aspetti del comando. È scritto da esperti informatici, per colleghi esperti informatici.
• Elenco di variabili e file di ambiente (ad es. File di configurazione) utilizzati dal comando.
• Riferimento ad altra documentazione (ad es. Libri) e altre manpagine - ad es. per il formato dei file di configurazione e comandi correlati / simili.

Detto questo, sono molto d'accordo con te sul fatto che le manpagine dovrebbero avere degli esempi, dal momento che possono spiegarne l'uso meglio che passare attraverso la stessa pagina man. Esempi troppo cattivi in ​​genere non sono disponibili nelle manpagine Linux ...

Esempio della parte di esempio di una pagina man di Solaris - zfs (1M):

(...)
ESEMPI
     Esempio 1 Creazione di una gerarchia di file system ZFS

     I seguenti comandi creano un filesystem chiamato pool / home
     e un filesystem chiamato pool / home / bob. Il punto di montaggio
     / export / home è impostato per il filesystem padre ed è
     ereditato automaticamente dal filesystem figlio.

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

     Esempio 2 Creazione di un'istantanea ZFS

     Il comando seguente crea un'istantanea denominata ieri.
     Questa istantanea è montata su richiesta in .zfs / snapshot
     directory alla radice del file system pool / home / bob.

       # zfs pool di istantanee / home / bob @ ieri

     Esempio 3 Creazione e distruzione di più istantanee

     Il comando seguente crea istantanee denominate ieri di
     pool / home e tutti i suoi file system discendenti. Ogni
     lo snapshot è montato su richiesta nella directory .zfs / snapshot
     alla radice del suo file system. Il secondo comando distrugge
     le istantanee appena create.

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

SunOS 5.11 Ultima modifica: 23 lug 2012 51

Comandi di amministrazione del sistema zfs (1M)

     Esempio 4 Disabilitazione e abilitazione della compressione del file system

     Il seguente comando disabilita la proprietà di compressione per
(...)

Questa particolare pagina man contiene 16 (!) Esempi del genere ... Complimenti a Solaris!
(E ammetto che io stesso ho seguito principalmente questi esempi, invece di leggere l'intera pagina man per questo comando ...)

Non credo che ci sia una buona risposta a questo. È una cosa culturale. Alcune pagine man hanno un esempio di utilizzo. Es man rsync. Puoi provare a cambiare la cultura scrivendo all'autore della pagina man e chiedendogli di aggiungere qualche esempio di utilizzo o (molto meglio) offrendo tu stesso alcuni esempi di utilizzo. Se offri a un autore di software libero una patch, in particolare una patch di documentazione, è circa diecimila volte più probabilità di ottenere il risultato desiderato rispetto a una semplice richiesta.

Dipende:

• la maggior parte dei programmi che potresti trovare interessanti sono sviluppati per un periodo di tempo, inizialmente per risolvere un problema e successivamente per migliorare la soluzione. Gli sviluppatori dei programmi spiegano ciò che pensavano fosse importante sapere (e la documentazione non era il problema che stavano risolvendo).

• per alcuni programmi, gli sviluppatori preferiscono fornire programmi o script di esempio che mostrano come utilizzare un determinato programma (o libreria). Ancora una volta, questo viene fatto per risolvere un problema: rendere il programma più facile da testare.

  Alcuni degli esempi potrebbero essere basati su segnalazioni di errori da parte degli utenti e, quando breve, trova un posto nel manuale. Raramente vengono forniti esempi lunghi nei manuali e brevi esempi hanno il problema che tendono ad essere banali, ripetitivi e che non forniscono realmente all'utente una visione tanto approfondita quanto una descrizione ben organizzata del modo in cui un programma funziona.

• in alcuni casi troverai la documentazione fornita da altri non coinvolti nel processo di sviluppo. Cioè, gli sviluppatori non hanno partecipato tranne per la revisione della documentazione. Questo tipo di sforzo può essere ignorato.

Se stai cercando un'alternativa alle pagine man, puoi sempre provare pagine bro , che mostrano solo vari esempi di un comando, su cui puoi votare in un elenco di esempi inviati dalla comunità. Ad esempio, il comando bro tarti darà: