Readme.txt vs. README.txt

33

Właśnie rozwidliłem projekt w Github, wprowadziłem zmiany itp. To mnie zastanowiło: w projektach typu open source widzę głównie README.txt, a edytowany przeze mnie plik to Readme.txt. Czy to jest jakaś standaryzacja, czy powinienem ją zostawić taką, jaka jest?

Tolga Ozses
źródło
All-caps prawdopodobnie miał swój początek w MS-DOS, wszystkie małe litery prawdopodobnie pochodziły z unixowego dziedzictwa. Nie jestem pewien co do dużej litery pierwszej - być może korzeni Maca. W końcu nie ma to znaczenia, chyba że jest to porządek lub styl.
Lawrence

Odpowiedzi:

29

Wielkie litery wyróżniają się i sprawiają, że plik jest dobrze widoczny, co ma sens, ponieważ jest to prawdopodobnie pierwsza rzecz, na którą nowy użytkownik chciałby spojrzeć. (Lub przynajmniej powinien był spojrzeć na ...) Jak już powiedzieli inni, nazwy plików zaczynające się od dużej litery będą wyświetlane przed małymi literami w sortowaniu ASCIIbetical ( LC_COLLATE=C), co pomaga sprawić, by plik był widoczny na pierwszy rzut oka.

READMEPlik jest częścią pęczek plików użytkownik darmowego pakietu oprogramowania normalnie oczekiwać. Inne to INSTALL(instrukcje budowania i instalowania oprogramowania), AUTHORS(lista współtwórców), COPYING(tekst licencji), HACKING(jak zacząć pisać, może zawierać listę punktów początkowych TODO), NEWS(ostatnie zmiany) lub ChangeLog(głównie zbędne z systemy kontroli wersji).

Oto, co na temat pliku mają do powiedzenia standardy kodowania GNUREADME .

Dystrybucja powinna zawierać plik o nazwie READMEz ogólnym przeglądem pakietu:

  • nazwa paczki;
  • numer wersji pakietu lub wskazać, gdzie w pakiecie można znaleźć wersję;
  • ogólny opis tego, co robi paczka;
  • odniesienie do pliku INSTALL, które z kolei powinno zawierać wyjaśnienie procedury instalacji;
  • krótkie wyjaśnienie wszelkich nietypowych katalogów lub plików najwyższego poziomu, lub inne wskazówki dla czytelników, aby znaleźć drogę do źródła;
  • odwołanie do pliku zawierającego warunki kopiowania. GNU GPL, jeśli jest używana, powinna znajdować się w pliku o nazwie COPYING. Jeśli używana jest GNU LGPL, powinna ona znajdować się w pliku o nazwie COPYING.LESSER.

Ponieważ zawsze warto dążyć do najmniejszej niespodzianki dla użytkowników, należy postępować zgodnie z tą konwencją, chyba że istnieją istotne powody odchylenia. W świecie UNIX rozszerzenia nazw plików były tradycyjnie używane oszczędnie, więc kanoniczna nazwa pliku READMEnie zawiera żadnego przyrostka. Ale większość użytkowników prawdopodobnie nie miałaby problemów ze zrozumieniem, że nazwany plik README.txtma takie samo znaczenie. Jeśli plik jest zapisany w Markdown , nazwa pliku README.mdmoże być również uzasadniona. Unikaj używania bardziej skomplikowanych języków znaczników, takich jak HTML, wREADMEplik, ponieważ powinien być wygodny do czytania na terminalu tekstowym. Możesz wskazać użytkownikom instrukcję oprogramowania lub jego dokumentację online, które mogą być napisane w bardziej wyrafinowanym formacie, w celu uzyskania szczegółowych informacji z READMEpliku.

5gon12eder
źródło
20

Tradycyjnie plik nazywał się README dużymi literami, ponieważ środowiska wiersza poleceń korzystające z porządku alfabetycznego umieszczałyby plik na górze. Dzięki temu są łatwo widoczne w dużych katalogach.

Najprawdopodobniej jest to pozostałość po świecie Unix / Linux, w którym można pobrać źródła, a następnie zbudować oprogramowanie. Posiadanie plików takich jak README i INSTALL na górze widoku „zawartość katalogu listy” ułatwia zobaczenie, że tam są, zamiast przeglądać całą zawartość z poziomu interfejsu wiersza poleceń. Ta sama podstawowa zasada działa również w przypadku github (i faktycznie działa również w interfejsach GUI, przyjdź i pomyśl o tym, aby nadal mieć wartość)

W żadnym wypadku nie jest to twarda zasada, ale bardzo prawdopodobne, że wszyscy robią to jako nawyk, ponieważ robią to inne projekty. O ile nie ma wyraźnego powodu, by tego NIE robić, prawdopodobnie powinieneś używać wszystkich wielkich liter tylko dlatego, że zobaczysz, że jest to używane w wielu innych projektach. Jest to również domyślne nazewnictwo używane przez Github podczas tworzenia nowego repozytorium.

JDT
źródło
Zawsze myślałem, że wielkie litery są formą podkreślenia, podobnie jak to, jak masz litery w języku legalnym.
Lars Viklund,
1
W interfejsie wiersza poleceń pliki, które znajdują się na górze listy, w rzeczywistości są tymi, które najpierw przewijają się z widoku, więc czasami są to najmniej widoczne pliki. Chyba że zawsze robisz coś takiego ls -l | less.
Marc van Leeuwen,
6

Plik README jest zwykle pisany wielkimi literami. W ten sposób lspolecenie uniksowe umieściło plik w pobliżu początku listy katalogów (wielkie litery pojawiają się przed małymi literami w porządku ASCII).

manlio
źródło
3
To był historyczny powód, ale lszwykle nie sortuje się tak w nowoczesnych systemach.
1
@ dan1111 Racja! Dziękuję (tylko spróbuj ... LC_COLLATE="en_US.ascii" ; ls -lvs LC_COLLATE="en_US.UTF-8" ; ls -l)
Manlio