É um fato muito comum que ninguém gosta de escrever documentação. Caramba, ninguém gosta de ler também. Mas há momentos em que precisamos lê -lo para, digamos, terminar o projeto no prazo, ou, especialmente quando trabalha no desenvolvimento de software, até escreva -o. Se você só precisar lê -lo, sempre o encorajamos a fazê -lo, mas se você precisar escrever as páginas manuais e precisar de um pontapé inicial, aqui está o artigo para você. Se você trabalhou anteriormente com html, sua vida será mais fácil, mas se não estiver tudo bem. Escrever páginas manuais para Linux não é tão difícil, apesar da aparência das páginas quando lido em texto simples. Então, basicamente, você precisará de algum conhecimento do Linux e a capacidade de usar um editor de texto. Você aprenderá (com exemplos, é claro) os principais conceitos na formatação de texto aplicados às páginas do homem e como escrever uma página manual simples. Como usamos o YEST como exemplo para o nosso tutorial de desenvolvimento C, usaremos trechos de sua página manual para ilustrar nosso ponto durante este artigo.

Um pouco de história

Dizem que os primeiros pacotes manuais escritos são de autoria de Dennis Ritchie e Ken Thompson em 1971. O software de formatação usado foi troff e esse formato continua sendo usado até hoje, embora as ferramentas possam ser diferentes. A ferramenta de formatação de texto nos sistemas Linux agora é Groff, com o líder 'G' vindo de GNU. A existência de Groff é devida ao fato de que, quando Troff foi escrito, terminais significavam algo diferente em termos de capacidades do que eles querem dizer hoje. Outro forte incentivo para o projeto GNU criar Groff foi a licença proprietária de Troff. Troff ainda vive em outros sistemas UNIX, como OpenSolaris ou Plan9, embora sob licenças de código aberto.

Antes de começarmos, devemos lhe contar algo sobre *roff: é um software de composição, como Tex, por exemplo, e é um idioma por si só. Não vamos transformar este artigo em um manual de Groff, nem faremos uma lista de diferenças entre Groff e Troff. Isso é apenas um iniciante para a escrita simples de página manual e, se você precisar de mais, encontrará muita documentação na Internet.

Alternativas

Se depois de ler isso, você sentirá que a sintaxe é assustadora, temos uma solução para o seu problema: Pod2man. O POD significa documentação antiga e oferece uma sintaxe mais simples, e há Pod2man, que é um módulo Perl (parte do Perlpod) que traduz a documentação escrita em formato de pod para o formato. O Perlpod também oferece ferramentas para converter o POD em texto ou html; portanto, consulte a documentação da sua distribuição sobre como instalá -lo.

Páginas manuais

Categorias

As páginas manuais são divididas em categorias, dependendo do assunto que eles estão tratando. Eles não diferem nas distribuições Linux, mas outros sistemas Unix têm maneiras diferentes de dividir as páginas manuais. Usando

 $ Man Man

dará a você essas categorias e muito mais em relação a como usar o comando do homem. As categorias no Linux são as seguintes:

 1 programas executáveis ​​ou comandos de shell
2 chamadas do sistema (funções fornecidas pelo kernel)
3 chamadas da biblioteca (funções nas 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 macro pacotes e convenções), e.g. Homem (7), Groff (7)
8 Comandos de administração do sistema (geralmente apenas para raiz)
9 Rotinas do kernel [não padrão]

Você é aconselhado a ler a página manual do homem, porque este não é um tutorial sobre como usar eles, mas como escrever eles.

Layout de uma página manual

Desde alguns anos atrás, existe um padrão sobre como escrever páginas manuais, o que elas devem conter e problemas de estilo. Eles devem ser concisos, respeitar o layout e comprimir o máximo de informações no mínimo de espaço possível. Quando se vê um manual de 100 páginas, o primeiro reflexo será fugir.

Longe. Por outro lado, uma página manual curta, mas informativa, que dará ao leitor o que ele/ela quer saber será de ajuda real, mas assustando/chata o usuário. Se o programa que você está escrevendo para as páginas manuais não estiver escrito por você (inteiramente), trabalhe com o (s) desenvolvedor (s) até que você se contente com a aparência do manual. Agora, queremos evitar ser chato ou assustador, vamos começar com o layout.

Primeiro de tudo, o nome do arquivo deve ser $ commandName.Categoria $, como, por exemplo, vim.1. Este arquivo, quando instalado, deve ser gzipado e copiado para o diretório apropriado, que para Vim deve ser/usr/share/man/man1. O arquivo não compactado é um arquivo de texto simples, nada mais. A leitura de qualquer página manual lhe dará uma idéia de como a sua deve ser: nome, sinopse, descrição, opções, exemplos, ajuda, arquivos, veja também, autor e bugs. Nem tudo isso é obrigatório, mas é recomendável que você forneça a todos, caso tudo seja suficiente, para uma melhor experiência do usuário.

A linguagem de marcação

Como afirmado anteriormente, se você está acostumado a escrever xml ou html, encontrará a sintaxe simples. Na verdade, é simples de qualquer maneira quando você se acostuma. Começamos com o cabeçalho, E o primeiro título é o título. O outro geralmente encontrado macros (o equivalente a tags em idiomas de marcação) são títulos de assunto e parágrafos, Mas mais sobre aqueles que mais tarde.

O cabeçalho do título deve conter o seguinte: nome, capítulo (categoria) e a data em que a página foi modificada pela última vez. Então, para molhar os pés, eis como deve parecer:

.º YEST 1 “19 de abril de 2010”

O TH significa título de título e, como é uma macro, deve ser prefeitada de ponto. YEST é o nome do aplicativo, categoria 1, editado pela última vez em 19 de abril de 2010. Antes de irmos mais longe, você pode querer inserir alguns comentários em seu arquivo antes do título. Estes começam com .\ ”(Citação de barra de barragem do DOT) e pode ficar assim:

.\ ”Copyright 2004, 2006, 2010 Kimball Hawkins .

.\" Todos os direitos reservados.

Agora, insira essas linhas (o título e o comentário acima) e verifique o resultado com

 $ Groff -Man -Tascii YEST.1

-O TASCII instrui Groff a produzir em formato ASCII (texto), mas Groff suporta outros tipos de saída. Convidamos você a conferir a página do manual do Groff para isso.

Em seguida, agora que sabemos como lidar com os títulos do título, vamos para o seção títulos. Como você deve ter adivinhado, a macro é .Sh e o que faz é introduzir o nome, sinopse, descrição, etc. seções como escritas acima. Portanto, a sintaxe será:

.Sh Nome YEST - Utilitário de manipulação de data.

.Sh SINOPSE .B YEST \ fr -Help

.P .B YEST \ fr -License

.P .B YEST \ fr -version

.P .B YEST \ fr [\ fb-idf = \ fistr \ fr] [\ fb-tz = \ fitzone \ fr] [[\ fb- \ fr | \ fb+\ fr] \ fiadjust \ fr [\ fbd \ fr | \ fbh \ fr | \ fbm \ fr]] [\ fidate \ fr] [\ fiformat string \ fr] .

Sh Descrição Isso é chamado de ""YEST"" porque o padrão é a data de ontem \. Este utilitário conhece o ano bisseno, o horário de verão e essas variações. Este utilitário adiciona ou subtrai dias, horas e/ou minutos de uma determinada data e produz os resultados no formato especificado. O padrão, se nenhum ajuste for especificado, é ""-1d""

Obviamente, isso faz apenas uma parte do manual, mas vamos ver o que as novas macros significam ... B significa BOLD, e recomendamos que você coloque esse código em um arquivo e teste -o à medida que avança, com o comando Groff acima… P Stands para o parágrafo, porque como você pode ver, após cada .P Há uma nova linha dupla na página formatada. As \ f* são sequências de fuga de mudança de fonte, e o que isso significa é que, após a palavra ""sinopse"" .B diz a Groff para imprimir em negrito. No entanto, após a palavra ""YEST"", que é realmente impressa em negrito, precisamos ""-Help"" para ser impressa com fontes regulares, então é isso que \ fr significa. Por outro lado, \ fb significa ""imprimir em negrito"" e pode ser usado de forma intercambiável com .B . Usando a lógica, você pode entender o que \ fl, por exemplo, significa.

Texto simples, que é um texto que não é um título ou uma seção, está contido em parágrafos. Um parágrafo simples é delimitado por um .Macro pp, que cria um pequeno espaço vertical entre o parágrafo real e o próximo. Se você quiser um parágrafo marcado, pode tê -lo com .Tp . Em seguida, falaremos sobre indentação.

Recomenda relativa significa que o texto é recuado em relação ao texto anterior e seguinte. Para iniciar um pedaço de texto relativamente indevido, use .Rs (início relativo), e para acabar com ele, use .Re (fim relativo). Aqui está um exemplo:

.Rs.7i Se houver espaços ou caracteres especiais na corda, deve ser citado. O programa reconhecerá a maioria das convenções de fuga do tipo \ fBecho \ FR, como ""\\ n"" (newline) e ""\\ t"" (tab) em \ fiformat-string \ fr, e escapes octal (\\ 0nn) são suportadas.

.P Se apenas um ajuste de dia for especificado, o padrão \ fiformat string \ fr é ""%x"". Se \ fiadjustment \ fr incluir um elemento de tempo, o padrão \ fiformat string \ fr se tornará “%x-%r”.

.RÉ

Como você pode ver, você pode ter um .P macro dentro de uma peça de texto relativamente recuada ... P é apenas um pseudônimo para .Pp, para que eles possam ser usados ​​de forma intercambiável. Você pode ter notado o “.7i ”depois .RS: Isso diz a Groff para recuar com sete espaços o texto dentro.

O uso de tabelas é tão simples quanto usar o recuo relativo: .Ts e .Te. Você pode, como dito anteriormente, modificar uma palavra ou um parágrafo inteiro (de um ponto de vista tipográfico, isto é) com macros. As três maneiras pelas quais você pode alterar um personagem são, como todos sabem, ousado, itálico e romano. Então, por exemplo, .Bi altera o texto seguindo -o em que aparecerá ambos audacioso e itálico.

Conclusão

Observe que isso pode ser suficiente para você começar, mas não está completo. Essas não são todas as macros e, se você mudar para um sistema BSD, poderá achar que eles usam Mandoc em vez de Groff, então você terá que aprender sozinho se quiser se tornar proficiente. Em seguida, leia algumas páginas manuais para ver as principais convenções que devem ser respeitadas, como colocar os argumentos opcionais em seu aplicativo (se for o caso) em colchetes ou usando para mostrar que pelo menos um dos argumentos dentro os aparelhos devem ser usados. Em suma, documentar seu software, mesmo que você não seja obrigado pelo seu empregador, é bom para você e os usuários do seu software. Você será considerado um desenvolvedor cuidadoso e os usuários podem usar sua criação mais fácil, sabendo o que podem e o que não podem fazer.

Tutoriais do Linux relacionados:

• Coisas para instalar no Ubuntu 20.04
• Coisas para fazer depois de instalar o Ubuntu 20.04 fossa focal linux
• Como executar instalações Linux sem assistência com o Kickstart
• Como verificar a duração da bateria no Ubuntu
• Coisas para fazer depois de instalar o Ubuntu 22.04 Jellyfish…
• Uma introdução à automação, ferramentas e técnicas do Linux
• Sistema Linux Hung? Como escapar para a linha de comando e…
• Coisas para instalar no Ubuntu 22.04
• Mint 20: Melhor que o Ubuntu e o Microsoft Windows?
• Instale Arch Linux na estação de trabalho VMware