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

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

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

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

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

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

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

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

Например...

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

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

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

• Text without brackets or braces

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

• <Text inside angle brackets>

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

• [Text inside square brackets]

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

• {Text inside braces}

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

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

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

• эллипсис <file> …

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

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

• Вариант дефис следует один алфавитно - цифровой символ, например: -o.
• Опция может потребовать аргумент (который должен появиться сразу после опции); например,-o argument или -oargument.
• Параметры, которые не требуют аргументов, могут быть сгруппированы после дефиса, например, -lst эквивалентны -t -l -s.
• Опции могут появляться в любом порядке; таким образом-lst эквивалентно -tls.
• Опции могут появляться несколько раз.
• Опции предшествуют другим неоптимальным аргументам: -lst неопции неопция.
• --Аргумент завершает варианты.
• Эта -опция обычно используется для представления одного из стандартных входных потоков.

Microsoft имеет свою собственную стандартную спецификацию командной строки :

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

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

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

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

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

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

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

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