Linux Lexicon — Anatomia de uma página de homem
Publicados: 2016-11-01
Bytes curtos: As páginas man e a documentação do software podem ser densas e difíceis o suficiente para qualquer iniciante sem as convenções enigmáticas atadas a todos os tipos de colchetes e parênteses. Aqui, tentaremos diminuir a complexidade das páginas de manual do Linux e torná-las mais fáceis de entender.
NOME
O primeiro é o título do nome, e isso resume tudo. Esta seção inclui o nome do utilitário, bem como uma breve descrição.
SINOPSE
Existem vários graus de legibilidade de página de manual para página de manual, mas uma coisa é certa, a parte mais difícil é normalmente decifrar uma sinopse cabeluda. Existem várias convenções para indicar as informações necessárias para qualquer comando. Essas convenções consistem em diferentes colchetes e parênteses, bem como outras formas de notação. Todas essas convenções diferentes podem ser extremamente confusas para um iniciante, e assustadoras ainda para alguém que é experiente, mas não versado na arte dos manuais. Abaixo, vamos quebrar o jargão em regras digeríveis.
| encorajado | Digite exatamente como mostrado. |
| itálico ou sublinhado | Substitua pelo argumento apropriado. |
| [-abcxyz] | Todos os sinalizadores entre colchetes são opcionais. |
| -a | -b | Opções separadas por pipe não podem ser usadas juntas. |
| <obrigatório> | Argumento obrigatório, geralmente encontrado nas descrições das opções. |
| {sim não} | Opções limitadas, apenas as especificadas funcionarão. |
| … | Argumentos seguidos por uma elipse podem ser repetidos. |
Essas regras são bastante simples, mas ficam mais difíceis, e até mesmo intimidantes, quando são usadas em definições de funções longas, especialmente quando estão aninhadas. Então, vamos dar uma olhada em alguns aninhamentos abaixo para construir o que dividimos.
tar {A|c|d|r|t|u|x}[GnSkUWOmpsMBiajJzZhPlRvwo] [ ARG …]
O comando tar tem muitas opções. Vemos o nome do comando tar em negrito porque ele deve ser digitado conforme mostrado. Em seguida, vemos as chaves abertas com opções separadas por tubos, indicando que estamos limitados a elas e devemos escolher apenas uma. Em seguida estão os sinalizadores opcionais, podemos usar qualquer número, porém, eles podem não funcionar todos juntos, ler mais na página do manual esclarecerá quaisquer possíveis conflitos de opções. E, por último, temos o argumento repetível, no caso de tar this para o(s) arquivo(s) em que você está operando.
su [opções] [-] [ usuário [ argumento …]]
Novamente, vemos su bold porque é o nome do comando. Segundo, vemos que nenhum sinalizador é realmente especificado, apenas que são opcionais. Em terceiro lugar, há um único sinalizador que é especificado, mas também é opcional. Por último, vemos um argumento opcional que pode ser repetido dentro de um argumento opcional. Agora, o que costumava parecer muito misterioso está fazendo mais sentido.
whois [{-h|–host } HOST ] [{-p|–port} PORT ] [-abBcdGHKlLmMrRx] [-g FONTE:FIRST-LAST ] [-i ATTR [, ATTR ]…] [-s SOURCE [, FONTE ]…] [-T TIPO [, TIPO ]…] [–verbose] OBJETO
Este é particularmente denso. Copie-o para o seu editor de texto favorito e adicione alguns espaços extras se isso ajudar você a lê-lo. Depois de digitalizar sobre isso, você deve começar a ver alguns padrões. As porções de host e porta usam a mesma formatação para a forma curta e longa da opção seguida pelo argumento para essa opção, enquanto ambas são opcionais. Em seguida, vemos a sequência de sinalizadores opcionais. A próxima parte sobre fontes do primeiro ao último é a sintaxe que é esperada pelo whois que é explicada posteriormente na página do manual. Agora vemos este trio de sinalizadores opcionais que aceitam um único argumento ou argumentos de repetição opcionais, esse é o tipo de composição das convenções que pode ser muito difícil de entender completamente no início. Por último, há a opção detalhada e o objeto (o host/domínio).
E é assim que se lê uma sinopse de página de manual. Existem algumas outras convenções, mas elas são muito obscuras para serem abordadas neste artigo.
DESCRIÇÃO
Geralmente, é onde o uso pretendido do programa ou utilitário é descrito. Alguns manuais serão muito mais detalhados sob este título do que outros.
OPÇÕES
Lembre-se de todos aqueles sinalizadores e argumentos diferentes que podem ser opcionais ou obrigatórios? É aqui que todos eles são explicados. Geralmente há boas informações aqui e geralmente é onde você encontrará a convenção <argument>, indicando que um determinado sinalizador requer um argumento correspondente. Às vezes, você descobrirá que as opções estarão na parte da descrição porque não há uma regra rígida definindo as páginas do manual, apenas convenções e a vontade de cumprir os padrões.
EXEMPLOS
Esta é uma das peças mais úteis que infelizmente não está incluída em todos os manuais. Você também descobrirá que a quantidade de informações e o número de exemplos variam significativamente, e nem todos os exemplos realmente ajudam no uso do comando.
Além disso, você encontrará regularmente seções para o autor, informações sobre direitos autorais, relatórios de bugs e veja também (a propósito).
Além disso, existem as seções formalmente definidas das páginas do manual, conforme definido abaixo.
| 1 | Programas executáveis ou comandos shell |
| 2 | Chamadas do sistema (funções fornecidas pelo kernel) |
| 3 | Chamadas de biblioteca (funções dentro de bibliotecas de programa) |
| 4 | Arquivos especiais (geralmente encontrados em /dev) |
| 5 | Formatos de arquivo e convenções, por exemplo, /etc/passwd |
| 6 | Jogos |
| 7 | Diversos (incluindo pacotes de macro e convenções), por exemplo, man(7), groff(7) |
| 8 | Comandos de administração do sistema (geralmente apenas para root) |
| 9 | Rotinas do kernel (normalmente não encontradas no Linux) |
Muitos comandos não possuem manuais em mais de uma seção, mas para aqueles que possuem, ou para alguns que podem ter nomes ambíguos, você pode especificar a seção como no exemplo abaixo.
Os comandos não são as únicas coisas que possuem manuais, como você pode ver nas seções disponíveis. Chamadas de sistema, arquivos de configuração e dispositivos especiais podem ter uma página de manual correspondente. A quantidade de informações em uma instalação típica do Linux apenas nas páginas man é incrível, e o mesmo se aplica a outros sistemas operacionais semelhantes ao UNIX de código aberto.
Se você achar que a página de manual não é suficiente e você ainda não entende um comando, sempre verifique online porque muitas pessoas oferecem explicações mais completas de certas ferramentas, mas também muitas distribuições têm suas próprias páginas de manual para diferentes pacotes de software. Depois de descobrir que está confortável com um software, mas ainda sentir que o manual está faltando, você sempre pode contribuir escrevendo o seu próprio e enviando para o respectivo projeto. A documentação é frequentemente a parte mais negligenciada dos projetos de software, então mesmo que você não consiga escrever código, você pode escrever manuais, artigos Wiki e tutoriais para ajudar outras pessoas.
Agora que você conhece a anatomia de uma página de manual, não tem desculpa a não ser RTFM (e isso é ler o manual gratuito para menores de 18 anos) ;)
Leia também: Linux Lexicon: Use o comando Watch para executar um comando a cada X segundos