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

239

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

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

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

shell command-line command-line-arguments Ифань
источник
8
Я думаю, что у GNU есть некоторые намеки. Я бы посмотрел на то, что делает большинство утилит GNU.
Василий Старынкевич,
1
@DanielPryden Я думаю, что ответ на этот вопрос немного вводит в заблуждение. Он дает ссылки, которые объясняют, какие переключатели должны быть приняты, а не как --helpдолжны выглядеть выходные данные . Но оба вопроса - хороший кандидат на слияние.
Пмр
@pmr: Я согласен - возможно, мод может объединить вопросы для нас.
Даниэль Приден
2
Я бы посмотрел на то, что делает большинство утилит GNU, и сделал бы это по-другому.
Яков Галка

Ответы:

160

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

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

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

davetron5000
источник
3
Что если у меня есть две формы одного требуемого аргумента? Например, более стандартный способ сказать: usage: move (+|-)pixelsт.е. когда один из + или - является обязательным ? (Я знаю, что у меня может быть 2 строки использования, но мне нравится идея удваивать их с каждым новым аргументом.) Можете ли вы привести пример из стандартного инструмента?
Алоис Махдал
4
@AloisMahdal я обычно вижу {a|b|c|...}в разделах справки для SysV Init / скриптов выскочка услуг, которые требуют особой аргумент, один из a, b, cи т.д. Например, service sddmбез аргумента в моей системе распечатывает Usage: /etc/init.d/sddm {start|stop|status|restart|try-restart|force-reload}. Поэтому большинство людей, вероятно, поймут usage: move {+|-}pixels}, особенно если дать пример:example: move +5
Брэден Бест
@JorgeBucaran они не должны выходить со статусом 0, не так ли? Я считаю, что выход со статусом 2 является стандартом для недопустимых команд оболочки.
Инавда
91

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

Например...

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>...
Лили Финли
источник
46

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

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

  • Text without brackets or braces

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

  • <Text inside angle brackets>

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

  • [Text inside square brackets]

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

  • {Text inside braces}

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

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

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

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

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

Steely Wing
источник
16

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

  • Вариант дефис следует один алфавитно - цифровой символ, например: -o.
  • Опция может потребовать аргумент (который должен появиться сразу после опции); например,-o argument или -oargument.
  • Параметры, которые не требуют аргументов, могут быть сгруппированы после дефиса, например, -lst эквивалентны -t -l -s.
  • Опции могут появляться в любом порядке; таким образом-lst эквивалентно -tls.
  • Опции могут появляться несколько раз.
  • Опции предшествуют другим неоптимальным аргументам: -lst неопции неопция.
  • --Аргумент завершает варианты.
  • Эта -опция обычно используется для представления одного из стандартных входных потоков.
MotherDawg
источник
2
Как правило, использование в GNU / Linux не соответствует в точности этому стандарту. Run , например , man aptitudeчто выводит этот (среди прочего): aptitude [<options>...] {add-user-tag | remove-user-tag} <tag> <packages>.... Он содержит {и} для связывания альтернативных обязательных команд. Я думаю (и) можно использовать для того же, что и в docopt .
Ярно
Этот ответ будет намного менее полезным, если предоставленная ссылка не работает. Может быть, вы могли бы обобщить важные части связанного документа в самом ответе?
Домсон
11

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

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

Джаред Харли
источник
9
У Microsoft ужасная справка по командной строке для большинства утилит, все настолько ужасно, что они заставили Powershell скрыть «обычную» командную строку под ковром.
Камило Мартин
25
Я не думаю, что ответ должен быть опущен только потому, что он имеет ссылку на стандарт Microsoft. «все так ужасно» - субъективное мнение. Точно так же можно сказать, что командная строка UNIX ужасна и уродлива, но давайте держаться подальше от таких мнений и быть профессионалами.
Дима
2
Согласен, это не то, почему этот ответ должен быть опущен. Если голосование отклонено, это должно произойти из-за того, что a) цитируемый раздел документа не отвечает на поставленный вопрос, и b) документ, на который ссылаются, не имеет значения. Вопрос состоит в том, существуют ли стандарты для «текста справки» с большим акцентом на синтаксис, используемый для передачи синопсисов использования команд. В документе не тух такой синтаксис , а скорее , как построить хорошие приложения командной строки в целом в экосистеме PowerShell (например , должны поддерживать -?, -Help, -Versionи т.д.). Ответ IMO Steely Wing ближе к цели.
Марк Г.
9

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

PMR
источник
0

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

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

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

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

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

shellter
источник
4
Нет нет нет. Команда должна иметь справочную страницу, которая включает в себя полную подробную ссылку на использование, и -h|--helpдолжна быть просто краткой ссылкой. Вы также можете включить более полную документацию (учебные пособия и т. Д.) В HTML или на страницы с информацией. Но man-страница должна быть там!
ниндзяль
Я согласен с вами, @ninjalj, но, как я уже сказал, «новая тенденция», и под этим я подразумеваю две системы, которые я использую, UWin и MinGW, обе со встроенной документацией. Я думаю, что у встроенного документа есть свои места, особенно для небольших сценариев на уровне пользователя, например, предлагаемых этим пользователем. Должен ли он учиться nroff и .info? Но хорошо, чтобы держать нас честными, спасибо за ваши комментарии и удачи всем.
Shellter
Лично, когда я печатаю someCommand --helpв своей оболочке, все, что мне нужно, это маленькое напоминание о точном порядке ввода аргументов, а не гигантская полоса текста, заполняющая экран, требующая, чтобы я перенаправил ее, lessчтобы увидеть все это. Страница руководства должна быть там, где вы поместите длинное подробное описание, а не текст справки.
AJMansfield
по словам создателя docopt на своей конференции, он упоминает, что у POSIX есть норма для этого.
v.oddou
0

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

rluks
источник
Что касается tar... если кто-то собирается сделать универсальную утилиту, такую ​​как tar, пожалуйста, сделайте короткие переключатели запоминающимися и включите раздел "пример использования" в --help. 90% времени я смотрю на инструкции tar для извлечения простого tar.gz.
Камило Мартин
« Нет никакой необходимости в« стандартной помощи ». Есть ли «реальная потребность» в большинстве вещей, которые мы используем? Или они просто делают нашу жизнь намного проще? Наличие согласованного способа представления параметров полезно не только для читателей, но также, например, для людей, которые создают, например, графические интерфейсы, которые могут управлять произвольными утилитами командной строки и хотят предоставить элементы управления для установки своих параметров. Возможно, есть лучшие варианты использования, которые я еще не рассматривал.
underscore_d