Из Википедии, бесплатной энциклопедии
  (Перенаправлено из Readme )
Перейти к навигации Перейти к поиску

Файл README для cURL

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

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

Содержание [ править ]

Содержимое обычно включает одно или несколько из следующего:

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

История [ править ]

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

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

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

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

Как общий термин [ править ]

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

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

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

См. Также [ править ]

  • FILE_ID.DIZ
  • ОПИСАНИЕ
  • WHATSNEW.TXT
  • .nfo
  • страница руководства

Заметки [ править ]

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

Ссылки [ править ]

  1. ^ a b c d e f Абдельхафит, Омар (13 августа 2015 г.). «README.md: История и компоненты» . Архивировано 25 января 2020 года . Проверено 25 января 2020 .
  2. ^ Раймонд, Эрик Стивен (1996). Словарь нового хакера . MIT Press . С. 378–79. ISBN 978-0-26268092-9. Введение глазами хакера, традиционно включенное в каталог верхнего уровня исходного дистрибутива Unix, содержит указатель на более подробную документацию, кредиты, разную историю изменений, примечания и т. Д. […] Когда их спрашивают, хакеры неизменно связывают соглашение README с знаменитая сцена из «Приключений Алисы в стране чудес» Льюиса Кэрролла, в которой Алиса противостоит волшебным закускам с надписью «Съешь меня» и «Выпей меня».
  3. ^ a b Манес, Стивен (ноябрь 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. Документация и программы были первоначально разработаны отделом EE Univ. из Калифорнии в Беркли на CDC 6400. За исключением преобразования FORTRAN в DECsystem-10, в программы не было внесено никаких изменений.Что касается тестовых данных, то SLIC и SINC показали небольшое отклонение по сравнению с 6400, SPICE не показывает никаких изменений. Удачи! Эшли Грейсон 27-НОЯ-74 [конец README.TXT]
  5. ^ "DECUS 10-LIB-4 Содержит от 10-210 до 10-241, кроме 10-223" . pdp-10.trailing-edge.com . 1975-03-27 . Проверено 3 марта 2018 . Файлы на этой ленте FAILSAFE составляют систему UCI LISP. По большей части они задокументированы в Руководстве UCI LISP, доступном в Департаменте информации и компьютерных наук Калифорнийского университета, Ирвин, Калифорния. [1]
  6. ^ "Programmer's Workbench / 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. ^ Langemeier, Джефф (2011-07-29). «Re: Происхождение README» . Проверено 25 января 2020 - через Stackexchange.[…] У них были README (реальные печатные файлы) для всех их перфокарт, магнитной ленты и всего остального, что было «программой». В то время он вам действительно был нужен из-за трудоемкого процесса, связанного с созданием, запуском и всем остальным. Эти README иногда также включали фактические распечатки того, как перфокарты должны были перфорироваться, в качестве формы проверки ошибок и отладки. Соглашение, по-видимому, также следует старой системе в том смысле, что ко всем перфокартам прилагалась «стопка» бумаги с надписью README в колпачках, напечатанной на ней, там были все инструкции по использованию и загрузке перфокарт в систему . Для справки, это были 60-е годы. […]
  10. ^ «Стандарты кодирования GNU: версии» . www.gnu.org . Проверено 3 марта 2018 .
  11. ^ «Сайту совместного использования кода Github исполняется пять лет, и он насчитывает 3,5 миллиона пользователей, 6 миллионов репозиториев» . TheNextWeb.com. 2013-04-11 . Проверено 11 апреля 2013 .
  12. ^ «Разметка» . GitHub . GitHub. 2014-12-25 . Проверено 8 февраля 2015 .

Дальнейшее чтение [ править ]

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

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