документирование параметров скриптов оболочки

Question

Есть ли соглашение для документирования параметров сценариев оболочки?

Например:

#!/usr/bin/env bash 

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

Несколько вещей, которые я не люблю об этом конкретном шаблоне:

• имени файла скрипта (myScript) появляется в пределах самого файла описание
• параметра кажется странным
• Ведущее пространство до $ визуально полезно, но может привести к путанице в langua ges с комментариями блоков, заставляя некоторые инструменты проверки жаловаться на смешение/несогласованность отступов (например, пробелы в этом блоке, вкладки для кода - если один предпочитает вкладки, конечно)

Есть ли какие-либо рекомендации по этому вопросу?

Answer 1

Я предпочел бы написать:

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

Попробуйте посмотреть на то, как помощь отформатирован для стандартных утилит UNIX (LS --help, например)

Answer 2

Я рекомендовал бы сделать сценарий автоматически печати использование (если он не должен быть запущен без аргументов):

#!/usr/bin/env bash 

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

Answer 3

Vim bash IDE, что делает это:

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

Я обычно обернуть использование в функции, так что я могу назвать это от -h парам и т.д.

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

EOM 
    exit 0 
} 

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

Answer 5

Традиционно документировать свои аргументы в использовании() функция:

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

я рекомендую используя Heredoc:

usage() { 
    cat <<HELP_USAGE 

    $0 [-a] -f <file> 

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

вместо:

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

Я думаю, что это путь чище, чем все эти эхо линии.