Como criar uma página man no Linux

Quer que seu novo programa Linux pareça profissional? Dê-lhe uma página de manual. 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 conhecer é homem”. As páginas de manual 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 manual 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 manual seja fornecida para um programa que foi escrito para Linux. Se você está dando suporte nativo ao Linux, uma página de manual é 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 leia o arquivo e gere saída formatada, de acordo com as macros no arquivo. A saída é canalizada para menos e, em seguida, exibido para você.

A menos que você crie páginas de manual com frequência, escrever uma e inserir manualmente as macros é um trabalho árduo. O ato de criar uma página de manual 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.

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 manual para que você não precise lutar com hieróglifos.

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

sudo apt-get install pandoc

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

sudo dnf install pandoc

No Manjaro, digite:

sudo pacman -Syu pandoc

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 que sua página de manual 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 manual mais complicadas, verá que também existem muitas outras seções. Por exemplo, tente homem homem. 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 a serem 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 manual, que são divididas nessas seções numeradas:

Programas executáveis: Ou comandos shell.
Chamadas do sistema: Funções fornecidas pelo kernel.
Chamadas de biblioteca: Funções dentro de bibliotecas de programas.
Arquivos especiais.
Formatos de arquivo e convenções: Por exemplo, “/etc/passwd”.
Jogos.
Diversos: Pacotes e convenções de macros, como groff.
Comandos de administração do sistema: Normalmente reservados para root.
Rotinas do kernel: geralmente não são instaladas por padrão.

Cada página de manual 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 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 manual. Um único asterisco

em ambos os lados de algum texto faz com que a página do manual 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 ().

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 manual 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 manual renderizada, que é a prova real no pudim.

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

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:

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 homem para não pesquisar no banco de dados do homem procurando a página do manual. Em vez disso, ele deve abrir o arquivo nomeado. Se o nome do arquivo for -, man receberá 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 manual, bem dentro de man.

Criando sua página man

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

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”:

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.

manpath

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

Os resultados nos dão as seguintes informações:
/usr/share/man: A localização da biblioteca padrão de páginas de manual. 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 manual.

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.

sudo mkdir /usr/local/man/man1

Para isso, digitamos o seguinte:

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

Em seguida, copiamos o arquivo “ms.1” para o diretório correto: man espera que as páginas man sejam compactadas, então usaremos gzippara comprimi-lo

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

:

sudo mandb

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

man ms

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

Nossa nova página man é encontrada e exibida.

Ela se parece com qualquer outra página de manual, 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 . . .