Есть ли "стандартный" формат текста командной строки/оболочки?

Если нет, существует ли де-факто стандарт? В основном я пишу текст справки командной строки так:

usage: app_name [options] required_input required_input2
  options:
    -a, --argument     Does something
    -b required     Does something with "required"
    -c, --command required     Something else
    -d [optlistitem1 optlistitem 2 ... ]     Something with list

Я сделал это, просто прочитав текст справки о различных инструментах, но есть ли список рекомендаций или что-то еще? Например, я использую квадратные скобки или круглые скобки? Как использовать интервал? Что, если аргумент - это список? Благодарю!

ОТВЕТЫ

Ответ 1

Как правило, ваш вывод справки должен включать:

  • Описание того, что делает приложение
  • Синтаксис использования, который:
    • Использует [options] чтобы указать, куда идут опции
    • arg_name для требуемого единственного аргумента
    • [arg_name] для необязательного единственного аргумента
    • arg_name... для требуемого аргумента, которых может быть много (это редко)
    • [arg_name...] для аргумента, для которого можно [arg_name...] любое число
    • обратите внимание, что arg_name должно быть описательным, коротким именем, в нижнем регистре, в виде змеи
  • Красиво отформатированный список опций, каждый:
    • иметь краткое описание
    • показывая значение по умолчанию, если оно есть
    • показывая возможные значения, если это применимо
    • Обратите внимание, что если опция может принимать краткую форму (например, -l) или длинную форму (например, --list), --list их вместе в одну строку, так как их описания будут одинаковыми
  • Краткий индикатор расположения конфигурационных файлов или переменных среды, которые могут быть источником аргументов командной строки, например, GREP_OPTS
  • Если есть справочная страница, укажите как таковой, в противном случае краткий индикатор того, где можно найти более подробную помощь

Далее обратите внимание, что это хорошая форма для принятия обоих -h и --help для запуска этого сообщения, и что вы должны показать это сообщение, если пользователь испортил синтаксис команды -l ine, например, пропустил обязательный аргумент.

Ответ 2

Взгляните на docopt. Это формальный стандарт для документирования (и автоматического разбора) аргументов командной строки.

Например...

Usage:
  my_program command --option <argument>
  my_program [<optional-argument>]
  my_program --another-option=<with-argument>
  my_program (--either-that-option | <or-this-argument>)
  my_program <repeating-argument> <repeating-argument>...

Ответ 3

Я думаю, что нет стандартного синтаксиса для использования командной строки, но большинство используют это соглашение:

Синтаксис командной строки Microsoft, IBM имеет аналогичный синтаксис командной строки

  • Text without brackets or braces

    Элементы, которые вы должны ввести, как показано

  • <Text inside angle brackets>

    Заполнитель, для которого вы должны указать значение

  • [Text inside square brackets]

    Дополнительные предметы

  • {Text inside braces}

    Набор необходимых предметов; Выбери один

  • Вертикальная черта {a|b}

    Разделитель для взаимоисключающих предметов; Выбери один

  • Многоточие <file> …

    Предметы, которые можно повторить

Ответ 5

Стандарт кодирования GNU является хорошей ссылкой на такие вещи. Этот раздел посвящен выводу --help. В этом случае это не очень специфично. Вероятно, вы не ошибетесь, распечатав таблицу, показывающую короткие и длинные варианты и краткое описание. Постарайтесь получить расстояние между всеми аргументами для удобства чтения. Вероятно, вы захотите предоставить страницу man (и, возможно, info) для вашего инструмента, чтобы предоставить более подробное объяснение.

Ответ 6

У Microsoft есть своя Стандартная спецификация командной строки:

Этот документ ориентирован на разработчиков утилит командной строки. В совокупности наша цель состоит в том, чтобы представить последовательный, настраиваемый пользовательский интерфейс командной строки. Достижение этого позволяет пользователю изучить основной набор концепций (синтаксис, именование, поведение и т.д.), А затем сможет перевести это знание в работу с большим набором команд. Эти команды должны иметь возможность выводить стандартизированные потоки данных в стандартизованном формате, чтобы обеспечить легкую компоновку без нагрузки на синтаксический анализ потоков выходного текста. Этот документ написан независимо от какой-либо конкретной реализации оболочки, набора утилит или технологий создания команд; однако Приложение J - Использование Windows Powershell для реализации Стандарта командной строки Microsoft показывает, как использование Windows PowerShell будет бесплатно выполнять многие из этих рекомендаций.

Ответ 7

да, вы на правильном пути.

да, квадратные скобки являются обычным индикатором для дополнительных элементов.

Как правило, по мере того, как вы набросали, в верхней части появляется сводка с командной строкой, а затем детали, в идеале с образцами для каждой опции. (В вашем примере показаны строки между описаниями каждого параметра, но я предполагаю, что это проблема редактирования, и что ваша реальная программа выводит отступы с опциями, без пробелов между ними. Это будет стандартом, который следует соблюдать в любом случае.)

Новая тенденция (может быть, есть спецификация POSIX, которая решает это?), является устранение системы справочной страницы для документации и включает всю информацию, которая будет в man-странице как часть вывода program --help. Это дополнительно будет включать более длинные описания, объясненные понятия, примеры использования, известные ограничения и ошибки, как сообщить об ошибке и, возможно, раздел "см. Также" для соответствующих команд.

Надеюсь, это поможет.

Ответ 8

В качестве примера я бы воспользовался официальными проектами, такими как tar. На мой взгляд, помогите msg. должно быть простым и описательным, насколько это возможно. Примеры использования тоже хороши. Нет никакой реальной необходимости в "стандартной помощи".