Readme.txt contre README.txt


33

Je viens de bifurquer un projet dans Github, j'ai fait mes changements, etc. Cela m'a fait me demander: je vois surtout README.txt dans les projets open source et le fichier que j'ai édité était Readme.txt. Est-ce une sorte de standardisation ou aurais-je dû le laisser tel quel?


Tout en majuscules a probablement fait ses débuts en MS-DOS, tous en minuscules probablement de l'héritage Unix. Pas sûr de la première lettre en majuscule - Racines Mac, peut-être. En fin de compte, cela n'a pas vraiment d'importance, sauf pour une question d'ordre ou de style.
Lawrence

Réponses:


29

Les lettres tout en majuscules ressortent et rendent le fichier facilement visible, ce qui est logique car c'est probablement la première chose qu'un nouvel utilisateur voudrait regarder. (Ou, au moins, aurait dû regarder ...) Comme d'autres l'ont déjà dit, les noms de fichiers commençant par une majuscule seront répertoriés avant les noms en minuscules dans le tri ASCIIbétique ( LC_COLLATE=C), ce qui permet de rendre le fichier visible au premier coup d'œil.

Le READMEfichier fait partie d'un ensemble de fichiers qu'un utilisateur d'un progiciel gratuit s'attendrait normalement à trouver. D'autres sont INSTALL(instructions pour la construction et l'installation du logiciel), AUTHORS(liste des contributeurs), COPYING(texte de la licence), HACKING(comment commencer à contribuer, peut-être en incluant une liste TODO de points de départ), NEWS(changements récents) ou ChangeLog(principalement redondant avec systèmes de contrôle de version).

C'est ce que les normes de codage GNU ont à dire sur le READMEfichier.

La distribution doit contenir un fichier nommé READMEavec un aperçu général du package:

  • le nom du colis;
  • le numéro de version du package, ou indiquez où se trouve la version dans le package;
  • une description générale de ce que fait le paquet;
  • une référence au fichier INSTALL, qui doit à son tour contenir une explication de la procédure d'installation;
  • une brève explication de tous les répertoires ou fichiers de niveau supérieur inhabituels, ou d'autres conseils pour que les lecteurs trouvent leur chemin dans la source;
  • une référence au fichier contenant les conditions de copie. La GNU GPL, si elle est utilisée, devrait se trouver dans un fichier appelé COPYING. Si la GNU LGPL est utilisée, elle devrait se trouver dans un fichier appelé COPYING.LESSER.

Puisqu'il est toujours bon de viser la moindre surprise de vos utilisateurs, vous devez suivre cette convention, sauf s'il existe des raisons impérieuses pour un écart. Dans le monde UNIX, les extensions de nom de fichier étaient traditionnellement utilisées avec parcimonie, de sorte que le nom canonique du fichier est READMEsans suffixe. Mais la plupart des utilisateurs n'auraient probablement aucun problème à comprendre qu'un fichier nommé README.txta la même signification. Si le fichier est écrit en Markdown , un nom de fichier comme README.mdpeut également être raisonnable. Évitez d'utiliser des langages de balisage plus complexes comme HTML dans leREADMEfichier, car il devrait être pratique de lire sur un terminal texte uniquement. Vous pouvez diriger les utilisateurs vers le manuel du logiciel ou sa documentation en ligne, qui peut être écrit dans un format plus sophistiqué, pour plus de détails sur le READMEfichier.


20

Traditionnellement, le fichier était appelé LISEZMOI en majuscules, car les environnements de ligne de commande qui utilisent un ordre alphabétique plaçaient alors le fichier en haut. Cela les rend facilement visibles dans les grands répertoires.

C'est très probablement une séquelle du monde Unix / Linux où vous téléchargeriez des sources et ensuite créeriez votre logiciel. Le fait d'avoir des fichiers comme README et INSTALL en haut de la vue 'list directory contents' permet de voir plus facilement qu'ils sont là, au lieu d'avoir à parcourir tout le contenu à partir d'une interface de ligne de commande. Le même principe de base fonctionne également pour github (et fonctionne également dans les interfaces GUI, pensez-y, donc il pourrait toujours avoir du mérite)

En aucun cas une règle stricte, mais très probablement quelque chose que tout le monde fait comme une habitude parce que d'autres projets le font. À moins qu'il n'y ait une raison explicite de NE PAS le faire, vous devriez probablement utiliser toutes les majuscules simplement parce que vous verrez qu'il est utilisé de cette façon dans de nombreux autres projets. C'est également le nom par défaut que Github utilise lorsque vous créez un nouveau référentiel.


J'ai toujours pensé que les majuscules étaient une forme d'accentuation, un peu comme la façon dont vous avez les sections de majuscules en jargon juridique.
Lars Viklund

1
Sur une interface de ligne de commande, les fichiers qui vont en haut de la liste sont en fait ceux qui défilent en premier, donc ce sont parfois les fichiers les moins visibles. Sauf si vous faites toujours quelque chose comme ça ls -l | less.
Marc van Leeuwen

6

README est généralement écrit en majuscules. De cette façon, la lscommande Unix a placé le fichier près du début de la liste des répertoires (les lettres majuscules précèdent les lettres minuscules dans l'ordre ASCII).


3
C'était la raison historique, mais lsne trie généralement pas de cette façon sur les systèmes modernes.

1
@ dan1111 C'est vrai! Merci (juste pour essayer ... LC_COLLATE="en_US.ascii" ; ls -lvs LC_COLLATE="en_US.UTF-8" ; ls -l)
manlio
En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.