README
A README fájlinformációkat tartalmaz más fájlokról egy könyvtárban, vagy egy számítógépes szoftver archívumában. Mint a dokumentáció egy formája, általában csak egy egyszerű szövegfájl, melynek neve lehet Read Me
, READ.
ME
, README.
TXT
, README.md
(a markdown nyelvet használó fájlokra), README.1ST
vagy egyszerűen README
.
A fájl nevét általában nagybetűvel írják. A Unix-szerű rendszerekben könnyen észrevehetővé teszi – mind azért, mert a kisbetűs fájlnevek gyakoribbak az ilyen rendszerekben, mind azért, mert hagyományosan az ls parancs ASCII-kód sorrendben rendezi és jeleníti meg a fájlokat, ezért először a nagybetűs fájlnevek jelennek meg.[nb 1]
Tartalom
szerkesztésA fájl általában az alábbiak közül egyet vagy többet tartalmaz:
- Konfigurációs utasítások
- Telepítési utasítások
- Használati utasítások
- Manifest fájl (a benne foglalt fájlok listája)
- Szerzői jog és licencinformáció
- Kapcsolattartási információk a forgalmazóhoz vagy a programozóhoz
- Ismert hibák
- Hibaelhárítás
- Készítők listája és köszönetnyilvánítások
- Változási napló (főként fejlesztők számára)
- Hírrovat (főként a felhasználók számára)
Története
szerkesztésNem világos, hogy mikor kezdődött a használata, de már az 1970-es évek közepén is találunk rá példát. A korai Macintosh-rendszerszoftver mindig telepített egy Read Me-t az indítólemezre, mely általában harmadik féltől származó szoftvereket kísért.
Különösen az ingyenes szoftverekben és a nyílt forráskódú szoftverben van hosszú múltja a README fájloknak; a GNU kódolási szabványok pedig ösztönözik a felvételét a "csomag általános áttekintésének" biztosítására.
Mióta a web mint a szoftverterjesztés de facto szabvány platformjára emelkedett, számos szoftvercsomag a fenti kiegészítő fájlok és információk egy részét átvitte (vagy esetenként átmásolta) egy weboldalra vagy wikire, néha magában a README-t is, néha csak egy rövid README fájlt hagyva maga után, a szoftver új felhasználója által igényelt összes információ nélkül.
Az utóbbi időben a népszerű GitHub saját Git-tárháza is erősen ösztönzi a README fájl használatát - ha szerepel egy fő (legfelső szintű) könyvtárban, akkor automatikusan megjelenik a fő weboldalon. Habár az egyszerű szövegfájl is támogatott, különféle fájlkiterjesztések és formátumok szintén támogatva vannak, és a HTML formátumba való konvertálás figyelembe veszi a fájl fájlkiterjesztését - például egy "README.md" fájl GitHub Flavored Markdown fájlként lenne kezelve.
Általános kifejezésként
szerkesztésA "readme fájl" kifejezést néha általános céllal is használják, hasonló célú fájlokhoz. Például számos ingyenes szoftvercsomag forráskódjának terjesztése, különösen a Gnits szabványokat követők vagy a GNU Autotoolsszal készített csomagok forráskódterjesztései tartalmazzák a readme fájlok alapvető készletét:
README
|
Általános információ |
AUTHORS
|
Készítők listája |
THANKS
|
Köszönetnyilvánítások |
CHANGELOG
|
Részletes változási napló, a programozók számára |
NEWS
|
Alapvető, szűk változási napló a felhasználók számára |
INSTALL
|
Telepítési útmutató |
COPYING / LICENSE
|
Szerzői jogi és licenszinformációk |
BUGS
|
Ismert programhibák és útmutatások az újak jelentésére |
CONTRIBUTING / HACKING
|
Útmutató a projekt leendő közreműködőinek |
Szoftverekkel általában terjesztenek más fájlokat, amelyeket között szerepel a GYIK és a TODO
fájl, amely felsorolja a lehetséges jövőbeni változásokat.
Megjegyzések
szerkesztés- ↑ Gyakran már nem ez a helyzet, de az LC_ALL = C ls megmutatja a régebbi viselkedést.
Hivatkozások
szerkesztésFordítás
szerkesztésEz a szócikk részben vagy egészben a README című angol Wikipédia-szócikk ezen változatának fordításán alapul. Az eredeti cikk szerkesztőit annak laptörténete sorolja fel. Ez a jelzés csupán a megfogalmazás eredetét és a szerzői jogokat jelzi, nem szolgál a cikkben szereplő információk forrásmegjelöléseként.
További irodalom
szerkesztés- (1997. február 1.) „Building a Better ReadMe”. Technical Communication 44 (1), 28–36. o, Kiadó: Society for Technical Communication. [1][2]
- (1997. augusztus 1.) „Hypertext good choice for README files”. Technical Communication 44 (3), 214. o, Kiadó: Society for Technical Communication.
- [3]
- (1996. szeptember 15.) „Readme: Writing Notes - Meditations on the temporality of writing” (en, fr nyelven). Surfaces, Department of Philosophy, University of Warwick, UK III (12), 1–12. o, Kiadó: Les Presses de l'Université de Montréal. [2006. február 20-i dátummal az eredetiből archiválva]. ISSN 1188-2492. (Hozzáférés: 2019. június 4.) [4] Archiválva 2006. szeptember 19-i dátummal a Wayback Machine-ben