Apakah ada standar untuk menulis sinopsis perintah?

Tampak bagi saya bahwa setiap orang memiliki ide mereka sendiri tentang cara menulis sinopsis yang menggambarkan penggunaan perintah untuk pengguna akhir.

Sebagai contoh, ini adalah format dari man grep:

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

Sekarang ini memiliki beberapa sintaks yang muncul di halaman manual lain. []diakui sebagai opsional, dan ...masuk akal sebagai kelipatan dari input yang sama.

Tetapi orang menggunakan |atau /untuk ATAU dan ada orang lain yang akan membalik apa []artinya. Atau mereka tidak memberikan indikasi ke mana harus [OPTIONS]pergi.

Saya ingin mengikuti standar untuk apa yang saya tulis, tetapi setiap situs web yang saya lihat memberi tahu saya sesuatu yang berbeda.

Apakah ada cara standar aktual untuk menulis sinopsis, atau adakah konvensi yang baru saja dilakukan orang dari waktu ke waktu?

command-line man

— Tormyst
sumber

Pilih satu dan pertahankan.

— Kevin

Untuk beberapa alasan saya tidak berpikir itu akan membantu. Setiap orang akan memiliki standar sendiri di sana, dan kemudian tidak ada yang bisa dilakukan tentang hal itu.

— Tormyst

Apakah ini jenis standar yang Anda maksud? pubs.opengroup.org/onlinepubs/009695399/basedefs/…

— Mark Plotnick

Ya, inilah tepatnya yang saya cari. Terima kasih.

— Tormyst

@ MarkPlotnick - Saya akan membuat nilai A sehingga OP dapat menerimanya. Itu standar jika pernah ada. Referensi tautan yang direferensikan oleh illuminÉ.

— slm

Standar klasik untuk ini adalah dari POSIX, Utility Argument Syntax (terima kasih kepada @ illuminÉ untuk tautan yang diperbarui). Ini menjelaskan sintaks yang akan digunakan di halaman manual, misalnya

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

Menjadi klasik, itu merekomendasikan menggunakan opsi satu karakter, dengan -Wdirekomendasikan untuk digunakan oleh vendor, dan itulah bagaimana pilihan multi-karakter ditampung (lihat, misalnya, Ringkasan Opsi gcc ).

Perangkat lunak GNU memperkenalkan opsi multi-karakter yang dimulai dengan --. Beberapa pedoman dari GNU untuk memformat halaman manual dengan opsi-opsi itu dapat ditemukan di referensi help2man .

— Tandai Plotnick
sumber