Bagaimana cara membuat kernel bagian 9 mengelola halaman mana fungsi dokumen, struktur data, dan header?

10

Kernel sumber mengandung fungsi dan struktur data yang didokumentasikan, misalnya dalam panic.c:

/**
 *  panic - halt the system
 *  @fmt: The text string to print
 *
 *  Display a message, then perform cleanups.
 *
 *  This function never returns.
 */
void panic(const char *fmt, ...)

Alih-alih menelusuri sumber setiap kali, akan bermanfaat untuk melihat API tersebut sebagai halaman manual dan memanfaatkan kerangka dokumentasi yang ada ini.

Bagaimana Anda menginstal / membuat halaman kernel bagian 9 ( /usr/share/man/man9) yang mendokumentasikan fungsi dan struktur data yang disebutkan di atas?

kernel man documentation kakeh
sumber
2
Ingin membagikan distro yang Anda gunakan?
tink
Mengapa Anda begitu yakin selalu ada halaman manual (terutama yang diperbarui) untuk setiap rilis?
mdpc
1
@mdpc mengapa kernel yang dipelihara dengan baik tidak akan memiliki halaman manual, saya pikir pertanyaan saya valid
kakeh
3
"Anda harus menginstal xmlto" sepertinya tempat untuk memulai, bukan?
Braiam
@Bralam memperbarui kejutan :(
kakeh

Jawaban:

6

Konten diuraikan secara langsung (lihat juga ini ) dari sumber .c file 1 :

Untuk menyediakan dokumentasi yang tertanam, 'C', mudah dipelihara, tetapi konsisten dan dapat diekstrak dari fungsi dan struktur data di kernel Linux, kernel Linux telah mengadopsi gaya yang konsisten untuk mendokumentasikan fungsi dan parameternya, dan struktur serta anggota

Format untuk dokumentasi ini disebut format kernel-doc. Itu didokumentasikan dalam file Documentation / kernel-doc-nano-HOWTO.txt ini.

Gaya ini menyematkan dokumentasi dalam file sumber, menggunakan beberapa konvensi sederhana. Script / skrip perl kernel-doc, beberapa templat SGML di Dokumentasi / DocBook, dan alat-alat lain memahami konvensi ini, dan digunakan untuk mengekstrak dokumentasi tersemat ini ke dalam berbagai dokumen. [...]

Tanda komentar pembuka "/ **" dicadangkan untuk komentar kernel-doc. Hanya komentar yang ditandai yang akan dipertimbangkan oleh skrip kernel-doc, dan komentar apa pun yang ditandai harus dalam format kernel-doc.

Yang berarti hanya komentar yang diformat yang dapat diekstraksi dengan cara ini dan Anda dapat memanfaatkan skrip Perl yang digunakan oleh proses:kernel-doc make

kernel-doc [ -docbook | -html | -html5 | -text | -man | -list ]
  [ -no-doc-sections ]
  [ -function funcname [ -function funcname ...] ]
  c file(s)s > outputfile

dan karena itu Anda tidak terbatas pada target mandocs :

Setelah instalasi, "make psdocs", "make pdfdocs", "make htmldocs", atau "make mandocs" akan menyajikan dokumentasi dalam format yang diminta.

Ada juga file teks khusus driver di repositori / sumber kernel. Secara umum, proyek halaman manual Linux mereka ( man1 hingga man8 ) tersedia untuk diunduh. Pada catatan terakhir kernel.org juga menyimpan beberapa dokumentasi keluaran .

1. Kernel bukan satu-satunya kasus di mana teknik seperti itu digunakan untuk menghasilkan halaman manual. GNU coreutils adalah salah satu kasus lainnya; sebagian besar halaman manualnya dihasilkan menggunakan output dari command --helpkonten yang dalam fungsi penggunaan file sumber utilitas ( 1 2 ).

Komunitas
sumber
membuat mandocs melempar sayaMakefile:19: /Documentation/DocBook/media/Makefile: No such file or directory
kakeh
ya saya memilikinya tetapi Documentation/tidak ada pada /saat ini di/lib/modules/3.2.0-57-generic-pae/build/
kakeh
@Shyam Itu adalah file untuk modul, dll., Seperti tautan ke file teks di A. saya. Anda mungkin dapat mencoba ./scripts/kernel-doc -man ./**/*.c >mydocdari direktori teratas sumber dan melihat apakah Anda tidak dapat memasukkan semuanya langsung ke satu file dengan mengurai sumber secara langsung .
4

Dengan asumsi Anda menggunakan Ubuntu,

apt-get install linux-manual-3.2

atau serupa (pilih versi yang benar). Ada juga paket dokumentasi lain

apt-get install linux-doc

tapi ini html.

Faheem Mitha
sumber
ini tidak menunjukkan dokumentasi kernel api
kakeh
Contoh @Shyam?
Faheem Mitha
1
Pada Arch (Bang) saya punya: linux-manpages 3.14-1 yang berisi bagian 9 manual! Terima kasih! Contohnya adalah kcalloc.9.gz . Ada sekitar 4000 dari mereka ...
@Faheem Mitha treid melihat man alloc_register_regiontetapi mengatakan tidak ada entri manual docs berbeda dari halaman manual ??
kakeh
@FaheemMitha saya tidak berpikir api tingkat rendah kernel tersedia dengan linux-doc!
kakeh
3

Unduh kode sumber kernel dan jalankan di source source

make mandocs

Setelah dokumen pria dibuat, jalankan

make installmandocs

Ini akan menginstal halaman buku panduan /usr/local/man/man9/. Sekarang Anda dapat melihat halaman manual dengan mengetik man <api-name>, atau jika Anda mengedit vimcukup tekan Knama API.

manav mn
sumber
Tapi makefile di /usr/src/linux-headers-5.0.0-38/Makefiletidak memiliki aturan mandocsjugainstallmandocs
Herdsman