Jak zrobić strony podręcznika sekcji 9 jądra, które dokumentują funkcje, struktury danych i nagłówki?

10

Źródła jądra zawierają funkcje i struktury danych, które są udokumentowane, na przykład w 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, ...)

Zamiast za każdym razem przeglądać źródła, przydatne byłoby przeglądanie tych interfejsów API jako stron podręcznika i wykorzystanie istniejącej struktury dokumentacji.


W jaki sposób instalujesz / tworzysz sekcję 9 manpages ( /usr/share/man/man9) dotyczącą jądra, która dokumentuje wyżej wymienione funkcje i struktury danych?

kakeh
źródło
2
Chcesz podzielić się dystrybucją, której używasz?
Tink
Dlaczego jesteś pewien, że dla każdej wersji zawsze są strony podręcznika (szczególnie zaktualizowane)?
mdpc,
1
@mdpc dlaczego dobrze utrzymane jądro nie będzie zawierało stron
podręcznika
3
„Musisz zainstalować xmlto” wydaje się miejscem, od którego można zacząć, nie?
Braiam
@Bralam zaktualizował niespodziankę :(
kakeh

Odpowiedzi:

6

Zawartość jest analizowana bezpośrednio (patrz także to ) ze źródłowych plików .c 1 :

Aby zapewnić osadzoną, przyjazną dla języka C, łatwą w utrzymaniu, ale spójną i możliwą do wyodrębnienia dokumentację funkcji i struktur danych w jądrze Linux, jądro Linux przyjęło spójny styl dokumentowania funkcji i ich parametrów oraz struktur i ich członkowie.

Format tej dokumentacji nazywa się formatem kernel-doc. Jest to udokumentowane w tym pliku Documentation / kernel-doc-nano-HOWTO.txt.

Ten styl osadza dokumentację w plikach źródłowych, stosując kilka prostych konwencji. Skrypty / skrypt kernel-doc perl, niektóre szablony SGML w Documentation / DocBook oraz inne narzędzia rozumieją te konwencje i są używane do wyodrębnienia tej osadzonej dokumentacji do różnych dokumentów. [...]

Znak komentarza otwierającego „/ **” jest zarezerwowany dla komentarzy jądra-doc. Tylko komentarze oznaczone w ten sposób będą rozpatrywane przez skrypty kernel-doc, a każdy tak oznaczony komentarz musi być w formacie kernel-doc.

Co oznacza, że ​​tylko takie sformatowane komentarze można wyodrębnić w ten sposób i że można wykorzystać skrypt Perla używany przez proces:kernel-doc make

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

i dlatego nie jesteś ograniczony do celu mandoc :

Po instalacji „make psdocs”, „make pdfdocs”, „make htmldocs” lub „make mandocs” renderują dokumentację w żądanym formacie.

Istnieją również pliki tekstowe specyficzne dla sterownika w repozytorium / źródle jądra. Mówiąc bardziej ogólnie, ich projekt stron man Linuxa (od man1 do man8 ) jest dostępny do pobrania. W ostatniej notatce kernel.org prowadzi również dokumentację wyjściową .


1. Jądro nie jest jedynym przypadkiem, w którym taka technika jest używana do generowania stron podręcznika. Coreutils GNU to jeden z takich przypadków; większość jego stron jest generowanych przy użyciu danych wyjściowych, command --helpktórych zawartość jest w funkcji użycia źródłowym pliku narzędziowym ( 1 2 ).

Społeczność
źródło
make mandocs rzuca mnąMakefile:19: /Documentation/DocBook/media/Makefile: No such file or directory
kakeh
tak, mam go, ale Documentation/nie jest obecny w /swoim obecnym/lib/modules/3.2.0-57-generic-pae/build/
kakeh
@Shyam Są to pliki modułów itp., Takie jak łącze do plików tekstowych w moim A. Możesz spróbować ./scripts/kernel-doc -man ./**/*.c >mydocz górnego katalogu źródeł i sprawdzić, czy nie możesz umieścić wszystkich bezpośrednio w jednym pliku, bezpośrednio analizując źródła .
4

Zakładając, że używasz Ubuntu,

apt-get install linux-manual-3.2

lub podobny (wybierz odpowiednią wersję). Istnieje również inny pakiet dokumentacji

apt-get install linux-doc

ale to jest HTML.

Faheem Mitha
źródło
to nie pokazuje dokumentacji interfejsu API jądra
kakeh
@Shyam Przykład?
Faheem Mitha,
1
Na Arch (Bang) mam: linux- manpages 3.14-1, który zawiera sekcję 9 stron! Dziękuję Ci! Przykładem jest kcalloc.9.gz . Jest ich około 4000 ...
@ Faeem Mitha treid oglądania, man alloc_register_regionale powiedział, że nie ma ręcznego wprowadzania, że ​​dokumenty różnią się od stron podręcznika?
kakeh
@FaheemMitha Nie sądzę, że interfejsy API niskiego poziomu jądra są dostępne z linux-doc!
kakeh
3

Pobierz kod źródłowy jądra i uruchom katalog źródłowy

make mandocs

Po utworzeniu dokumentów man wykonaj polecenie

make installmandocs

Spowoduje to zainstalowanie stron podręcznika w /usr/local/man/man9/. Teraz możesz przeglądać strony podręcznika man <api-name>, pisząc lub, jeśli edytujesz, po vimprostu naciśnij Knazwę interfejsu API.

manav mn
źródło
Ale plik makefile /usr/src/linux-headers-5.0.0-38/Makefileteż nie ma mandocsżadnej regułyinstallmandocs
Herdsman