Como tornar a seção do kernel 9 manpages quais funções de documentos, estruturas de dados e cabeçalhos?

Question

O kernel sources contém funções 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, ...)

Em vez de percorrer as fontes todas as vezes, seria útil visualizar essas APIs como manpages e aproveitar essa estrutura de documentação existente.

Como você instala / faz a seção do kernel 9 manpages ( /usr/share/man/man9 ) que documenta as funções e estruturas de dados mencionadas acima?

    

Answer 1

O conteúdo é analisado diretamente (veja também this ) dos arquivos source .c ¹ :

In order to provide embedded, 'C' friendly, easy to maintain, but consistent and extractable documentation of the functions and data structures in the Linux kernel, the Linux kernel has adopted a consistent style for documenting functions and their parameters, and structures and their members.

The format for this documentation is called the kernel-doc format. It is documented in this Documentation/kernel-doc-nano-HOWTO.txt file.

This style embeds the documentation within the source files, using a few simple conventions. The scripts/kernel-doc perl script, some SGML templates in Documentation/DocBook, and other tools understand these conventions, and are used to extract this embedded documentation into various documents. [...]

The opening comment mark "/**" is reserved for kernel-doc comments. Only comments so marked will be considered by the kernel-doc scripts, and any comment so marked must be in kernel-doc format.

O que significa que apenas esses comentários formatados podem ser extraídos dessa maneira e que você pode aproveitar o kernel-doc Script Perl usado pelo processo make :

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

e, portanto, você não está limitado aos mandocs segmentar :

After installation, "make psdocs", "make pdfdocs", "make htmldocs", or "make mandocs" will render the documentation in the requested format.

Há também arquivos de texto específicos do driver no repositório / fonte do kernel. Mais geralmente, o projeto man-pages do Linux ( man1 através de man8 ) é disponível para download. Em uma última nota, o kernel.org também mantém alguma documentação sobre saída .

^{1. O kernel não é o único caso em que tal técnica é usada para gerar manpages. O GNU coreutils é um desses outros casos; a maioria de suas páginas de manual são geradas usando a saída de command --help cujo conteúdo é na função uso , o arquivo de origem do utilitário ( 1 2 ).}

    

Answer 2

Supondo que você esteja usando o Ubuntu,

apt-get install linux-manual-3.2

ou similar (escolha a versão correta). Existe também outro pacote de documentação

apt-get install linux-doc

mas isso é html.

    

Answer 3

Faça o download do código-fonte do kernel e, no diretório de origem, execute

make mandocs

Após os documentos do homem terem sido feitos, execute

make installmandocs

Isso instalará as páginas de manual em /usr/local/man/man9/ . Agora você pode ver man pages digitando man <api-name> , ou se você está editando em vim apenas pressione K sobre o nome da API.