ПРОЧТИ МЕНЯ

Информационный файл программного обеспечения

Скриншот файла README cURL

При разработке программного обеспечения файл README содержит информацию о других файлах в каталоге или архиве компьютерного программного обеспечения . Форма документации . Обычно это простой текстовый файл с именем , , , , ^[1] (чтобы указать на использование Markdown ) или . ^[2]READMERead MeREAD.MEREADME.TXT README.mdREADME.1ST

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

Содержание

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

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

История

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

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

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

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

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

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

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

Смотрите также

• FILE_ID.DIZ
• ОПИСАНИЕ
• .nfo
• справочная страница

Примечания

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

Рекомендации

1. Раймонд, Эрик Стивен (1996). Новый словарь хакера. МТИ Пресс . стр. 378–79. ISBN 978-0-26268092-9. Введение с точки зрения хакера, традиционно включенное в каталог верхнего уровня дистрибутива исходного кода Unix, содержащее указатель на более подробную документацию, сведения об авторах, различную историю изменений, примечания и т. д. […] Когда хакеры спрашивают об этом, они неизменно связывают соглашение README с соглашением README. знаменитая сцена из «Приключений Алисы в стране чудес» Льюиса Кэрролла, в которой Алиса противостоит волшебным закускам с надписями «Съешь меня» и «Выпей меня».
2. Абдельхафит, Омар (13 августа 2015 г.). «README.md: История и компоненты». Архивировано из оригинала 25 января 2020 г. Проверено 25 января 2020 г.
3. Манес, Стивен (ноябрь 1996 г.). «README? Конечно, прежде чем купить!». Мир ПК . 14 (11): 366.
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]
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]
6. "Инструменты программиста /sys/source/lex/README" . Июль 1977 года . Проверено 25 января 2020 г.
7. "Unix 7-е издание /usr/doc/README" . 1979 год . Проверено 25 января 2020 г.
8. «Первая 32-битная BSD usr/doc/README» . Март 1980 года . Проверено 25 января 2020 г.
9. Лангемайер, Джефф (29 июля 2011 г.). «Re: Происхождение README» . Получено 25 января 2020 г. - через Stackexchange. […] у них были README (настоящие физические печатные файлы) для всех их перфокарт, магнитных лент и почти всего остального, что было «программой». В то время он вам действительно был нужен из-за трудоемкого процесса, связанного с созданием, запуском и всем остальным. Эти файлы README иногда также включали фактические распечатки того, как должны были быть перфорированы перфокарты, в качестве формы проверки ошибок и отладки. Соглашение, по-видимому, также следует старой системе в том смысле, что ко всем перфокартам была прикреплена стопка бумаги с напечатанным заглавными буквами заявлением README, в котором были все инструкции по использованию и загрузке перфокарт в систему. . Для справки по времени это было бы в 60-х годах. […]
10. «Стандарты кодирования GNU: выпуски» . www.gnu.org . Проверено 3 марта 2018 г.
11. «Разметка». Гитхаб . 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 (Электронный журнал) (на английском и французском языках). Университет Монреаля , Монреаль (Квебек), Канада: Les Presses de l'Université de Montréal . III (12): 1–12. ISSN  1188-2492. Архивировано из оригинала 20 февраля 2006 г. Проверено 4 июня 2019 г.[5]

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