Preciso escrever man pages para a biblioteca C?

Question

Eu escrevi uma pequena biblioteca C para Linux e FreeBSD, e vou escrever a documentação para ela. Eu tentei aprender mais sobre a criação de páginas man e não encontrei as instruções ou descrições das melhores práticas que fazem man pages para bibliotecas. Em particular, estou interessado em que seção colocar páginas man das funções? 3? Talvez haja bons exemplos ou manuais? Crie man pages para cada função da biblioteca uma má idéia?

    

Answer 1

As páginas de manual de uma biblioteca entrariam na seção 3.

Para bons exemplos de páginas de manual, tenha em mente que algumas são escritas usando detalhes específicos de groff e / ou usam macros específicas que não são realmente portáveis.

Sempre há algumas armadilhas na portabilidade de páginas man, já que alguns sistemas podem (ou não) usar recursos especiais. Por exemplo, ao documentar dialog , tive que ter em mente (e contornar) diferenças em vários sistemas para exibir exemplos (que não são justificados).

Comece por ler as seções relevantes de man man onde ele menciona as macros padrão, e compare aquelas descrições para FreeBSD e Linux.

Se você escolher escrever uma página de manual para a biblioteca ou separar páginas de manual para as funções (ou grupos de funções) depende de quão complicadas seriam as descrições das funções:

• ncurses tem algumas centenas de funções em várias dúzias de páginas de manual.
• O diálogo tem várias dezenas de funções em uma página de manual. Outros certamente mostrarão muitos outros exemplos.

Leitura adicional:

• man - exiba as páginas de documentação on-line do manual (FreeBSD)
• man-pages - convenções para escrever man pages do Linux
• groff_mdoc - referência para a implementação do mdoc do groff
• HowTo: Crie uma página de manual do zero. (FreeBSD)
• O que é um "ciclado"?

Answer 2

Eu uso ronn . Você simplesmente escreve um markdown e o transforma em uma manpage. Há também um clone ( um pouco menos capaz) js chamado marked-man .

Tenho documentado meus scripts com ele usando% coed =% heredocs delimitados e meu código C / C ++ usando os mesmos heredocs delimitados por END_MAN exceto dentro de END_MAN . É facilmente extraível com sed e, em seguida, renderizável em uma manpage. (Com um pouco de invasão do sinal do UNIX junto com o inotifywait, você pode extrair e visualizar suas seções de manpage ao vivo e fazer com que o navegador do manpage seja recarregado à medida que a fonte for atualizada.)

Quanto à seção, então 3 seria para uma biblioteca C no nível do usuário. Você pode ler sobre os números de seção (entre outras coisas) em man (1) .

Se você quiser ver alguns man pages de exemplo bem estruturados e legíveis, eu vou dar uma olhada as bibliotecas link do Plan9, onde você pode ver como os próprios criadores de /* */ e c e seu sistema de documentação provavelmente se destinam essas coisas para trabalhar.

    

Answer 3

Para complementar as outras respostas, outra linguagem de marcação que pode ser usada para simplificar a criação de páginas de manuais é reStructuredText e o < um comando href="http://manpages.ubuntu.com/manpages/precise/man1/rst2man.1.html"> rst2man que faz parte do pacote python-docutils .

Esta linguagem de marcação foi adotada pelo python para sua documentação e é muito mais fácil de aprender, escrever e mantenha, do que as boas e velhas macros do troff man que o rst2man irá gerar para você a partir do seu reStructuredText.

    

Answer 4

Você pode documentar a API usando o Doxygen para fornecer a referência como HTML, além de gerar páginas de manual e outros formatos para leitura off-line.

A vantagem do Doxygen é que ele é uma espécie de documentação "in-line", como JavaDoc ou PythonDoc, duplicando como comentários de interface (ou vv., comentários duplicando como texto doc); você adiciona os textos do documento aos seus arquivos de fonte / cabeçalho, e é extraído de lá, o que aumenta as chances de se manter atualizado.