Halaman man itu hebat, masalahnya ada pada pembaca man

• Kritik bahwa halaman man "tidak memiliki tautan yang saling terhubung" atau "teks tidak mengalir ulang saat jendela terminal diperkecil" memang umum, tetapi sebenarnya format man itu sendiri mendukung fitur tautan dan pengaturan ulang aliran teks
• Masalahnya adalah alat untuk membaca halaman man (seperti perintah man dan less) tidak mengimplementasikan fitur ini dengan baik

Struktur format halaman man

• Dokumen man umumnya ditulis dalam dua format berikut:
  • mdoc(7): format markup modern berbasis semantik
  • man(7): format lama yang digunakan pada 1979~1989
• Contoh (sebagian sintaks mdoc):

  .Sh NAME  
  .Nm openrc  
  .Nd stops and starts services for the specified runlevel  
  .Sh SYNOPSIS  
  

• .Sh, .Nm, .Nd masing-masing berarti header bagian, nama perintah, dan deskripsi
• Untuk mengeditnya secara langsung, perlu merujuk ke daftar makro mdoc

Fitur referensi (tautan) juga sudah tertanam

• Format mdoc mencakup makro tautan berikut:
• .Xr: referensi silang ke halaman man lain
• .Sx: referensi ke bagian lain dalam halaman yang sama
• Saat dikonversi ke HTML, ini dirender sebagai tautan nyata dan bisa diklik di browser
• Header bagian .Sh diperlakukan sebagai anchor sehingga dapat menjadi tujuan tautan .Sx
• Namun, saat dilihat di terminal dengan perintah man, fitur tautan ini tidak berfungsi

Kesimpulan: masalahnya bukan pada format man, melainkan pada penampilnya

• Saat ini perintah man menampilkan halaman dengan mem-pipe-nya ke less, dan cara ini tidak dapat menangani tautan
• Solusinya adalah:
• diperlukan penampil halaman baru yang memahami format man dan mendukung tautan
• Akan lebih baik jika sekaligus mengimplementasikan fitur pengaliran ulang teks otomatis (reflow) saat lebar terminal berubah

Informasi latar

• mdoc(7) adalah format yang diperkenalkan di 4.4BSD pada 1990-an
• man(7) adalah format klasik yang digunakan antara 1979 hingga 1989, dan kini hampir tidak lagi dipakai

[scari]

Saya langsung merasa relate hanya dengan melihat baris pertama di notifikasi Slackbot, jadi saya klik. Saya juga 100% setuju dengan pendapat bahwa yang jadi masalah adalah reader-nya.

...Tapi sepertinya manusia modern bahkan tidak memakai terminal, apalagi man. rtfm sudah menjadi peninggalan romantis dari zaman lampau.

[winterjung]

Saya mendeklarasikan seperti di bawah ini di mac dan menggunakannya seperti pman ls untuk melihatnya dalam bentuk PDF.

pman() {  
  mandoc -Tpdf "$(man -w $@)" | open -f -a Preview  
}  

[pcj9024]

Tips luar biasa... terima kasih

[pkj3186]

Wah, terima kasih banyak

[bbulbum]

Wah, ini benar-benar relate. Kalau bisa membaca man dengan baik, itu memang sangat berguna, tapi membacanya dengan baik itu terlalu sulit..

[GN⁺]

Opini Hacker News

• Ada pendapat bahwa meski sudah lama menulis dokumentasi dalam format mdoc dan mandb, menguasai bahasanya tetap sulit
  • mdoc dan mandb mirip seperti kumpulan makro di atas roff
  • Ada gagasan untuk mengubah semua halaman man ke Markdown agar bisa ditampilkan oleh sistem
  • Markdown punya lebih banyak alat, sehingga pengguna nonteknis pun bisa lebih mudah menulis dokumentasi
  • Namun Markdown kurang terstruktur, sehingga ada berbagai dialek berbeda di banyak program
• Menjelajahi halaman info di Emacs itu berguna, dan hal serupa juga bisa dilakukan untuk halaman man
  • Kekayaan halaman man yang ada saat ini adalah keunggulan yang tidak disadari banyak orang
  • Ada rasa sayang terhadap orang-orang yang ingin beralih ke Markdown
  • Jika beralih ke Markdown, akan sulit menerapkan tautan dan semantik umum dari solusi yang sudah ada
  • Jika melihat kasus pemindahan data ke JSON, ada upaya untuk menambahkan fitur yang rumit
• Menggunakan ft-man-plugin bawaan Vim sebagai penampil man default membantu menyelesaikan masalah
  • Tautan berfungsi, dan indentasi tetap terjaga saat baris dibungkus
  • Pengaturan default less bisa diperbaiki, tetapi tetap memerlukan pengguliran horizontal
• Banyak versi web dari halaman man menggunakan font monospace sehingga agak disayangkan
  • Halaman man online OpenBSD sangat bagus
  • Membaca halaman man di terminal juga menyenangkan
  • Fitur pencarian dan pengguliran setengah halaman paling sering digunakan
• pinfo memang untuk melihat halaman GNU Info, tetapi juga bisa menampilkan halaman man
  • Ia bisa mengenali dan menavigasi referensi silang antarhalaman
• Ada pendapat bahwa akan bagus jika ada fitur untuk langsung lompat ke penjelasan flag tertentu
  • Saat ini orang memakai ekspresi reguler untuk mencari penjelasan flag
• Disarankan untuk mempertimbangkan proyek mandoc
  • Halaman bisa diproses secara semantik untuk mendapatkan hasil yang lebih baik
• Ada pendapat bahwa Markdown adalah solusi yang lebih baik
  • Orang sudah terbiasa membaca dokumentasi di web atau editor kode, sehingga antarmuka lain terasa tidak nyaman
  • Para pengembang sudah terbiasa dengan Markdown, dan kebanyakan dokumentasi juga ditulis dalam Markdown
  • Halaman man lebih inferior baik bagi penulis dokumentasi maupun pembacanya