Mengapa halaman manual tidak memiliki contoh?

52

Apakah ada alasan mengapa sebagian besar halaman manual tidak menyertakan beberapa contoh umum? Mereka biasanya menjelaskan semua opsi yang mungkin, tetapi itu membuat lebih sulit bagi pemula untuk memahami bagaimana "biasanya" digunakan.

man history

— Deepak Joy
sumber

1

Dugaan saya adalah bahwa mereka ingin menghemat ruang disk yang berharga, seperti dengan menyingkirkan CR. Lih Beckett, Watt , hal.8: "Banyak ruang berharga telah dihemat [...] dengan menghindari kata ganti refleksif kebanyakan setelah mengatakan ."

— Peter - Pasang kembali Monica

3

Salah satu upaya pemecahan masalah ini adalah tldr-pages.github.io , meskipun saya tidak melihat mengapa mereka membuatnya mudah untuk mengunduh semuanya di depan untuk akses offline.

— Nathan Long

man jqmemiliki lebih dari 1000 baris contoh (di Ubuntu 16.04)

— Motte001

49

Itu tergantung pada halaman manual ... Secara tradisional, mereka telah memasukkan bagian dengan contoh - tetapi untuk beberapa alasan yang biasanya hilang dari halaman manual di Linux (dan saya menganggap lain menggunakan perintah GNU - yang sebagian besar hari ini). Di Solaris di sisi lain, hampir setiap halaman manual menyertakan bagian Contoh, seringkali dengan beberapa contoh.

Jika saya menebak, FSF / GNU telah lama tidak menggunakan manhalaman dan lebih memilih pengguna untuk menggunakan info untuk dokumentasi. infohalaman cenderung lebih komprehensif daripada halaman manual, dan biasanya tidak menyertakan contoh-contoh. infohalaman juga lebih "topikal" - yaitu perintah terkait (mis. perintah untuk mencari file) sering kali dapat ditemukan bersama.

Alasan lain mungkin karena GNU dan manhalaman - halamannya digunakan pada banyak sistem operasi berbeda yang mungkin berbeda satu sama lain (ada banyak perbedaan di antara distro Linux yang berbeda). Maksudnya mungkin penerbit menambahkan contoh yang relevan dengan OS / distro tertentu - yang jelas jarang dilakukan.

Saya juga ingin menambahkan bahwa manhalaman tidak pernah dimaksudkan untuk "mengajar pemula". UNIX dikembangkan oleh para pakar komputer (istilah lama "peretas") dan dimaksudkan untuk digunakan oleh para pakar komputer. Halaman manual tidak dibuat untuk mengajar pemula, tetapi untuk dengan cepat membantu ahli komputer yang membutuhkan pengingat untuk beberapa opsi yang tidak jelas atau format file yang aneh - dan ini tercermin dalam bagaimana halaman manual dibagi.

man-halaman tersebut dimaksudkan sebagai

Referensi cepat untuk menyegarkan ingatan Anda; menunjukkan kepada Anda bagaimana perintah harus dipanggil, dan daftar opsi yang tersedia.
Deskripsi yang mendalam dan menyeluruh - dan biasanya sangat teknis - dari semua aspek perintah. Ini ditulis oleh para ahli komputer, untuk sesama ahli komputer.
Daftar variabel dan file lingkungan (yaitu file config) yang digunakan oleh perintah.
Referensi ke dokumentasi lain (mis. Buku), dan manhalaman lain - mis. untuk format file config dan perintah terkait / serupa.

Yang mengatakan, saya sangat setuju dengan Anda bahwa manhalaman harus memiliki contoh, karena mereka dapat menjelaskan penggunaan lebih baik daripada mengarungi halaman manual itu sendiri. Contoh yang terlalu buruk umumnya tidak tersedia di manhalaman Linux ...

Contoh bagian Contoh halaman manual Solaris - zfs (1M):

(...)
CONTOH
     Contoh 1 Membuat Hirarki Sistem File ZFS

     Perintah berikut membuat sistem file bernama pool / home
     dan sistem file bernama pool / home / bob. Titik pemasangan
     / export / home diatur untuk sistem file induk, dan
     secara otomatis diwarisi oleh sistem file anak.

       # zfs membuat kolam / rumah
       # zfs mengatur mountpoint = / export / home pool / home
       # zfs membuat pool / home / bob

     Contoh 2 Membuat Snapshot ZFS

     Perintah berikut ini membuat snapshot bernama kemarin.
     Snapshot ini dipasang sesuai permintaan di .zfs / snapshot
     direktori pada akar sistem file pool / home / bob.

       # zfs snapshot pool / home / bob @ kemarin

     Contoh 3 Membuat dan Menghancurkan Banyak Foto

     Perintah berikut ini membuat snapshot bernama kemarin dari
     pool / home dan semua sistem file turunannya. Setiap
     snapshot dipasang sesuai permintaan di direktori .zfs / snapshot
     di root sistem file-nya. Perintah kedua menghancurkan
     snapshot yang baru dibuat.

       # zfs snapshot -r pool / home @ kemarin
       # zfs menghancurkan -r pool / home @ kemarin

SunOS 5.11 Perubahan terakhir: 23 Jul 2012 51

Perintah Administrasi Sistem zfs (1M)

     Contoh 4 Menonaktifkan dan Mengaktifkan Kompresi Sistem File

     Perintah berikut menonaktifkan properti kompresi untuk
(...)

Halaman manual ini dilengkapi dengan 16 (!) Contoh seperti itu ... Kudos to Solaris!
(Dan saya akui saya sendiri kebanyakan mengikuti contoh-contoh ini, daripada membaca halaman manual keseluruhan untuk perintah ini ...)

— Baard Kopperud
sumber

2

Kalimat terakhir itu menyoroti masalah dengan memiliki contoh dalam manual. Kita mengambil contoh-contoh yang paling sesuai dengan kebutuhan seseorang tanpa sepenuhnya memahami implikasi penerapan alat tertentu. Dan kemudian, orang bisa mengatakan "Aku melakukannya seperti ini", tetapi tidak benar-benar mengapa atau apa artinya.

— Kusalananda

6

@ Kusalananda Dalam pembelaan saya, saya telah membaca tentang berbagai opsi dan tentang sub-perintah yang sebenarnya saya butuhkan - tidak semuanya (belum). Ini sama sekali tidak relevan untuk saya gunakan ... Meskipun ada bahaya penyalahgunaan, contoh memang memiliki tujuan - dan jika yang Anda butuhkan hanyalah penggunaan perintah yang paling dasar, membaca tentang semua lonceng dan peluit hampir tidak diperlukan.

— Baard Kopperud

@ Kusalananda Mungkin juga tergantung pada perintah. Sebagian besar utilitas Unix dan GNU yang saya tahu didokumentasikan dengan baik, tetapi Anda memerlukan dokumentasi untuk melakukan sesuatu yang masuk akal. Perintah Solaris yang lebih baru (terutama zfs) dirancang dengan sangat alami. Misalnya, zfs destroy pool/filesystempenggunaan dasar dan denda untuk 90% dari kasus penggunaan. Pilihan pendek seperti -runtuk recursivelebih khusus dan perlu konsultasi sebelum digunakan, karena mereka mungkin memiliki efek samping yang tidak diinginkan.

— user121391

26

Saya tidak berpikir ada jawaban yang bagus untuk ini. Itu hal budaya. Beberapa halaman manual memiliki contoh penggunaan. Misalnya man rsync. Anda dapat mencoba mengubah budaya dengan menulis ke penulis halaman manual dan memintanya untuk menambahkan beberapa penggunaan sampel atau (jauh lebih baik) menawarkan beberapa contoh penggunaan sampel sendiri. Jika Anda menawarkan tambalan pembuat perangkat lunak gratis, terutama tambalan dokumentasi, kemungkinan sepuluh ribu kali lebih besar untuk mencapai hasil yang diinginkan daripada permintaan sederhana.

— Faheem Mitha
sumber

7

Tergantung:

sebagian besar program yang menurut Anda menarik dikembangkan selama periode waktu tertentu, awalnya untuk memecahkan masalah dan kemudian untuk memperbaiki solusinya. Pengembang program menjelaskan apa yang mereka pikir penting untuk diketahui (dan dokumentasi bukanlah masalah yang mereka selesaikan).
untuk beberapa program, pengembang lebih suka memberikan contoh program atau skrip yang menunjukkan cara menggunakan program (atau pustaka) tertentu. Sekali lagi, ini dilakukan untuk menyelesaikan masalah: membuat program lebih mudah untuk diuji.

Beberapa contoh mungkin didasarkan pada laporan bug dari pengguna, dan ketika pendek menemukan tempat di manual. Contoh-contoh panjang jarang disediakan dalam manual, dan contoh-contoh pendek memiliki masalah yang cenderung sepele, berulang-ulang dan tidak benar-benar memberikan wawasan sebanyak mungkin kepada pengguna serta deskripsi yang terorganisir dengan baik tentang cara kerja program.
dalam beberapa kasus Anda akan menemukan dokumentasi yang disediakan oleh orang lain yang tidak terlibat dalam proses pengembangan. Artinya, pengembang tidak berpartisipasi kecuali untuk meninjau dokumentasi. Upaya semacam itu dapat diabaikan.

— Thomas Dickey
sumber

5

"Upaya semacam itu bisa diabaikan." Saya tidak yakin apa artinya ini.

— Faheem Mitha

Dokumentasi tidak berkontribusi apa pun yang berguna ketika tidak didasarkan pada pengalaman.

— Thomas Dickey

Sebenarnya, dokumentasi yang tidak didasarkan pada pengalaman dapat memberikan kontribusi negatif - yaitu kesalahan besar.

— alephzero

Tentu - saya sebutkan karena beberapa contoh yang pasti ada dalam pikiran OP masuk ke dalam kategori ini (saya akan menahan diri dari memberikan daftar di forum ini).

— Thomas Dickey

2

@ThomasDickey. Saya sepenuhnya tidak setuju dengan penilaian ini. Kemampuan untuk menulis utilitas tidak selalu disertai dengan kemampuan untuk menjelaskan API kepada pengguna akhir. T

— chiggsy

6

Jika Anda mencari alternatif untuk halaman manual, Anda selalu dapat mencoba halaman bro , yang hanya menampilkan berbagai contoh perintah, yang kemudian dapat Anda pilih di antara daftar contoh yang dikirimkan komunitas. Sebagai contoh, perintah bro tarakan memberi Anda:

— BandW2011
sumber