использование <> на странице руководства для указания необязательного пробела - PullRequest
Новая
       41

использование <> на странице руководства для указания необязательного пробела

0 голосов
/ 08 июня 2018

Я поддерживаю старый сценарий оболочки KornShell и его справочную страницу.

Параметры командной строки сценария оболочки включают в себя оба параметра: -w ширина (пробелов нет) и -w ширина (с пробелами), которые имеют тот же эффект.На странице руководства это задокументировано в разделе SYNOPSIS как [ -w <> width ], очевидно, используя <> для обозначения необязательного пробела.

У меня естьНе удалось найти в Интернете другие справочные страницы UNIX или Linux, которые используют для этой цели <>, поэтому я предполагаю, что это не соответствует соглашению, которого ожидают пользователи UNIX или Linux, и поэтому пользователи могут быть сбиты с толку <>на странице руководства.

Какое из следующих представлений на странице руководства наиболее четко показывает, что пробел между -w и ширина является необязательным:

  • [ -w <> ширина ],
  • [ -w [] ширина ] или
  • [ -w ширина | -w ширина ]?

Лучше просто иметь один из [ -w width ] или [ -w width ] в справочной странице, исходя из того, что они делают одно и то же, поэтому пользователь получает небольшую или нулевую добавленную стоимостьдокументально подтвердить, что оба из этих вариантов доступны?

1 Ответ

0 голосов
/ 08 июня 2018

Я бы просто задокументировал -w <i>width</i>, потому что это универсальное соглашение о том, что параметры с аргументами могут принимать аргумент либо в том же аргументе командной строки (-w80), либо в следующем аргументе командной строки (-w 80).

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

...