страница руководства - man page

Страница руководства по man (1) в различных дистрибутивах Linux . Эта версия взята из man-db.

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

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

Страницы руководства часто называют онлайновой или онлайновой формой документации по программному обеспечению, даже если для этой manкоманды не требуется доступ в Интернет, что относится к тем временам, когда печатные внеполосные руководства были нормой.

История

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

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

Более поздние версии документации имитировали лаконичность первых страниц руководства. Ричи добавил раздел «Как начать» к введению к третьему изданию , а Лоринда Черри предоставила карманный справочник «Пурпурная карта» для шестого и седьмого изданий. Версии программного обеспечения были названы в честь редакции руководства; седьмое издание Руководства программиста Unix , например, пришло с 7-м изданием или версией 7 Unix.

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

В версии man-db команды man было скрытое пасхальное яйцо , которое заставляло команду возвращать "gimme gimme gimme" при запуске в 00:30 (отсылка к песне ABBA Gimme! Gimme! Gimme! (Человек После полуночи) . Он был представлен в 2011 году, но сначала был ограничен, а затем был удален в 2017 году после того, как был наконец обнаружен.

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

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

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

В некоторых системах Unix есть пакет для команды man2html , которая позволяет пользователям просматривать свои справочные страницы с помощью HTML-браузера. Системы с groff и man-db должны использовать вместо этого высококачественный собственный HTML-вывод ( man --html ). GNU Emacs Программа женщина (от «без человека») позволяет просматривать человек страниц из редактора.

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

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

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

В феврале 2013 года сообщество BSD увидело запуск новой службы mdoc.su с открытым исходным кодом , которая унифицировала и сократила доступ к сценариям man.cgi основных современных проектов BSD с помощью уникальной службы детерминированного сокращения URL-адресов на основе nginx для * BSD man. страниц.

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

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

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

man <command_name>

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

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

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

man -s 3c printf

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

man 3 printf

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

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

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

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

Системные вызовы POSIX часто присутствуют в разделах 2 и 3, где раздел 2 содержит документацию по системным вызовам из локальной операционной системы, а раздел 3 содержит документацию по системным вызовам из Руководства программиста POSIX.

В Unix System V используется аналогичная схема нумерации, но в другом порядке:

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

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

Раздел Описание
0 Заголовочные файлы библиотеки C (Unix v6)
9 Подпрограммы ядра (FreeBSD, SVR4, Linux)
л Функции библиотеки LAPACK
п Команды Tcl / Tk
Икс Система X Window

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

Подраздел Описание
п Спецификации POSIX
Икс Документация по системе X Window

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

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

Макет

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

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

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

Авторская

Страницы руководства могут быть написаны либо в старых manмакросах, либо в новых docмакросах, либо в их комбинации ( mandoc). Набор manмакросов предоставляет минимальные функции форматированного текста с директивами для строки заголовка, заголовков разделов, (полужирный, мелкий или курсив) шрифтов, абзацев и добавления / уменьшения отступа. Новый mdocязык более семантический по своей природе и содержит специализированные макросы для большинства стандартных разделов, таких как имя программы, синопсис, имена функций и имена авторов. Эта информация может быть использована для реализации семантического поиска руководств такими программами, как mandoc . Хотя он также включает директивы для непосредственного управления стилем, ожидается, что специализированные макросы охватят большинство вариантов использования. И проекты mandoc, и groff считают mdocпредпочтительный формат для новых документов.

Хотя man-страницы для troff представляют собой текст, набранный римским шрифтом из 10 пунктов , это различие обычно спорно, потому что man-страницы просматриваются в терминале (TTY), а не на бумаге. В результате макрос «мелкий шрифт» используется редко. С другой стороны, полужирный и курсивный текст поддерживается терминалом через ECMA-48 , и groff grottyвыдает их по запросу, когда обнаруживает поддерживающий терминал. Однако стандарт BSD поддерживает только полужирный и подчеркнутый (как замену курсиву) текст с помощью последовательности «backspace-then-overstrike» пишущей машинки, которая должна быть переведена в ECMA-48 с помощью less.

Страницы руководства обычно написаны на английском языке, но в системе могут быть доступны переводы на другие языки. Известно, что GNU man-dbи mandoc manищут локализованные справочные страницы в подкаталогах.

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

Несколько альтернатив, manкоторые пользовались большой популярностью, за исключением, возможно, системы GNU Project " info", ранней и простой гипертекстовой системы. Существует также сторонняя программа, известная как TLDR pages ( tldr), которая предоставляет простые примеры для распространенных случаев использования, похожие на шпаргалку .

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

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

использованная литература

внешние ссылки