Как писать заметки об использовании

Мой сценарий можно назвать так:Как писать заметки об использовании

myScript -a some_name 
myScript -a all 
myScript -b some_name 
myScript -b all 
myScript -c

Как я пишу свои заметки об использовании? Я знаю [] средние необязательные аргументы и | означает альтернативный, но в моем случае я должен был бы вложенная альтернатива, что-то вроде:

usage myScript (-a some_name | all) | (-b some_name | all) | -c

Сейчас я не думаю, что я могу использовать () для этой цели, так как иначе я могу написать это? Должен ли я писать его в нескольких строках или есть лучший способ?

myScript -a some_name | all 
myScript -b some_name | all 
myScript -c

Я имею в виду это все равно будет нормально в моем случае, но если у меня было больше вложенных альтернатив было бы получить действительно многословным.

Также есть исчерпывающий источник, описывающий стандартные примечания об использовании unix/linux?

источник

2016-07-18 NPS

Возможный дубликат [Есть ли спецификация раздела SYNOPSIS страницы man?] (Http://stackoverflow.com/questions/8716047/is-there-a-specification-for-a-man-pages-synopsis- раздел) –

Это не тот же вопрос. Несомненно, синтаксис секции SYNOPSIS страницы 'man' похож/аналогичен, но общий макет отличается. Я не хочу создавать страницу «man», просто (и короткие) заметки об использовании, когда пользователь предоставляет неверные аргументы. И, честно говоря, я также хотел бы узнать, есть ли стандартный макет/отступы в примечаниях к использованию. – NPS

Я не подразумевал, что это _same_ вопрос, следовательно, _possible_ duplicate. Речь шла не о главной странице человека, а о (предлагаемом) синтаксисе/обозначении для необязательных, обязательных и т. Д. Параметров. YMMV, конечно. –

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

Если вы хотите, чтобы получить все это в одной строке, вы можете сделать это следующим образом:

myScript ((-a|-b) (some_name|all) | -c)

, но это довольно грязно. Я бы предпочел, чтобы сделать это в два:

myScript (-a|-b) (some_name|all) 
myScript -c

или на самом деле три, как вы должны добавить myScript --help в там.

Если я нахожусь в попытке объяснить клинику программы, я перестаю думать, правильно ли я ее разработал. Есть -a, -b и -c действительно команды, из которых вы можете выбрать только один? Тогда было бы больше смысла, чтобы структурировать вашу программу, как имеющие подкомандами, как мерзавец:

myScript <command> [<args>] 

Commands: 
    a Attach an aardvark. 
    b Belay the border. 
    c Capture the castle.

с Подкоманды имея свой собственный вывод справки:

[$]> myScript a --help 
Usage: 
    myScript a <target> 
    myScript a --help

Использование опций только для дополнительных значений помогает избежать путаницы («Могу ли я запустить myScript -a some_name -b all?»), А разделение API на компоненты уменьшает сложность того, что должен смотреть пользователь.

источник

2016-07-19 21:47:29

Итак, суть в этом - да, я могу использовать круглые скобки для группировки, это правильно? – NPS

Вы можете делать все, что хотите. Тем не менее, пункт использования документации заключается в том, чтобы дать понять пользователям, как использовать вашу программу.Будь то то, что вы написали, придерживается какого-либо конкретного стандарта, это не имеет значения; люди * понимают это *. Помните эту цель, когда вы ее пишете, и помните об этой цели, когда вы тестируете программное обеспечение и видите, как люди его используют. –

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

Как писать заметки об использовании

ответ

Смежные вопросы