Itu adalah fakta yang sangat umum bahwa tidak ada yang suka menulis dokumentasi. Heck, tidak ada yang suka membacanya juga. Tetapi ada saat -saat ketika kita harus membacanya untuk, katakanlah, menyelesaikan proyek tepat waktu, atau, terutama saat bekerja dalam pengembangan perangkat lunak, bahkan menulisnya. Jika Anda hanya perlu membacanya, kami selalu mendorong Anda untuk melakukannya, tetapi jika Anda harus menulis halaman manual dan membutuhkan kickstart, inilah artikel untuk Anda. Jika Anda sebelumnya bekerja dengan HTML, hidup Anda akan lebih mudah, tetapi jika tidak, tidak apa -apa. Menulis halaman manual untuk Linux tidak terlalu sulit, terlepas dari tampilan halaman saat dibaca dalam teks biasa. Jadi pada dasarnya Anda akan membutuhkan beberapa pengetahuan Linux dan kemampuan untuk menggunakan editor teks. Anda akan belajar (dengan contoh, tentu saja) konsep utama dalam pemformatan teks sebagaimana diterapkan pada halaman manusia dan cara menulis halaman manual sederhana. Karena kami menggunakan yest sebagai contoh untuk tutorial pengembangan C kami, kami akan menggunakan cuplikan dari halaman manualnya untuk menggambarkan poin kami selama artikel ini.

Sedikit Sejarah

Paket manual pertama yang ditulis dikatakan ditulis oleh Dennis Ritchie dan Ken Thompson pada tahun 1971. Perangkat lunak pemformatan yang digunakan adalah troff, dan format itu terus digunakan hingga hari ini, meskipun alatnya mungkin berbeda. Alat pemformatan teks pada sistem Linux sekarang menjadi groff, dengan 'G' terkemuka yang berasal dari GNU. Keberadaan Groff berutang pada fakta bahwa ketika Troff ditulis, terminal berarti sesuatu yang berbeda dalam hal kemampuan dari yang mereka maksudkan saat ini. Insentif kuat lainnya untuk proyek GNU untuk membuat GROFF adalah lisensi milik Troff. Troff masih hidup di sistem UNIX lainnya, seperti OpenSolaris atau Plan9, meskipun di bawah lisensi open source.

Sebelum kita mulai, kami harus memberi tahu Anda sesuatu tentang *roff: ini adalah perangkat lunak yang mengatur huruf, seperti Tex misalnya, dan ini adalah bahasa di dalamnya sendiri. Kami tidak akan mengubah artikel ini menjadi manual groff, kami juga tidak akan membuat daftar perbedaan antara Groff dan Troff. Ini hanya pemula untuk penulisan halaman manual sederhana, dan jika Anda membutuhkan lebih banyak, Anda akan menemukan banyak dokumentasi di internet.

Alternatif

Jika setelah membaca ini, Anda akan merasa bahwa sintaksnya menakutkan, kami memiliki solusi untuk masalah Anda: pod2man. POD adalah singkatan dari Dokumentasi Lama Polos dan menawarkan sintaksis yang lebih sederhana, dan ada Pod2man, yang merupakan modul perl (bagian dari perlpod) yang menerjemahkan dokumentasi yang ditulis dalam format pod untuk format manpage. Perlpod juga menawarkan alat untuk mengonversi pod ke teks atau html, jadi cukup rujuk ke dokumentasi distribusi Anda tentang cara menginstalnya.

Halaman manual

Kategori

Halaman manual dibagi menjadi kategori, tergantung pada subjek apa yang mereka perlakukan. Mereka tidak berbeda pada distribusi Linux, tetapi sistem UNIX lainnya memiliki cara berbeda untuk membagi halaman manual. Menggunakan

 $ man man

akan memberi Anda kategori -kategori itu dan lebih banyak lagi sehubungan dengan cara menggunakan perintah manusia. Kategori di Linux adalah sebagai berikut:

 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 (biasanya ditemukan di /dev)
5 format file dan konvensi misalnya /etc /passwd
6 pertandingan
7 Lain -lain (termasuk paket dan konvensi makro), e.G. Man (7), Groff (7)
8 perintah administrasi sistem (biasanya hanya untuk root)
9 rutinitas kernel [non standar]

Anda disarankan untuk membaca halaman manual pria, karena ini bukan tutorial tentang cara menggunakan mereka, tapi bagaimana caranya menulis mereka.

Tata letak halaman manual

Sejak beberapa tahun yang lalu, ada standar tentang cara menulis halaman manual, apa yang harus dikandung dan masalah gaya. Mereka harus ringkas, menghormati tata letak dan mengompres informasi sebanyak mungkin dalam ruang sesedikit mungkin. Ketika seseorang melihat manual 100 halaman, refleks pertama adalah melarikan diri.

Jauh, Jauh. Di sisi lain, halaman manual singkat namun informatif yang akan memberi pembaca apa yang ingin dia ketahui akan sangat membantu, alih -alih menakut -nakuti/membosankan pengguna. Jika program yang Anda tulis halaman manual tidak ditulis oleh Anda (seluruhnya), bekerja dengan pengembang sampai Anda puas dengan bagaimana manual itu seharusnya terlihat. Sekarang, kami ingin menghindari membosankan atau menakutkan, mari kita mulai dengan tata letak.

Pertama -tama, nama file harus $ commandName.$ kategori, seperti, misalnya, vim.1. File ini, saat diinstal, harus di -gzip dan disalin ke direktori yang sesuai, yang untuk vim harus/usr/share/man/man1. File yang tidak dikompresi adalah file teks biasa, tidak lebih. Membaca halaman manual apa pun akan memberi Anda ide tentang bagaimana Anda seharusnya terlihat: nama, sinopsis, deskripsi, opsi, contoh, bantuan, file, lihat juga, penulis dan bug. Tidak semua ini wajib, tetapi disarankan Anda menyediakan semuanya harus cukup ruang, untuk pengalaman pengguna yang lebih baik.

Bahasa markup

Seperti yang dinyatakan sebelumnya, jika Anda terbiasa menulis XML atau HTML, Anda akan menemukan sintaksnya sederhana. Faktanya, itu sederhana setelah Anda terbiasa. Kami mulai dengan menuju, Dan judul pertama adalah judul judul. Yang lain biasanya ditemui makro (setara dengan tag dalam bahasa markup) judul subjek Dan paragraf, Tapi lebih banyak lagi nanti.

Judul judul harus berisi yang berikut: Nama, Bab (Kategori) dan tanggal halaman terakhir dimodifikasi. Jadi, untuk membuat kaki Anda basah, beginilah penampilannya:

.TH Yest 1 "19 Apr 2010"

TH singkatan dari judul judul, dan karena itu adalah makro itu harus di-dot-prefixed. Yest adalah nama aplikasi, Kategori 1, terakhir diedit pada 19 April 2010. Sebelum kita melangkah lebih jauh, Anda mungkin ingin memasukkan beberapa komentar di file Anda sebelum judul judul. Ini dimulai dengan .\ ”(Dot Backslash Quote) dan dapat terlihat seperti ini:

.\ ”Hak Cipta 2004, 2006, 2010 Kimball Hawkins .

.\" Seluruh hak cipta.

Sekarang, masukkan baris ini (judul dan komentar di atasnya) dan periksa hasilnya dengan

 $ groff -man -tascii yest.1

-TASCII menginstruksikan groff ke output dalam format ASCII (teks), tetapi Groff mendukung jenis output lainnya. Kami mengundang Anda untuk memeriksa halaman manual groff untuk itu.

Selanjutnya, sekarang kita tahu bagaimana menangani judul judul, mari kita pergi ke bagian judul. Seperti yang mungkin Anda duga, makro itu .SH dan apa yang dilakukannya adalah memperkenalkan nama, sinopsis, deskripsi, dll. bagian seperti tertulis di atas. Jadi sintaksnya akan:

.SH Nama Yest - Utilitas Manipulasi Tanggal.

.SH RINGKASAN .B yest \ fr -help

.P .B yest \ fr -license

.P .B yest \ fr -version

.P .B yest \ fr [\ fb-idf = \ fistr \ fr] [\ fb-tz = \ fitzone \ fr] [[\ fb- \ fr | \ fb+\ fr] \ fiadjust \ fr [\ fbd \ fr | \ fbh \ fr | \ fbm \ fr]] [\ fidate \ fr] [\ fiformat-string \ fr] .

SH Deskripsi Ini disebut ""yest"" karena standarnya adalah tanggal output kemarin. Utilitas ini tahu tentang tahun kabisat, waktu penghematan siang hari, dan variasi seperti itu. Utilitas ini menambah atau mengurangi hari, jam, dan/atau menit dari tanggal tertentu, dan menghasilkan hasil dalam format yang ditentukan. Standarnya, jika tidak ada penyesuaian yang ditentukan, adalah ""-1d""

Ini tentu saja hanyalah bagian dari manual, tapi mari kita lihat apa arti makro baru ... B adalah singkatan dari Bold, dan kami sarankan Anda menempelkan kode ini dalam file dan mengujinya saat Anda pergi, dengan perintah groff di atas ... P berdiri untuk paragraf, karena seperti yang Anda lihat, setelah masing -masing .P Ada baris baru ganda di halaman yang diformat. The \ f* adalah font mengubah urutan pelarian, dan apa artinya setelah kata ""sinopsis"" .B memberitahu Groff untuk mencetak dengan huruf tebal. Namun, setelah kata ""yest"" yang memang dicetak dengan huruf tebal, kita perlu ""-Help"" untuk dicetak dengan font biasa, jadi inilah yang diperjuangkan. Sebaliknya, \ fb adalah singkatan dari ""Print In Bold"" dan dapat digunakan secara bergantian .B . Menggunakan logika Anda dapat memahami apa \ fl.

Teks sederhana, yaitu teks yang bukan heading atau bagian, terkandung dalam paragraf. Paragraf sederhana dibatasi oleh a .PP makro, yang menciptakan ruang vertikal kecil antara paragraf yang sebenarnya dan yang berikutnya. Jika Anda menginginkan paragraf yang ditandai, Anda dapat memilikinya .Tp . Selanjutnya kita akan bicarakan lekukan.

Indentasi relatif berarti bahwa teks tersebut indentasi relatif terhadap teks sebelumnya dan berikut. Untuk memulai sepotong teks yang relatif indentasi, gunakan .RS (Relative Start), dan untuk mengakhiri penggunaannya .Re (Akhir Relatif). Inilah contohnya:

.Rs.7i Jika ada spasi atau karakter khusus dalam string, itu harus dikutip. Program ini akan mengenali sebagian besar konvensi pelarian seperti \ fbecho \ fr seperti ""\\ n"" (newline) dan ""\\ t"" (tab) di \ fiformat-string \ fr, dan oktal pelarian (\\ 0nn) didukung.

.P Jika hanya penyesuaian hari yang ditentukan, default \ fiformat-string \ fr adalah ""%x"". Jika \ fiadjustment \ fr mencakup elemen waktu, default \ fiformat-string \ fr menjadi ""%x-%r"".

.ULANG

Seperti yang Anda lihat, Anda dapat memiliki file .P makro di dalam teks yang relatif indentasi ... P hanyalah alias untuk .Pp, sehingga mereka dapat digunakan secara bergantian. Anda mungkin telah memperhatikan “.7i ”setelah .RS: Itu memberitahu Groff untuk indentasi dengan tujuh spasi teks di dalamnya.

Menggunakan tabel sama mudahnya dengan menggunakan indentasi relatif: .Ts dan .Te. Anda dapat, seperti yang dikatakan sebelumnya, memodifikasi satu kata atau seluruh paragraf (dari sudut pandang tipografi, yaitu) dengan makro. Tiga cara Anda dapat mengubah karakter, seperti yang diketahui semua orang, berani, miring, dan Romawi. Jadi, misalnya, .Bi mengubah teks yang mengikutinya karena akan muncul keduanya berani Dan miring.

Kesimpulan

Harap dicatat bahwa ini mungkin cukup untuk memulai, tetapi tidak lengkap. Ini bukan semua makro, dan jika Anda beralih ke sistem BSD, Anda mungkin menemukan bahwa mereka menggunakan mandoc alih -alih groff, jadi Anda harus melakukan pembelajaran sendiri jika Anda ingin menjadi mahir. Selanjutnya, silakan baca beberapa halaman manual untuk melihat konvensi utama yang harus dihormati, seperti meletakkan argumen opsional ke aplikasi Anda (jika itu masalahnya) dalam kurung persegi atau menggunakan untuk menunjukkan bahwa setidaknya salah satu argumen di dalam Kawat gigi harus digunakan. Secara keseluruhan, mendokumentasikan perangkat lunak Anda, bahkan jika Anda tidak dipaksa oleh majikan Anda, baik untuk Anda dan pengguna perangkat lunak Anda. Anda akan dianggap sebagai pengembang yang cermat dan pengguna dapat menggunakan kreasi Anda dengan lebih mudah, mengetahui apa yang mereka bisa dan apa yang tidak dapat mereka lakukan.

Tutorial Linux Terkait:

• Hal -hal yang harus diinstal pada ubuntu 20.04
• Hal -hal yang harus dilakukan setelah menginstal ubuntu 20.04 FOSSA FOSSA Linux
• Cara melakukan instalasi linux tanpa pengawasan dengan kickstart
• Cara memeriksa masa pakai baterai di ubuntu
• Hal -hal yang harus dilakukan setelah menginstal ubuntu 22.04 Jammy Jellyfish…
• Pengantar Otomatisasi Linux, Alat dan Teknik
• Sistem Linux Hung? Cara melarikan diri ke baris perintah dan…
• Hal -hal yang harus diinstal pada Ubuntu 22.04
• Mint 20: Lebih baik dari Ubuntu dan Microsoft Windows?
• Instal Arch Linux di VMware Workstation