WikiDer > Страница руководства - Википедия

man page - Wikipedia

Страница руководства на мужчина (1), как видно из различных Дистрибутивы Linux. Эта версия утилиты предшествует самой Linux, но теперь поддерживается Debian проект.

А страница руководства (Короче для страница руководства) является формой документация по программному обеспечению обычно встречается на Unix или же Unix-подобный Операционная система. Охваченные темы включают компьютерные программы (включая библиотека и системные вызовы), формальных стандартов и условностей и даже абстрактных концепций. А Пользователь может вызвать страницу руководства, выполнив человек команда.

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

Поскольку страницы руководства распространяются вместе с программным обеспечением, которое они документируют, они являются более подходящим средством документирования программного обеспечения по сравнению с из группы документация как веб-страница, поскольку существует большая вероятность совпадения фактических функций программного обеспечения с задокументированными.[1]По этой причине man-страницы часто называют онлайн или же онлайн форма документации к ПО,[2] хотя человек команда не требует доступа в Интернет, начиная с тех времен, когда печаталась из группы мануалы были нормой.

История

Икс-мэн, человек-Икс, рано X11 приложение для просмотра страниц руководства
OpenBSD раздел 8 вводная страница руководства, отображаемая в текстовой консоли

В первые два года история Unix, документации не существовало.[3] В Руководство программиста Unix была впервые опубликована 3 ноября 1971 года. Первые реальные страницы руководства были написаны Деннис Ричи и Кен Томпсон по настоянию[нужна цитата] их менеджера Дуг Макилрой в 1971 году. Помимо страниц руководства, Руководство программиста также накопился набор коротких работ, некоторые из них учебные пособия (например, для общего использования Unix C язык программирования и такие инструменты, как Yacc) и другие более подробные описания функций операционной системы. Печатная версия руководства изначально помещалась в единую папку, но по состоянию на PWB / UNIX и 7-е издание из Исследование Unix, он был разделен на два тома, а печатные страницы руководства составляли Том 1.[4]

Более поздние версии документации имитировали лаконичность первых страниц руководства. Ричи добавил в раздел «Как начать» Третье издание введение и Лоринда Черри предоставил карманный справочник "Purple Card" для Шестой и Седьмой Издания.[3] Версии программного обеспечения были названы в честь редакции руководства; седьмое издание Руководство программиста Unix, например, поставлялся с 7-м изданием или версией 7 Unix.[5]

Для Четвертый Edition страницы руководства были отформатированы с использованием Troff наборный пакет[3] и его набор -человек макросы (которые были полностью переработаны между Шестым и Седьмым изданиями Руководство,[4] но с тех пор кардинально не изменились). В то время доступность онлайн-документации через систему справочных страниц считалась большим достижением. По сей день практически каждое приложение командной строки Unix имеет справочную страницу, и многие пользователи Unix воспринимают отсутствие справочных страниц в программе как признак низкого качества; действительно, некоторые проекты, такие как Debian, стараются изо всех сил писать справочные страницы для программ, в которых он отсутствует. Современные потомки 4.4BSD также распространять справочные страницы как одну из основных форм системной документации (заменив старую -человек макросы с более новой -mdoc).

Был скрытый пасхальное яйцо в версии man-db команды man, которая заставляла бы команду возвращать "gimme gimme gimme" при запуске в 00:30 (ссылка на ABBA песня Дай мне! Дай мне! Дай мне! (Мужчина после полуночи). Представлен в 2011 году.[6] но сначала ограничено[7] а затем удален в 2017 году[8] после того, как его наконец нашли.[9]

Форматирование

Часть FreeBSD мужчина (1) справочная страница, набранная в PDF формат.

Формат страниц руководства по умолчанию: Troff, либо с пакет макросов мужчина (ориентированный на внешность) или mdoc (смысловая направленность). Это позволяет набирать справочную страницу в PostScript, PDF, и различные другие форматы для просмотра или печати.

Наиболее Unix системы имеют пакет для man2html команда, которая позволяет пользователям просматривать свои справочные страницы с помощью HTML-браузера (textproc / man2html на FreeBSD или же человек на некоторых Linux дистрибутивов). GNU Emacs программа Женщина (от "WithOut man") позволяет просматривать справочные страницы из редактора.[10]

В 2010, OpenBSD устарел Troff для форматирования страниц в пользу Mandoc, специализированный компилятор / форматировщик для страниц с встроенной поддержкой вывода в PostScript, HTML, XHTML, и терминал. Он предназначен только для поддержки подмножества troff, используемого на страницах руководства, особенно тех, которые используют макросы mdoc.

Онлайн-сервисы

Довольно много веб-сайтов предлагают онлайн-доступ к страницам руководства из различных Unix-подобных систем.

В феврале 2013 г. BSD сообщество увидело новый открытый исходный код mdoc.su запущен сервис, который унифицировал и сократил доступ к сценариям man.cgi основных современных проектов BSD через уникальный nginxдетерминированный Сокращение URL сервис для страниц руководства * BSD.[11][12][13]

Для Linux настроена служба man7.org для обслуживания руководств, относящихся к системе.[14] Сервис ManKier предоставляет более широкий выбор, а также интегрирует страницы TLDR.[15]

Использование команд

Чтобы прочитать страницу руководства для команды Unix, пользователь может ввести:

мужчина <имя_команды>

Страницы традиционно упоминаются с использованием обозначения «имя (раздел)»: например, ftp (1). В этом разделе описаны различные способы ссылки на тему - например, системный вызов, команда или пакет оболочки (командной строки), файл конфигурации пакета или конструкция / заголовок кодирования.

Одно и то же имя страницы может присутствовать в нескольких разделах руководства, например, когда имена системные вызовы, Пользователь команды, или же пакеты макросов совпадают. Примеры мужчина (1) и мужчина (7), или же выход (2) и выход (3). Синтаксис для доступа к разделу руководства, отличному от заданного по умолчанию, варьируется в зависимости от реализации man.

В Solaris и illumos, например, синтаксис для чтения printf (3C) является:

мужчина -s 3c printf

В производных от Linux и BSD такой же вызов будет:

человек 3 printf

который ищет printf в разделе 3 справочных страниц.

Разделы руководства

Руководство обычно делится на восемь пронумерованных разделов, организованных следующим образом (на Исследование Unix, BSD, macOS и Linux):[16][17][18][19]

РазделОписание
1Общий команды
2Системные вызовы
3Библиотека функции, охватывающие, в частности, Стандартная библиотека C
4Специальные файлы (обычно устройства, которые находятся в / dev) и водители
5Форматы файлов и условности
6Игры и заставки
7Разное
8Системное администрирование команды и демоны

Unix Система V использует аналогичную схему нумерации, но в другом порядке:[20]

РазделОписание
1Общий команды
1 млнСистемное администрирование команды и демоны
2Системные вызовы
3Библиотека C функции
4Форматы файлов и условности
5Разное
6Игры и заставки
7Специальные файлы (обычно устройства, которые находятся в / dev) и водители

В некоторых системах доступны некоторые из следующих разделов:

РазделОписание
0Библиотека C файлы заголовков (Unix v6)
9Ядро подпрограммы (FreeBSD, SVR4, Linux)[19][17]
пTcl/Тк ключевые слова
ИксВ X Window System

Некоторые разделы дополнительно подразделяются с помощью суффикса; например, в некоторых системах раздел 3C предназначен для вызовов библиотеки C, 3M - для математической библиотеки и так далее. Следствием этого является то, что раздел 8 (команды системного администрирования) иногда отнесен к подразделу 1M раздела основных команд. Некоторые суффиксы подразделов имеют общее значение в разделах:

ПодразделОписание
пPOSIX технические характеристики
ИксX Window System документация

(Раздел 3 обычно является исключением из-за множества суффиксов для разных языков.)

Некоторые версии человек кэшировать отформатированные версии нескольких последних просмотренных страниц. Одна форма - это страница кошки, просто передается на пейджер для отображения.

Макет

Все страницы руководства имеют общий макет, оптимизированный для представления на простом ASCII отображение текста, возможно, без какой-либо формы выделения или управления шрифтом. Присутствующие разделы могут включать:[21](СТРУКТУРА РУКОВОДСТВА)

ИМЯ
Имя команды или функции, за которым следует однострочное описание того, что она делает.
ОБЗОР
В случае команды - формальное описание того, как ее запускать и какие параметры командной строки она принимает. Для программных функций - список параметров, которые принимает функция, и заголовочный файл, содержащий ее объявление.
ОПИСАНИЕ
Текстовое описание функционирования команды или функции.
ПРИМЕРЫ
Некоторые примеры общего использования.
СМОТРИТЕ ТАКЖЕ
Список связанных команд или функций.

Могут присутствовать и другие разделы, но они недостаточно стандартизированы на страницах руководства. Типичные примеры: ОПЦИИ, СТАТУС ВЫХОДА, ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ, ОКРУЖЕНИЕ, ОШИБКИ, ФАЙЛЫ, АВТОР, СООБЩЕНИЕ ОБ ОШИБКАХ, ИСТОРИЯ и АВТОРСКИЕ ПРАВА.

Авторская

Страницы руководства могут быть написаны на старом человек макросы, новые док макросы или их комбинация (Mandoc).[22] В человек набор макросов обеспечивает минимальный богатый текст функции, с директивами для строки заголовка, заголовков разделов, (полужирный, мелкий или курсив) шрифтов, абзацев и добавления / уменьшения отступа.[23] Новее mdoc язык имеет более семантический характер и содержит специализированные макросы для большинства стандартных разделов, таких как имя программы, синопсис, имена функций и имена авторов. Эта информация может быть использована для реализации семантический поиск для руководств по таким программам, как Mandoc. Хотя он также включает директивы для непосредственного управления стилем, ожидается, что специализированные макросы охватят большинство вариантов использования.[21]

Хотя страницы руководства представляют собой текст, разбитый на 10 пунктов Римский шрифт, Это различие, как правило, вопрос спорный, потому что страницы человека рассматриваются в терминале (TTY), а раскладывают на бумаге. В результате макрос «мелкий шрифт» используется редко.[24] С другой стороны, полужирный и курсивный текст поддерживается терминалом через ECMA-48, и Гроффа безобразный испускает их по запросу, когда обнаруживает поддерживающий терминал. BSD mandoc, однако, поддерживает только полужирный и подчеркнутый текст через последовательность пишущей машинки с заменой символа обратного пробела, которая должна быть переведена в ECMA-48 с помощью меньше.[25][26]

Страницы руководства обычно написаны на английском языке, но в системе могут быть доступны переводы на другие языки. GNU человек-дб и мандок человек известен тем, что ищет локализованные справочные страницы в подкаталогах.[27][16](Обзор)[17]

Альтернативы

Мало альтернатив человек пользовались большой популярностью, за возможным исключением Проект GNU "Информация"система, ранняя и простая гипертекст система. Есть также сторонние усилия, известные как "TL; DR страниц ", который предоставляет простые примеры для распространенных случаев использования, аналогичные шпаргалка.[28]

Кроме того, некоторые Unix GUI приложения (особенно созданные с использованием ГНОМ и KDE среды разработки) теперь предоставляют документацию для конечных пользователей на HTML и включить встроенные средства просмотра HTML, такие как визг для чтения справки в приложении.

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

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

  1. ^ der Mouse (30 марта 2019 г.). "Веб" документация "[была Re: Удаление PF]". tech-kern @ NetBSD (Список рассылки). NetBSD. Получено 2019-04-01.
  2. ^ "man (1) - отображать страницы документации онлайн-руководства". Перекрестная ссылка BSD. FreeBSD. Получено 2019-04-01. Сложить резюме. Утилита man находит и отображает страницы документации онлайн-руководства.
  3. ^ а б c Макилрой, М.Д. (1987). Читатель Research Unix: аннотированные выдержки из Руководства программиста, 1971–1986 (PDF) (Технический отчет). CSTR. Bell Labs. 139.
  4. ^ а б Дарвин, Ян; Коллиер, Джеффри. "Эволюция UNIX: 1975-1984 гг. Часть I - Разнообразие". Получено 22 декабря 2012. Первоначально опубликовано в Микросистемы 5(11), ноябрь 1984 г.
  5. ^ Фидлер, Райан (октябрь 1983 г.). "Учебное пособие по Unix / Часть 3: Unix на рынке микрокомпьютеров". БАЙТ. п. 132. Получено 30 января 2015.
  6. ^ "GIT коммит 002a6339b1fe8f83f4808022a17e1aa379756d99". Получено 22 ноября 2017.
  7. ^ "GIT совершает 84bde8d8a9a357bd372793d25746ac6b49480525". Получено 22 ноября 2017.
  8. ^ "GIT совершает b225d9e76fbb0a6a4539c0992fba88c83f0bd37e". Получено 25 сентября 2018.
  9. ^ ""Почему мужчина печатает «дай мне дай мне дай» в 00:30?"". Получено 22 ноября 2017.
  10. ^ Райт, Фрэнсис Дж. "WoMan: Обзор страниц руководств по Unix" W.O. (без) человек"". GNU. Получено 3 августа 2020.
  11. ^ Пали, Габор, изд. (12 мая 2013 г.). «Ежеквартальный отчет о состоянии FreeBSD, январь-март 2013 г.». FreeBSD. Получено 25 декабря 2014.
  12. ^ Муренин, Константин А. (19 февраля 2013 г.). "объявление mdoc.su, короткие URL страницы руководства". [email protected] (Список рассылки). Получено 25 декабря 2014.
  13. ^ Муренин, Константин А. (23 февраля 2013 г.). "mdoc.su - Краткие URL-адреса страниц руководства для FreeBSD, OpenBSD, NetBSD и DragonFly BSD". Получено 25 декабря 2014.
  14. ^ "Справочные страницы Linux в Интернете". man7.org.
  15. ^ "О". ManKier.
  16. ^ а б мужчина (1) – Linux Общие команды Руководство
  17. ^ а б c мужчина (1) – FreeBSD Общие команды Руководство
  18. ^ "Справочные страницы для исследований Unix, восьмое издание". man.cat-v.org.
  19. ^ а б "Руководство программиста Unix - Введение". www.bell-labs.com. 3 ноября 1971 г.
  20. ^ "System V выпуск 4 руководства". bitsavers.trailing-edge.com.
  21. ^ а б mdoc (7) – FreeBSD Разнообразная информация Руководство
  22. ^ groff_tmac (5) – Linux Форматы файлов Руководство
  23. ^ мужчина (7) – Linux Разное Руководство
  24. ^ "человек". Руководство GNU Troff. Получено 31 декабря 2019.
  25. ^ «Курсив и цвет на страницах руководства на виртуальном терминале nosh в пользовательском пространстве». jdebp.eu.
  26. ^ мандок (1) – FreeBSD Общие команды Руководство. «Стили шрифтов применяются с использованием кодировки с обратным интервалом ...»
  27. ^ "командная строка - справочные страницы Linux на разных языках". Спросите Ubuntu.
  28. ^ "Страницы TLDR". tldr.sh.

внешняя ссылка

Статья основана на материалах, взятых из Бесплатный онлайн-словарь по вычислительной технике до 1 ноября 2008 г. и зарегистрированы в соответствии с условиями «перелицензирования» GFDL, версия 1.3 или новее.