ЧИТАЙТЕ

При распространении и разработке программного обеспечения файл README содержит информацию о других файлах в каталоге или архиве компьютерного программного обеспечения . Форма документации . Обычно это простой текстовый файл, называемый README, Read Me, READ.ME, README.txt, ^[1] или README.md (чтобы указать использование Markdown )

Имя файла обычно пишется заглавными буквами. В частности, в Unix-подобных системах это выделяет его – как потому, что имена файлов в нижнем регистре более распространены, так и потому, что ls Команда обычно сортирует и отображает файлы в порядке ASCII-кода , в котором имена файлов в верхнем регистре появляются первыми. ^{[номер 1]}

Содержание

Файл README обычно включает в себя:

по настройке Инструкции
по установке Инструкции
Инструкция по эксплуатации
файла Манифест (список файлов в каталоге или архиве)
об авторских правах и лицензировании Информация
Контактная информация дистрибьютора или автора
Список известных ошибок ^[2]
по устранению неполадок Инструкции ^[2]
Кредиты и благодарности
Журнал изменений (обычно предназначен для коллег-программистов)
Раздел новостей (обычно ориентирован на конечных пользователей )

История

Неясно, когда появилось соглашение о включении файла README, но были найдены примеры, относящиеся к середине 1970-х годов. ^[3]^[4]^[5]^[6]^[7]^[8]^[9]^{[ нужен лучший источник ]} Раннее системное программное обеспечение Macintosh устанавливало файл Read Me на загрузочный диск, а файлы README обычно сопровождали стороннее программное обеспечение.

В частности, существует долгая история свободного программного обеспечения и программного обеспечения с открытым исходным кодом, включая файл README; Стандарты кодирования GNU поощряют включение одного из них для предоставления «общего обзора пакета». ^[10]

С момента появления Интернета как стандартной де-факто платформы для распространения программного обеспечения , многие пакеты программного обеспечения переместили (или иногда скопировали) некоторые из вышеперечисленных вспомогательных файлов и фрагментов информации на веб-сайт или вики , иногда включая сам README или иногда остается лишь краткий файл README без всей информации, необходимой новому пользователю программного обеспечения.

Популярный исходный код размещающий веб-сайт GitHub, , настоятельно рекомендует создавать файл README: если он существует в главном каталоге (верхнего уровня) репозитория, он автоматически отображается на главной странице репозитория. ^[11] Помимо обычного текста, различные другие форматы и расширения файлов . также поддерживаются ^[12] и преобразование HTML учитывает расширения, в частности README.md рассматривается как Markdown со вкусом GitHub .

Как общий термин

Выражение «файл readme» также иногда используется в общем для других файлов аналогичного назначения. ^{[ нужна ссылка ]} Например, дистрибутивы исходного кода многих пакетов бесплатного программного обеспечения (особенно тех, которые соответствуют стандартам Gnits или созданы с помощью GNU Autotools ) включают стандартный набор файлов readme:

`README`	Общая информация
`AUTHORS`	Кредиты
`THANKS`	Благодарности
`CHANGELOG`	Подробный список изменений, предназначенный для программистов.
`NEWS`	Базовый журнал изменений, предназначенный для пользователей.
`INSTALL`	Инструкции по установке
`COPYING` / `LICENSE`	Информация об авторских правах и лицензировании
`BUGS`	Известные ошибки и инструкции по сообщению о новых.
`CONTRIBUTING` / `HACKING`	Руководство для потенциальных участников проекта

Вместе с программными пакетами также обычно распространяются файл часто задаваемых вопросов и TODO файл, в котором перечислены запланированные улучшения.

См. также

Примечания

^ Часто это уже не так, но LC_ALL=C ls будет показывать старое поведение.

Ссылки

^ Раймонд, Эрик Стивен (1996). Новый словарь хакера . МТИ Пресс . стр. 378–79. ISBN 978-0-26268092-9 . Введение с точки зрения хакера, традиционно включенное в каталог верхнего уровня дистрибутива исходного кода Unix, содержащее указатель на более подробную документацию, сведения об авторах, различную историю изменений, примечания и т. д. […] Когда хакеры спрашивают об этом, они неизменно связывают соглашение README с соглашением README. знаменитая сцена из «Приключений Алисы в стране чудес» Льюиса Кэрролла, в которой Алиса противостоит волшебным закускам с надписями «Съешь меня» и «Выпей меня».
^ Jump up to: ^а ^б Манес, Стивен (ноябрь 1996 г.). «README? Конечно, прежде чем купить!». Мир ПК . 14 (11): 366.
^ «Архив PDP-10: decus/20-0079/readme.txt из decus_20tap3_198111» . pdp-10.trailing-edge.com . 1974-11-27 . Проверено 3 марта 2018 г. [README.TXT — это файл DOC для SPICE/SINC/SLIC] Эта отказоустойчивая лента содержит программы анализа цепей SPICE SINC и SLIC, описанные в Бюллетене прикладного программного обеспечения, том 4. Требования: SPICE требует FORTRAN-10 версии 4 из-за использования в нем Правильно скорректированные данные Холерита. Выполняется примерно за 47К. […] он также включает в себя этот файл, FOROTS для сохранения и источник SECOND.MAC, процедуры синхронизации. SPICE разбит на три части: 1SPICE.FOR, 2 и 3. Для описания каждой программы имеется печатный документ. Они включены в пакет DECUS. Документация и программы изначально были разработаны кафедрой ЭЭ Университета. из Калифорнии в Беркли на CDC 6400. За исключением преобразования FORTRAN в DECsystem-10, в программы не было внесено никаких изменений. Тестовые данные SLIC и SINC показали небольшое изменение по сравнению с 6400, SPICE не показывает никаких изменений. Удачи! Эшли Грейсон, 27 ноября 2074 г. [конец README.TXT]
^ «DECUS 10-LIB-4 Содержит номера с 10-210 по 10-241, кроме 10-223» . pdp-10.trailing-edge.com . 27 марта 1975 г. Проверено 3 марта 2018 г. Файлы на этой ленте FAILSAFE составляют систему UCI LISP. Они по большей части задокументированы в Руководстве UCI LISP, которое можно получить на факультете информации и компьютерных наук Калифорнийского университета в Ирвине, Калифорния. [1]
^ «Инструменты программиста /sys/source/lex/README» . Июль 1977 года . Проверено 25 января 2020 г.
^ «Unix 7-е издание /usr/doc/README» . 1979 год . Проверено 25 января 2020 г.
^ «Первая 32-битная версия BSD usr/doc/README» . Март 1980 года . Проверено 25 января 2020 г.
^ Лангемайер, Джефф (29 июля 2011 г.). «Re: Происхождение README» . Получено 25 января 2020 г. - через Stackexchange. […] у них были README (настоящие физические печатные файлы) для всех их перфокарт, магнитных лент и почти всего остального, что было «программой». В то время он вам действительно был нужен из-за трудоемкого процесса, связанного с созданием, запуском и всем остальным. Эти файлы README иногда также включали фактические распечатки того, как должны были перфорироваться перфокарты, в качестве формы проверки ошибок и отладки. Соглашение, по-видимому, также следует старой системе в том смысле, что ко всем перфокартам была прикреплена «пачка» бумаги с напечатанным заглавными буквами заявлением README, в котором были все инструкции по использованию и загрузке перфокарт в систему. . Для справки по времени это было бы в 60-х годах. […]
^ Абдельхафит, Омар (13 августа 2015 г.). «README.md: История и компоненты» . Архивировано из оригинала 25 января 2020 г. Проверено 25 января 2020 г.
^ «Стандарты кодирования GNU: выпуски» . www.gnu.org . Проверено 3 марта 2018 г.
^ «О README» . Документы GitHub . Проверено 31 мая 2024 г.
^ «Разметка» . Гитхаб . 25 декабря 2014 г. Проверено 8 февраля 2015 г.

Дальнейшее чтение

Джонсон, Марк (1 февраля 1997 г.). «Создание лучшего ReadMe». Техническая связь . 44 (1). Общество технических коммуникаций : 28–36. JSTOR 43089849 . [2] [3]
Рескиньо, Жанна (август 1997 г.). «Гипертекст — хороший выбор для файлов README». Техническая связь . 44 (3). Общество технических коммуникаций : 214. JSTOR 43089876 .
Ливингстон, Брайан (14 сентября 1998 г.). «Проверьте файлы Readme, чтобы избежать распространенных проблем Windows» . Инфомир . Том. 20, нет. 37. InfoWorld Media Group, Inc. с. 34. Архивировано из оригинала 18 ноября 2006 г. Проверено 4 июня 2019 г. [4]
Бенджамин, Эндрю (15 сентября 1996 г.) [1993]. Написано на факультете философии Уорикского университета , Великобритания. Гедон, Жан-Клод (ред.). «Readme: Написание заметок — размышления о временности письма» . Surfaces (Электронный журнал) (на английском и французском языках). III (12). Университет Монреаля , Монреаль (Квебек), Канада: Les Presses de l'Université de Montréal : 1–12. ISSN 1188-2492 . Архивировано из оригинала 20 февраля 2006 г. Проверено 4 июня 2019 г. [5]

Эта статья частично основана на Файле жаргона , который находится в свободном доступе.

[NB1-2] Часто это уже не так, но LC_ALL=C ls будет показывать старое поведение.

[ESR_1996_Dict-1] Раймонд, Эрик Стивен (1996). Новый словарь хакера . МТИ Пресс . стр. 378–79. ISBN 978-0-26268092-9 . Введение с точки зрения хакера, традиционно включенное в каталог верхнего уровня дистрибутива исходного кода Unix, содержащее указатель на более подробную документацию, сведения об авторах, различную историю изменений, примечания и т. д. […] Когда хакеры спрашивают об этом, они неизменно связывают соглашение README с соглашением README. знаменитая сцена из «Приключений Алисы в стране чудес» Льюиса Кэрролла, в которой Алиса противостоит волшебным закускам с надписями «Съешь меня» и «Выпей меня».

[Manes_1996-3] Jump up to: ^а ^б Манес, Стивен (ноябрь 1996 г.). «README? Конечно, прежде чем купить!». Мир ПК . 14 (11): 366.

[Decus_1974_readme-4] «Архив PDP-10: decus/20-0079/readme.txt из decus_20tap3_198111» . pdp-10.trailing-edge.com . 1974-11-27 . Проверено 3 марта 2018 г. [README.TXT — это файл DOC для SPICE/SINC/SLIC] Эта отказоустойчивая лента содержит программы анализа цепей SPICE SINC и SLIC, описанные в Бюллетене прикладного программного обеспечения, том 4. Требования: SPICE требует FORTRAN-10 версии 4 из-за использования в нем Правильно скорректированные данные Холерита. Выполняется примерно за 47К. […] он также включает в себя этот файл, FOROTS для сохранения и источник SECOND.MAC, процедуры синхронизации. SPICE разбит на три части: 1SPICE.FOR, 2 и 3. Для описания каждой программы имеется печатный документ. Они включены в пакет DECUS. Документация и программы изначально были разработаны кафедрой ЭЭ Университета. из Калифорнии в Беркли на CDC 6400. За исключением преобразования FORTRAN в DECsystem-10, в программы не было внесено никаких изменений. Тестовые данные SLIC и SINC показали небольшое изменение по сравнению с 6400, SPICE не показывает никаких изменений. Удачи! Эшли Грейсон, 27 ноября 2074 г. [конец README.TXT]

[Decus_1975_readme-5] «DECUS 10-LIB-4 Содержит номера с 10-210 по 10-241, кроме 10-223» . pdp-10.trailing-edge.com . 27 марта 1975 г. Проверено 3 марта 2018 г. Файлы на этой ленте FAILSAFE составляют систему UCI LISP. Они по большей части задокументированы в Руководстве UCI LISP, которое можно получить на факультете информации и компьютерных наук Калифорнийского университета в Ирвине, Калифорния. [1]

[PWB_1977-6] «Инструменты программиста /sys/source/lex/README» . Июль 1977 года . Проверено 25 января 2020 г.

[UNIX7_1979-7] «Unix 7-е издание /usr/doc/README» . 1979 год . Проверено 25 января 2020 г.

[BSD_1980-8] «Первая 32-битная версия BSD usr/doc/README» . Март 1980 года . Проверено 25 января 2020 г.

[Langemeier_2011-9] Лангемайер, Джефф (29 июля 2011 г.). «Re: Происхождение README» . Получено 25 января 2020 г. - через Stackexchange. […] у них были README (настоящие физические печатные файлы) для всех их перфокарт, магнитных лент и почти всего остального, что было «программой». В то время он вам действительно был нужен из-за трудоемкого процесса, связанного с созданием, запуском и всем остальным. Эти файлы README иногда также включали фактические распечатки того, как должны были перфорироваться перфокарты, в качестве формы проверки ошибок и отладки. Соглашение, по-видимому, также следует старой системе в том смысле, что ко всем перфокартам была прикреплена «пачка» бумаги с напечатанным заглавными буквами заявлением README, в котором были все инструкции по использованию и загрузке перфокарт в систему. . Для справки по времени это было бы в 60-х годах. […]

[Abdelhafith_2015-10] Абдельхафит, Омар (13 августа 2015 г.). «README.md: История и компоненты» . Архивировано из оригинала 25 января 2020 г. Проверено 25 января 2020 г.

[GNU_Standards-11] «Стандарты кодирования GNU: выпуски» . www.gnu.org . Проверено 3 марта 2018 г.

[12] «О README» . Документы GitHub . Проверено 31 мая 2024 г.

[Github_2014_Markup-13] «Разметка» . Гитхаб . 25 декабря 2014 г. Проверено 8 февраля 2015 г.

[1]

[номер 1]

[2]

[3]

[4]

[5]

[6]

[7]

[8]

[9]

[10]

[11]

[12]