stringtranslate.com

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

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

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

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

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

История

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

До появления Unix (например, GCOS ) документация представляла собой печатные страницы, доступные пользователям (сотрудникам, студентам...) на месте, организованные в стальные папки, скрепленные вместе на одной монолитной стальной стойке для чтения, прикрепленной болтами к столу или стойке, при этом страницы были организованы для модульных обновлений информации, замен, исправлений и дополнений. [ необходима ссылка ]

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

Более поздние версии документации имитировали краткость первых man-страниц. Ритчи добавил раздел «Как начать» во введение к третьему изданию , а Лоринда Черри предоставила карманный справочник «Purple Card» для шестого и седьмого изданий. [2] Версии программного обеспечения были названы в честь редакции руководства; седьмое издание Unix Programmer's Manual , например, поставлялось с 7-м изданием или версией 7 Unix. [4]

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

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

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

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

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

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

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

Онлайн-услуги

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

В феврале 2013 года сообщество BSD увидело запуск нового сервиса с открытым исходным кодом mdoc.su, который объединил и сократил доступ к скриптам man.cgi основных современных проектов BSD с помощью уникального детерминированного сервиса сокращения URL-адресов на основе nginx для страниц руководства *BSD. [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)следующий:

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

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

человек 3 printf

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

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

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

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

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

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

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

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

Макет

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

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

Другие разделы могут присутствовать, но они не стандартизированы на страницах руководства. Обычные примеры включают: OPTIONS, EXIT STATUS, RETURN VALUE, ENVIRONMENT, BUGS, FILES, AUTHOR, REPORTING BUGS, HISTORY и COPYRIGHT.

Авторинг

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

Хотя man-страницы, по мнению troff, представляют собой текст, набранный с использованием 10-точечного римского шрифта , это различие обычно не имеет смысла, поскольку man-страницы просматриваются в терминале (TTY), а не на бумаге. В результате макрос «мелкий шрифт» используется редко. [25] С другой стороны, жирный и курсивный текст поддерживаются терминалом через ECMA-48 , и groff's grottyвыдает их по запросу, когда обнаруживает поддерживающий терминал. Однако BSD mandoc поддерживает только жирный и подчеркнутый (в качестве замены курсиву) текст с помощью последовательности пишущей машинки backspace-then-overstrike, которую необходимо перевести в 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 Project " info", ранней и простой гипертекстовой системы. Существует также сторонняя работа, известная как TLDR pages ( tldr), которая предоставляет простые примеры для общих случаев использования, похожие на шпаргалку . [32]

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

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

Ссылки

  1. ^ "man(1)". FreeBSD General Commands Manual . Архивировано из оригинала 2023-01-30 . Получено 2023-07-15 .
  2. ^ abc McIlroy, MD (1987). Исследовательский ридер Unix: аннотированные выдержки из Руководства программиста, 1971–1986 (PDF) (Технический отчет). CSTR. Bell Labs. 139. Архивировано (PDF) из оригинала 2017-11-11 . Получено 2015-02-01 .
  3. ^ ab Дарвин, Ян; Коллиер, Джеффри. "UNIX Evolution: 1975-1984 Часть I - Разнообразие". Архивировано из оригинала 17 июля 2012 года . Получено 22 декабря 2012 года .Первоначально опубликовано в журнале Microsystems 5 (11), ноябрь 1984 г.
  4. ^ Фидлер, Райан (октябрь 1983 г.). «Учебник Unix / Часть 3: Unix на рынке микрокомпьютеров». BYTE . стр. 132 . Получено 30 января 2015 г. .
  5. ^ "GIT commit 002a6339b1fe8f83f4808022a17e1aa379756d99". Архивировано из оригинала 4 декабря 2017 г. Получено 22 ноября 2017 г.
  6. ^ "GIT commit 84bde8d8a9a357bd372793d25746ac6b49480525". Архивировано из оригинала 5 сентября 2018 г. Получено 22 ноября 2017 г.
  7. ^ "GIT commit b225d9e76fbb0a6a4539c0992fba88c83f0bd37e". Архивировано из оригинала 9 ноября 2020 г. Получено 25 сентября 2018 г.
  8. ^ ""Почему человек печатает "gimme gimme gimme" в 00:30?"". Архивировано из оригинала 21 ноября 2017 года . Получено 22 ноября 2017 года .
  9. ^ Райт, Фрэнсис Дж. «WoMan: Browse Unix Manual Pages «WO (without) Man»». GNU. Архивировано из оригинала 11 ноября 2020 г. Получено 3 августа 2020 г.
  10. ^ Pali, Gabor, ed. (12 мая 2013 г.). "FreeBSD Quarterly Status Report, January-March 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 man pages online". man7.org . Архивировано из оригинала 2020-05-07 . Получено 2020-05-05 .
  14. ^ "About". ManKier . Архивировано из оригинала 2020-04-25 . Получено 2020-05-05 .
  15. ^ abc man(1) –  Руководство по основным командам FreeBSD
  16. ^ ab man(1) –  Руководство по основным командам Linux
  17. ^ "Manual Pages for Research Unix Eighth Edition". man.cat-v.org . Архивировано из оригинала 2020-06-30 . Получено 2020-05-06 .
  18. ^ ab "Unix Programmer's Manual - Introduction". www.bell-labs.com . 3 ноября 1971 г. Архивировано из оригинала 1 июня 2020 г. Получено 6 мая 2020 г.
  19. ^ "System V release 4 manuals". bitsavers.trailing-edge.com . Архивировано из оригинала 2020-08-03 . Получено 2020-05-06 .
  20. ^ "lapack (l) - Linux Man Pages". www.systutorials.com . Архивировано из оригинала 2023-03-11 . Получено 2021-05-29 .
  21. ^ ab mdoc(7) –  Руководство по различным сведениям о FreeBSD
  22. ^ groff_tmac(5)  –  Руководство по форматам файлов Linux
  23. ^ man(7)  -  Руководство по разным Linux
  24. ^ "Groff Mission Statement - 2014". www.gnu.org . Архивировано из оригинала 2020-12-03 . Получено 2021-01-02 . Параллельно с работой над man(7), mdoc(7) будет активно поддерживаться, а его использование продвигаться.
  25. ^ "man". Руководство GNU Troff . Архивировано из оригинала 24 декабря 2019 г. Получено 31 декабря 2019 г.
  26. ^ "Курсив и цвет на страницах руководства на виртуальном терминале пользовательского пространства Nosh". jdebp.eu . Архивировано из оригинала 28.01.2021 . Получено 21.01.2021 .
  27. ^ mandoc(1)  –  Руководство по основным командам FreeBSD . «Стили шрифтов применяются с использованием кодировки back-spaced...»
  28. ^ "help2man Reference Manual". Архивировано из оригинала 6 марта 2023 г. Получено 5 марта 2023 г.
  29. ^ "Man Pages (GNU Coding Standards)". www.gnu.org . Архивировано из оригинала 2023-03-05 . Получено 2023-03-05 .
  30. ^ Инго Шварце. "Новый конвертер mandoc -mdoc -T markdown". undeadly.org . Архивировано из оригинала 2023-03-05 . Получено 2023-03-05 .– для конкретных жалоб автора см. Ingo Schwarze (28 февраля 2014 г.). "Re: Groff man pages (tangential to Future Redux)". Groff (список рассылки). Архивировано из оригинала 2023-03-05.
  31. ^ "командная строка - страницы руководства Linux на разных языках". Спросите Ubuntu . Архивировано из оригинала 2023-03-11 . Получено 2020-05-05 .
  32. ^ "Страницы TLDR". tldr.sh . Архивировано из оригинала 2020-04-27 . Получено 2020-05-05 .
  33. ^ Raymond, Eric S. "Re: [Groff] man pages (tangential to Future Redux)". groff (список рассылки). Архивировано из оригинала 2023-03-05 . Получено 2023-03-05 – через lists.gnu.org.

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

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