Como tornar a seção 9 do kernel páginas de manual que documentam funções, estruturas de dados e cabeçalhos?

9

As fontes do kernel contêm funções e estruturas de dados que estão documentadas, por exemplo 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 procurar as fontes todas as vezes, seria útil visualizar essas APIs como páginas de manual e aproveitar essa estrutura de documentação existente.


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

kakeh
fonte
2
Gostaria de compartilhar a distribuição que você está usando?
tink
Por que você tem tanta certeza de que sempre há páginas de manual (especialmente atualizadas) para cada versão?
Mdpc
1
@mdpc porque não vai um kernel bem conservado não terá quaisquer páginas do homem, eu acho que a minha pergunta é válida
kakeh
3
"Você precisa instalar o xmlto" parece ser o lugar para começar, não?
Braiam 5/08/2014
@Bralam atualizou a surpresa :(
kakeh 5/14

Respostas:

6

O conteúdo é analisado diretamente (veja também isso ) dos arquivos .c de origem 1 :

Para fornecer documentação incorporada, amigável ao C, fácil de manter, mas consistente e extraível das funções e estruturas de dados no kernel Linux, o kernel Linux adotou um estilo consistente para documentar funções e seus parâmetros, estruturas e seus membros.

O formato para esta documentação é chamado de formato kernel-doc. Está documentado neste arquivo Documentação / kernel-doc-nano-HOWTO.txt.

Esse estilo incorpora a documentação nos arquivos de origem, usando algumas convenções simples. O script scripts / kernel-doc perl, alguns modelos SGML na Documentação / DocBook e outras ferramentas compreendem essas convenções e são usados ​​para extrair essa documentação incorporada em vários documentos. [...]

A marca de comentário de abertura "/ **" está reservada para comentários do kernel-doc. Somente comentários marcados serão considerados pelos scripts do kernel-doc, e qualquer comentário marcado deve estar no formato do kernel-doc.

O que significa que apenas esses comentários formatados podem ser extraídos dessa maneira e que você pode aproveitar o script Perl usado pelo processo:kernel-doc 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 ao destino mandocs :

Após a instalação, "make psdocs", "make pdfdocs", "make htmldocs" ou "make mandocs" renderizarão a documentação no formato solicitado.

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


1. O kernel não é o único caso em que essa técnica é usada para gerar páginas de manual. GNU coreutils é outro caso; a maioria de suas páginas de manual é gerada usando a saída command --helpcujo conteúdo está na função de uso , no arquivo de origem do utilitário ( 1 2 ).

Comunidade
fonte
make mandocs me jogaMakefile:19: /Documentation/DocBook/media/Makefile: No such file or directory
kakeh
sim eu tenho, mas Documentation/não está presente no /seu presente em/lib/modules/3.2.0-57-generic-pae/build/
kakeh
@Shyam Esses são os arquivos dos módulos, etc., como o link para os arquivos de texto no meu A. Você pode tentar ./scripts/kernel-doc -man ./**/*.c >mydocno diretório superior do sources e ver se não consegue colocar todos diretamente em um arquivo, analisando os fontes diretamente .
4

Supondo que você esteja usando o Ubuntu,

apt-get install linux-manual-3.2

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

apt-get install linux-doc

mas isso é html.

Faheem Mitha
fonte
documentação isto não mostram o kernel do api
kakeh
@Shyam Exemplo?
Faheem Mitha
1
No Arch (Bang) eu tenho: linux-manpages 3.14-1, que contém a seção 9 manpages! Obrigado! Um exemplo é kcalloc.9.gz . Há cerca de 4000 deles ...
@Faheem Mitha treid de ver o documento, man alloc_register_regionmas disse que nenhuma entrada manual é diferente dos documentos?
kakeh
@FaheemMitha eu não acho que as APIs de baixo nível do kernel estejam disponíveis com o linux-doc!
kakeh
3

Faça o download do código fonte do kernel e no diretório source execute

make mandocs

Depois que os documentos do homem forem feitos, execute

make installmandocs

Isso instalará as páginas de manual no /usr/local/man/man9/. Agora você pode visualizar as páginas de manual digitando man <api-name>ou, se estiver editando, vimpressione Ko nome da API.

manav mn
fonte
Mas o makefile em /usr/src/linux-headers-5.0.0-38/Makefilenão ter regra mandocsnenhumainstallmandocs
Herdsman