Script Bash: arquivo de ajuda dentro do script ou em um arquivo diferente?

Question

Estou escrevendo um roteiro que tem a vocação de ser um programa completo no final. Tanto quanto sei, BASH é suficiente para o seu propósito (gerenciar PPA's, tipo Y-PPA). Gostaria de saber como gerar a ajuda myscript --help .

Atualmente, a ajuda é escrita com echo -e diretamente no script e chamada com if [ "$1" == "--help" ] || [ "$1" == "-h" ] (planejo mudar isso para getopts em breve).

Mas o que é melhor? Para deixar a seção help dentro do script ou apenas escrever uma linha para chamar outro arquivo contendo a ajuda?

Na minha opinião, deixá-lo dentro do script pode ser melhor porque:

• Meu programa continuará sendo um script de arquivo de texto
• Economiza espaço no disco rígido
• Evita ter um erro ao exibir outro arquivo que pode estar corrompido ou em um local diferente

Mas ter um arquivo de texto diferente contendo a ajuda também pode ser melhor porque:

• O script principal chamado com o comando myscript seria mais claro
• Simplifica a leitura humana do script
• Permite atualizar a página de ajuda separadamente, se necessário
• Poderia até mesmo permitir exibir apenas a página de ajuda com uma GUI e / ou imprimi-la.

Então você vê, eu não sei qual é a maneira "usual" de fazer isso. Obrigado !

PS: por favor, note também que desde que eu estou planejando lançar um programa completo, um man-page seria ótimo então eu teria que fornecer mais de 1 arquivo, talvez simplesmente um .deb

    

Answer 1

As duas abordagens que vejo aqui são mais:

• definir uma seção inline ou uma documentação semelhante ao POD para exibir como ajuda ou
• definindo corretamente um arquivo .man para adicionar ao seu local man structure

Eu sinceramente não vejo o ponto de ter um arquivo separado para esse tipo de ajuda, a menos que você tenha uma ferramenta muito grande e a interface / GUI já esteja em arquivo (s) diferente (s).

Portanto, fique " simples e simples ": tudo em um arquivo relacionado ao seu front-end de linha de comando.

Você ainda pode organizá-lo como um bloco de texto embutido ou função adequadamente definida cujo único objetivo é exibir a ajuda. Então, nada de mal feito ao pobre rapaz que manterá seu roteiro em 10 anos.

    

Answer 2

Eu concordo com o Ouki em relação a mantê-lo simples e dentro do script por enquanto. Quando e se você decidir que quer uma página man, você pode transplantar para lá e deixar uma ajuda simplificada.

Examinando 3 de 4 das suas desvantagens para essa abordagem em comparação com um arquivo separado:

• The main script called with myscript command would be lighter

  Haveria um número trivial de bytes carregados na memória - tão trivial que seria bobagem pensar em fazer isso.

• It simplifies the human-reading of the script

  Se você é bem organizado, o oposto é verdadeiro, já que ter essa ajuda na fonte é uma forma de documentação para o próprio código (veja abaixo).

• It could even allow to display only the help page with a GUI, and/or print it.

  A ênfase na modularidade em sistemas de estilo unix significa que você é melhor não se preocupar com isso. Se o seu script grava na saída padrão, o usuário é capaz de combinar isso com quaisquer ferramentas que ele / ela preferir em relação à impressão e exibição. Existem algumas coisas mais irritantes do que os programas que se esforçam para implementar recursos desnecessários que reflitam, por exemplo, os meios preferidos do autor de visualizar a documentação. Não faça isso. Se for uma ferramenta de linha de comando em primeiro plano, sua saída normal deve ser o fluxo de saída padrão e o erro para o fluxo de erro padrão. Não fique maluco.

Se você não tem conhecimento dos documentos "aqui" , isso pode simplificar a tarefa para você e mantenha a fonte mais clara e mais legível:

#!/bin/bash

function myHelp () {
# Using a here doc with standard out.
cat <<-END
Usage:
------
   -h | --help
     Display this help
   -n
     Do nothing loudly.
END
}

doNothing=0;
while [ -n "$1" ]; do
    case "$1" in
        -h | --help)
            myHelp
            exit
            ;;
        -n)
            doNothing=1;
            shift
            ;;
    esac 
done 

if [ $doNothing -gt 0 ]; then
    echo -e "****\nDoing nothing!\n****"
fi        

Observe que há uma função chamada para a opção de ajuda, que mantém o if block arrumado. Isso também significa que você pode colocar essa função no topo , tornando-a uma forma óbvia de referência à própria fonte.

Você pode recuar o documento aqui em myHelp() , BTW - as guias são ignoradas, mas os espaços são preservados. Eu fiz isso dessa forma aqui para evitar qualquer resultado confuso de cortar e colar.