Como criar uma página de homem no Linux

Quer que seu novo programa Linux tenha uma aparência profissional? Dê um man página. 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. ” o man As páginas contêm uma riqueza de conhecimento e devem ser o primeiro lugar que você deve consultar quando quiser aprender sobre um comando.

Fornecendo um man página 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 um man página a ser fornecida para um programa que foi escrito para Linux. Se você tem suporte nativo para Linux, um man página é obrigatória se você quiser que seu programa seja levado a sério.

Historicamente, o man as páginas 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 saída formatada, de acordo com as macros do arquivo. A saída é canalizada para lesse, em seguida, exibido para você.

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

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

RELACIONADOS: Como usar o comando man do Linux: princípios básicos e segredos ocultos

pandoc para o resgate

o pandoc programa lê arquivos de marcação e gera novos em cerca de 40 linguagens de marcação e formatos de documentos diferentes, incluindo o do man página. Isso transforma totalmente o man processo de escrita de página para que você não tenha que 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 de que você precisa é o seguinte:

sudo dnf install pandoc

No Manjaro, digite:

sudo pacman -Syu pandoc

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

Seções de uma página de homem

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

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

• Nome: O nome do comando e uma breve linha 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 códigos de retorno possíveis e seus significados.
• Insetos: Uma lista de bugs e peculiaridades conhecidos. Às vezes, isso é complementado (ou substituído por) um link para o rastreador de problemas do projeto.
• Autor: A pessoa ou pessoas que escreveram o comando.
• direito autoral: Sua mensagem de direitos autorais. Geralmente, também incluem o tipo de licença sob a qual o programa é lançado.

Se você olhar alguns dos mais complicados man páginas, você verá que há muitas outras seções também. Por exemplo, tente man man. Você não precisa incluir todos eles – apenas aqueles de que você realmente precisa. man páginas não são lugar para prolixo.

Algumas outras seções que você verá com razoável 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.
• Ressalvas: Outros pontos a conhecer ou observar.
• História: Um histórico de alterações para o comando.

Seções do manual

O manual do Linux é composto por todos os man páginas, que são então divididas nestas seções numeradas:

1. Programas executáveis: Ou comandos do shell.
2. Chamadas de sistema: Funções fornecidas pelo kernel.
3. Chamadas da biblioteca: Funções nas bibliotecas do programa.
4. Arquivos especiais.
5. Formatos e convenções de arquivo: Por exemplo, “/ etc / passwd”.
6. Jogos
7. Diversos: Pacotes de macros e convenções, como groff.
8. Comandos de administração do sistema: Normalmente reservado para root.
9. Rotinas do kernel: Normalmente não instalado por padrão.

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

O formato de uma página de homem

o groff o formato macro não é fácil de analisar visualmente. Em contraste, a redução é uma brisa.

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

A mesma página é mostrada abaixo na redução.

Matéria frontal

As primeiras três linhas formam algo chamado assunto frontal. 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 pela seção do manual entre parênteses, sem espaços. O nome se torna as seções esquerda e direita do man cabeçalho da página. Por convenção, o nome do comando está em maiúsculas, embora você descubra muitos que não estão. Tudo o que segue o nome do comando e o número da seção do manual torna-se 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 do man página. Você não precisa adicionar uma seção “Autores” – basta incluir 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 na marcação. O sinal numérico (#) deve ser o primeiro caractere da linha, seguido por 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 breve descrição 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 qualquer lado do nome do comando significa que o nome será exibido em negrito no man página. Um único asterisco (*) em qualquer lado de algum texto causa o man página para exibi-lo 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 abranger os detalhes importantes de forma sucinta. Lembre-se de que você não está escrevendo um guia do usuário.

Usando 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 quaisquer 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 o texto descritivo das opções na próxima linha e comece com dois pontos (:), seguido por um espaço.

Se a descrição for curta o suficiente, man irá exibi-lo 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 começamos 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. Pode ser o shell, se você o chamou da linha de comando, ou um script, se você 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 um link aqui 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 o seu man página em seu editor favorito. A maioria dos que suportam o destaque de sintaxe reconhecerá a marcação e colorir o texto para destacar os títulos, bem como negrito e sublinhado. Isso é ótimo até onde vai, mas você não está olhando para uma imagem renderizada man página, que é a verdadeira prova no pudim.

Abra uma janela de terminal no diretório que contém o arquivo markdown. Com ele aberto em seu editor, salve periodicamente seu arquivo em seu disco rígido. Cada vez que o fizer, 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 pandoc no arquivo de marcação (aqui, é chamado de “ms.1.md”):

• o -s (autônomo) opção gera um completo de cima para baixo man página, em vez de apenas algum texto em man formato.
• o -t (tipo de saída) opção com o operador “man” diz pandoc para gerar sua saída em man formato. Nós não contamos 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 o -l opção (arquivo local). Diz man não pesquisar através do man banco de dados procurando pelo man página. Em vez disso, ele deve abrir o arquivo nomeado. Se o nome do arquivo for -, man pegará sua contribuição de stdin.

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

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

Criando sua página de homem

Depois de completar o seu man página, você precisa criar uma versão final dele e, em seguida, instalá-lo em seu sistema. O seguinte comando diz pandoc para gerar um man página chamada “ms.1”:

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

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

Isso cria um arquivo “ms.1”, que é nosso novo man página. Onde vamos colocá-lo? Este comando nos dirá onde man procura por man Páginas:

manpath

Os resultados nos fornecem as seguintes informações:

• / usr / share / man: A localização da biblioteca padrão de man Páginas. 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 que precisamos colocar nosso novo man página.

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 para a seção não existir, precisamos criá-lo.

Para fazer 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 o man páginas a serem compactadas, então usaremos gzip para compactá-lo:

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

Fazer man adicione o novo arquivo ao seu banco de dados, digite o seguinte:

sudo mandb

É isso aí! Agora podemos chamar nosso novo man página igual a qualquer outra digitando:

man ms

Nosso novo man a página é encontrada e exibida.

Se parece com qualquer outro man página, com texto em negrito, sublinhado e recuado nos locais apropriados.

As linhas de descrição que cabem 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, data e nome do comando, conforme definido na capa.

Se você quiser . . .

Uma vez pandoc criou o seu man página, você também pode editar diretamente o arquivo no groff formato macro antes de movê-lo para o man diretório da página, e gzip isto.