Readme.txt vs. README.txt

33

Acabo de bifurcar un proyecto en Github, hice mis cambios, etc. Esto me hizo preguntarme: veo principalmente README.txt en proyectos de código abierto y el archivo que edité fue Readme.txt. ¿Es esto algún tipo de estandarización o debería haberlo dejado como está?

Tolga Ozses
fuente
Todo en mayúsculas probablemente tuvo su inicio en MS-DOS, todas en minúsculas probablemente de herencia de Unix. No estoy seguro acerca de la primera letra en mayúscula: quizás raíces de Mac. Al final, realmente no importa, excepto como una cuestión de orden o estilo.
Lawrence

Respuestas:

29

Las letras mayúsculas destacan y hacen que el archivo sea fácilmente visible, lo que tiene sentido porque es probablemente lo primero que un nuevo usuario desearía mirar. (O, al menos, debería haber mirado ...) Como ya han dicho otros, los nombres de archivo que comienzan con una letra mayúscula se enumerarán antes de los nombres en minúsculas en la clasificación ASCIIbetical ( LC_COLLATE=C) que ayuda a hacer que el archivo sea visible a primera vista.

El READMEarchivo es parte de un montón de archivos que un usuario de un paquete de software libre normalmente esperaría encontrar. Otros son INSTALL(instrucciones para construir e instalar el software), AUTHORS(lista de contribuyentes), COPYING(texto de la licencia), HACKING(cómo comenzar a contribuir, tal vez incluyendo una lista TODO de puntos de partida), NEWS(cambios recientes) o ChangeLog(en su mayoría redundantes con sistemas de control de versiones).

Esto es lo que los estándares de codificación GNU tienen que decir sobre el READMEarchivo.

La distribución debe contener un archivo READMEcon una descripción general del paquete:

  • El nombre del paquete;
  • el número de versión del paquete, o consulte en qué parte del paquete se puede encontrar la versión;
  • una descripción general de lo que hace el paquete;
  • una referencia al archivo INSTALL, que a su vez debe contener una explicación del procedimiento de instalación;
  • una breve explicación de cualquier directorio o archivo de nivel superior inusual, u otras sugerencias para que los lectores encuentren su camino en la fuente;
  • una referencia al archivo que contiene las condiciones de copia. La GNU GPL, si se usa, debe estar en un archivo llamado COPYING. Si se utiliza GNU LGPL, debe estar en un archivo llamado COPYING.LESSER.

Como siempre es bueno tratar de sorprender a sus usuarios, debe seguir esta convención a menos que existan razones convincentes para una desviación. En el mundo UNIX, las extensiones de nombre de archivo se usaban tradicionalmente con moderación, por lo que el nombre canónico del archivo READMEno tiene sufijo. Pero la mayoría de los usuarios probablemente no tendrían problemas para entender que un archivo llamado README.txttiene el mismo significado. Si el archivo está escrito en Markdown , un nombre de archivo como README.mdtambién podría ser razonable. Evite usar lenguajes de marcado más complicados como HTML en elREADMEarchivo, sin embargo, porque debería ser conveniente leer en un terminal de solo texto. Puede indicar a los usuarios el manual del software o su documentación en línea, que podría estar escrita en un formato más sofisticado, para obtener detalles del READMEarchivo.

5gon12eder
fuente
20

Tradicionalmente, el archivo se llamaba README en mayúsculas porque los entornos de línea de comandos que utilizan el orden alfabético colocarían el archivo en la parte superior. Esto los hace fácilmente visibles en grandes directorios.

Es muy probable que sea un remanente del mundo Unix / Linux donde descargaría fuentes y luego crearía su software. Tener archivos como README e INSTALL en la parte superior de la vista 'lista de contenidos del directorio' hace que sea más fácil ver que están allí, en lugar de tener que navegar por todo el contenido desde una interfaz de línea de comandos. El mismo principio básico también funciona para github (y en realidad también funciona en las interfaces GUI, ahora que lo pienso, por lo que aún podría tener mérito)

De ninguna manera es una regla difícil, pero muy probablemente es algo que todos están haciendo como hábito porque otros proyectos lo están haciendo. A menos que haya alguna razón explícita para NO hacerlo, probablemente debería usar mayúsculas solo porque verá que se usa de esa manera en muchos otros proyectos. También es el nombre predeterminado que utiliza Github cuando crea un nuevo repositorio.

JDT
fuente
Siempre he pensado que todo en mayúscula era una forma de énfasis, muy parecido a cómo se usan las secciones en mayúscula en jerga legal.
Lars Viklund el
1
En una interfaz de línea de comandos, los archivos que van a la parte superior de la lista son en realidad los que se desplazan primero fuera de la vista, por lo que a veces estos son los archivos menos visibles. A menos que siempre hagas algo así ls -l | less.
Marc van Leeuwen el
6

README generalmente se escribe en mayúsculas. De esta manera, el lscomando Unix colocó el archivo cerca del comienzo de la lista del directorio (las letras mayúsculas van antes que las minúsculas en el orden ASCII).

manlio
fuente
3
Esta fue la razón histórica, pero lsgeneralmente no se ordena de esa manera en los sistemas modernos.
1
@ dan1111 ¡Correcto! Gracias (solo para probar ... LC_COLLATE="en_US.ascii" ; ls -lvs LC_COLLATE="en_US.UTF-8" ; ls -l)
manlio