Como criar uma página de manual do Linux

O comando cara no Linux está embutido na memória muscular de cada desenvolvedor e usuário Linux. É usado literalmente por todos; de desenvolvedores amadores e novatos a profissionais e especialistas em Linux.

É usado para ler a página de manual da linha de comando para um comando Linux, arquivo de configuração ou qualquer outro recurso. As páginas do manual geralmente são instaladas junto com a instalação de um software no Linux. Existe uma sintaxe definida para páginas de manual, que é analisada pelo comando.

Vamos criar uma página de manual para o seguinte script bash que escrevi: 

#! / bin / bash if ["$ 1" == "h"]; então echo "Hello" fi if ["$ 1" = "b"]; então echo "Tchau" fi

Este script faz apenas duas coisas: imprime “Hello” se a opção ‘h’ for especificada como argumento e imprime “Bye” se a opção ‘b’ for especificada como argumento.

Vamos criar uma página de manual para este programa. Usar vim ou qualquer editor de sua escolha para criar um arquivo de texto.

vim test.1

A extensão ‘.1’ significa que esta página do manual é para um comando executável. Não é uma compulsão, mas sim uma convenção amplamente seguida ao escrever páginas de manual. A página do manual para o homem (homem homem !) lista as categorias:

 1 Programas executáveis ​​ou comandos shell 2 Chamadas de sistema (funções fornecidas pelo kernel) 3 Chamadas de biblioteca (funções dentro de bibliotecas de programas) 4 Arquivos especiais (geralmente encontrados em / dev) 5 Formatos de arquivo e convenções, por exemplo, / etc / passwd 6 Jogos 7 Diversos ( incluindo pacotes de macro e convenções), por exemplo man (7), groff (7) 8 Comandos de administração do sistema (geralmente apenas para root) 9 Rotinas do kernel [não padrão]

Uma página de manual é criada usando a linguagem de marcação roff muito antiga. Possui comandos (marcadores de leitura) para vários títulos e seções.

  • .º - Este deve ser o primeiro comando no arquivo man. É usado para especificar o título da página do manual.
  • .SH - Título da seção.
  • .B - É usado para exibir o texto ao lado em negrito.
  • .TP - É usado para exibir informações sobre um argumento (sinalizador) para o comando.
  • .BR - É usado para exibir o texto em negrito e na fonte romana normal.

A seguir está a página do manual para meu programa criado usando apenas os comandos roff acima (simples).

.TH test.sh 1 .SH NOME test.sh \ - Imprimir Olá ou Tchau .SH SINOPSE .B test.sh [h] [b] .SH DESCRIÇÃO .B test.sh Este é um script de amostra que faz apenas 2 coisas . Ele imprime "Hello" se o argumento for 'h' ou "Bye" se o argumento for 'b' .SH OPTIONS .TP .BR h Imprimir Hello .TP .BR b Print Bye

Salve o arquivo pressionando primeiro o ESC chave e, em seguida, digite : wq para salvar o arquivo e sair do console do vim.

Teste a página de manual que acabamos de criar usando o comando abaixo:

man ./test.1

Para mais informações sobre cara uso, correr man-pages comando em seu terminal.

? Dica

Esta é a sintaxe básica para escrever páginas de manual. Para tornar as coisas mais fáceis, você pode usar ferramentas como txt2man para converter um arquivo em algum formato de linguagem de marcação para o formato roff.