Readme.txt vs. README.txt


33

Saya baru saja bercabang proyek di Github, membuat perubahan saya dll. Ini membuat saya bertanya-tanya: Saya melihat sebagian besar README.txt dalam proyek opensource dan file yang saya edit adalah Readme.txt. Apakah ini semacam standar atau haruskah saya membiarkannya?


All-caps mungkin memiliki permulaan dalam MS-DOS, semua huruf kecil mungkin dari warisan unix. Tidak yakin tentang huruf pertama dengan huruf besar - akar Mac, mungkin. Pada akhirnya, itu tidak terlalu penting kecuali sebagai masalah kerapian atau gaya.
Lawrence

Jawaban:


29

Huruf besar semua menonjol dan membuat file mudah terlihat yang masuk akal karena mungkin hal pertama yang ingin dilihat pengguna baru. (Atau, setidaknya, harus melihat ...) Seperti yang telah dikatakan orang lain, nama file yang dimulai dengan huruf kapital akan didaftar sebelum nama huruf kecil dalam ASCII penyortiran klinis ( LC_COLLATE=C) yang membantu membuat file terlihat pada pandangan pertama.

The READMEfile bagian dari sekelompok file pengguna dari paket perangkat lunak bebas biasanya akan berharap untuk menemukan. Lainnya adalah INSTALL(instruksi untuk membangun dan menginstal perangkat lunak), AUTHORS(daftar kontributor), COPYING(teks lisensi), HACKING(cara memulai untuk berkontribusi, mungkin termasuk daftar titik awal TODO), NEWS(perubahan terbaru) atau ChangeLog(kebanyakan berlebihan dengan sistem kontrol versi).

Inilah yang dikatakan Standar Pengkodean GNU tentang READMEfile tersebut.

Distribusi harus berisi file bernama READMEdengan gambaran umum paket:

  • nama paket;
  • nomor versi paket, atau lihat di mana dalam paket versi dapat ditemukan;
  • gambaran umum tentang apa yang dilakukan paket;
  • referensi ke file INSTALL, yang pada gilirannya harus berisi penjelasan tentang prosedur instalasi;
  • penjelasan singkat tentang direktori atau file tingkat atas yang tidak biasa, atau petunjuk lain bagi pembaca untuk menemukan jalan mereka di sekitar sumber;
  • referensi ke file yang berisi kondisi penyalinan. GNU GPL, jika digunakan, harus dalam file bernama COPYING. Jika GNU LGPL digunakan, itu harus dalam file bernama COPYING.LESSER.

Karena selalu baik untuk mengusahakan yang paling mengejutkan pengguna Anda, Anda harus mengikuti konvensi ini kecuali ada alasan kuat untuk penyimpangan. Di dunia UNIX, ekstensi nama file secara tradisional digunakan hemat sehingga nama kanonik file READMEtanpa akhiran. Tetapi sebagian besar pengguna mungkin tidak akan kesulitan memahami bahwa file bernama README.txtmemiliki arti yang sama. Jika file ditulis dalam penurunan harga , nama file seperti README.mdmungkin juga masuk akal. Hindari menggunakan bahasa markup yang lebih rumit seperti HTML diREADMEfile, bagaimanapun, karena itu akan nyaman untuk dibaca pada terminal teks saja. Anda dapat mengarahkan pengguna ke manual perangkat lunak atau dokumentasi on-line-nya, yang mungkin ditulis dalam format yang lebih canggih, untuk detail dari READMEfile.


20

Secara tradisional file itu disebut README dalam huruf besar karena lingkungan baris perintah yang menggunakan pemesanan alfabet kemudian akan meletakkan file di atas. Ini membuatnya mudah terlihat di direktori besar.

Kemungkinan besar peninggalan dari dunia Unix / Linux tempat Anda mengunduh sumber dan kemudian membangun perangkat lunak Anda. Memiliki file seperti README dan INSTALL di bagian atas tampilan 'daftar direktori konten' Anda membuatnya lebih mudah untuk melihat bahwa mereka ada di sana, daripada harus menelusuri seluruh konten dari antarmuka baris perintah. Prinsip dasar yang sama juga berfungsi untuk github (dan sebenarnya bekerja di antarmuka GUI juga, kalau dipikir-pikir, sehingga mungkin masih memiliki kemampuan)

Tidak mungkin aturan yang keras, tetapi sangat mungkin sesuatu yang dilakukan semua orang sebagai kebiasaan karena proyek lain melakukannya. Kecuali ada alasan eksplisit TIDAK untuk melakukannya, Anda mungkin harus menggunakan semua huruf besar hanya karena Anda akan melihatnya digunakan dalam banyak proyek lain. Itu juga penamaan default yang digunakan Github ketika Anda membuat repositori baru.


Saya selalu berpikir bahwa huruf besar semua adalah bentuk penekanan, seperti bagaimana Anda memiliki bagian huruf besar dalam legalese.
Lars Viklund

1
Pada antarmuka baris perintah, file yang masuk ke bagian atas daftar sebenarnya adalah file yang gulir keluar dari tampilan pertama, jadi kadang-kadang ini adalah file yang paling tidak terlihat. Kecuali jika Anda selalu melakukan sesuatu seperti ls -l | less.
Marc van Leeuwen

6

README biasanya ditulis dalam huruf besar. Dengan cara ini lsperintah Unix meletakkan file di dekat awal daftar direktori (huruf besar datang sebelum huruf kecil dalam urutan ASCII).


3
Ini adalah alasan historis, tetapi lsbiasanya tidak seperti itu pada sistem modern.

1
@ dan1111 Benar! Terima kasih (hanya untuk mencoba ... LC_COLLATE="en_US.ascii" ; ls -lvs LC_COLLATE="en_US.UTF-8" ; ls -l)
manlio
Dengan menggunakan situs kami, Anda mengakui telah membaca dan memahami Kebijakan Cookie dan Kebijakan Privasi kami.
Licensed under cc by-sa 3.0 with attribution required.