справочная страница
Страница руководства (сокращение от « страница руководства» ) — это форма документации по программному обеспечению, обычно встречающаяся в Unix или Unix-подобных операционных системах . Рассматриваемые темы включают компьютерные программы (включая библиотечные и системные вызовы ), формальные стандарты и соглашения и даже абстрактные концепции. Пользователь может вызвать справочную страницу , выполнив команду man команда .
По умолчанию, man обычно использует программу терминального пейджера, такую как more или less для отображения его вывода.
Страницы руководства часто называют онлайн - . формой документации по программному обеспечению [ 1 ] хотя man Команда не требует доступа в Интернет, начиная с тех времен, когда печатные руководства по внешнему интерфейсу были нормой.
История
[ редактировать ]
До появления Unix (например, GCOS ) документация представляла собой распечатанные страницы, доступные пользователям (сотрудникам, студентам...), организованные в стальные папки, скрепленные в одну монолитную стальную стойку для чтения, прикрепленную болтами к столу или стойке, с страницы организованы для модульных обновлений, замен, исправлений и дополнений. [ нужна ссылка ]
В первые два года истории Unix не существовало никакой документации. [ 2 ] было «Руководство программиста Unix» впервые опубликовано 3 ноября 1971 года. Первые настоящие справочные страницы были написаны Деннисом Ритчи и Кеном Томпсоном по настоянию [ нужна ссылка ] их менеджера Дуга Макилроя в 1971 году. Помимо справочных страниц, в «Руководстве программиста» также собран набор коротких статей, некоторые из которых представляют собой учебные пособия (например, по общему использованию Unix, языку программирования C и таким инструментам, как Yacc ), а другие более подробные описания возможностей операционной системы. Печатная версия руководства изначально помещалась в одну подшивку, но начиная с PWB/UNIX и 7-го издания Research Unix , она была разделена на два тома, причем печатные страницы руководства составляли том 1. [ 3 ]
Более поздние версии документации имитировали краткость первых страниц руководства. Ричи добавил раздел «Как начать» во введение к третьему изданию , а Лоринда Черри предоставила карманный справочник «Фиолетовая карта» для шестого и седьмого изданий. [ 2 ] Версии программного обеспечения были названы в честь редакции руководства; седьмое издание « Руководства программиста Unix» входило в состав 7-го издания или версии 7 Unix. например, [ 4 ]
В четвертом издании страницы руководства были отформатированы с использованием troff. пакета набора текста [ 2 ] и его набор -man макросы (которые были полностью переработаны между шестым и седьмым изданиями Руководства , [ 3 ] но с тех пор кардинально не изменились). В то время доступность онлайн-документации через систему страниц руководства считалась большим достижением. По сей день практически каждое приложение командной строки Unix имеет справочную страницу, и многие пользователи Unix воспринимают отсутствие справочных страниц программы как признак низкого качества; действительно, некоторые проекты, такие как Debian , изо всех сил стараются писать справочные страницы для программ, у которых их нет. Современные потомки 4.4BSD также распространяют справочные страницы как одну из основных форм системной документации (заменив старые -man макросы с более новой версией -mdoc).
было скрытое пасхальное яйцо В версии man-db команды man ABBA , которое заставляло команду возвращать «дай мне, дай мне, дай мне» при запуске в 00:30 (отсылка к песне Gimme! Gimme! Gimme! (A Man) После полуночи) Был представлен в 2011 году. [ 5 ] но сначала ограничил [ 6 ] а затем удален в 2017 году [ 7 ] после того, как его наконец нашли. [ 8 ]
Форматирование
[ редактировать ]
Формат страниц руководства по умолчанию — troff с макропакетом man (ориентированный на внешний вид) или mdoc (ориентированный на семантику). Это позволяет верстать справочную страницу в PostScript , PDF и различные другие форматы для просмотра или печати.
Некоторые системы Unix имеют пакет для Команда man2html , которая позволяет пользователям просматривать свои справочные страницы с помощью HTML-браузера. Системы с groff и man-db должны использовать собственный HTML-вывод более высокого качества ( man --html ) вместо этого. Программа GNU Emacs WoMan (от «WithOut man») позволяет просматривать справочные страницы из редактора. [ 9 ]
В 2010 году OpenBSD отказалась от использования troff для форматирования man-страниц в пользу mandoc , специализированного компилятора/форматера для man-страниц со встроенной поддержкой вывода в PostScript , HTML , XHTML и терминал. Он предназначен для поддержки только подмножества troff, используемого на страницах руководства, особенно тех, которые используют макросы mdoc.
Онлайн-сервисы
[ редактировать ]Довольно много веб-сайтов предлагают онлайн-доступ к страницам руководств из различных Unix-подобных систем.
В феврале 2013 года в сообществе BSD был запущен новый сервис mdoc.su с открытым исходным кодом , который унифицировал и сократил доступ к сценариям man.cgi основных современных проектов BSD с помощью уникальной на базе nginx службы детерминированного сокращения URL-адресов для *BSD man. страницы. [ 10 ] [ 11 ] [ 12 ]
Для Linux была создана служба man7.org для обслуживания руководств, специфичных для этой системы. [ 13 ] Сервис ManKier предоставляет более широкий выбор, а также интегрирует страницы TLDR. [ 14 ]
Использование команд
[ редактировать ]Чтобы прочитать страницу руководства для команды Unix, пользователь может ввести:
man <command_name>
Страницы традиционно обозначаются обозначением «имя (раздел)»: например, . В этом разделе описаны различные способы обращения к теме — например, в виде системного вызова, команды или пакета оболочки (командной строки), файла конфигурации пакета или конструкции/заголовка кода.
Одно и то же имя страницы может встречаться в нескольких разделах руководства, например, когда имена системных вызовов , пользовательских команд или пакетов макросов совпадают. Примеры: и , или и . Синтаксис доступа к разделу руководства, отличному от стандартного, варьируется в зависимости от реализации man.
Например, в Solaris и Illumos синтаксис чтения является:
man -s 3c printf
В производных Linux и BSD тот же вызов будет:
man 3 printf
который ищет printf в разделе 3 страниц руководства.
Разделы руководства
[ редактировать ]Руководство обычно разделено на восемь пронумерованных разделов. Большинство современных систем (например, BSD , [ 15 ] macOS , Linux , [ 16 ] и Solaris 11.4) наследуют схему нумерации, используемую Research Unix . [ 17 ] [ 18 ] Хотя System V использует другой порядок: [ 19 ]
| Общий | System V | Описание |
|---|---|---|
| 1 | 1 | Общие команды |
| 2 | 2 | Системные вызовы |
| 3 | 3 | Библиотечные функции, в частности, стандартная библиотека C. |
| 4 | 7 | Специальные файлы (обычно устройства, находящиеся в /dev) и драйверы. |
| 5 | 4 | Форматы файлов и соглашения |
| 6 | 6 | Игры и заставки |
| 7 | 5 | Разнообразный |
| 8 | 1М | системного администрирования Команды и демоны |
API POSIX присутствуют как в разделах 2, так и в 3, где раздел 2 содержит API, реализованные как системные вызовы, а раздел 3 содержит API, реализованные как библиотечные процедуры.
В некоторых системах доступны некоторые из следующих разделов:
| Раздел | Описание |
|---|---|
| 0 | библиотеки C Заголовочные файлы (Unix v6) |
| 9 | Подпрограммы ядра (FreeBSD, SVR4, Linux) [ 18 ] [ 15 ] |
| л | LAPACK Функции библиотеки [ 20 ] |
| н | Tcl / Tk Команды |
| х | Система X Window |
Некоторые разделы дополнительно подразделяются с помощью суффикса; например, в некоторых системах раздел 3C предназначен для вызовов библиотеки C, 3M — для математической библиотеки и так далее. Следствием этого является то, что раздел 8 (команды системного администрирования) иногда относят к подразделу 1M раздела основных команд. Некоторые суффиксы подразделов имеют общее значение для всех разделов:
| Подраздел | Описание |
|---|---|
| п | POSIX- спецификации |
| х | по X Window System Документация |
(Раздел 3, как правило, является исключением из-за большого количества суффиксов для разных языков.)
Некоторые версии man кэшировать отформатированные версии нескольких последних просмотренных страниц. Одной из форм является страница cat , просто передаваемая по конвейеру на пейджер для отображения.
Макет
[ редактировать ]Все справочные страницы имеют общий макет, оптимизированный для представления в простом текстовом формате ASCII , возможно, без какой-либо формы выделения или управления шрифтом. Присутствующие разделы могут включать в себя: [ 21 ] : СТРУКТУРА РУКОВОДСТВА
- ИМЯ
- Имя команды или функции, за которым следует однострочное описание того, что она делает.
- СИНОПСИС
- В случае команды — формальное описание того, как ее запустить и какие параметры командной строки она принимает. Для программных функций — список параметров, которые принимает функция, и файл заголовка, содержащий ее объявление.
- ОПИСАНИЕ
- Текстовое описание функционирования команды или функции.
- ПРИМЕРЫ
- Несколько примеров общего использования.
- СМОТРИТЕ ТАКЖЕ
- Список связанных команд или функций.
Могут присутствовать и другие разделы, но они недостаточно стандартизированы на страницах руководства. Общие примеры включают: ОПЦИИ, СТАТУС ВЫХОДА, ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ, ОКРУЖАЮЩУЮ СРЕДУ, ОШИБКИ, ФАЙЛЫ, АВТОР, СООБЩЕНИЯ ОБ ОШИБКАХ, ИСТОРИЯ и АВТОРСКИЕ ПРАВА.
Авторская работа
[ редактировать ]Страницы руководства могут быть написаны либо на старом man макросы, новые doc макросы или их сочетание ( mandoc). [ 22 ] man Набор макросов предоставляет минимальные функции форматированного текста с директивами для строки заголовка, заголовков разделов, шрифтов (жирный, мелкий или курсив), абзацев и добавления/уменьшения отступов. [ 23 ] Чем новее mdoc язык более семантический по своей природе и содержит специализированные макросы для большинства стандартных разделов, таких как имя программы, описание, имена функций и имена авторов. Эту информацию можно использовать для реализации семантического поиска руководств такими программами, как mandoc . Хотя он также включает директивы для непосредственного управления стилем, ожидается, что специализированные макросы будут охватывать большинство вариантов использования. [ 21 ] Проекты «Мандок» и «Грофф» учитывают mdoc предпочтительный формат для новых документов. [ 24 ]
Хотя справочные страницы, по сути, представляют собой текст, набранный латинским шрифтом размером 10 пунктов , это различие обычно спорно, поскольку справочные страницы просматриваются в терминале (TTY), а не размещаются на бумаге. В результате макрос «мелкий шрифт» используется редко. [ 25 ] С другой стороны, жирный и курсивный текст поддерживается терминалом через ECMA-48 , а groff grotty выдает их по запросу, когда обнаруживает поддерживающий терминал. Однако мандок BSD поддерживает только жирный и подчеркнутый (в качестве замены курсива) текст с помощью последовательности пишущей машинки «обратное пространство, затем перечеркивание», которую необходимо перевести в ECMA-48 с помощью less. [ 26 ] [ 27 ]
Некоторые инструменты использовались для преобразования документов в менее надуманном формате в страницы руководства. Примеры включают GNU help2man, что занимает --help выходные данные и некоторый дополнительный контент для создания страницы руководства. [ 28 ] Руководство вряд ли будет более полезным, чем упомянутый вывод, но для программ GNU это не проблема, поскольку texinfo является основной системой документации. [ 29 ] Ряд инструментов, включая pandoc , ronn и md2man, поддерживают преобразование из Markdown в страницы руководства. Все эти инструменты излучают man формате, поскольку Markdown недостаточно выразителен, чтобы соответствовать семантическому содержанию mdoc. В DocBook есть встроенный конвертер man(7) — ужасного качества, по словам автора mandoc. [ 30 ] который написал отдельный конвертер mdoc(7).
Страницы руководства обычно пишутся на английском языке, но в системе могут быть доступны переводы на другие языки. ГНУ man-db и мандок man известно, что он ищет локализованные страницы руководства в подкаталогах. [ 31 ] [ 16 ] : Обзор [ 15 ]
Альтернативы
[ редактировать ]Мало альтернатив man пользовались большой популярностью, за исключением, возможно, проекта GNU Project . info«система, ранняя и простая гипертекстовая система. Существует также сторонняя разработка, известная как страницы TLDR ( tldr), который предоставляет простые примеры для распространенных случаев использования, похожие на шпаргалку . [ 32 ]
Кроме того, некоторые Unix с графическим пользовательским интерфейсом приложения (особенно те, которые созданы с использованием сред разработки GNOME и KDE ) теперь предоставляют документацию для конечного пользователя в формате HTML и включают встроенные средства просмотра HTML, такие как yelp для чтения справки в приложении. Система HTML в Emacs также должна заменить texinfo. [ 33 ]
См. также
[ редактировать ]- Список команд Unix
- Список приложений Plan 9
infoapropos- ЧИТАЙТЕ
- РТФМ
- ManOpen — NeXT / macOS графическая утилита
Ссылки
[ редактировать ]- ^ "мужчина(1)" . Руководство по основным командам FreeBSD . Архивировано из оригинала 30 января 2023 г. Проверено 15 июля 2023 г.
- ^ Jump up to: а б с Макилрой, доктор медицины (1987). Читатель Research Unix: аннотированные выдержки из Руководства программиста, 1971–1986 (PDF) (Технический отчет). CSTR. Лаборатории Белла. 139. Архивировано (PDF) из оригинала 11 ноября 2017 г. Проверено 1 февраля 2015 г.
- ^ Jump up to: а б Дарвин, Ян; Коллайер, Джеффри. «Эволюция UNIX: 1975–1984 гг. Часть I — Разнообразие» . Архивировано из оригинала 17 июля 2012 года . Проверено 22 декабря 2012 г. Первоначально опубликовано в Microsystems 5 (11), ноябрь 1984 г.
- ^ Фидлер, Райан (октябрь 1983 г.). «Учебное пособие по Unix / Часть 3: Unix на рынке микрокомпьютеров» . БАЙТ . п. 132 . Проверено 30 января 2015 г.
- ^ «GIT коммит 002a6339b1fe8f83f4808022a17e1aa379756d99» . Архивировано из оригинала 4 декабря 2017 года . Проверено 22 ноября 2017 г. .
- ^ «GIT коммит 84bde8d8a9a357bd372793d25746ac6b49480525» . Архивировано из оригинала 5 сентября 2018 года . Проверено 22 ноября 2017 г. .
- ^ «GIT коммит b225d9e76fbb0a6a4539c0992fba88c83f0bd37e» . Архивировано из оригинала 9 ноября 2020 года . Проверено 25 сентября 2018 г.
- ^ " "Почему мужчина печатает "дай мне, дай мне, дай мне" в 00:30?" " . Архивировано из оригинала 21 ноября 2017 года . Проверено 22 ноября 2017 г. .
- ^ Райт, Фрэнсис Дж. «Женщина: просмотр страниц руководства Unix «WO (без) Man» » . ГНУ. Архивировано из оригинала 11 ноября 2020 года . Проверено 3 августа 2020 г.
- ^ Пали, Габор, изд. (12 мая 2013 г.). «Ежеквартальный отчет о состоянии FreeBSD, январь-март 2013 г.» . FreeBSD . Архивировано из оригинала 22 декабря 2014 года . Проверено 25 декабря 2014 г.
- ^ Муренин, Константин А. (19 февраля 2013 г.). «анонсируем mdoc.su, URL-адреса коротких страниц руководства» . [электронная почта защищена] (список рассылки). Архивировано из оригинала 7 августа 2014 года . Проверено 25 декабря 2014 г.
- ^ Муренин, Константин А. (23 февраля 2013 г.). «mdoc.su — URL-адреса кратких страниц руководства для FreeBSD, OpenBSD, NetBSD и DragonFly BSD» . Архивировано из оригинала 17 декабря 2014 года . Проверено 25 декабря 2014 г.
- ^ «Справочные страницы Linux в Интернете» . man7.org . Архивировано из оригинала 07 мая 2020 г. Проверено 5 мая 2020 г.
- ^ "О" . МанКьер . Архивировано из оригинала 25 апреля 2020 г. Проверено 5 мая 2020 г.
- ^ Jump up to: а б с – FreeBSD по основным командам Руководство
- ^ Jump up to: а б – Linux по основным командам Руководство
- ^ «Страницы руководства для исследований Unix, восьмое издание» . man.cat-v.org . Архивировано из оригинала 30 июня 2020 г. Проверено 6 мая 2020 г.
- ^ Jump up to: а б «Руководство программиста Unix — Введение» . www.bell-labs.com . 3 ноября 1971 года. Архивировано из оригинала 1 июня 2020 года . Проверено 6 мая 2020 г.
- ^ «Руководства по System V, выпуск 4» . bitsavers.trailing-edge.com . Архивировано из оригинала 03 августа 2020 г. Проверено 6 мая 2020 г.
- ^ «lapack (l) — Руководства по Linux» . www.systutorials.com . Архивировано из оригинала 11 марта 2023 г. Проверено 29 мая 2021 г.
- ^ Jump up to: а б – по FreeBSD по разной информации Руководство
- ^ – Linux по форматам файлов Руководство
- ^ – по Linux Разное руководство
- ^ «Заявление Гроффа о миссии – 2014» . www.gnu.org . Архивировано из оригинала 03 декабря 2020 г. Проверено 02 января 2021 г.
Одновременно с работой над man(7) будет активно поддерживаться mdoc(7) и продвигаться его использование.
- ^ "мужчина" . Руководство GNU Troff . Архивировано из оригинала 24 декабря 2019 года . Проверено 31 декабря 2019 г.
- ^ «Курсив и цвет на страницах руководства на виртуальном терминале в пользовательском пространстве nosh» . jdebp.eu . Архивировано из оригинала 28 января 2021 г. Проверено 21 января 2021 г.
- ^ – FreeBSD по основным командам Руководство . «Стили шрифтов применяются с использованием кодировки с обратным интервалом...»
- ^ «Справочное руководство help2man» . Архивировано из оригинала 6 марта 2023 года . Проверено 5 марта 2023 г.
- ^ «Страницы руководства (стандарты кодирования GNU)» . www.gnu.org . Архивировано из оригинала 05 марта 2023 г. Проверено 5 марта 2023 г.
- ^ Инго Шварце. «Новый конвертер уценки mandoc -mdoc -T» . undeadly.org . Архивировано из оригинала 05 марта 2023 г. Проверено 5 марта 2023 г. – конкретные жалобы автора см. Инго Шварце (28 февраля 2014 г.). «Re: Справочные страницы Гроффа (касательно Future Redux)» . Грофф (список рассылки). Архивировано из оригинала 05 марта 2023 г.
- ^ «командная строка — справочные страницы Linux на разных языках» . Спросите Убунту . Архивировано из оригинала 11 марта 2023 г. Проверено 5 мая 2020 г.
- ^ «Страницы TLDR» . tldr.sh . Архивировано из оригинала 27 апреля 2020 г. Проверено 5 мая 2020 г.
- ^ Рэймонд, Эрик С. «Re: Справочные страницы [Гроффа] (касательно Future Redux)» . groff (список рассылки). Архивировано из оригинала 05 марта 2023 г. Получено 5 марта 2023 г. - через lists.gnu.org.
Внешние ссылки
[ редактировать ]
- История справочных страниц UNIX — первоисточник истории справочных страниц UNIX.
- Репозиторий man-страниц UNIX и Linux, содержащий около 300 000 хорошо отформатированных man-страниц.
- Что означают цифры на странице руководства?
- Страницы руководства по FreeBSD , freebsd.org – также содержит справочные страницы для Darwin, Debian, HP-UX, IRIS, NetBSD, OpenBSD, NextSTEP, SunOS и других.
| Файловая система | |
|---|---|
| Процессы | |
| Пользовательская среда | |
| Обработка текста | |
| Встроенные функции оболочки | |
| Идет поиск | |
| Документация | |
| Разработка программного обеспечения | |
| Разнообразный | |
