Чи існує "стандартний" формат для довідкового тексту командного рядка / оболонки?

Якщо ні, чи існує фактичний стандарт? В основному я пишу довідковий текст командного рядка так:

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запустити це повідомлення, і ви повинні показати це повідомлення, якщо користувач переплутає синтаксис командного рядка, наприклад, не вимагає аргументу.

Погляньте на 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>...

Я думаю, що немає стандартного синтаксису для використання командного рядка, але більшість використовують цю конвенцію:

Синтаксис командного рядка 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примітки : nonoption.
• --Аргумент завершує варіанти.
• Цей -параметр зазвичай використовується для подання одного зі стандартних вхідних потоків.

Майкрософт має власну стандартну специфікацію командного рядка :

Цей документ орієнтований на розробників утиліт командного рядка. Наша мета колективно - представити послідовний, компільований досвід користування командним рядком. Досягнення, що дозволяє користувачеві вивчити основний набір понять (синтаксис, іменування, поведінка тощо), а потім змогти перевести ці знання в роботу з великим набором команд. Ці команди повинні мати можливість виводити стандартизовані потоки даних у стандартизованому форматі, щоб забезпечити просту композицію без тягаря розбору потоків вихідного тексту. Цей документ написаний таким чином, щоб він не залежав від конкретної реалізації оболонки, набору утиліт або технологій створення команд; однак додаток J - Використання Windows Powershell для впровадження стандарту командного рядка Microsoft показує, як за допомогою Windows PowerShell безкоштовно забезпечуватиме реалізацію багатьох цих рекомендацій.

Стандарт кодування GNU є хорошим посиланням на такі речі. У цьому розділі йдеться про вихід --help. У цьому випадку це не дуже конкретно. Напевно, ви не можете помилитися, надрукувавши таблицю, де відображаються короткі та довгі варіанти та стислий опис. Спробуйте отримати пробіл між усіма аргументами на користь читабельності. Напевно, ви хочете надати manсторінку (а можливо, і infoпосібник) для свого інструменту, щоб дати більш детальне пояснення.

так, ти на правильному шляху.

так, квадратні дужки - звичайний показник для додаткових предметів.

Як правило, як ви накреслили, вгорі є резюме командного рядка з подальшими деталями, в ідеалі із зразками для кожного варіанту. (У вашому прикладі показано рядки між описом кожного варіанта, але я припускаю, що це проблема редагування, і що ваша реальна програма виводить перелічені опції списків опцій без порожніх рядків між ними. Це було б стандартом, який слід дотримуватися в будь-якому випадку.)

Більш нова тенденція (можливо, існує специфікація POSIX, яка вирішує це?) - це усунення системи підручних сторінок для документації та включення всієї інформації, яка міститиметься у вкладці як частина program --helpвиводу. Цей додатковий опис буде містити більш довгі описи, пояснені поняття, зразки використання, відомі обмеження та помилки, як повідомити про помилку та, можливо, розділ "див. Також" для відповідних команд.

Я сподіваюся, що це допомагає.

Я б брав за приклад офіційні проекти, як смола. На мій погляд, довідка msg. має бути простим і описовим, наскільки це можливо. Приклади використання теж хороші. Немає реальної потреби в «стандартній допомозі».