Страница человека (сокращенно странице руководства ) является формой программной документации обычно можно найти на Unix или Unix-подобных операционных систем . Охватываемые темы включают компьютерные программы (включая библиотечные и системные вызовы ), формальные стандарты и соглашения и даже абстрактные концепции. Пользователь может вызвать страницу человека, выполнив man
команду .
По умолчанию man
обычно используется программа терминального пейджера, такая как more
или, less
для отображения ее вывода.
Страницы руководства часто упоминаются как онлайновая или онлайновая форма документации по программному обеспечению [1], хотя для этой man
команды не требуется доступ в Интернет, начиная с тех времен, когда печатные внеполосные руководства были нормой.
История
В первые два года истории Unix документации не существовало. [2] В Руководство Unix программиста впервые был опубликован 3 ноября 1971 г. Первые фактические страницы человека были написаны Деннис Ритчи и Кен Томпсон по настоянию [ править ] их менеджер Дуг Макилрой в 1971. Помимо человека страниц, Руководство программиста также накопилось множество коротких статей, некоторые из них учебники (например , для общего использования Unix, то C язык программирования, и инструменты , такие как Yacc ), и другие , более подробные описания операционных функций системы. Печатная версия руководство изначально уместиться в одном связующем, а также из PWB / UNIX и 7 - е издание из Исследовательского Unix , он был разбит на два тома с напечатанных страниц человека , образующих Том 1. [3]
Более поздние версии документации имитировали лаконичность первых страниц руководства. Ричи добавил раздел «Как начать» к введению к третьему изданию , а Лоринда Черри предоставила карманный справочник «Пурпурная карта» для шестого и седьмого изданий. [2] Версии программного обеспечения были названы в честь редакции руководства; седьмое издание Руководства программиста Unix , например, пришло с 7-м изданием или версией 7 Unix. [4]
Для Четвертого издания страницы руководства были отформатированы с использованием пакета набора troff [2] и его набора -man
макросов (которые были полностью пересмотрены между Шестым и Седьмым изданиями Руководства , [3], но с тех пор кардинально не изменились). В то время доступность онлайн-документации через систему справочных страниц считалась большим достижением. По сей день практически каждое приложение командной строки Unix поставляется со страницей руководства, и многие пользователи Unix воспринимают отсутствие страниц руководства в программе как признак низкого качества; действительно, некоторые проекты, такие как Debian , стараются изо всех сил писать справочные страницы для программ, в которых он отсутствует. Современные потомки 4.4BSD также распространяют страницы руководства как одну из основных форм системной документации (заменив старые -man
макросы на новые -mdoc
).
В версии man-db команды man было скрытое пасхальное яйцо , которое заставляло команду возвращать "gimme gimme gimme" при запуске в 00:30 (отсылка к песне ABBA Gimme! Gimme! Gimme! (Человек После полуночи) . Он был представлен в 2011 году [5], но сначала был ограничен [6], а затем удален в 2017 году [7] после того, как был окончательно обнаружен [8].
Форматирование
Форматом страниц руководства по умолчанию является troff , либо с макро-пакетом man (ориентированным на внешний вид), либо с mdoc (ориентированным на семантику). Это позволяет набирать справочную страницу в PostScript , PDF и другие различные форматы для просмотра или печати.
В некоторых системах Unix есть пакет для man2html , которая позволяет пользователям просматривать свои справочные страницы с помощью HTML-браузера. Системы с groff и man-db должны использовать высококачественный собственный HTML-вывод ( man --html ) вместо этого. GNU Emacs Программа женщина (от «без человека») позволяет просматривать человек страниц из редактора. [9]
В 2010 году OpenBSD отказался от troff для форматирования man-страниц в пользу mandoc , специализированного компилятора / форматировщика для man-страниц с встроенной поддержкой вывода в PostScript , HTML , XHTML и терминал. Он предназначен только для поддержки подмножества troff, используемого на страницах руководства, особенно тех, которые используют макросы mdoc.
Онлайн-сервисы
Довольно много веб-сайтов предлагают онлайн-доступ к страницам руководства из различных Unix-подобных систем.
В феврале 2013 года сообщество BSD увидело запуск новой службы mdoc.su с открытым исходным кодом , которая унифицировала и сократила доступ к сценариям man.cgi основных современных проектов BSD с помощью уникальной службы детерминированного сокращения URL-адресов на основе nginx для * BSD man. страниц. [10] [11] [12]
Для Linux настроена служба man7.org для обслуживания руководств, относящихся к системе. [13] Сервис ManKier предоставляет более широкий выбор и также интегрирует страницы TLDR. [14]
Использование команд
Чтобы прочитать страницу руководства для команды Unix, пользователь может ввести:
мужчина <имя_команды>
Страницы традиционно обозначаются обозначением «имя (раздел)»: например
,. В этом разделе описаны различные способы ссылки на тему - например, как системный вызов, или команда или пакет оболочки (командной строки), или файл конфигурации пакета, или как конструкция / заголовок кодирования.Одно и то же имя страницы может появляться в нескольких разделах руководства, например, когда совпадают имена системных вызовов , пользовательских команд или пакетов макросов . Примеры:
и , или и . Синтаксис доступа к разделу руководства, отличному от заданного по умолчанию, варьируется в зависимости от реализации man.Например, в Solaris и illumos синтаксис чтения
:мужчина -s 3c printf
В производных от Linux и BSD такой же вызов будет:
мужчина 3 printf
который ищет printf в разделе 3 справочных страниц.
Разделы руководства
Руководство обычно делится на восемь пронумерованных разделов, организованных следующим образом (по Research Unix , BSD , macOS и Linux ): [15] [16] [17] [18]
Раздел | Описание |
---|---|
1 | Общие команды |
2 | Системные вызовы |
3 | Библиотечные функции, охватывающие, в частности, стандартную библиотеку C |
4 | Специальные файлы (обычно устройства, которые находятся в / dev) и драйверы |
5 | Форматы файлов и соглашения |
6 | Игры и заставки |
7 | Разнообразный |
8 | Команды и демоны системного администрирования |
Системные вызовы POSIX часто присутствуют в разделах 2 и 3, где раздел 2 содержит документацию по системным вызовам из локальной операционной системы, а раздел 3 содержит документацию по системным вызовам из Руководства программиста POSIX. [ необходима цитата ]
В Unix System V используется аналогичная схема нумерации, но в другом порядке: [19]
Раздел | Описание |
---|---|
1 | Общие команды |
1 млн | Команды и демоны системного администрирования |
2 | Системные вызовы |
3 | Функции библиотеки C |
4 | Форматы файлов и соглашения |
5 | Разное |
6 | Игры и заставки |
7 | Специальные файлы (обычно устройства, которые находятся в / dev) и драйверы |
В некоторых системах доступны некоторые из следующих разделов:
Раздел | Описание |
---|---|
0 | Заголовочные файлы библиотеки C (Unix v6) |
9 | Подпрограммы ядра (FreeBSD, SVR4, Linux) [18] [16] |
л | Библиотечные функции LAPACK [20] |
п | Команды Tcl / Tk |
Икс | Система X Window |
Некоторые разделы далее подразделяются с помощью суффикса; например, в некоторых системах раздел 3C предназначен для вызовов библиотеки C, 3M - для математической библиотеки и так далее. Следствием этого является то, что раздел 8 (команды системного администрирования) иногда отнесен к подразделу 1M раздела основных команд. Некоторые суффиксы подразделов имеют общее значение в разделах:
Подраздел | Описание |
---|---|
п | Спецификации POSIX |
Икс | Документация по системе X Window |
(Раздел 3 обычно является исключением из-за множества суффиксов для разных языков.)
Некоторые версии man кэшируют отформатированные версии нескольких последних просмотренных страниц. Одна из форм - это страница-кошка , которая просто передается на пейджер для отображения.
Макет
Все страницы руководства имеют общий макет, оптимизированный для представления на простом текстовом дисплее ASCII , возможно, без какой-либо формы выделения или управления шрифтом. Присутствующие разделы могут включать: [21] ( СТРУКТУРА РУКОВОДСТВА )
- НАЗВАНИЕ
- Имя команды или функции, за которым следует однострочное описание того, что она делает.
- ОБЗОР
- В случае команды - формальное описание того, как ее запускать и какие параметры командной строки она принимает. Для программных функций - список параметров, которые принимает функция, и заголовочный файл, содержащий ее объявление.
- ОПИСАНИЕ
- Текстовое описание функционирования команды или функции.
- ПРИМЕРЫ
- Некоторые примеры общего использования.
- СМОТРИТЕ ТАКЖЕ
- Список связанных команд или функций.
Могут присутствовать и другие разделы, но они недостаточно стандартизированы на страницах руководства. Типичные примеры: ОПЦИИ, СТАТУС ВЫХОДА, ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ, ОКРУЖЕНИЕ, ОШИБКИ, ФАЙЛЫ, АВТОР, СООБЩЕНИЕ ОБ ОШИБКАХ, ИСТОРИЯ и АВТОРСКИЕ ПРАВА.
Авторская
Страницы руководства могут быть написаны либо в старых man
макросах, либо в новых doc
макросах, либо в их комбинации ( mandoc
). [22] Набор man
макросов предоставляет минимальные функции форматированного текста с директивами для строки заголовка, заголовков разделов, (полужирный, мелкий или курсив) шрифтов, абзацев и добавления / уменьшения отступа. [23] Новый mdoc
язык более семантический по своей природе и содержит специализированные макросы для большинства стандартных разделов, таких как имя программы, синопсис, имена функций и имена авторов. Эта информация может использоваться для реализации семантического поиска руководств такими программами, как mandoc . Хотя он также включает директивы для непосредственного управления стилем, ожидается, что специализированные макросы охватят большинство вариантов использования. [21] Оба проекта - mandoc и groff - считают mdoc
предпочтительным формат для новых документов. [24]
Хотя man-страницы для troff представляют собой текст, набранный римским шрифтом из 10 пунктов , это различие обычно спорно, потому что man-страницы просматриваются в терминале (TTY), а не на бумаге. В результате макрос «мелкий шрифт» используется редко. [25] С другой стороны, полужирный и курсивный текст поддерживается терминалом через ECMA-48 , и groff grotty
отправляет их по запросу, когда обнаруживает поддерживающий терминал. Однако стандарт BSD поддерживает только полужирный и подчеркнутый (как замену курсиву) текст с помощью последовательности «backspace-then-overstrike» пишущей машинки, которая должна быть переведена в ECMA-48 с помощью less
. [26] [27]
Страницы руководства обычно написаны на английском языке, но в системе могут быть доступны переводы на другие языки. Известно, что GNU man-db
и mandoc man
ищут локализованные справочные страницы в подкаталогах. [28] [15] ( Обзор ) [16]
Альтернативы
Несколько альтернатив, man
которые пользовались большой популярностью, за исключением, возможно, системы GNU Project " info
", ранней и простой гипертекстовой системы. Существует также сторонняя программа, известная как TLDR pages ( tldr
), которая предоставляет простые примеры для распространенных случаев использования, похожие на шпаргалку . [29]
Кроме того, некоторые приложения с графическим интерфейсом пользователя Unix (особенно те, которые созданы с использованием сред разработки GNOME и KDE ) теперь предоставляют документацию для конечных пользователей в формате HTML и включают встроенные средства просмотра HTML, например, yelp
для чтения справки внутри приложения.
Смотрите также
- Список команд Unix
- Список приложений Plan 9
- Информация
- по поводу
- ПРОЧТИ МЕНЯ
- RTFM
- ManOpen - графическая утилита man для NeXT / macOS
Рекомендации
- ^ "man (1) - отображать страницы документации онлайн-руководства" . Перекрестная ссылка BSD . FreeBSD . Проверено 1 апреля 2019 . Выложите резюме .
Утилита man находит и отображает страницы документации онлайн-руководства.
- ^ а б в Макилрой, доктор медицины (1987). Читатель Research Unix: аннотированные выдержки из Руководства программиста, 1971–1986 (PDF) (технический отчет). CSTR. Bell Labs. 139.
- ^ а б Дарвин, Ян; Коллиер, Джеффри. «Эволюция UNIX: 1975–1984 Часть I - Разнообразие» . Проверено 22 декабря 2012 года .Первоначально опубликовано в Microsystems 5 (11), ноябрь 1984 г.
- ^ Фидлер, Райан (октябрь 1983 г.). «Учебник по Unix / Часть 3: Unix на рынке микрокомпьютеров» . БАЙТ . п. 132 . Проверено 30 января 2015 года .
- ^ "GIT коммит 002a6339b1fe8f83f4808022a17e1aa379756d99" . Проверено 22 ноября 2017 года .
- ^ "GIT совершает 84bde8d8a9a357bd372793d25746ac6b49480525" . Проверено 22 ноября 2017 года .
- ^ "GIT совершает b225d9e76fbb0a6a4539c0992fba88c83f0bd37e" . Проверено 25 сентября 2018 года .
- ^ « » Почему люди печать «дай дай дай» в 00:30? " " . Проверено 22 ноября 2017 года .
- ^ Райт, Фрэнсис Дж. "WoMan: Просмотрите страницы руководства Unix" WO (без) Man " " . GNU . Дата обращения 3 августа 2020 .
- ^ Пали, Габор, изд. (12 мая 2013 г.). «Ежеквартальный отчет о состоянии FreeBSD, январь-март 2013 г.» . FreeBSD . Проверено 25 декабря 2014 .
- ^ Муренин, Константин А. (19 февраля 2013 г.). "объявление mdoc.su, короткие URL-адреса страниц руководства" . [email protected] (список рассылки) . Проверено 25 декабря 2014 .
- ^ Муренин, Константин А. (23 февраля 2013 г.). «mdoc.su - Краткие URL-адреса страниц руководства для FreeBSD, OpenBSD, NetBSD и DragonFly BSD» . Проверено 25 декабря 2014 .
- ^ "Справочные страницы Linux в Интернете" . man7.org .
- ^ «О» . ManKier .
- ^ a b - Руководство по основным командам Linux
- ^ a b c - Руководство по основным командам FreeBSD
- ^ "Справочные страницы для исследований Unix, восьмое издание" . man.cat-v.org .
- ^ а б "Руководство программиста Unix - Введение" . www.bell-labs.com . 3 ноября 1971 г.
- ^ "System V выпуск 4 руководства" . bitsavers.trailing-edge.com .
- ^ "Lapack (l) - Справочные страницы Linux" . www.systutorials.com . Проверено 29 мая 2021 .
- ^ a b - Руководство по разной информации FreeBSD
- ^ - Руководство по форматам файлов Linux
- ^ - Руководство Linux Miscellanea
- ^ «Заявление о миссии Groff - 2014» . www.gnu.org .
Параллельно с работой над man (7) будет активно поддерживаться mdoc (7) и продвигаться его использование.
- ^ "мужчина" . Руководство GNU Troff . Проверено 31 декабря 2019 года .
- ^ «Курсив и цвет на страницах руководства виртуального терминала nosh в пользовательском пространстве» . jdebp.eu .
- ^ - Руководство по основным командам FreeBSD . «Стили шрифтов применяются с использованием кодировки с обратным интервалом ...»
- ^ «командная строка - справочные страницы Linux на разных языках» . Спросите Ubuntu .
- ^ «Страницы TLDR» . tldr.sh .
Внешние ссылки
- History of UNIX Manpages для истории первоисточников UNIX Manpages.
- Репозиторий страниц руководства UNIX и Linux с почти 300 000 хорошо отформатированных страниц руководства.
- Что означают числа на странице руководства?
Эта статья основана на материалах, взятых из Free On-line Dictionary of Computing до 1 ноября 2008 г. и включенных в соответствии с условиями «перелицензирования» GFDL версии 1.3 или новее.