Documentação da Debian

A Debian, assim como outras grandes distribuições do Linux, prima por sua vasta documentação. Esta inclui as fontes tradicionais de documentacao:

• Info. O formato texinfo, introduzido pelo projeto GNU, pode tanto convertido para TeX e daí impresso, como ser convertido para o formato info e então ser consultado através do programa info, ou pelo emacs através do comando M-x info. O formato info, ao contrário das man pages, é estruturado e fornece referência cruzada através de links, no estilo HTML.

  O GNU Coding Standards recomenda que todos os programas do projeto GNU incluam documentação em formato info. Assim, grande parte dos utilitários que compõem a base da Debian, incluindo fileutils, textutils, shellutils e binutils tem documentação info. Como as manpages são opcionais para o projeto GNU, e é trabalhoso manter duas fontes de documentação, muitas vezes as manpages nao sao atualizadas. Portanto, sempre que existirem, os manuais info devem ser recomendados ao usuario, em detrimento das manpages.

• Man pages: são a fonte mais tradicional de documentação em sistemas Unix. São armazenadas em formato fonte nroff em /usr/share/man[1-8], e visualizadas através do comando man. Os diretórios man[1-8] correspondem às seções (de acordo com a própria manpage man(1)):
  • 1 Programas executáveis ou comandos do shell
  • 2 Chamadas de sistema (funções fornecidas pelo kernel)
  • 3 Chamadas de biblioteca
  • 4 Arquivos especiais (normalmente encontrados em /dev)
  • 5 Formatos de arquivo e convenções
  • 6 Jogos
  • 7 Macro-pacotes e convenções, como man(7) e groff(7).
  • 8 Comandos de administração do sistema (somente para root, normalmente)

  Embora o projeto GNU, como mencionado acima, prefira documentação info, a política da Debian determina que todo pacote deve ter uma manpage. Quando não houver documentação info, deve-se recomendar aos usuários que consultem a manpage apropriada.

  Há um importante comando relacionado ao man: apropos. Cada manpage tem uma curta descrição associada. O comando apropos recebe uma expressão regular e devolve todas as descrições de manpages que casem com essa expressão. Esse comando deve ser recomendado a usuários que requisitem informações sobre um tópico.

• Documentação Adicional. A política da Debian determina que todo pacote deve instalar sua licença de distribuição e copyright no arquivo /usr/share/doc/PACOTE/copyright (alguns pacotes ainda usam /usr/doc/PACOTE, mas isso não está em conformidade com o FHS), onde PACOTE é o nome do pacote.

  No mesmo diretório, normalmente há documentação adicional no arquivo README e outros arquivos. Arquivos de exemplo ficam no subdiretório examples/.

Além dessas fontes, há também os HOWTOs do Linux Documentation Project (LDP). Entretanto, por serem mais úteis aos administradores que aos usuários, são descritos abaixo em 8.2.