stringtranslate.com

справочная страница

Страница руководства утилиты sed в различных дистрибутивах Linux .

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

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

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

История

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

До 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 было скрытое пасхальное яйцо , из-за которого команда возвращала «дай мне, дай мне, дай мне» при запуске в 00:30 (отсылка к песне ABBA Gimme ! Gimme! Gimme! (A Man) After Midnight) . Он был введен в 2011 году [5] , но сначала был ограничен [6] , а затем удален в 2017 году [7] после того, как наконец был найден. [8]

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

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

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

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

человек  <имя_команды>

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

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

Например, в Solaris и Illumos синтаксис чтения printf(3C)следующий:

человек  -s  3c printf

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

мужчина 3 распечатать

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

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

Руководство обычно разделено на восемь пронумерованных разделов. Большинство современных систем (например , BSD , [15] macOS , Linux , [16] и Solaris 11.4) наследуют схему нумерации, используемую Research Unix . [17] [18] Хотя в Системе V используется другой порядок: [19]

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

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

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

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

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

Макет

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

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

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

Авторская работа

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

Хотя справочные страницы, по сути, представляют собой текст, набранный латинским шрифтом размером 10 пунктов , это различие обычно спорно, поскольку справочные страницы просматриваются в терминале (TTY), а не размещаются на бумаге. В результате макрос «мелкий шрифт» используется редко. [25] С другой стороны, жирный и курсивный текст поддерживается терминалом через ECMA-48 , и groff's 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).

Страницы руководства обычно пишутся на английском языке, но в системе могут быть доступны переводы на другие языки. GNU man-dbи mandoc, manкак известно, ищут локализованные страницы руководства в подкаталогах. [31] [16] : Обзор  [15]

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

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

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

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

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

  1. ^ "Человек (1)" . Руководство по основным командам FreeBSD . Архивировано из оригинала 30 января 2023 г. Проверено 15 июля 2023 г.
  2. ^ abc Макилрой, доктор медицины (1987). Читатель Research Unix: аннотированные выдержки из Руководства программиста, 1971–1986 (PDF) (Технический отчет). CSTR. Лаборатории Белла. 139. Архивировано (PDF) из оригинала 11 ноября 2017 г. Проверено 1 февраля 2015 г.
  3. ^ Аб Дарвин, Ян; Коллайер, Джеффри. «Эволюция UNIX: 1975–1984 гг., часть I – Разнообразие». Архивировано из оригинала 17 июля 2012 года . Проверено 22 декабря 2012 г.Первоначально опубликовано в Microsystems 5 (11), ноябрь 1984 г.
  4. ^ Фидлер, Райан (октябрь 1983 г.). «Учебное пособие по Unix / Часть 3: Unix на рынке микрокомпьютеров». БАЙТ . п. 132 . Проверено 30 января 2015 г.
  5. ^ "GIT коммит 002a6339b1fe8f83f4808022a17e1aa379756d99" . Архивировано из оригинала 4 декабря 2017 года . Проверено 22 ноября 2017 г. .
  6. ^ "GIT фиксирует 84bde8d8a9a357bd372793d25746ac6b49480525" . Архивировано из оригинала 5 сентября 2018 года . Проверено 22 ноября 2017 г. .
  7. ^ "GIT коммит b225d9e76fbb0a6a4539c0992fba88c83f0bd37e" . Архивировано из оригинала 9 ноября 2020 года . Проверено 25 сентября 2018 г.
  8. ^ «Почему мужчина печатает «дай мне, дай мне, дай мне» в 00:30?» Архивировано из оригинала 21 ноября 2017 года . Проверено 22 ноября 2017 г. .
  9. ^ Райт, Фрэнсис Дж. «Женщина: просмотрите страницы руководства Unix «WO (без) человека»». ГНУ. Архивировано из оригинала 11 ноября 2020 года . Проверено 3 августа 2020 г.
  10. ^ Пали, Габор, изд. (12 мая 2013 г.). «Ежеквартальный отчет о состоянии FreeBSD, январь-март 2013 г.». FreeBSD . Архивировано из оригинала 22 декабря 2014 года . Проверено 25 декабря 2014 г.
  11. ↑ Муренин, Константин А. (19 февраля 2013 г.). «анонсируем mdoc.su, короткие URL-адреса страниц руководства». [email protected] (список рассылки). Архивировано из оригинала 7 августа 2014 года . Проверено 25 декабря 2014 г.
  12. ^ Муренин, Константин А. (23 февраля 2013 г.). «mdoc.su — URL-адреса кратких страниц руководства для FreeBSD, OpenBSD, NetBSD и DragonFly BSD». Архивировано из оригинала 17 декабря 2014 года . Проверено 25 декабря 2014 г.
  13. ^ "Справочные страницы Linux в Интернете" . man7.org . Архивировано из оригинала 07 мая 2020 г. Проверено 5 мая 2020 г.
  14. ^ «О» . МанКьер . Архивировано из оригинала 25 апреля 2020 г. Проверено 5 мая 2020 г.
  15. ^ abc man(1) -  Руководство по общим командам FreeBSD
  16. ^ ab man(1) -  Руководство по общим командам Linux
  17. ^ «Страницы руководства для исследований Unix, восьмое издание» . man.cat-v.org . Архивировано из оригинала 30 июня 2020 г. Проверено 6 мая 2020 г.
  18. ^ ab «Руководство программиста Unix — Введение». www.bell-labs.com . 3 ноября 1971 года. Архивировано из оригинала 1 июня 2020 года . Проверено 6 мая 2020 г.
  19. ^ «Система V, выпуск 4 руководства» . bitsavers.trailing-edge.com . Архивировано из оригинала 3 августа 2020 г. Проверено 6 мая 2020 г.
  20. ^ "lapack (l) - Руководства по Linux" . www.systutorials.com . Архивировано из оригинала 11 марта 2023 г. Проверено 29 мая 2021 г.
  21. ^ ab mdoc(7) -  Руководство по разной информации FreeBSD
  22. ^ groff_tmac(5)  -  Руководство по форматам файлов Linux .
  23. ^ man(7)  -  Руководство по разным Linux
  24. ^ "Заявление о миссии Гроффа - 2014" . www.gnu.org . Архивировано из оригинала 03 декабря 2020 г. Проверено 02 января 2021 г. Одновременно с работой над man(7) будет активно поддерживаться mdoc(7) и продвигаться его использование.
  25. ^ «Человек». Руководство GNU Troff . Архивировано из оригинала 24 декабря 2019 года . Проверено 31 декабря 2019 г.
  26. ^ «Курсив и цвет на страницах руководства на виртуальном терминале пользовательского пространства nosh» . jdebp.eu . Архивировано из оригинала 28 января 2021 г. Проверено 21 января 2021 г.
  27. ^ mandoc(1)  -  Руководство по основным командам FreeBSD . «Стили шрифтов применяются с использованием кодировки с обратным интервалом...»
  28. ^ «Справочное руководство help2man» . Архивировано из оригинала 6 марта 2023 года . Проверено 5 марта 2023 г.
  29. ^ «Страницы руководства (стандарты кодирования GNU)» . www.gnu.org . Архивировано из оригинала 05 марта 2023 г. Проверено 05 марта 2023 г.
  30. ^ Инго Шварце. «Новый конвертер уценки mandoc -mdoc -T». undeadly.org . Архивировано из оригинала 05 марта 2023 г. Проверено 05 марта 2023 г.– конкретные жалобы автора см. в Ingo Schwarze (28 февраля 2014 г.). «Re: Справочные страницы Гроффа (касательно Future Redux)». Грофф (список рассылки). Архивировано из оригинала 05 марта 2023 г.
  31. ^ «Командная строка — справочные страницы Linux на разных языках» . Спросите Убунту . Архивировано из оригинала 11 марта 2023 г. Проверено 5 мая 2020 г.
  32. ^ "Страницы TLDR" . tldr.sh . Архивировано из оригинала 27 апреля 2020 г. Проверено 5 мая 2020 г.
  33. ^ Рэймонд, Эрик С. «Re: Справочные страницы [Гроффа] (касательно Future Redux)». groff (список рассылки). Архивировано из оригинала 05 марта 2023 г. Получено 5 марта 2023 г. - через lists.gnu.org.

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

В Wikibook Guide to Unix есть страница на тему: Команды.