Существует ли «стандартный» формат для текста справки командной строки / оболочки?

Question

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

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

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

Answer 1

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

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

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

Answer 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>...

Answer 3

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

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

---

• Text without brackets or braces

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

• <Text inside angle brackets>

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

• [Text inside square brackets]

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

• {Text inside braces}

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

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

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

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

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

Answer 4

Мы используем Linux, в основном POSIX-совместимую ОС.Стандарты POSIX должны быть такими: Синтаксис служебного аргумента .

Answer 5

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

Answer 6

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

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

Answer 7

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

Answer 8

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

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

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

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

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