This article has multiple issues. Please help improve it or discuss these issues on the talk page . (Learn how and when to remove these template messages)
|
In software development, a README file contains information about the other files in a directory or archive of computer software. A form of documentation, it is usually a simple plain text file called README
, Read Me
, READ.ME
, README.TXT
, [1] README.md
(to indicate the use of Markdown), or README.1ST
. [2]
The file's name is generally written in uppercase. On Unix-like systems in particular, this causes it to stand out –both because lowercase filenames are more common, and because the ls
command commonly sorts and displays files in ASCII-code order, in which uppercase filenames will appear first. [nb 1]
A README file typically encompasses:
This section needs expansion. You can help by adding to it. (February 2015) |
It is unclear when the convention of including a README file began, but examples dating to the mid-1970s have been found. [4] [5] [6] [7] [8] [9] [2] [ better source needed ] Early Macintosh system software installed a Read Me on the Startup Disk, and README files commonly accompanied third-party software.
In particular, there is a long history of free software and open-source software including a README file; the GNU Coding Standards encourage including one to provide "a general overview of the package". [10]
Since the advent of the web as a de facto standard platform for software distribution, many software packages have moved (or occasionally, copied) some of the above ancillary files and pieces of information to a website or wiki, sometimes including the README itself, or sometimes leaving behind only a brief README file without all of the information required by a new user of the software.
The popular source code hosting website GitHub strongly encourages the creation of a README file –if one exists in the main (top-level) directory of a repository, it is automatically presented on the repository's front page. In addition to plain text, various other formats and file extensions are also supported, [11] and HTML conversion takes extensions into account –in particular a README.md
is treated as GitHub Flavored Markdown.
The expression "readme file" is also sometimes used generically, for other files with a similar purpose.[ citation needed ] For example, the source-code distributions of many free software packages (especially those following the Gnits Standards or those produced with GNU Autotools) include a standard set of readme files:
README | General information |
AUTHORS | Credits |
THANKS | Acknowledgments |
CHANGELOG | A detailed changelog, intended for programmers |
NEWS | A basic changelog, intended for users |
INSTALL | Installation instructions |
COPYING /LICENSE | Copyright and licensing information |
BUGS | Known bugs and instructions on reporting new ones |
CONTRIBUTING /HACKING | Guide for prospective contributors to the project |
Also commonly distributed with software packages are an FAQ file and a TODO
file, which lists planned improvements.
Cygwin is a Unix-like environment and command-line interface for Microsoft Windows. Cygwin's purpose is expressed in its motto: "Get that Linux feeling – on Windows".
In computing, a linker or link editor is a computer system program that takes one or more object files and combines them into a single executable file, library file, or another "object" file.
In computers, case sensitivity defines whether uppercase and lowercase letters are treated as distinct (case-sensitive) or equivalent (case-insensitive). For instance, when users interested in learning about dogs search an e-book, "dog" and "Dog" are of the same significance to them. Thus, they request a case-insensitive search. But when they search an online encyclopedia for information about the United Nations, for example, or something with no ambiguity regarding capitalization and ambiguity between two or more terms cut down by capitalization, they may prefer a case-sensitive search.
Revision Control System(RCS) is an early implementation of a version control system (VCS). It is a set of UNIX commands that allow multiple users to develop and maintain program code or documents. With RCS, users can make their own revisions of a document, commit changes, and merge them. RCS was originally developed for programs but is also useful for text documents or configuration files that are frequently revised.
A man page is a form of software documentation usually found on a Unix or Unix-like operating system. Topics covered include computer programs, formal standards and conventions, and even abstract concepts. A user may invoke a man page by issuing the man
command.
The cd
command, also known as chdir
, is a command-line shell command used to change the current working directory in various operating systems. It can be used in shell scripts and batch files.
The GNU Autotools, also known as the GNU Build System, is a suite of programming tools designed to assist in making source code packages portable to many Unix-like systems.
In software development, Make is a build automation tool that builds executable programs and libraries from source code by reading files called makefiles which specify how to derive the target program. Though integrated development environments and language-specific compiler features can also be used to manage a build process, Make remains widely used, especially in Unix and Unix-like operating systems.
GoboLinux is a Linux distribution whose most prominent feature is a reorganization of the traditional Linux file system. Rather than following the Filesystem Hierarchy Standard like most Unix-like systems, each program in a GoboLinux system has its own subdirectory tree, where all of its files may be found. Thus, a program "Foo" has all of its specific files and libraries in /Programs/Foo
, under the corresponding version of this program at hand. For example, the commonly known GCC compiler suite version 8.1.0, would reside under the directory /Programs/GCC/8.1.0
.
DICT is a dictionary network protocol created by the DICT Development Group in 1997, described by RFC 2229. Its goal is to surpass the Webster protocol to allow clients to access a variety of dictionaries via a uniform interface.
Ratfor is a programming language implemented as a preprocessor for Fortran 66. It provides modern control structures, unavailable in Fortran 66, to replace GOTOs and statement numbers.
A changelog is a log or record of all notable changes made to a project. The project is often a website or software project, and the changelog usually includes records of changes such as bug fixes, new features, etc. Some open-source projects include a changelog as one of the top-level files in their distribution.
The computer tool patch is a Unix program that updates text files according to instructions contained in a separate file, called a patch file. The patch file is a text file that consists of a list of differences and is produced by running the related diff program with the original and updated file as arguments. Updating files with patch is often referred to as applying the patch or simply patching the files.
In Unix and Unix-like operating systems, iconv is a command-line program and a standardized application programming interface (API) used to convert between different character encodings. "It can convert from any of these encodings to any other, through Unicode conversion."
GnuTLS is a free software implementation of the TLS, SSL and DTLS protocols. It offers an application programming interface (API) for applications to enable secure communication over the network transport layer, as well as interfaces to access X.509, PKCS #12, OpenPGP and other structures.
Markdown is a lightweight markup language for creating formatted text using a plain-text editor. John Gruber created Markdown in 2004 as a markup language that is easy to read in its source code form. Markdown is widely used for blogging and instant messaging, and also used elsewhere in online forums, collaborative software, documentation pages, and readme files.
GNU Emacs is a free software text editor. It was created by GNU Project founder Richard Stallman, based on the Emacs editor developed for Unix operating systems. GNU Emacs has been a central component of the GNU project and a flagship project of the free software movement. Its tag line is "the extensible self-documenting text editor."
Unix is a family of multitasking, multi-user computer operating systems that derive from the original AT&T Unix, whose development started in 1969 at the Bell Labs research center by Ken Thompson, Dennis Ritchie, and others.
SMPlayer is a cross-platform graphical front-end for MPlayer and mpv and forks of Mplayer using GUI widgets offered by Qt. SMPlayer is free and open-source software subject to the terms of the GNU General Public License version 2 or later. SMplayer has been localized in more than 30 languages.
Hacker's-eye introduction traditionally included in the top-level directory of a Unix source distribution, containing a pointer to more detailed documentation, credits, miscellaneous revision history, notes, etc. […] When asked, hackers invariably relate the README convention to the famous scene in Lewis Carroll's Alice's Adventures In Wonderland in which Alice confronts magic munchies labeled "Eat Me" and "Drink Me".
[README.TXT is the DOC file for SPICE/SINC/SLIC] This failsafe tape contains the circuit analysis programs SPICE SINC and SLIC described in the Applications Software Bulletin Volume 4. requirements: SPICE requires FORTRAN-10 version 4 because of its use of Right adjusted Holerith data. Executes in about 47K. […] it also includes this file, the FOROTS to go with the SAVes and the source for SECOND.MAC, the timing routine. SPICE is broken into three parts: 1SPICE.FOR, 2 and 3. There is a printed document to describe each of the programs. These are included in the DECUS packet. The documentation and programs were originally developed by the E.E. department of the Univ. of Calif. at Berkeley on a CDC 6400. Except to convert the FORTRAN to the DECsystem-10 no changes have been made to the programs. For the test data SLIC and SINC have shown a slight variation with respect to the 6400, SPICE shows no variation. Good luck! Ashley Grayson 27-NOV-74 [end of README.TXT]
The files on this FAILSAFE tape constitute the UCI LISP system. They are for the most part documented in the UCI LISP Manual, available from the Department of Information and Computer Science at the University of California, Irvine, California.
[…] they had READMEs (actual physical printed files) for all of their punch cards and mag tape and pretty much anything else that was a "program". At that time you really needed one because of the labourous process that was involved with getting the created, ran, and everything else. These READMEs sometimes also included the actual printouts of how the punch cards were supposed to be punched as a form of error checking and debugging. The convention apparently also follows the old system in that with all the punch cards a "reem" of paper was attached with the statement README in caps printed on it, this had all of the instructions for use and loading of the punch cards into the system. For a time reference, this would have been in the 60s. […]
This article is based in part on the Jargon File, which is in the public domain.