Hispanopedia Wiki
Articulo de referencia

LÉAME

Captura de pantalla del archivo README de cURL Un archivo README contiene información descriptiva sobre el contenido de un directorio en el que se encuentra el archivo. El alcan...

Hispanopedia WikiContenido en espanolLectura gratuita

Captura de pantalla del archivo README de cURL

Un archivo README contiene información descriptiva sobre el contenido de un directorio en el que se encuentra el archivo. El alcance de la información generalmente incluye los archivos del directorio y puede incluir directorios descendientes, o incluso todo el árbol de directorios. El nombre tiene como objetivo llamar la atención del usuario sobre información importante y orientativa sobre el contenido del directorio. Una regla general para alguien que no está familiarizado con el contenido de un directorio es leer el archivo README antes que otros archivos. Aunque el nombre README se usa con frecuencia, hay muchos otros nombres similares que se usan para el mismo propósito, incluidos "Read Me" y "READ.ME". A veces, el nombre del archivo incluye una extensión para indicar el formato del archivo, como "README.txt" para texto plano o "README.md" para Markdown . [ 1 ] El nombre del archivo a menudo está todo en mayúsculas .

Un archivo README en un archivo comprimido funciona igual que en un directorio, ya que un archivo comprimido es funcionalmente un directorio almacenado como un único archivo.

Contenido

Debido a la falta de estandarización, el formato y el contenido de un archivo README varían drásticamente. En un proyecto de software , un archivo README suele incluir información como:

Historia

La convención de incluir un archivo README comenzó a mediados de la década de 1970. [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] En Unix , donde la mayoría de los nombres de archivo estaban en minúsculas , el nombre se puso en mayúscula para que destacara y apareciera cerca del principio de las listas ordenadas por ASCII . El software del sistema Macintosh de las primeras versiones instalaba un Read Me en el disco de arranque, y los archivos README solían acompañar al software de terceros.

En particular, existe una larga historia de software libre y software de código abierto que incluye un archivo README; los Estándares de Codificación GNU recomiendan incluir uno para proporcionar "una descripción general del paquete". [ 10 ]

Desde la aparición de la web como plataforma estándar de facto para la distribución de software , muchos paquetes de software han trasladado (o, en ocasiones, copiado) algunos de los archivos auxiliares y fragmentos de información mencionados anteriormente a un sitio web o wiki , a veces incluyendo el propio archivo README, o a veces dejando solo un breve archivo README sin toda la información necesaria para un nuevo usuario del software.

El popular sitio web de alojamiento de código fuente GitHub recomienda encarecidamente la creación de un archivo README : si existe uno en el directorio principal (de nivel superior) de un repositorio, se presenta automáticamente en la página principal del repositorio. [ 11 ] Además del texto plano, también se admiten otros formatos y extensiones de archivo , [ 12 ] y la conversión a HTML tiene en cuenta las extensiones ; en particular, un README.md se trata como Markdown con formato de GitHub .  

Los metadatos del contenido del directorio a veces se almacenan en archivos además de, o en lugar de, un README. [ 13 ] La siguiente tabla enumera los nombres de archivo de uso común junto con el contenido que suele contener. Al igual que con el README, no existen estándares formales que rijan los nombres de archivo ni su contenido. Sin embargo, existen convenciones dictadas por los estándares de Gnits y GNU Autotools .

Véase también

Referencias

  1. ↑ Raymond, Eric Steven (1996). The New Hacker's Dictionary . MIT Press . págs. 378–79 . ISBN  978-0-26268092-9La introducción al estilo hacker , tradicionalmente incluida en el directorio de nivel superior de una distribución de código fuente de Unix, contiene un enlace a documentación más detallada, créditos, historial de revisiones, notas, etc. […] Cuando se les pregunta, los hackers invariablemente relacionan la convención README con la famosa escena de Alicia en el País de las Maravillas de Lewis Carroll en la que Alicia se enfrenta a bocadillos mágicos etiquetados como "Cómeme" y "Bébeme".
  2. 1 2 Manes, Stephen (noviembre de 1996). "¿LEERME? ¡Claro, antes de comprarlo!". PC World . 14 (11): 366.
  3. ↑ "Archivo PDP-10: decus/20-0079/readme.txt de decus_20tap3_198111" . pdp-10.trailing-edge.com . 27-11-1974 . Recuperado el 03-03-2018 . [README.TXT es el archivo DOC para SPICE/SINC/SLIC] Esta cinta de seguridad contiene los programas de análisis de circuitos SPICE, SINC y SLIC descritos en el Boletín de software de aplicaciones Volumen 4. Requisitos: SPICE requiere FORTRAN-10 versión 4 debido a su uso de datos Holerith ajustados a la derecha. Se ejecuta en aproximadamente 47K. [...] también incluye este archivo, los FOROTS para acompañar a los SAVes y el código fuente para SECOND.MAC, la rutina de temporización. SPICE se divide en tres partes: 1SPICE.FOR, 2 y 3. Hay un documento impreso para describir cada uno de los programas. Estos se incluyen en el paquete DECUS. La documentación y los programas fueron desarrollados originalmente por el departamento de Ingeniería Eléctrica de la Universidad de California en Berkeley en una CDC 6400. Excepto por la conversión de FORTRAN al DECsystem-10, no se han realizado cambios en los programas. Para los datos de prueba, SLIC y SINC mostraron una ligera variación con respecto a la 6400, mientras que SPICE no mostró variación. ¡Buena suerte! Ashley Grayson 27-NOV-74 [fin de README.TXT]
  4. ↑ "DECUS 10-LIB-4 Contiene los archivos 10-210 al 10-241, excepto el 10-223" . pdp-10.trailing-edge.com . 27 de marzo de 1975. Consultado el 3 de marzo de 2018. Los archivos de esta cinta FAILSAFE constituyen el sistema UCI LISP. Están documentados en su mayor parte en el Manual UCI LISP, disponible en el Departamento de Información y Ciencias de la Computación de la Universidad de California, Irvine, California.
  5. ↑ "Entorno de trabajo del programador /sys/source/lex/README" . Julio de 1977. Consultado el 25 de enero de 2020 .
  6. ↑ "Unix 7th edition /usr/doc/README" . 1979. Consultado el 25 de enero de 2020 .
  7. ↑ "Primer BSD de 32 bits usr/doc/README" . Marzo de 1980. Consultado el 25 de enero de 2020 .
  8. ↑ Langemeier, Jeff (29/07/2011). "Re: Origen de README" . Recuperado el 25/01/2020 a través de Stackexchange. […] Tenían archivos README (archivos físicos impresos) para todas sus tarjetas perforadas, cintas magnéticas y prácticamente cualquier otro programa. En aquella época, era imprescindible debido al laborioso proceso de creación, ejecución y demás. Estos archivos README a veces también incluían las impresiones de cómo debían perforarse las tarjetas, como método de comprobación de errores y depuración. Al parecer, la convención seguía el antiguo sistema: con todas las tarjetas perforadas se adjuntaba una resma de papel con la palabra README impresa en mayúsculas, que contenía todas las instrucciones de uso y carga de las tarjetas en el sistema. Esto sería en la década de los 60. […]
  9. ↑ Abdelhafith, Omar (13 de agosto de 2015). "README.md: Historia y componentes" . Recuperado el 25 de enero de 2020 .{{cite web}}: CS1 maint: servicio de archivado obsoleto ( enlace )
  10. ↑ "Estándares de codificación GNU: Lanzamientos" . www.gnu.org . Consultado el 3 de marzo de 2018 .
  11. ↑ "Acerca de los README" . Documentación de GitHub . Consultado el 31 de mayo de 2024 .
  12. ↑ "Marcado" . GitHub . 25-12-2014 . Consultado el 08-02-2015 .
  13. ↑ Prana, Gede Artha Azriadi; Treude, Christoph; Thung, Ferdian; Atapattu, Thushari; Lo, David (2019-06-01). "Categorizing the Content of GitHub README Files" . Empirical Software Engineering . 24 (3): 1296–1327 . arXiv : 1802.06997 . doi : 10.1007/s10664-018-9660-3 . ISSN 1573-7616 . 

Lecturas adicionales

Este artículo se basa en parte en el Jargon File , que es de dominio público.