che documenta i parametri degli script di shell

Question

Esiste una convenzione per documentare i parametri degli script di shell?

Ad esempio:

#!/usr/bin/env bash 

# <description> 
# 
# Usage: 
# $ ./myScript param1 [param2] 
# * param1: <description> 
# * param2: <description> 

Un paio di cose che non mi piacciono di questo particolare modello:

• nome del file dello script (myScript) appare all'interno del file stesso descrizione
• parametro sembra strano
• lo spazio iniziale prima di $ è visivamente utile, ma può portare a confusione nelle lingue con commenti di blocco, causando alcuni strumenti di convalida per lamentarsi di indentazione mista/incongruente (ad es. spazi in questo blocco, schede per codice - purché uno preferisca schede, ovviamente)

Ci sono delle linee guida su questo?

Answer 1

avrei preferito scrivere:

Usage: `basename $0` [option1]|[option2] param1 
    Options: 
    - option1: ..... 
    - option2: ..... 
    Parameters: 
    - param1: ..... 

provare a guardare il modo in cui l'aiuto è formattato per utilità standard UNIX (ls --help, per esempio)

Answer 2

Consiglierei di effettuare automaticamente lo script di stampa utilizzo (se non dovrebbe essere eseguito senza argomenti):

#!/usr/bin/env bash 

if [ ${#@} == 0 ]; then 
    echo "Usage: $0 param1 [param2]" 
    echo "* param1: <description>" 
    echo "* param2: <description>" 
fi 

Answer 3

Il Vim bash IDE che fa questo:

#!/bin/bash 
#=============================================================================== 
# 
#   FILE: test.sh 
# 
#   USAGE: ./test.sh 
# 
# DESCRIPTION: 
# 
#  OPTIONS: --- 
# REQUIREMENTS: --- 
#   BUGS: --- 
#   NOTES: --- 
#  AUTHOR: Joe Brockmeier, jzb@zonker.net 
#  COMPANY: Dissociated Press 
#  VERSION: 1.0 
#  CREATED: 05/25/2007 10:31:01 PM MDT 
#  REVISION: --- 
#=============================================================================== 

Answer 4

solito avvolgere il mio utilizzo in funzione, in modo che posso chiamare da un -h param ecc

#!/bin/bash 
usage() { 
    cat <<EOM 
    Usage: 
    $(basename $0) Explain options here 

EOM 
    exit 0 
} 

[ -z $1 ] && { usage; } 

Answer 5

Tradizionalmente documentare i vostri argomenti nella funzione di utilizzo():

#!/bin/bash 

programname=$0 

function usage { 
    echo "usage: $programname [-abch] [-f infile] [-o outfile]" 
    echo " -a  turn on feature a" 
    echo " -b  turn on feature b" 
    echo " -c  turn on feature c" 
    echo " -h  display help" 
    echo " -f infile specify input file infile" 
    echo " -o outfile specify output file outfile" 
    exit 1 
} 

usage 

Answer 6

io lo consiglio con un heredoc:

usage() { 
    cat <<HELP_USAGE 

    $0 [-a] -f <file> 

    -a All the instances. 
    -f File to write all the log lines 
HELP_USAGE 
} 

invece di:

echo "$0 [-a] -f <file>" 
echo 
echo "-a All the instances." 
echo "-f File to write all the log lines." 

ritengo sia modo più pulito di tutti questi eco linee.