Czy istnieje standard pisania streszczenia poleceń?

14

Wydaje mi się, że każdy ma własny pomysł na napisanie streszczenia opisującego użycie polecenia dla użytkownika końcowego.

Na przykład jest to format z man grep:

grep [OPTIONS] PATTERN [FILE...]
grep [OPTIONS] [-e PATTERN | -f FILE] [FILE...]

Teraz ma pewną składnię, która pojawia się na innych stronach. []jest rozpoznawany jako opcjonalny i ...ma sens jako wielokrotność tego samego wejścia.

Ale ludzie używają |lub /dla OR, i są inni, którzy odwrócą to, co []znaczy. Lub nie dają żadnych wskazówek, dokąd [OPTIONS]idzie.

Chciałbym przestrzegać tego, co piszę, ale każda witryna, na którą patrzę, mówi mi coś innego.

Czy istnieje rzeczywisty standardowy sposób pisania streszczeń, czy też konwencja jest po prostu tym, co ludzie robili z czasem?

command-line man Tormyst
źródło
Wybierz jeden i trzymaj się go.
Kevin
Z jakiegoś powodu nie sądzę, żeby to pomogło. Każda osoba miałaby swój własny standard, a wtedy nic się z tym nie zrobiłoby.
Tormyst
4
Czy masz na myśli ten standard? pubs.opengroup.org/onlinepubs/009695399/basedefs/…
Mark Plotnick
Tak, dokładnie tego szukałem. Dziękuję Ci.
Tormyst
1
@MarkPlotnick - Zrobiłbym to A, aby OP mógł je zaakceptować. To standard, jeśli w ogóle taki był. Odwołaj się do linku, do którego odwołuje się oświetlenie
slm

Odpowiedzi:

8

Klasycznym standardem tego jest POSIX, Utility Argument Syntax (dzięki @ illuminÉ za zaktualizowany link). Opisuje na przykład składnię, która ma być używana na stronach podręcznika

utility_name[-a][-b][-c option_argument]
    [-d|-e][-f[option_argument]][operand...]

Będąc klasycznym, zaleca stosowanie opcji jednoznakowych, -Wzalecanych przez dostawców, i w ten sposób uwzględniane są opcje wieloznakowe (patrz na przykład Podsumowanie opcji gcc ).

Oprogramowanie GNU wprowadziło wieloznakowe opcje, które zaczynają się od --. Niektóre wytyczne GNU dotyczące formatowania stron podręcznika przy użyciu tych opcji można znaleźć w dokumentacji help2man .

Mark Plotnick
źródło