documentando los parámetros de los scripts de shell

Question

¿Existe una convención para documentar los parámetros de los scripts de shell?

Por ejemplo:

#!/usr/bin/env bash 

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

Un par de cosas que no me gustan de esta plantilla en particular:

• nombre de archivo de la secuencia de comandos (myScript) aparece dentro del propio archivo Descripción
• parámetro parece extraño
• el espacio anterior antes de $ es visualmente útil, pero puede causar confusión en los idiomas con comentarios de bloque, lo que hace que algunas herramientas de validación se quejen de una sangría mixta/inconsistente (p. espacios en este bloque, pestañas para el código - siempre que uno prefiera pestañas, por supuesto)

¿Hay alguna guía al respecto?

Answer 1

yo preferiría escribir:

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

Trate de mirar la forma de ayuda está formateada para utilidades estándar de UNIX (ls --help, por ejemplo)

Answer 2

Recomendaría hacer su secuencia de comandos de impresión de forma automática uso (si no debe hacerse funcionar sin argumentos):

#!/usr/bin/env bash 

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

Answer 3

El Vim bash IDE que hace esto:

#!/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

generalmente envuelvo mi uso en función de lo que se puede llamar desde un parámetro -h etc.

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

EOM 
    exit 0 
} 

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

Answer 5

Tradicionalmente a documentar sus argumentos en la función de uso():

#!/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

Se lo recomiendo el uso de un heredoc:

usage() { 
    cat <<HELP_USAGE 

    $0 [-a] -f <file> 

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

en lugar de:

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

creo que es mucho más limpio que todos estos eco líneas.