Fakta yang sangat umum bahawa tiada siapa yang suka menulis dokumentasi. Heck, tidak ada yang suka membacanya sama ada. Tetapi ada kalanya kita perlu membacanya untuk, katakan, menyelesaikan projek tepat pada waktunya, atau, terutama ketika bekerja dalam pembangunan perisian, bahkan menulisnya. Sekiranya anda hanya perlu membacanya, kami sentiasa menggalakkan anda untuk berbuat demikian, tetapi jika anda perlu menulis halaman manual dan memerlukan kickstart, inilah artikel untuk anda. Sekiranya anda bekerja sebelum ini dengan html hidup anda akan lebih mudah, tetapi jika tidak ia baik -baik saja. Menulis halaman manual untuk linux tidak begitu sukar, walaupun melihat halaman ketika dibaca dalam teks biasa. Jadi pada dasarnya anda memerlukan pengetahuan Linux dan keupayaan untuk menggunakan editor teks. Anda akan belajar (dengan contoh, tentu saja) konsep utama dalam pemformatan teks seperti yang digunakan pada halaman manusia dan bagaimana menulis halaman manual mudah. Oleh kerana kami menggunakan yest sebagai contoh untuk tutorial pembangunan C kami, kami akan menggunakan coretan dari halaman manualnya untuk menggambarkan titik kami semasa artikel ini.

Sedikit Sejarah

Pakej manual pertama yang ditulis dikatakan ditulis oleh Dennis Ritchie dan Ken Thompson pada tahun 1971. Perisian pemformatan yang digunakan adalah troff, dan format itu terus digunakan hingga ke hari ini, walaupun alat mungkin berbeza. Alat pemformatan teks pada sistem linux kini groff, dengan 'g' terkemuka dari gnu. Kewujudan Groff berhutang kepada hakikat bahawa ketika Troff ditulis, terminal bermaksud sesuatu yang berbeza dari segi keupayaan daripada apa yang mereka maksudkan hari ini. Satu lagi insentif yang kuat untuk projek GNU untuk membuat Groff adalah lesen proprietari Troff. Troff masih hidup di sistem Unix yang lain, seperti OpenSolaris atau Plan9, walaupun di bawah lesen sumber terbuka.

Sebelum kita memulakan, kami mesti memberitahu anda sesuatu tentang *roff: perisian menaip, seperti Tex misalnya, dan itu bahasa di dalamnya sendiri. Kami tidak akan mengubah artikel ini menjadi manual groff, dan tidak akan membuat senarai perbezaan antara Groff dan Troff. Ini hanya starter untuk menulis halaman manual mudah, dan jika anda memerlukan lebih banyak, anda akan mendapat banyak dokumentasi di internet.

Alternatif

Sekiranya selepas membaca ini, anda akan merasakan bahawa sintaks yang menakutkan, kami mempunyai penyelesaian untuk masalah anda: pod2man. POD bermaksud dokumentasi lama biasa dan menawarkan sintaks yang lebih mudah, dan terdapat Pod2man, yang merupakan modul Perl (sebahagian daripada perlpod) yang menerjemahkan dokumentasi yang ditulis dalam format pod untuk format manpage. Perlpod juga menawarkan alat untuk menukar pod ke teks atau html, jadi rujuk dokumentasi pengedaran anda mengenai cara memasangnya.

Halaman manual

Kategori

Halaman manual dibahagikan kepada kategori, bergantung pada subjek yang mereka jalankan. Mereka tidak berbeza dengan pengagihan Linux, tetapi sistem Unix lain mempunyai cara yang berbeza untuk membahagikan halaman manual. Menggunakan

 $ lelaki lelaki

akan memberi anda kategori tersebut dan lebih banyak lagi mengenai cara menggunakan arahan lelaki. Kategori di Linux adalah seperti berikut:

 1 program yang boleh dilaksanakan atau arahan shell
2 panggilan sistem (fungsi yang disediakan oleh kernel)
3 Panggilan Perpustakaan (Fungsi dalam Perpustakaan Program)
4 fail khas (biasanya dijumpai di /dev)
5 Format dan Konvensyen Fail misalnya /etc /Passwd
6 permainan
7 Pelbagai (termasuk Pakej dan Konvensyen Makro), E.g. Man (7), Groff (7)
8 Perintah Pentadbiran Sistem (biasanya hanya untuk akar)
9 rutin kernel [bukan standard]

Anda dinasihatkan untuk membaca halaman manual lelaki, kerana ini bukan tutorial mengenai cara gunakan mereka, tetapi bagaimana untuk tulis mereka.

Susun atur halaman manual

Sejak beberapa tahun yang lalu, terdapat standard bagaimana menulis halaman manual, apa yang harus mereka ada dan masalah gaya. Mereka harus ringkas, menghormati susun atur dan memampatkan sebanyak mungkin ruang yang mungkin. Apabila seseorang melihat manual 100 muka surat, refleks pertama akan melarikan diri.

Jauh, jauh. Sebaliknya, halaman manual yang pendek tetapi bermaklumat yang akan memberi pembaca apa yang ingin dia ketahui akan menjadi bantuan sebenar, sebaliknya menakutkan/membosankan pengguna. Sekiranya program yang anda tulis halaman manual tidak ditulis oleh anda (sepenuhnya), bekerjasama dengan pemaju sehingga anda menyelesaikan bagaimana manual itu kelihatan seperti. Sekarang, kita ingin mengelakkan diri daripada membosankan atau menakutkan, mari kita mulakan dengan susun atur.

Pertama sekali, nama fail mestilah $ commandName.$ kategori, seperti, contohnya, vim.1. Fail ini, apabila dipasang, hendaklah disalurkan dan disalin ke direktori yang sesuai, yang untuk VIM harus/usr/share/man/man1. Fail yang tidak dikompres adalah fail teks biasa, tidak ada lagi. Membaca mana -mana halaman manual akan memberi anda idea tentang bagaimana anda kelihatan seperti: nama, sinopsis, keterangan, pilihan, contoh, bantuan, fail, lihat juga, pengarang dan pepijat. Tidak semua ini adalah wajib, tetapi disarankan anda memberikan mereka semua harus ruang cukup, untuk pengalaman pengguna yang lebih baik.

Bahasa markup

Seperti yang dinyatakan sebelum ini, jika anda biasa menulis XML atau HTML, anda akan mendapati sintaks mudah. Sebenarnya, ia mudah sekali apabila anda membiasakannya. Kami mulakan dengan tajuk, Dan tajuk pertama adalah tajuk tajuk. Yang lain biasanya menemui makro (setara dengan tag dalam bahasa markup) adalah tajuk subjek dan perenggan, Tetapi lebih banyak lagi pada mereka yang kemudian.

Tajuk tajuk mesti mengandungi yang berikut: nama, bab (kategori) dan tarikh halaman terakhir diubah suai. Oleh itu, untuk mendapatkan kaki anda basah, inilah caranya:

.Th Yest 1 "19 Apr 2010"

TH bermaksud tajuk tajuk, dan kerana ia adalah makro mesti dot-prefixed. Yest adalah nama permohonan, Kategori 1, yang terakhir diedit pada 19 April 2010. Sebelum kita pergi lebih jauh, anda mungkin ingin memasukkan beberapa komen dalam fail anda sebelum tajuk tajuk. Ini bermula dengan .\ "(Quote dot backslash) dan boleh kelihatan seperti ini:

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

.\" Hak cipta terpelihara.

Sekarang, masukkan baris ini (tajuk dan komen di atasnya) dan periksa hasilnya dengan

 $ groff -man -tascii yest.1

-TASCII mengarahkan Groff untuk output dalam format ASCII (teks), tetapi Groff menyokong jenis output lain. Kami menjemput anda untuk menyemak halaman manual groff untuk itu.

Seterusnya, sekarang kita tahu bagaimana menangani tajuk tajuk, mari kita pergi ke seksyen tajuk. Seperti yang anda mungkin fikirkan, makro adalah .SH dan apa yang dilakukannya ialah memperkenalkan nama, sinopsis, keterangan, dll. Bahagian seperti yang ditulis di atas. Jadi sintaks akan menjadi:

.Sh Nama Yest - Utiliti Manipulasi Tarikh.

.Sh Sinopsis .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 Penerangan Ini dipanggil ""yest"" kerana lalai adalah untuk mengeluarkan tarikh semalam. Utiliti ini mengetahui tentang tahun lompat, waktu simpanan siang, dan variasi sedemikian. Utiliti ini menambah atau menolak hari, jam, dan/atau minit dari tarikh tertentu, dan mengeluarkan hasilnya dalam format yang ditentukan. Lalai, jika tiada pelarasan ditentukan, adalah ""-1d""

Ini sudah tentu hanya sebahagian daripada manual, tetapi mari kita lihat apa maksud makro baru ... b bermaksud berani, dan kami mengesyorkan anda menampal kod ini dalam fail dan mengujinya semasa anda pergi, dengan perintah groff di atas ... p berdiri untuk perenggan, kerana seperti yang anda lihat, selepas masing -masing .P Terdapat garis baru dua di halaman yang diformat. \ F* 's adalah urutan perubahan fon, dan apa maksudnya ialah selepas perkataan ""sinopsis"" .B memberitahu Groff untuk mencetak dengan berani. Walau bagaimanapun, selepas perkataan ""yest"" yang sememangnya dicetak dengan huruf tebal, kita perlu ""-belek"" dicetak dengan fon biasa, jadi inilah yang dimaksudkan. Sebaliknya, \ fb bermaksud ""cetak dengan berani"" dan ia boleh digunakan secara bergantian dengan .B . Menggunakan logik anda dapat memahami apa \ fl, sebagai contoh,.

Teks mudah, iaitu teks yang bukan tajuk atau seksyen, terkandung dalam perenggan. Perenggan mudah dibatasi oleh a .PP Macro, yang mewujudkan ruang menegak kecil antara perenggan sebenar dan yang seterusnya. Sekiranya anda mahukan perenggan yang ditandakan, anda boleh memilikinya .Tp . Seterusnya kita akan bercakap lekukan.

Lekukan relatif bermaksud bahawa teks itu diindentasi relatif terhadap teks sebelumnya dan berikut. Untuk memulakan teks yang agak induk, gunakan .RS (permulaan relatif), dan untuk mengakhiri penggunaannya .Re (akhir relatif). Inilah contoh:

.Rs.7i Sekiranya terdapat ruang atau watak khas dalam rentetan, ia mesti disebutkan. Program ini akan mengiktiraf kebanyakan konvensyen melarikan diri seperti ""\\ n"" (newline) dan ""\\ t"" (tab) dalam \ fiformat-string \ fr, dan octal excapes (\\ 0nn) disokong.

.P Jika hanya pelarasan hari ditentukan, lalai \ fiformat-string \ fr ialah ""%x"". Jika \ fiadjustment \ fr termasuk elemen masa, lalai \ fiformat-string \ fr menjadi ""%x-%r"".

.Re

Seperti yang anda lihat, anda boleh mempunyai .P makro di dalam sekeping teks yang agak terikat ... P hanyalah alias untuk .Pp, jadi mereka boleh digunakan secara bergantian. Anda mungkin perasan "".7i ""selepas .RS: Itu memberitahu Groff untuk indent dengan tujuh ruang teks di dalamnya.

Menggunakan jadual adalah sama seperti menggunakan relatif: .Ts dan .Te. Anda boleh, seperti yang dikatakan sebelum ini, mengubah suai satu perkataan atau keseluruhan perenggan (dari sudut pandangan tipografi, iaitu) dengan makro. Tiga cara anda boleh mengubah watak, seperti yang diketahui oleh semua orang, berani, italik, dan Roman. Jadi, sebagai contoh, .BI mengubah teks yang mengikutinya kerana ia akan muncul kedua -duanya berani dan Italic.

Kesimpulan

Sila ambil perhatian bahawa ini mungkin cukup untuk memulakan anda, tetapi tidak lengkap. Ini bukan semua makro, dan jika anda beralih ke sistem BSD, anda mungkin mendapati bahawa mereka menggunakan Mandoc dan bukannya Groff, jadi anda perlu melakukan pembelajaran sendiri jika anda ingin menjadi mahir. Seterusnya, sila baca beberapa halaman manual untuk melihat konvensyen utama yang mesti dihormati, seperti meletakkan argumen pilihan untuk permohonan anda (jika itu berlaku) dalam kurungan persegi atau menggunakan untuk menunjukkan bahawa sekurang -kurangnya satu argumen di dalamnya pendakap mesti digunakan. Semuanya, mendokumentasikan perisian anda, walaupun anda tidak dipaksa oleh majikan anda, baik untuk anda dan pengguna perisian anda. Anda akan dianggap sebagai pemaju yang teliti dan pengguna dapat menggunakan penciptaan anda lebih mudah, mengetahui apa yang mereka dapat dan apa yang mereka tidak dapat lakukan.

Tutorial Linux Berkaitan:

• Perkara yang hendak dipasang di Ubuntu 20.04
• Perkara yang perlu dilakukan setelah memasang ubuntu 20.04 Focal Fossa Linux
• Cara Melakukan Pemasangan Linux Tanpa Jauh dengan Kickstart
• Cara memeriksa hayat bateri di Ubuntu
• Perkara yang perlu dilakukan setelah memasang Ubuntu 22.04 Jur -ubur Jammy ..
• Pengenalan kepada Automasi, Alat dan Teknik Linux
• Sistem Hung Linux? Cara melarikan diri ke baris arahan dan ..
• Perkara yang perlu dipasang di Ubuntu 22.04
• Mint 20: Lebih baik daripada Ubuntu dan Microsoft Windows?
• Pasang Arch Linux di Workstation VMware