☰

Bash 脚本：帮助文件位于脚本内还是位于不同的文件中？

tag-icon • tag-icon bash shell-script scripting
Bash 脚本：帮助文件位于脚本内还是位于不同的文件中？

我正在编写一个脚本，最终目标是成为一个功能齐全的程序。据我所知，BASH 足以满足他的目的（管理 PPA，有点像 Y-PPA）。我想知道如何输出帮助myscript --help。

目前，帮助是echo -e直接在脚本内编写的，并使用 a 调用if [ "$1" == "--help" ] || [ "$1" == "-h" ]（我计划很快将其切换为 getopts）。

但什么更好呢？将该help部分留在脚本中还是只编写一行来调用另一个包含帮助的文件？

在我看来，将其留在脚本中可能会更好，因为：

  • 我的程序仍将是一个文本文件脚本
  • 它节省了硬盘空间
  • 它可以避免显示另一个可能已损坏或位于不同位置的文件时出现错误

但是使用包含帮助的不同文本文件也可能会更好，因为：

  • 用命令调用的主脚本myscript会更轻
  • 它简化了脚本的人类阅读
  • 如果需要，它允许单独更新帮助页面
  • 它甚至可以只允许使用 GUI 显示帮助页面，和/或打印它。

所以你看，我不知道这样做的“通常”方式是什么。谢谢 ！

PS：另请注意，由于我计划发布一个完整的程序，因此手册页会很棒，所以我无论如何都必须提供超过 1 个文件，也许只是一个 .deb

答案1

我同意 Ouki 的观点，即暂时保持简单并在脚本内进行。当您决定需要一个手册页时，您可以移植到那里并留下简化的帮助。

检查此方法与单独文件相比的 4 个缺点中的 3 个：

  • 使用 myscript 命令调用的主脚本会更轻

    加载到内存中的字节数微不足道——微不足道，以至于懒得去思考。

  • 它简化了脚本的人类阅读

    如果您组织得很好，则情况恰恰相反，因为源代码中的帮助是代码本身的一种文档形式（见下文）。

  • 它甚至可以只允许使用 GUI 显示帮助页面，和/或打印它。

    Unix 风格系统对模块化的强调意味着您最好不要关心这一点。如果您的脚本写入标准输出，用户就可以将其与他/她喜欢的打印和显示工具结合起来。没有什么比努力实现不必要的功能（例如，作者查看文档的首选方式）的程序更烦人的了。不要那样做。如果是前台命令行工具，你的正常输出应该到标准输出流，错误到标准错误流。别发疯。

如果您不知道“这里”文件，这可以简化您的任务并使源代码更整洁且更具可读性：

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

请注意，有一个为帮助选项调用的函数，它可以保持if块整洁。这也意味着您可以将该功能在顶部，使其成为对来源本身的明显引用形式。

您可以在 中缩进此处的文档myHelp()，顺便说一句 - 制表符将被忽略，但空格将被保留。我在这里这样做是为了防止剪切和粘贴产生任何令人困惑的结果。

答案2

我在这里看到的两种方法更多：

  • 设置内联部分或类POD显示为帮助的文档，或者
  • 正确定义.man要添加到本地man结构的文件

老实说，我不认为拥有一个单独的文件来提供此类帮助有什么意义，除非您有一个非常大的工具并且界面/GUI 已经位于不同的文件中。

所以留下来”干净利落"：有关命令行前端的所有内容都在一个文件中。

您仍然可以将其组织为一块内联文本或正确定义的函数，其唯一目的是显示帮助。所以，对于 10 年后维护你的脚本的可怜人来说，这并不是什么坏事。

相关内容