Antes que você possa entender o que está realmente acontecendo quando há um problema, você precisa conhecer o papel teórico desempenhado por cada programa envolvido no problema. Para fazer isso, a melhor coisa a fazer é consultar a documentação; mas uma vez que estes documentos são muitos e dispersos, você deve conhecer todos os lugares onde podem ser encontrados.
Páginas de manual, apesar de relativamente concisas em estilo, contêm uma grande quantidade de informações essenciais. Vamos rapidamente passar pelo comando para visualizá-las, fornecido pelo pacote
man-db. Basta digitar
man página-do-manual - a página do manual normalmente atende pelo mesmo nome que o comando cuja documentação é solicitada. Por exemplo, para aprender sobre as opções possíveis para o comando
cp, você deve digitar
man cp no prompt do shell (veja barra lateral
DE VOLTA AO BÁSICO O shell, um interpretador de linha de comando).
Páginas de manual não apenas documentam comandos e programas acessíveis a partir da linha de comando, mas também arquivos de configuração, chamadas de sistema, funções de biblioteca, e assim por diante. Às vezes os nomes podem colidir. Por exemplo, o comando read do shell tem o mesmo nome que a chamada de sistema read. É por isso que as páginas de manual são organizadas em seções numeradas:
- 1
comandos que podem ser executados da linha de comando;
- 2
chamadas de sistema (funções disponibilizadas pelo kernel);
- 3
funções da biblioteca (fornecidas pelas bibliotecas do sistema);
- 4
dispositivos (em sistemas similares ao Unix, estes são arquivos especiais, geralmente colocados no diretório /dev/);
- 5
arquivos de configuração (formatos e convenções);
- 6
jogos;
- 7
conjunto de macros e padrões;
- 8
comandos de administração do sistema;
- 9
rotinas do núcleo.
É possível especificar a seção da página do manual que você está procurando: para ver a documentação para o chamada de sistema read, você deve digitar man 2 read. Quando a seção não é especificada explicitamente, a primeira seção que tiver uma página de manual com o nome solicitado será mostrada. Assim, man shadow retorna shadow(5) porque não há páginas de manual para shadow nas seções de 1 a 4.
obviamente que se você não sabe os nomes dos comandos, o manual não vai ser de muita utilidade para você. Este é o propósito do comando apropos, o que ajuda você a realizar uma busca nas páginas de manual, ou mais especificamente em suas descrições curtas. Cada página do manual começa essencialmente com um resumo de uma linha. apropos retorna uma lista de páginas de manual que mencionam a(s) palavra(s)-chave solicitada(s). Se você escolher bem, você encontrará o nome do comando que você precisa.
Exemplo 7.1. Procurando cp com apropos
$ apropos "copy file"
cp (1) - copy files and directories
cp (1posix) - copy files
cpio (1) - copy files to and from archives
exec (1posix) - execute commands and open, close, or copy file descriptors
install (1) - copy files and set attributes
ntfscp (8) - copy file to an NTFS volume.
O comando
man não é o único meio de consulta às páginas do manual, já que os programas
khelpcenter e
konqueror (do KDE) e
yelp (no GNOME) também oferecem essa possibilidade. Há também uma interface web, fornecida pelo pacote
man2html, que permite visualizar páginas de manual em um navegador web. Em um computador onde esse pacote está instalado, use esta URL depois de seguir as instruções em
/usr/share/doc/man2html/README.Debian:
Este utilitário requer um servidor web. É por isso que você deve optar por instalar este pacote em um dos servidores: todos os usuários da rede local poderão se beneficiar deste serviço (incluindo máquinas não-Linux), e isso permitirá que você não configure um servidor HTTP em cada estação de trabalho. Se o seu servidor também é acessível a partir de outras redes, pode ser desejável restringir o acesso a este serviço apenas para usuários da rede local.
Por último mas não menos importante, você pode ver todas as páginas de manual disponíveis no Debian (mesmo as que não estão instaladas na sua máquina) no serviço
manpages.debian.org. Ele oferece cada página de manual em múltiplas versões, uma para cada lançamento do Debian.
7.1.2. Documentos de info
O projeto GNU escreveu manuais para a maioria de seus programas no formato info; é por isso que muitas páginas do manual referem-se à documentação info correspondente. Esse formato oferece algumas vantagens, mas o programa padrão para ver estes documentos (chamado info) é também um pouco mais complexo. Esteja você aconselhado a usar o pinfo em seu lugar (do pacote pinfo).
A documentação info tem uma estrutura hierárquica, e se você invocar pinfo sem parâmetros, ele irá mostrar uma lista de nós disponíveis no primeiro nível. Normalmente, os nós levam o nome dos comandos correspondentes.
Com o
pinfo a navegação por esses nós é facilmente feita através das teclas de seta. Alternativamente, você também pode usar um navegador gráfico, que é muito mais amigável com o usuário. Mais uma vez, o
konqueror e o
yelp funcionam; o pacote
info2www também fornece uma interface web.
Observe que o sistema info não é adequado para tradução, ao contrário do Sistema de página man. Documentos info são, portanto, quase sempre em Inglês. No entanto, quando você pedir ao sistema pinfo para exibir uma página info inexistente, ele retornará a página man com o mesmo nome (se existir), que pode estar traduzida.
7.1.3. Documentação Específica
Cada pacote inclui a sua própria documentação. Mesmo os programas mais mal documentados costumam ter um arquivo README que contém algumas informações interessantes e/ou importantes. Esta documentação está instalada no diretório /usr/share/doc/pacote/ (onde pacote é o nome do pacote). Se a documentação é particularmente grande, não pode ser incluída no pacote principal do programa, mas pode ser transferida para um pacote dedicado que normalmente é chamado pacote-doc. O pacote principal geralmente recomenda o pacote de documentação para que você possa encontrá-lo facilmente.
O diretório
/usr/share/doc/package/ também contém alguns arquivos fornecidos pelo Debian que completam a documentação especificando as particularidades do pacote ou melhorias em relação a uma instalação tradicional do software. O arquivo
README.Debian também indica todas as adaptações que foram feitas para cumprir com a política Debian. O arquivo
changelog.Debian.gz permite ao usuário acompanhar as modificações feitas no pacote ao longo do tempo: é muito útil para tentar entender o que mudou entre as duas versões instaladas que não têm o mesmo comportamento. Finalmente, às vezes existe um arquivo
NEWS.Debian.gz que documenta as maiores mudanças no programa que pode diretamente se referir ao administrador (veja
Seção 6.7.2, “Lidando com Problemas após uma Atualização”).
7.1.4. Paginas da Internet
In most cases, free software programs have websites that are used to distribute it and to bring together the community of its developers and users. These sites are frequently loaded with relevant information in various forms: official documentation,
FAQ (Frequently Asked Questions), mailing list archives, etc. Problems that you may encounter have often already been the subject of many questions; the FAQ or mailing list archives may have a solution for it. A good mastery of search engines will prove immensely valuable to find relevant pages quickly (by restricting the search to the Internet domain or sub-domain dedicated to the program). If the search returns too many pages or if the results do not match what you seek, you can add the keyword
debian to limit results and target relevant information.
Se você não sabe o endereço para o site do software, existem vários meios de consegui-lo. Primeiro, verifique se existe um campo
Homepage na meta-informação do pacote (
apt show pacote). Alternativamente, a descrição do pacote pode conter um link para o site oficial do programa. Se nenhuma URL for indicada, olhe em
/usr/share/doc/pacote/copyright. O mantenedor do Debian geralmente indica neste arquivo de onde ele pegou o código-fonte do programa, e este é provavelmente o site que você precisa encontrar. Se nesta fase a sua pesquisa ainda é infrutífera, consulte um diretório de software livre, como o Diretório de Software Livre da FSF, ou procure diretamente com um motor de busca, como Google, DuckDuckGo, Yahoo, etc.
You might also want to check the Debian wiki, a collaborative website where anybody, even new visitors, can make suggestions directly from their browsers. It is used equally by developers who design and specify their projects, and by users who share their knowledge by writing documents collaboratively.
Um HOWTO é um documento que descreve, em termos concretos e passo a passo, como atingir uma meta pré-definida. Os objetivos cobertos são relativamente variados, mas muitas vezes de natureza técnica: por exemplo, a criação de mascara IP, configuração do software RAID, a instalação de um servidor Samba, etc. Estes documentos geralmente tentam cobrir todos os potenciais problemas susceptíveis de ocorrer durante a execução de uma determinada tecnologia.
Many such tutorials are managed by the Linux Documentation Project (
LDP), whose website hosts all of these documents:
O Debian também fornece tutoriais para seus usuários:
All these documents should be taken with a grain of salt. They are often several years old; the information they contain is sometimes obsolete. This phenomenon is even more frequent for their translations, since updates are neither systematic nor instant after the publication of a new version of the original documents. Further many tutorials nowadays are provided by bloggers, sharing their individual solution with the interested reader. They often lack important information, i.e. the reason why some configuration has been chosen over another, or why some option has been enabled or disabled. Because blogging and creating personal websites made it so easy to share, many of these often short tutorials exist, but only a few are actively maintained and well-kept. This can make it hard to find the "right" one for you. This is all part of the joys of working in a volunteer environment and without constraints…
