Como incorporar documentação em scripts Bash

Documentar como um aplicativo funciona, sua finalidade e seu uso pretendido é muito importante, mesmo que estejamos falando apenas de um simples script de shell. Para facilitar a manutenção do código nos casos mais básicos, a documentação pode ser incorporada diretamente nos scripts. Neste tutorial, aprendemos como incluir a sintaxe Plain Old Documentation (POD) do Pearl em scripts bash e como convertê-la para vários formatos usando utilitários pod2, como pod2man e pod2html.

Neste tutorial você aprenderá:

• Como incorporar documentação formatada em POD em scripts Bash usando Heredoc e construções do-nothing
• Como converter a documentação POD em vários formatos usando utilitários pod2

As construções Heredoc e não fazer nada

Para incorporar documentação dentro de scripts Bash podemos fazer uso de duas construções: “Heredoc” e “do-nothing”. O primeiro permite passar uma entrada multilinha para um comando específico. Ele pode ser usado, por exemplo, para imprimir uma mensagem multilinha na saída padrão, sem repetir um comando echo diversas vezes. Em vez de escrever:

echo "Script usage:"
echo "  myscript [options] argument"
echo ""
echo "Options:"
echo "  -h, --help Show this message"
echo "  -f, --foo This option does foo"
echo "  -b, --bar This option does bar"

Nós escreveríamos:

cat << EOF
Script usage:
  myscript [options] argument

Options:
  -h, --help Show this message
  -f, --foo This option does foo
  -b, --bar This option does bar
EOF

O segundo trecho, como você pode ver, é muito mais limpo (e mais rápido de digitar). A sintaxe de uma construção “Heredoc ” é bastante simples: à esquerda do operador << escrevemos o comando para o qual queremos passar a entrada multilinha; à direita do operador, em vez disso, passamos um delimitador, (EOF é frequentemente usado, mas é apenas um padrão), que marca o fim do Heredoc. Se o delimitador estiver sem aspas, as variáveis dentro do documento serão expandidas.

Podemos usar a construção “Heredoc” para incorporar documentação em um script Bash. Em tal situação, entretanto, não queremos executar nenhum comando: é aqui que a construção “não fazer nada” entra em ação.

No Bash, : é um comando Null: ele não faz nada e sempre sai com sucesso (seu status de existência é sempre 0). Usando as duas construções juntas, podemos incorporar documentação em scripts shell, da seguinte maneira:

#!/bin/bash
#
# Bash code goes here
#
exit 0

: << EOF
Script usage:
  myscript [options] argument

Options:
  -h, --help Show this message
  -f, --foo This option does foo
  -b, --bar This option does bar

EOF

Observe que adicionei explicitamente uma instrução exit 0  logo antes da seção de documentação: isso evita que o shell processe essa parte quando o script é executado.

Usando o formato Plain Old Documentation do Perl

Nos exemplos acima, a documentação do script consistia apenas em texto simples. Para produzir documentos bem formatados, entretanto, podemos usar o formato Plain Old Documentation (POD) do Perl. Aqui está um exemplo que usa um conjunto mínimo de comandos:

: << EOF
=pod

=head1 NAME

Here is a brief description of what are script does.

=head1 SYNOPSYS

scriptname [options] argument

=head1 OPTIONS

-h, --help 
    Show this message
        
-f, --foo
    This option does foo
        
-b, --bar 
    This option does bar

=cut

EOF

O primeiro “parágrafo de comando” que usamos no exemplo é =pod. Apenas sinaliza o início do documento POD. Neste caso é supérfluo, pois qualquer comando inicia o bloco do documento; pode ser útil, entretanto, quando a documentação deve começar com texto comum. Em seguida, usamos =head1, que produz um título de nível 1 (os níveis vão de 1 a 6). Finalmente, usamos =cut, que sinaliza o fimde um bloco POD. Uma linha em branco deve preceder o comando e outra deve segui-lo.

Extraindo e gerando documentação com programas pod2

Assim que terminarmos de descrever as funcionalidades do nosso script, podemos usar os utilitários “pod2” para gerar vários tipos de documentos como um roff ou páginas HTML, que são legíveis, com o utilitário “man” e com qualquer navegador web, respectivamente.

No Archlinux e no Debian, os utilitários pod2 fazem parte do pacote “perl”, que já deve estar instalado em seu sistema. No entanto, para instalar explicitamente o pacote na distribuição anterior, podemos executar:

$ sudo pacman -S perl

Neste último, em vez disso, usamos apt:

$ sudo apt install perl

No Fedora e em outras distribuições baseadas nele, os utilitários pod2 são fornecidos em pacotes separados. O pacote “perl-podlators” inclui pod2man, enquanto  “perl-Pod-Html” fornece pod2html. Podemos instalá-los usando dnf:

$ sudo dnf install perl-podlators perl-Pod-Html

Para gerar uma página roff, invocamos pod2man e passamos o caminho do script como argumento, depois redirecionamos o utilitário stdout para um arquivo:

$ pod2man testscript.sh > testscript.1

Podemos ler o documento executando:

$ man ./testscript.1

Para disponibilizar a página em todo o sistema, para que possamos lê-la sem fornecer o caminho completo, podemos copiá-la para o diretório /usr/share/man/man1 .

Para gerar a versão HTML do documento, usamos pod2html:

$ pod2html testscript.sh > testscript.html

Conclusões

Neste tutorial, aprendemos como incorporar documentação em scripts Bash usando construções “Heredoc” e “do-nothing”. Vimos como usar a sintaxe Plain Old Documentation do Perl e como gerar páginas formatadas em roff e HTML com base nela, usando os utilitários pod2man e pod2html.