Apropos, whatis e catman: pesquisando a documentação do Linux

O comando apropos

O nome apropos vem de uma expressão francesa que significa aproximadamente “a respeito de” ou “com relação a”. No Linux, ele é utilizado para pesquisar nomes e descrições de páginas de manual.

Sua sintaxe básica é:

$ apropos palavra

Imagine que você queira procurar comandos relacionados a calendários:

$ apropos calendar
cal (1)              - display a calendar
calendar (1)         - reminder service

Cada linha possui três elementos:

cal (1) - display a calendar

• cal é o nome do comando ou da página de manual;
• (1) identifica a seção do manual;
• o texto depois do hífen é uma descrição resumida.

Depois de encontrar um comando interessante, podemos abrir seu manual:

$ man cal

Pesquisando outros assuntos

Para procurar ferramentas relacionadas a senhas:

$ apropos password

Para localizar comandos relacionados a compactação:

$ apropos compression

Para pesquisar ferramentas de rede:

$ apropos network

As descrições das páginas de manual geralmente estão em inglês. Portanto, mesmo que o sistema esteja configurado em português, costuma ser mais produtivo pesquisar com termos em inglês.

Pesquisa com mais de uma palavra

Podemos fornecer várias palavras:

$ apropos copy file

Por padrão, serão mostradas páginas que correspondam a qualquer um dos termos. Isso pode produzir muitos resultados.

Para mostrar somente as páginas que contenham correspondências para todos os termos, usamos a opção -a, que representa a operação lógica “E”:

$ apropos -a copy file

Esse comando procura páginas relacionadas simultaneamente a copy e file.

Outro exemplo:

$ apropos -a network monitor

Limitando a pesquisa a uma seção

As páginas de manual são organizadas em seções. Algumas das principais são:

Para procurar somente comandos de usuário, usamos:

$ apropos -s 1 password

Para pesquisar nas seções 1 e 8:

$ apropos -s 1,8 user

Isso pode ser útil quando queremos encontrar comandos executáveis e evitar resultados relacionados a funções de programação.

Pesquisa exata

A opção -e procura uma correspondência exata:

$ apropos -e passwd

Sem essa opção, a pesquisa também poderia apresentar páginas cujas descrições apenas contivessem a palavra passwd.

O atalho "man -k"

O comando apropos também pode ser executado por meio de man -k:

$ man -k password

Esse comando produz essencialmente o mesmo resultado que:

$ apropos password

A letra k pode ser associada a keyword, palavra-chave.

O comando whatis

O whatis responde a uma pergunta simples: “O que é este comando?”. Ele mostra a descrição resumida existente na página de manual.

Sua sintaxe básica é:

$ whatis comando

Por exemplo:

$ whatis ls

A saída normalmente será semelhante a:

ls (1) - list directory contents

Isso nos informa que ls está documentado na seção 1 e serve para listar o conteúdo de diretórios.

Outros exemplos:

$ whatis cp
$ whatis mkdir
$ whatis passwd
$ whatis ssh

Também podemos consultar vários nomes de uma só vez:

$ whatis cp mv rm

A saída poderá ser:

cp (1) - copy files and directories
mv (1) - move or rename files
rm (1) - remove files or directories

O whatis é útil quando encontramos um comando em um tutorial ou script e queremos descobrir rapidamente sua finalidade, sem abrir toda a página de manual.

Diferença entre apropos e whatis

A diferença principal está no tipo de informação que fornecemos:

$ apropos compact

Nesse caso, conhecemos o assunto e queremos descobrir os comandos relacionados.

$ whatis gzip

Aqui, já conhecemos o nome gzip e queremos obter uma explicação curta.

Em termos simples:

• use apropos quando souber o que deseja fazer, mas ainda não souber o nome do comando;
• use whatis quando já souber o nome e quiser descobrir rapidamente para que ele serve;
• use man quando quiser ler a documentação completa.

O atalho "man -f"

O whatis possui um equivalente dentro do próprio comando man:

$ man -f ls

Esse comando produz essencialmente o mesmo resultado que:

$ whatis ls

A letra f pode ser lembrada como find by name, localizar pelo nome.

O índice das páginas de manual

Tanto apropos quanto whatis consultam um banco de dados com os nomes e as descrições das páginas de manual. Esse índice permite que a pesquisa seja realizada rapidamente.

Em sistemas que usam o pacote man-db, o banco de dados é criado e atualizado pelo comando mandb:

$ sudo mandb

Normalmente, a distribuição atualiza esse índice automaticamente quando programas são instalados ou removidos. A execução manual pode ser necessária quando uma página recém-instalada não aparece nas pesquisas.

Se o comando abaixo não produzir resultados, embora você saiba que a página de manual está instalada:

$ apropos palavra

tente atualizar o índice:

$ sudo mandb

Em seguida, repita a pesquisa.

É importante não confundir mandb com catman. O mandb atualiza o índice pesquisado por apropos e whatis. O catman cria cópias já formatadas das páginas de manual.

O comando catman

As páginas de manual são armazenadas em uma linguagem de formatação chamada roff. Quando executamos:

$ man ls

o sistema localiza o arquivo correspondente, interpreta as instruções de formatação e apresenta o texto na tela.

O catman pode realizar essa formatação antecipadamente e armazenar o resultado em arquivos conhecidos como cat pages. Na consulta seguinte, o sistema pode exibir a versão pronta, economizando o trabalho de formatá-la novamente. Segundo a documentação atual do man-db, isso melhora a velocidade de exibição, porém consome espaço adicional em disco. O suporte a essas páginas depende da configuração adotada pelo administrador do sistema.

Para criar ou atualizar as páginas pré-formatadas, utiliza-se:

$ sudo catman

Como ele trabalha com diretórios e arquivos pertencentes ao sistema, normalmente precisa ser executado com privilégios administrativos.

Processando uma seção específica

É possível indicar uma ou mais seções do manual:

$ sudo catman 1

Esse comando processa as páginas da seção 1, que contém os comandos comuns utilizados pelos usuários.

Para processar as seções 1 e 8:

$ sudo catman 1 8

Indicando outro caminho

A opção -M permite selecionar uma hierarquia de páginas de manual:

$ sudo catman -M /usr/local/share/man

Esse recurso é mais útil para administradores que mantêm documentação instalada em locais específicos.

O catman ainda é necessário?

Para a maioria dos usuários, não. Os computadores atuais conseguem formatar uma página de manual rapidamente, e muitas distribuições nem sequer mantêm diretórios destinados às cat pages. Por isso, é possível que catman não esteja instalado ou que seu uso não produza uma diferença perceptível.

Também não existe razão para executá-lo rotineiramente em um computador pessoal. Ele permanece relevante principalmente em ambientes administrados de maneira centralizada, em sistemas com hardware limitado ou em situações nas quais muitas consultas às mesmas páginas de manual justificam a criação das versões pré-formatadas.

Um exemplo de uso combinado

Imagine que você queira comparar dois arquivos, mas não saiba qual comando usar.

Primeiro, pesquise pelo assunto:

$ apropos -a compare files

Entre os resultados, poderá aparecer:

cmp (1)  - compare two files byte by byte
diff (1) - compare files line by line

Agora obtenha uma explicação rápida sobre os comandos:

$ whatis cmp diff

Depois de escolher diff, abra a documentação completa:

$ man diff

Se programas tiverem sido instalados recentemente e os resultados não aparecerem, atualize o índice:

$ sudo mandb

Nesse fluxo, cada ferramenta cumpre uma função:

Conclusão

Aprender a pesquisar a documentação local é um passo importante para conquistar autonomia no Linux. Não é necessário memorizar todos os comandos ou todas as suas opções. É muito mais útil saber encontrar a informação necessária quando surge um problema.

O apropos transforma uma ideia ou necessidade em uma lista de comandos possíveis. O whatis explica rapidamente a finalidade de um comando. O man fornece os detalhes necessários para utilizá-lo. Nos bastidores, mandb mantém o índice das páginas de manual, enquanto catman, quando adotado pelo sistema, prepara versões pré-formatadas para acelerar sua exibição.

Esses recursos formam um sistema de consulta integrado e disponível mesmo quando o computador está sem acesso à internet. Dominar esse sistema significa transformar a própria instalação do Linux em uma fonte permanente de aprendizado.