Como criar uma página de manual no Linux

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

As páginas do homem

Pode haver alguma verdade na velha piada do Unix, “a só o comando que você precisa saber é man. ” a man As páginas contêm uma riqueza de conhecimento e devem ser o primeiro lugar para ir quando você deseja informações sobre um comando.

Providencie um man página de um utilitário ou comando que você escreveu o eleva de um 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 for nativamente compatível com Linux, man A página é necessá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ê ligar man para abrir uma página, lama groff para leia o arquivo e gere uma saída formatada, de acordo com as macros no arquivo. A saída é canalizada para less, e posteriormente mostrado para você.

A menos que você acredite man páginas frequentemente, escrever um e inserir macros manualmente é um trabalho árduo. O ato de criar um man página que analisa corretamente e tem boa aparência pode exceder sua meta de fornecer uma descrição concisa, mas completo, do seu comando.

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

RELACIONADO: Como usar o comando man do Linux: segredos ocultos e noções básicas

pandoc para o resgate

a pandoc Programa lê arquivos de marcação e gera novos em cerca de 40 diferentes linguagens de marcação e formatos de documento, incluindo aquele de man página. Transforme totalmente o man procedimento de escrita de página para que você não tenha que lutar com hieróglifos.

Para iniciar, pode instalar pandoc no Ubuntu com este comando:

sudo apt-get install pandoc

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

sudo dnf install pandoc

Em manjaro, escriba:

sudo pacman -Syu pandoc

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

Seções de uma página de manual

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

Minimamente, a maioria das páginas de manual contém essas seções:

• Nome: O nome do comando e um breve resumo 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.
• Escolhas: Uma lista de alternativas de linha de comando e o que elas fazem.
• Exemplos de: Alguns exemplos de uso comum.
• Valores de saída: Possíveis códigos de retorno e seus significados.
• Insetos: Uma lista de bugs e peculiaridades conhecidos. As 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. Isso também geralmente inclui o tipo de licença sob a qual o programa é lançado.

Se você olhar para alguns dos mais complicados man Páginas, você verá que também existem muitas outras seções. Como um exemplo, Experimente man man. Apesar disto, você não tem que incluir todos eles, apenas aqueles que você realmente precisa. man as páginas não são lugar para verborragia.

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

• Veja também: Outros comandos relacionados ao tópico que alguns achariam úteis ou relevantes.
• Registros: Uma lista de arquivos incluídos no pacote.
• Avisos: Outros pontos para saber ou prestar atenção.
• História: Um histórico de mudanças para o comando.

Seções do manual

O manual do Linux consiste em todos os man Páginas, que é posteriormente dividido nessas seções numeradas:

1. Programas executáveis: Os comandos do shell.
2. Chamadas de sistema: Funções fornecidas pelo kernel.
3. Chamadas para a biblioteca: Funções nas bibliotecas do programa.
4. Arquivos especiais.
5. Convenções e formatos de arquivo: Como um exemplo, “/ etc / senha”.
6. Jogos.
7. Diferente: Pacotes de macro e convenções, O que groff.
8. Comandos de administração do sistema: Regularmente reservado para root.
9. Rotinas de 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 armazenado no local apropriado para essa seção, como discutido abaixo. a man as páginas de comandos e utilitários pertencem à seção um.

O formato de uma página de manual

a groff O formato macro não é fácil de analisar visualmente. Pelo contrário, o desconto é muito simples.

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

A mesma página é mostrada abaixo em promoção.

Matéria de frente

As primeiras três linhas formam algo chamado problema principal. Todos eles devem começar com um sinal de porcentagem (%), sem espaços principais, exceto um depois, seguido de:

• 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úscula, mesmo que você encontre muitos que não sã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 (a) Nome (s) do (a) Autor (isto é). 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”, apenas inclua pelo menos um nome aqui.
• A terceira linha: 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 libra (#), que é a marcação que indica um título na marcação. O sinal numérico (#) deve ser o primeiro personagem da linha, seguido por um espaço.

A seção de nome tem uma única linha que inclui o nome do comando, um espaço, um traço (-), 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 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. Apenas um asterisco (*) em ambos os lados de um texto torna o man página para exibir 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 no final ().

Descrição

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

Usando dos signos numéricos (##) no início de uma linha, crie um título de nível dois. Você pode usá-los para quebrar sua descrição em partes menores.

Escolhas

A seção de alternativas contém uma descrição das alternativas de linha de comando que podem ser usadas com o comando. Por convenção, estes são mostrados em negrito, portanto, inclua dois asteriscos (**) antes e depois deles. Inclua a descrição do texto das alternativas na próxima linha e comece com dois pontos (:), seguido por um espaço.

Se a descrição for curta o suficiente, man irá mostrá-lo na mesma linha que a opção da linha de comando. Se for muito longo, é mostrado como um parágrafo recuado começando na linha abaixo da opção da linha de comando.

Exemplos de

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 (:), da mesma forma que fizemos com a seção de alternativas.

Valores de saída

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

Insetos

A seção de bugs lista os bugs conhecidos, as armadilhas ou peculiaridades que as pessoas deveriam 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..

Direitos autorais

A seção de direitos autorais contém sua declaração de direitos autorais e, em geral, 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 no seu editor favorito. A maioria dos que suportam realce de sintaxe estará ciente das marcações e colorir o texto para realçar os títulos, bem como negrito e sublinhá-lo. Isso é legal na medida do possível., mas você não está vendo uma renderização man página, qual é o verdadeiro teste no pudim.

Abra uma janela de terminal no diretório que contém seu arquivo de redução. Com ele aberto em seu editor, salve periodicamente seu arquivo em seu disco rígido. Toda vez que eu faço, você pode executar o seguinte comando na janela do terminal:

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

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

Este comando também invoca pandoc no arquivo de venda (aqui, se chama “Você não precisa adicionar uma seção”):

• a -s (Independente) gera um completo de cima para baixo man página, em vez de apenas texto em man formato.
• a -t Opção (tipo de saída) Você não precisa adicionar uma seção “cara” indica pandoc para gerar sua saída em man formato. Nós não dissemos pandoc para enviar sua saída para um arquivo, então será enviado para stdout.

Também estamos canalizando essa saída para man com ele -l (arquivo local) opção. Dados man não procure através man banco de dados procurando pelo man página. Em seu lugar, deve abrir o arquivo nomeado. Se o nome do arquivo for -, man pegará sua opinião de stdin.

Você pode salvar do seu editor e clicar em Q para fechar man se estiver rodando na janela do terminal. Depois de, você pode pressionar a seta para cima, seguido por Enter para ver uma versão renderizada de seu man página, justo dentro man.

RELACIONADO: O que são stdin, stdout y stderr en Linux?

Criando sua página de manual

Depois de ter concluído o seu man página, você deve criar uma versão final e, em seguida, instalá-la em seu sistema. O seguinte comando diz pandoc para gerar um man Você não precisa adicionar uma seção “Você não precisa adicionar uma seção”:

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 você descreve e adicionando o número da seção do manual como se fosse uma extensão de arquivo.

Você não precisa adicionar uma seção “Você não precisa adicionar uma seção”, qual é o nosso novo man página. Onde colocamos isso? Este comando nos dirá onde man procura man Páginas:

manpath

Os resultados nos fornecem as próximas informações:

• / usr / compartilhado / cara: A localização da biblioteca padrão de man Páginas. Não adicionamos páginas a esta biblioteca.
• / usr / local / compartilhado / cara: Você não precisa adicionar uma seção “/ usr / local / cara”.
• / usr / local / cara: É aqui que devemos 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, etc. Se o diretório da seção não existe, devemos criá-lo.

Para faze-lo, nós escrevemos o seguinte:

sudo mkdir / usr / local / man / man1

Você não precisa adicionar uma seção “Você não precisa adicionar uma seção” Você não precisa adicionar uma seção:

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

man espere pelo man páginas para comprimir, portanto, vamos usar gzip para comprimirlo:

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

Para fazer man adicione o novo arquivo ao seu banco de dados, escreva o seguinte:

sudo mandb

Isso é tudo! Agora podemos chamar nosso novo man página como qualquer outra escrita:

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 recuo nos locais apropriados.

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

Você não precisa adicionar uma seção “Autores”. O rodapé também inclui o número da versão do software, a data e o nome do comando, como indicado na página principal.

Se você deseja . . .

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 isso.