Cara Membuat Halaman manual di Linux

Ingin program Linux baru Anda terlihat profesional? Berikan halaman man . Kami akan menunjukkan cara termudah dan tercepat untuk melakukannya.

Halaman pria

Ada inti kebenaran dalam lelucon Unix lama, "satu-satunya perintah yang perlu Anda ketahui adalah man ." Halaman man berisi banyak pengetahuan, dan mereka harus menjadi tempat pertama yang Anda buka ketika Anda ingin belajar tentang sebuah perintah.

Menyediakan halaman man untuk utilitas atau perintah yang telah Anda tulis akan meningkatkannya dari bagian kode yang berguna menjadi paket Linux yang lengkap. Orang mengharapkan halaman man disediakan untuk program yang ditulis untuk Linux. Jika Anda secara native mendukung Linux, halaman man adalah wajib jika Anda ingin program Anda dianggap serius.

Secara historis halaman man telah ditulis menggunakan satu set makro pemformatan. Saat Anda memanggil man untuk membuka halaman, ia akan memanggil groff untuk membaca file dan menghasilkan output yang diformat, sesuai dengan makro dalam file. Output disalurkan ke less , dan kemudian ditampilkan untuk Anda.

Kecuali Anda sering membuat halaman man , menulis satu dan memasukkan makro secara manual adalah kerja keras. Tindakan membuat halaman man yang diurai dengan benar dan terlihat benar dapat menyalip tujuan Anda untuk memberikan deskripsi perintah Anda yang ringkas, namun menyeluruh.

Anda harus berkonsentrasi pada konten Anda, tidak melawan sekumpulan makro yang tidak jelas.

TERKAIT: Cara Menggunakan Perintah man Linux: Rahasia dan Dasar Tersembunyi

pandoc untuk Penyelamatan

Program pandoc membaca file penurunan harga dan menghasilkan file baru dalam sekitar 40 bahasa markup dan format dokumen yang berbeda, termasuk halaman man . Ini benar-benar mengubah proses penulisan halaman man sehingga Anda tidak perlu bergulat dengan hieroglif.

Untuk memulai, Anda dapat menginstal pandoc di Ubuntu dengan perintah ini:

 sudo apt-get install pandoc 

Di Fedora, perintah yang Anda butuhkan adalah sebagai berikut:

 sudo dnf instal pandoc 

Di Manjaro, ketik:

 sudo pacman -Syu pandoc 

TERKAIT: Cara Menggunakan pandoc untuk Mengonversi File di Baris Perintah Linux

Bagian dari Halaman pria

halaman man berisi bagian yang mengikuti konvensi penamaan standar. Bagian man Anda ditentukan oleh kecanggihan perintah yang Anda gambarkan.

Minimal, sebagian besar halaman manual berisi bagian ini:

• Name : Nama perintah dan one-liner bernas yang menjelaskan fungsinya.
• Sinopsis : Deskripsi singkat tentang doa yang dapat digunakan seseorang untuk meluncurkan program. Ini menunjukkan jenis parameter baris perintah yang diterima.
• Description : Deskripsi perintah atau fungsi.
• Opsi : Daftar opsi baris perintah, dan apa yang mereka lakukan.
• Contoh : Beberapa contoh penggunaan umum.
• Nilai Keluar : Kemungkinan kode kembali dan artinya.
• Bugs : Daftar bug dan kebiasaan yang diketahui. Terkadang, ini dilengkapi dengan (atau diganti dengan) tautan ke pelacak masalah untuk proyek tersebut.
• Author : Orang atau orang yang menulis perintah.
• Hak Cipta : Pesan hak cipta Anda. Ini juga biasanya mencakup jenis lisensi di mana program dirilis.

Jika Anda melihat beberapa halaman man yang lebih rumit, Anda akan melihat ada banyak bagian lain juga. Misalnya, coba man man . Namun, Anda tidak harus memasukkan semuanya—hanya yang benar-benar Anda butuhkan. halaman man bukanlah tempat untuk bertele-tele.

Beberapa bagian lain yang cukup sering Anda lihat adalah:

• Lihat Juga : Perintah lain yang terkait dengan materi pelajaran yang menurut sebagian orang berguna atau relevan.
• Files : Daftar file yang disertakan dalam paket.
• Peringatan : Hal-hal lain yang perlu diketahui atau diwaspadai.
• History : Riwayat perubahan untuk perintah.

Bagian dari Manual

Manual Linux terdiri dari semua halaman man , yang kemudian dibagi menjadi beberapa bagian bernomor ini:

1. Program yang dapat dieksekusi: Atau, perintah shell.
2. Panggilan sistem: Fungsi yang disediakan oleh kernel.
3. Panggilan perpustakaan: Fungsi dalam perpustakaan program.
4. File khusus.
5. Format dan konvensi file: Misalnya, “/etc/passwd”.
6. Permainan.
7. Miscellaneous: Paket dan konvensi makro, seperti groff .
8. Perintah administrasi sistem: Biasanya disediakan untuk root.
9. Rutinitas kernel: Biasanya tidak diinstal secara default.

Setiap halaman man harus menunjukkan milik bagian mana, dan itu juga harus disimpan di lokasi yang sesuai untuk bagian itu, seperti yang akan kita lihat nanti. Halaman man untuk perintah dan utilitas termasuk dalam bagian satu.

Format Halaman pria

Format makro groff tidak mudah diuraikan secara visual. Sebaliknya, penurunan harga sangat mudah.

Di bawah ini adalah halaman manual di groff .

Halaman yang sama ditunjukkan di bawah ini dengan penurunan harga.

Bagian Depan

Tiga baris pertama membentuk sesuatu yang disebut materi depan . Ini semua harus dimulai dengan tanda persentase ( % ), tanpa spasi di depan kecuali satu setelahnya, diikuti oleh:

• Baris pertama: Berisi nama perintah, diikuti oleh bagian manual dalam tanda kurung, tanpa spasi. Nama menjadi bagian kiri dan kanan dari header halaman man . Menurut konvensi, nama perintah dalam huruf besar, meskipun Anda akan menemukan banyak yang tidak. Apa pun yang mengikuti nama perintah dan nomor bagian manual menjadi bagian kiri footer. Lebih mudah menggunakan ini untuk nomor versi perangkat lunak.
• Baris kedua: Nama penulis. Ini ditampilkan di bagian penulis yang dibuat secara otomatis di halaman man . Anda tidak perlu menambahkan bagian "Penulis"—cukup sertakan setidaknya satu nama di sini.
• Baris ketiga: Tanggal, yang juga menjadi bagian tengah footer.

Nama

Bagian ditunjukkan oleh garis yang dimulai dengan tanda angka ( # ), yang merupakan markup yang menunjukkan header dalam penurunan harga. Tanda angka ( #) harus berupa karakter pertama pada baris, diikuti dengan spasi.

Bagian nama berisi satu baris yang berisi nama perintah, spasi, tanda hubung ( - ), spasi, dan kemudian deskripsi singkat tentang apa yang dilakukan perintah.

Ringkasan

Sinopsis berisi format berbeda yang dapat diambil oleh baris perintah. Perintah ini dapat menerima pola pencarian atau opsi baris perintah. Dua tanda bintang ( ** ) di kedua sisi nama perintah berarti nama tersebut akan ditampilkan dalam huruf tebal pada halaman man . Tanda bintang tunggal ( * ) di kedua sisi beberapa teks menyebabkan halaman man menampilkannya digarisbawahi.

Secara default, jeda baris diikuti oleh baris kosong. Untuk memaksa jeda tanpa garis kosong, Anda dapat menggunakan garis miring terbalik ( \ ).

Keterangan

Deskripsi menjelaskan apa yang dilakukan perintah atau program. Ini harus mencakup detail penting secara ringkas. Ingat, Anda tidak sedang menulis panduan pengguna.

Menggunakan dua tanda angka ( ## ) di awal baris membuat heading level dua. Anda dapat menggunakan ini untuk memecah deskripsi Anda menjadi potongan-potongan yang lebih kecil.

Pilihan

Bagian opsi berisi deskripsi opsi baris perintah apa pun yang dapat digunakan dengan perintah. Menurut konvensi, ini ditampilkan dalam huruf tebal, jadi sertakan dua tanda bintang ( ** ) sebelum dan sesudahnya. Sertakan deskripsi teks opsi pada baris berikutnya dan mulai dengan titik dua ( : ), diikuti dengan spasi.

Jika deskripsinya cukup pendek, man akan menampilkannya pada baris yang sama dengan opsi baris perintah. Jika terlalu panjang, akan ditampilkan sebagai paragraf indentasi yang dimulai pada baris di bawah opsi baris perintah.

Contoh

Bagian contoh berisi pilihan format baris perintah yang berbeda. Perhatikan bahwa kita memulai baris deskripsi dengan titik dua ( : ), seperti yang kita lakukan pada bagian opsi.

Nilai Keluar

Bagian ini mencantumkan nilai kembalian yang dikirim perintah Anda ke proses pemanggilan. Ini mungkin shell jika Anda memanggilnya dari baris perintah, atau skrip jika Anda meluncurkannya dari skrip shell. Kami juga memulai baris deskripsi dengan titik dua ( : ) di bagian ini.

Bug

Bagian bug mencantumkan bug yang diketahui, gotcha, atau kebiasaan yang perlu diketahui orang. Untuk proyek sumber terbuka, biasanya menyertakan tautan di sini ke pelacak masalah proyek untuk memeriksa status bug atau melaporkan bug baru.

hak cipta

Bagian hak cipta berisi pernyataan hak cipta Anda, dan, biasanya, deskripsi jenis lisensi di mana perangkat lunak dirilis.

Alur Kerja yang Efisien

Anda dapat mengedit halaman man Anda di editor favorit Anda. Sebagian besar yang mendukung penyorotan sintaks akan menyadari penurunan harga dan mewarnai teks untuk menyorot judul, serta menebalkan dan menggarisbawahinya. Itu bagus sejauh ini, tetapi Anda tidak melihat halaman man yang diberikan, yang merupakan bukti nyata dalam puding.

Buka jendela terminal di direktori yang berisi file penurunan harga Anda. Dengan itu terbuka di editor Anda, simpan file Anda secara berkala ke hard drive Anda. Setiap kali melakukannya, Anda dapat menjalankan perintah berikut di jendela terminal:

 pandoc ms.1.md -s -t man | /usr/bin/man -l - 

Setelah Anda menggunakan perintah ini, Anda dapat menekan panah Atas untuk mengulanginya, lalu tekan Enter.

Perintah ini juga memanggil pandoc pada file penurunan harga (di sini, ini disebut "ms.1.md"):

• Opsi -s (mandiri) menghasilkan halaman man lengkap dari atas ke bawah, bukan hanya beberapa teks dalam format man .
• Opsi -t (tipe keluaran) dengan operator "man" memberi tahu pandoc untuk menghasilkan keluarannya dalam format man . Kami belum memberi tahu pandoc untuk mengirim hasilnya ke file, jadi itu akan dikirim ke stdout .

Kami juga menyalurkan output itu ke man dengan opsi -l (file lokal). Ini memberitahu man untuk tidak mencari melalui database man mencari halaman man . Sebaliknya, itu harus membuka file bernama. Jika nama filenya adalah - , man akan mengambil inputnya dari stdin .

Intinya adalah Anda dapat menyimpan dari editor Anda dan tekan Q untuk menutup man jika itu berjalan di jendela terminal. Kemudian, Anda dapat menekan panah Atas, diikuti oleh Enter untuk melihat versi yang dirender dari halaman man Anda, tepat di dalam man .

TERKAIT: Apa itu stdin, stdout, dan stderr di Linux?

Membuat Halaman manual Anda

Setelah Anda menyelesaikan halaman man Anda, Anda perlu membuat versi finalnya, dan kemudian menginstalnya di sistem Anda. Perintah berikut memberitahu pandoc untuk membuat halaman man yang disebut "ms.1":

 pandoc ms.1.md -s -t man -o ms.1 

Ini mengikuti konvensi penamaan halaman man setelah perintah yang dijelaskan dan menambahkan nomor bagian manual seolah-olah itu adalah ekstensi file.

Ini membuat file "ms.1", yang merupakan halaman man baru kami. Di mana kita meletakkannya? Perintah ini akan memberi tahu kita di mana man mencari halaman man :

 jalan manusia 

Hasilnya memberi kami info berikut:

• /usr/share/man: Lokasi perpustakaan standar halaman man . Kami tidak menambahkan halaman ke perpustakaan ini.
• /usr/local/share/man: Tautan simbolis ini menunjuk ke "/usr/local/man."
• /usr/local/man: Di sinilah kita perlu menempatkan halaman man baru kita.

Perhatikan bahwa bagian manual yang berbeda terkandung dalam direktori mereka sendiri: man1, man2, man3, dan seterusnya. Jika direktori untuk bagian tidak ada, kita perlu membuatnya.

Untuk melakukannya, kita ketik berikut ini:

 sudo mkdir /usr/local/man/man1

Kami kemudian menyalin file "ms.1" ke direktori yang benar:

 sudo cp ms.1 /usr/local/man/man1

man mengharapkan halaman man dikompres, jadi kami akan menggunakan gzip untuk mengompresnya:

 sudo gzip /usr/local/man/man1/ms.1

Untuk membuat man menambahkan file baru ke databasenya, ketikkan yang berikut ini:

 sudo mandb 

Itu dia! Kami sekarang dapat memanggil halaman man baru kami sama seperti yang lain dengan mengetik:

 pria ms 

Halaman man baru kami ditemukan dan ditampilkan.

Itu terlihat seperti halaman man lainnya, dengan teks tebal, bergaris bawah, dan menjorok di tempat yang sesuai.

Baris deskripsi yang sesuai dengan opsi yang mereka deskripsikan muncul di baris yang sama. Garis yang terlalu panjang untuk muat muncul di bawah opsi yang dijelaskan.

Kami juga telah membuat bagian "Penulis" secara otomatis. Footer juga menyertakan nomor versi perangkat lunak, tanggal, dan nama perintah, seperti yang didefinisikan di bagian depan.

Jika Anda menghendaki . . .

Setelah pandoc membuat halaman man Anda, Anda juga dapat langsung mengedit file dalam format makro groff sebelum memindahkannya ke direktori halaman man , dan gzip .