Richtige Methode zum Dokumentieren von Optionen mit variabler Länge in Manpages

Richtige Methode zum Dokumentieren von Optionen mit variabler Länge in Manpages

Manchmal sehe ich Nutzungsinformationen wie

some_utility [arg [arg [...]]]

oder

some_utility [arg[, arg[...]]]

Das bedeutet, dass Sie mehr als ein gleiches Argument übergeben können.

Ich habe es auch gesehen wie

some_utility [args]

oder

some_utility [arg][, arg][...]

Gibt es hierfür eine Standardmethode?

Antwort1

Nein, nichtWirklich, aber meistens ist es ziemlich einheitlich. Die meisten Handbücher listen optionale Argumente in eckigen Klammern ( [foo]), obligatorische Argumente in spitzen Klammern oder gar keine Klammern ( <bar>, baz, letztere oft unterstrichen) auf.

Außerdem erhalten Sie in fast allen Fällen, in denen die Anzahl der Argumente variabel ist, eine Art Liste (wie Sie erwähnt haben, [quux ...]oder [quux[, quux[...]]]...), wobei in ähnlicher Weise [quuz]in den meisten Fällen genaueinsArgument. In seltenen Fällen [quuz]könnte es auch »ein oder mehrere Argumente« bedeuten, aber die meisten Handbücher halten sich an die Auslassungspunkte der Aufzählungsform.

Es ist ein Quasi-Standard, aber man kann sich nicht unbedingt darauf verlassen. Aber meiner Erfahrung nach ist es in 95 % der Fälle in Ordnung.

Der Punkt ist, dass es Hunderte von Softwareanbietern aller Couleur gibt, nicht nur »Big Player«, sondern auch Software, die von einzelnen Personen geschrieben wurde und sich als nützlich erwiesen hat. Alle von ihnen schreiben (hoffentlich) ihre Manpages auf eine individuelle Art und Weise … die meisten von ihnen wissen lange genug Bescheid, um sich an gängige Konventionen zu halten, aber es gibt auch welche, denen das egal ist oder die irgendeine Art von geistigem Defekt in Bezug auf Stil, Geschmack usw. haben ;)

verwandte Informationen