Readme.txt vs. README.txt

33

Ich habe gerade ein Projekt in Github gegabelt, meine Änderungen vorgenommen usw. Das hat mich gefragt: Ich sehe hauptsächlich README.txt in OpenSource-Projekten und die Datei, die ich bearbeitet habe, war Readme.txt. Ist das eine Art von Standardisierung oder hätte ich es so lassen sollen, wie es ist?

Tolga Ozses
quelle
All-Caps hatten wahrscheinlich ihren Anfang in MS-DOS, alle Kleinbuchstaben wahrscheinlich aus dem Unix-Erbe. Ich bin mir nicht sicher über den großgeschriebenen Anfangsbuchstaben - vielleicht Mac-Wurzeln. Am Ende ist es nur eine Frage der Ordnung oder des Stils.
Lawrence

Antworten:

29

Alle Großbuchstaben sind hervorzuheben und machen die Datei leicht sichtbar. Dies ist sinnvoll, da dies wahrscheinlich das erste ist, was ein neuer Benutzer sehen möchte. (Zumindest hätte man sich das ansehen müssen ...) Wie bereits erwähnt, werden Dateinamen, die mit einem Großbuchstaben beginnen, vor den Kleinbuchstaben in ASCIIbetical sorting ( LC_COLLATE=C) aufgeführt, um die Datei auf den ersten Blick sichtbar zu machen.

Die READMEDatei ist Teil einer Reihe von Dateien, die ein Benutzer eines kostenlosen Softwarepakets normalerweise erwarten würde. Andere sind INSTALL(Anweisungen zum Erstellen und Installieren der Software), AUTHORS(Liste der Mitwirkenden), COPYING(Lizenztext), HACKING(Erste Schritte zum Mitwirken, möglicherweise einschließlich einer TODO-Liste der Startpunkte), NEWS(letzte Änderungen) oder ChangeLog(meistens überflüssig mit Versionskontrollsysteme).

Das sagen die GNU Coding Standards über die READMEDatei.

Die Distribution sollte eine Datei READMEmit einem allgemeinen Überblick über das Paket enthalten:

  • den Namen des Pakets;
  • die Versionsnummer des Pakets oder verweisen Sie darauf, wo in dem Paket die Version zu finden ist;
  • eine allgemeine Beschreibung der Funktionsweise des Pakets;
  • einen Verweis auf die Datei INSTALL, die wiederum eine Erläuterung des Installationsvorgangs enthalten sollte;
  • eine kurze Erläuterung ungewöhnlicher Verzeichnisse oder Dateien auf oberster Ebene oder andere Hinweise für den Leser, um sich in der Quelle zurechtzufinden;
  • ein Verweis auf die Datei, die die Kopierbedingungen enthält. Die GNU GPL sollte sich, falls verwendet, in einer Datei mit dem Namen befinden COPYING. Wenn die GNU LGPL verwendet wird, sollte sie sich in einer Datei mit dem Namen befinden COPYING.LESSER.

Da es immer gut ist, die geringste Überraschung Ihrer Benutzer anzustreben, sollten Sie diese Konvention befolgen, es sei denn, es gibt zwingende Gründe für eine Abweichung. In der UNIX-Welt wurden Dateinamenerweiterungen traditionell sparsam verwendet, sodass der kanonische Name der Datei READMEkein Suffix enthält. Aber die meisten Benutzer hätten wahrscheinlich keine Probleme damit, zu verstehen, dass eine Datei mit dem Namen README.txtdieselbe Bedeutung hat. Wenn die Datei in Markdown geschrieben ist , kann ein Dateiname wie README.mdauch sinnvoll sein. Vermeiden Sie die Verwendung komplizierterer Auszeichnungssprachen wie HTML in derREADMEDatei, da es praktisch sein sollte, auf einem Nur-Text-Terminal zu lesen. Sie können Benutzer auf das Handbuch der Software oder deren Online-Dokumentation verweisen, die möglicherweise in einem komplexeren Format verfasst ist, um Details aus der READMEDatei zu erhalten.

5gon12eder
quelle
20

Üblicherweise wurde die Datei in Großbuchstaben als README bezeichnet, da in Befehlszeilenumgebungen, in denen die alphabetische Reihenfolge verwendet wird, die Datei an die erste Stelle gesetzt wird. Dadurch sind sie in großen Verzeichnissen gut sichtbar.

Es ist höchstwahrscheinlich ein Überbleibsel aus der Unix / Linux-Welt, in der Sie Quellen herunterladen und dann Ihre Software erstellen. Wenn Sie Dateien wie README und INSTALL oben in der Ansicht "Listenverzeichnisinhalte" haben, können Sie leichter erkennen, dass sie vorhanden sind, anstatt den gesamten Inhalt über eine Befehlszeilenschnittstelle durchsuchen zu müssen. Dasselbe Grundprinzip funktioniert auch für Github (und tatsächlich auch für GUI-Benutzeroberflächen, denken Sie mal darüber nach, es könnte also immer noch von Nutzen sein).

Auf keinen Fall eine harte Regel, aber sehr wahrscheinlich etwas, das jeder zur Gewohnheit macht, weil andere Projekte es tun. Sofern es keinen ausdrücklichen Grund gibt, NICHT zu verwenden, sollten Sie wahrscheinlich alle Großbuchstaben verwenden, nur weil Sie sehen, dass es in vielen anderen Projekten so verwendet wird. Dies ist auch der Standardname, den Github verwendet, wenn Sie ein neues Repository erstellen.

JDT
quelle
Ich habe immer gedacht, dass Großbuchstaben eine Form der Betonung sind, ähnlich wie Sie Großbuchstaben in legaler Sprache haben.
Lars Viklund
1
Auf einer Befehlszeilenschnittstelle werden die Dateien, die sich oben in der Liste befinden, zuerst aus der Ansicht verschoben. In einigen Fällen handelt es sich also um die am wenigsten sichtbaren Dateien. Es sei denn, Sie machen immer so etwas ls -l | less.
Marc van Leeuwen
6

README wird normalerweise in Großbuchstaben geschrieben. Auf diese Weise platzierte der lsUnix-Befehl die Datei am Anfang der Verzeichnisliste (Großbuchstaben stehen in ASCII-Reihenfolge vor Kleinbuchstaben).

Manlio
quelle
3
Dies war der historische Grund, aber lsbei modernen Systemen ist dies normalerweise nicht der Fall.
1
@ dan1111 Richtig! Vielen Dank (nur um zu versuchen ... LC_COLLATE="en_US.ascii" ; ls -lvs LC_COLLATE="en_US.UTF-8" ; ls -l)
Manlio