Deseja que o seu novo programa Linux tenha uma aparência profissional? Então, ele necessita de uma página de manual. Vamos mostrar a forma mais simples e rápida de criar uma.
O que são as páginas de manual?
Existe uma pitada de verdade na antiga piada do Unix: “o único comando que você precisa conhecer é ‘man’”. As páginas de manual contêm um vasto conhecimento e devem ser o primeiro local a ser consultado quando se pretende aprender sobre um comando.
Fornecer uma página de manual para um utilitário ou comando que você criou, eleva-o de um simples código útil para um pacote Linux completo. Espera-se que um programa escrito para Linux inclua uma página de manual. Se você está a oferecer suporte nativo para Linux, uma página de manual é essencial para que seu programa seja levado a sério.
Historicamente, as páginas de manual eram escritas utilizando um conjunto de macros de formatação. Quando você usa o comando `man` para abrir uma página, ele invoca o `groff` para ler o arquivo e gerar a saída formatada, de acordo com as macros presentes no arquivo. A saída é então direcionada para o comando `less` e exibida para você.
A menos que você crie páginas de manual com frequência, escrever uma e inserir manualmente as macros é uma tarefa complexa. O processo de criar uma página de manual que seja interpretada corretamente e que tenha uma aparência adequada pode superar o objetivo de fornecer uma descrição concisa, mas completa, do seu comando.
O seu foco deve ser o conteúdo, e não lutar com um conjunto obscuro de macros.
Pandoc para nos ajudar
O programa Pandoc lê arquivos em formato Markdown e gera novos arquivos em cerca de 40 linguagens de marcação e formatos de documentos distintos, incluindo o formato de página de manual. Ele transforma completamente o processo de escrita da página de manual, permitindo que você se livre da necessidade de lidar com hieróglifos.
Para começar, instale o Pandoc no Ubuntu com o seguinte comando:
sudo apt-get install pandoc
No Fedora, o comando necessário é:
sudo dnf install pandoc
No Manjaro, execute:
sudo pacman -Syu pandoc
As seções de uma página de manual
As páginas de manual incluem seções que seguem uma convenção de nomenclatura padrão. As seções que sua página de manual necessita são definidas pela complexidade do comando que você está a descrever.
No mínimo, a maioria das páginas de manual incluem estas seções:
Nome: O nome do comando e uma frase concisa descrevendo sua função.
Sinopse: Uma descrição resumida das formas como alguém pode iniciar o programa. Elas 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 das opções de linha de comando e suas funcionalidades.
Exemplos: Alguns exemplos de uso comum.
Valores de Saída: Os possíveis códigos de retorno e seus significados.
Bugs: Uma lista de erros e particularidades conhecidas. Em alguns casos, esta seção é complementada por (ou substituída por) um link para o rastreador de problemas do projeto.
Autor: A(s) pessoa(s) que escreveu(ram) o comando.
Direitos Autorais: A sua declaração de direitos autorais. Esta seção geralmente inclui o tipo de licença sob a qual o programa foi lançado.
Ao analisar algumas das páginas de manual mais complexas, você notará que existem muitas outras seções. Por exemplo, tente `man man`. Você não necessita incluir todas, apenas as que são realmente necessárias. As páginas de manual não são adequadas para linguagem imprópria.
Algumas outras seções que você encontrará com frequência são:
Ver Também: Outros comandos relacionados ao assunto que podem ser úteis ou relevantes.
Arquivos: Uma lista de arquivos incluídos no pacote.
Avisos: Outros pontos que precisam de atenção.
Histórico: Um histórico de alterações do comando.
Seções do Manual
O manual do Linux é formado por todas as páginas de manual, que são divididas nestas seções numeradas:
Programas executáveis: Ou comandos de shell.
Chamadas de 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 o usuário root.
Rotinas do kernel: Geralmente nã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 adequado para essa seção, como veremos mais adiante. As páginas de manual para comandos e utilitários pertencem à seção um.
O Formato de uma Página de Manual
O formato de macro Groff não é fácil de analisar visualmente. Em contraste, o Markdown é muito mais simples.
Abaixo está uma página de manual em Groff.
A mesma página é mostrada abaixo em Markdown.
Matéria Inicial
As três primeiras linhas formam o que é conhecido como matéria inicial. Todas elas devem começar com um sinal de porcentagem (%), sem espaços à esquerda, mas com um espaço após, 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 torna-se as seções esquerda e direita do cabeçalho da página de manual. Por convenção, o nome do comando está em letras maiúsculas, embora muitos não o façam. Qualquer texto que siga o nome do comando e o número da seção manual torna-se a seção esquerda do rodapé. É útil utilizar este campo para o número da versão do software.
A segunda linha: O(s) nome(s) do(s) autor(es). Estes são exibidos na seção de autores gerada automaticamente na página de manual. 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 identificadas por linhas que começam com um sinal de número (#), que é a marcação que indica um cabeçalho em Markdown. O sinal de número (#) deve ser o primeiro caractere da linha, seguido por um espaço.
A seção de nome inclui uma única linha que contém o nome do comando, um espaço, um hífen (-), um espaço e uma descrição muito breve 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 (**) de cada lado do nome do comando indicam que o nome será exibido em negrito na página de manual. Um único asterisco em ambos os lados de algum texto faz com que a página de 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, utilize uma barra invertida (\).
Descrição
A descrição explica o que o comando ou programa faz. Ela deve cobrir os detalhes importantes de forma concisa. Lembre-se, você não está a escrever um guia do utilizador.
A utilização de dois sinais de número (##) no início de uma linha cria um título de nível dois. Pode usá-los para dividir a sua descrição em segmentos 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, elas são exibidas em negrito, então inclua dois asteriscos (**) antes e depois delas. 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 longa, será exibida 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. Note que iniciamos as linhas de descrição com dois pontos (:), tal como fizemos na seção de opções.
Valores de Saída
Esta seção lista os valores de retorno que o seu comando envia de volta ao processo de chamada. Este pode ser o shell, se o chamou a partir da linha de comando, ou um script, se o iniciou a partir de um script de shell. Também começamos as linhas de descrição com dois pontos (:) nesta seção.
Bugs
A seção de bugs lista erros conhecidos, armadilhas ou particularidades que as pessoas precisam de saber. Para projetos de código aberto, é comum incluir aqui um link para o rastreador de problemas do projeto, para verificar o estado de quaisquer bugs ou relatar novos.
Direito Autoral
A seção de direitos autorais inclui a sua declaração de direitos autorais e, geralmente, uma descrição do tipo de licença sob a qual o software foi lançado.
Um fluxo de trabalho eficiente
Você pode editar sua página de manual no seu editor favorito. A maioria dos editores que suportam realce de sintaxe estão cientes do Markdown e colorirão o texto para destacar os títulos, bem como negrito e sublinhado. Isso é ótimo, mas você não está a olhar para uma página de manual renderizada, que é o verdadeiro teste.
pandoc ms.1.md -s -t man | /usr/bin/man -l -
Abra uma janela de terminal no diretório que contém o seu arquivo Markdown. Com ele aberto no seu editor, salve periodicamente o seu arquivo no disco rígido. Sempre que você fizer isso, execute o seguinte comando na janela do terminal:
Depois de usar este comando, pode pressionar a seta para cima para repeti-lo e, em seguida, pressione Enter.
Este comando também invoca o Pandoc no arquivo Markdown (aqui, é chamado de “ms.1.md”):
A opção -s (standalone) gera uma página de manual 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 a sua saída no formato Man. Não solicitamos ao Pandoc que envie a sua saída para um arquivo, portanto, ela será enviada para o stdout.
Também estamos a direcionar essa saída para o comando `man` com a opção -l (arquivo local). Ela diz ao `man` para não pesquisar na base de dados de `man` procurando pela página de manual. Em vez disso, ele deverá abrir o arquivo especificado. Se o nome do arquivo for -, o `man` receberá a sua entrada do stdin.
O resultado é que você pode salvar as alterações no seu editor e pressionar Q para fechar o man caso esteja a ser executado na janela do terminal. Em seguida, você pode pressionar a seta para cima, seguida de Enter para ver uma versão renderizada da sua página de manual, dentro do próprio `man`.
Criando a sua página de manual
pandoc ms.1.md -s -t man -o ms.1
Após terminar a sua página de manual, precisa de criar uma versão final da mesma e instalá-la no seu sistema. O seguinte comando indica ao Pandoc para gerar uma página de manual chamada “ms.1”:
Isto segue a convenção de nomear a página de manual com base no comando que ela descreve e anexar o número da seção do manual como se fosse uma extensão de arquivo.
manpath
Este comando cria um arquivo “ms.1”, que é a nossa nova página de manual. Onde devemos colocá-lo? Este comando irá indicar onde `man` procura páginas de manual:
Os resultados indicam o seguinte:
/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 que precisamos colocar nossa nova página de manual.
Note que as diferentes seções do manual estão contidas nos seus próprios diretórios: man1, man2, man3 e assim por diante. Se o diretório da seção não existir, é necessário 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: o `man` espera que as páginas de manual estejam compactadas, então vamos usar o gzip para as comprimir.
sudo gzip /usr/local/man/man1/ms.1
:
sudo mandb
Para que o `man` adicione o novo arquivo à sua base de dados, execute o seguinte comando:
man ms
É tudo! Agora podemos chamar a nossa nova página de manual da mesma forma que qualquer outra, digitando:
A nossa nova página de manual é encontrada e exibida.
Ela apresenta-se como qualquer outra página de manual, com texto em negrito, sublinhado e recuado nos locais apropriados.
As linhas de descrição que se ajustam ao lado da opção que descrevem aparecem na mesma linha. As 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 na matéria inicial.
Se você quiser…
Após o Pandoc criar sua página de manual, 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 manual e compactá-lo com gzip.