Como criar uma página man no Linux

Quer que seu novo programa Linux pareça profissional? Dê-lhe uma página de man . Mostraremos a maneira mais fácil e rápida de fazer isso.

As páginas de homem

Há um fundo de verdade na velha piada do Unix, “o único comando que você precisa saber é man ”. As páginas de man contêm uma riqueza de conhecimento e devem ser o primeiro lugar que você deve consultar quando quiser aprender sobre um comando.

Fornecer uma página de man para um utilitário ou comando que você escreveu eleva-o de um pedaço de código útil a um pacote Linux totalmente formado. As pessoas esperam que uma página de man seja fornecida para um programa que foi escrito para Linux. Se você está dando suporte nativo ao Linux, uma página de man é obrigatória se você quiser que seu programa seja levado a sério.

Historicamente, as páginas man foram escritas usando um conjunto de macros de formatação. Quando você chama man para abrir uma página, ele chama groff para ler o arquivo e gerar uma saída formatada, de acordo com as macros no arquivo. A saída é canalizada para less e, em seguida, exibida para você.

A menos que você crie páginas de man com frequência, escrever uma e inserir manualmente as macros é um trabalho árduo. O ato de criar uma página de man que analisa corretamente e parece correta pode ultrapassar seu objetivo de fornecer uma descrição concisa, porém completa, do seu comando.

Você deve se concentrar em seu conteúdo, não lutando contra um conjunto obscuro de macros.

RELACIONADO: Como usar o comando man do Linux: segredos e fundamentos ocultos

pandoc ao resgate

O programa pandoc lê arquivos markdown e gera novos em cerca de 40 linguagens de marcação e formatos de documentos diferentes, incluindo o da página man . Ele transforma totalmente o processo de escrita da página de man para que você não precise lutar com hieróglifos.

Para começar, você pode instalar pandoc no Ubuntu com este comando:

 sudo apt-get install pandoc 

No Fedora, o comando que você precisa é o seguinte:

 sudo dnf instalar pandoc 

No Manjaro, digite:

 sudo pacman -Syu pandoc 

RELACIONADO: Como usar o pandoc para converter arquivos na linha de comando do Linux

Seções de uma página man

As páginas man contêm seções que seguem uma convenção de nomenclatura padrão. As seções man precisa são ditadas pela sofisticação do comando que você está descrevendo.

No mínimo, a maioria das páginas man contém estas seções:

• Nome : O nome do comando e uma frase concisa que descreve sua função.
• Sinopse : Uma descrição concisa das invocações que alguém pode usar para iniciar o programa. Eles mostram os tipos de parâmetros de linha de comando aceitos.
• Descrição : Uma descrição do comando ou função.
• Opções : uma lista de opções de linha de comando e o que elas fazem.
• Exemplos : Alguns exemplos de uso comum.
• Valores de saída : Os possíveis códigos de retorno e seus significados.
• Bugs : Uma lista de bugs e peculiaridades conhecidos. Às vezes, isso é complementado com (ou substituído por) um link para o rastreador de problemas do projeto.
• Autor : A pessoa ou pessoas que escreveram o comando.
• Direitos autorais : Sua mensagem de direitos autorais. Estes também geralmente incluem o tipo de licença sob a qual o programa é lançado.

Se você examinar algumas das páginas de man mais complicadas, verá que também existem muitas outras seções. Por exemplo, tente man man . Você não precisa incluir todos eles, apenas aqueles que você realmente precisa. páginas man não são lugar para palavrões.

Algumas outras seções que você verá com bastante frequência são:

• Veja também : Outros comandos relacionados ao assunto que alguns achariam úteis ou relevantes.
• Arquivos : Uma lista de arquivos incluídos no pacote.
• Advertências : Outros pontos a serem conhecidos ou observados.
• Histórico : Um histórico de alterações para o comando.

Seções do Manual

O manual do Linux é composto de todas as páginas do man , que são divididas nessas seções numeradas:

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 programas.
4. Arquivos especiais.
5. Formatos de arquivo e convenções: Por exemplo, “/etc/passwd”.
6. Jogos.
7. Diversos: Pacotes e convenções de macros, como groff .
8. Comandos de administração do sistema: Normalmente reservados para root.
9. Rotinas do kernel: geralmente não são instaladas por padrão.

Cada página de man deve indicar a qual seção pertence e também deve ser armazenada no local apropriado para essa seção, como veremos mais adiante. As páginas man para comandos e utilitários pertencem à seção um.

O formato de uma página man

O formato de macro groff não é fácil de analisar visualmente. Em contraste, o markdown é uma brisa.

Abaixo está uma página de manual em groff .

A mesma página é mostrada abaixo em markdown.

Front Matter

As três primeiras linhas formam algo chamado matéria de frente . Todos eles devem começar com um sinal de porcentagem ( % ), sem espaços à esquerda, mas um depois, seguido por:

• A primeira linha: Contém o nome do comando, seguido da seção do manual entre parênteses, sem espaços. O nome se torna as seções esquerda e direita do cabeçalho da página man . Por convenção, o nome do comando está em letras maiúsculas, embora você encontre muitos que não estão. Qualquer coisa que segue o nome do comando e o número da seção manual se torna a seção esquerda do rodapé. É conveniente usar isso para o número da versão do software.
• A segunda linha: O(s) nome(s) do(s) autor(es). Eles são exibidos em uma seção de autores gerada automaticamente da página man . Você não precisa adicionar uma seção “Autores”—apenas inclua pelo menos um nome aqui.
• A terceira linha: A data, que também se torna a parte central do rodapé.

Nome

As seções são indicadas por linhas que começam com um sinal de número ( # ), que é a marcação que indica um cabeçalho em remarcação. O sinal de número ( #) deve ser o primeiro caractere da linha, seguido de um espaço.

A seção de nome contém uma linha simples que inclui o nome do comando, um espaço, um hífen ( - ), um espaço e, em seguida, uma descrição muito curta do que o comando faz.

Sinopse

A sinopse contém os diferentes formatos que a linha de comando pode assumir. Este comando pode aceitar um padrão de pesquisa ou uma opção de linha de comando. Os dois asteriscos ( ** ) em cada lado do nome do comando significam que o nome será exibido em negrito na página do man . Um único asterisco ( * ) em cada lado de algum texto faz com que a página do man o exiba sublinhado.

Por padrão, uma quebra de linha é seguida por uma linha em branco. Para forçar uma quebra brusca sem uma linha em branco, você pode usar uma barra invertida à direita ( \ ).

Descrição

A descrição explica o que o comando ou programa faz. Deve cobrir os detalhes importantes de forma sucinta. Lembre-se, você não está escrevendo um guia do usuário.

O uso de dois sinais numéricos ( ## ) no início de uma linha cria um título de nível dois. Você pode usá-los para quebrar sua descrição em pedaços menores.

Opções

A seção de opções contém uma descrição de todas as opções de linha de comando que podem ser usadas com o comando. Por convenção, eles são exibidos em negrito, então inclua dois asteriscos ( ** ) antes e depois deles. Inclua a descrição de texto das opções na próxima linha e comece com dois pontos ( : ), seguido de um espaço.

Se a descrição for curta o suficiente, man a exibirá na mesma linha que a opção de linha de comando. Se for muito longo, será exibido como um parágrafo recuado que começa na linha abaixo da opção de linha de comando.

Exemplos

A seção de exemplos contém uma seleção de diferentes formatos de linha de comando. Observe que iniciamos as linhas de descrição com dois pontos ( : ), assim como fizemos na seção de opções.

Valores de saída

Esta seção lista os valores de retorno que seu comando envia de volta ao processo de chamada. Este pode ser o shell, se você o chamou da linha de comando, ou um script, se o iniciou a partir de um script de shell. Começamos as linhas de descrição com dois pontos ( : ) nesta seção também.

Insetos

A seção de bugs lista bugs conhecidos, pegadinhas ou peculiaridades que as pessoas precisam conhecer. Para projetos de código aberto, é comum incluir aqui um link para o rastreador de problemas do projeto para verificar o status de quaisquer bugs ou relatar novos.

direito autoral

A seção de direitos autorais contém sua declaração de direitos autorais e, geralmente, uma descrição do tipo de licença sob a qual o software é lançado.

Um fluxo de trabalho eficiente

Você pode editar sua página de man em seu editor favorito. A maioria que suporta o realce de sintaxe estará ciente do markdown e colorir o texto para destacar os títulos, bem como negrito e sublinhado. Isso é ótimo, mas você não está olhando para uma página de man renderizada, que é a prova real no pudim.

Abra uma janela de terminal no diretório que contém seu arquivo markdown. Com ele aberto em seu editor, salve periodicamente seu arquivo em seu disco rígido. Cada vez que você fizer isso, você pode executar o seguinte comando na janela do terminal:

 pandoc ms.1.md -s -t man | /usr/bin/man -l - 

Depois de usar esse comando, você pode pressionar a seta para cima para repeti-lo e, em seguida, pressionar Enter.

Este comando também invoca o pandoc no arquivo markdown (aqui, é chamado de “ms.1.md”):

• A opção -s (independente) gera uma página man completa de cima para baixo, em vez de apenas algum texto no formato man .
• A opção -t (tipo de saída) com o operador “man” diz ao pandoc para gerar sua saída no formato man . Nós não dissemos ao pandoc para enviar sua saída para um arquivo, então ela será enviada para stdout .

Também estamos canalizando essa saída para man com a opção -l (arquivo local). Ele diz ao man para não pesquisar no banco de dados do man procurando a página do man . Em vez disso, ele deve abrir o arquivo nomeado. Se o nome do arquivo for - , man pegará sua entrada de stdin .

O que isso se resume é que você pode salvar do seu editor e pressionar Q para fechar o man se estiver sendo executado na janela do terminal. Em seguida, você pode pressionar a seta para cima, seguida de Enter para ver uma versão renderizada de sua página de man , bem dentro de man .

RELACIONADO: O que são stdin, stdout e stderr no Linux?

Criando sua página man

Depois de concluir sua página man , você precisa criar uma versão final dela e instalá-la em seu sistema. O seguinte comando diz ao pandoc para gerar uma página man chamada “ms.1”:

 pandoc ms.1.md -s -t man -o ms.1 

Isso segue a convenção de nomear a página man após o comando que ela descreve e anexar o número da seção do manual como se fosse uma extensão de arquivo.

Isso cria um arquivo “ms.1”, que é nossa nova página de man . Onde o colocamos? Este comando nos dirá onde man procura por páginas man :

 caminho de homem 

Os resultados nos dão as seguintes informações:

• /usr/share/man: A localização da biblioteca padrão de páginas de man . Não adicionamos páginas a esta biblioteca.
• /usr/local/share/man: Este link simbólico aponta para “/usr/local/man.”
• /usr/local/man: Aqui é onde precisamos colocar nossa nova página de man .

Observe que as diferentes seções do manual estão contidas em seus próprios diretórios: man1, man2, man3 e assim por diante. Se o diretório da seção não existir, precisamos criá-lo.

Para isso, digitamos o seguinte:

 sudo mkdir /usr/local/man/man1

Em seguida, copiamos o arquivo “ms.1” para o diretório correto:

 sudo cp ms.1 /usr/local/man/man1

man espera que as páginas man sejam compactadas, então usaremos gzip para compactar:

 sudo gzip /usr/local/man/man1/ms.1

Para fazer man adicionar o novo arquivo ao seu banco de dados, digite o seguinte:

 sudo mandb 

É isso! Agora podemos chamar nossa nova página de man da mesma forma que qualquer outra digitando:

 homem ms 

Nossa nova página man é encontrada e exibida.

Ela se parece com qualquer outra página de man , com texto em negrito, sublinhado e recuado nos locais apropriados.

As linhas de descrição que se encaixam ao lado da opção que descrevem aparecem na mesma linha. Linhas muito longas para caber aparecem abaixo da opção que descrevem.

Também geramos automaticamente uma seção "Autores". O rodapé também inclui o número da versão do software, a data e o nome do comando, conforme definido no material inicial.

Se você quiser . . .

Uma vez que o pandoc tenha criado sua página de man , você também pode editar diretamente o arquivo no formato de macro groff antes de movê-lo para o diretório da página de man e compactar com gzip .