Введение

Документация к программному обеспечению Unix

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

История

До Unix (например, GCOS) документация представляла собой напечатанные страницы, доступные пользователям (сотрудникам, студентам) непосредственно на месте, организованные в металлические переплёты, запертые вместе в единой монолитной металлической подставке для чтения, прикреплённой к столу или стойке, с организацией страниц для модульного обновления информации, замены, исправления ошибок и дополнений. В первые два года истории Unix документация отсутствовала. Руководство программиста Unix было впервые опубликовано 3 ноября 1971 года. Первые настоящие страницы руководства (man pages) были написаны Деннисом Ричи и Кеном Томпсоном по настоянию их руководителя Дага Макилроя в 1971 году. Помимо страниц руководства, в Руководстве программиста также накапливался набор коротких статей, некоторые из которых были учебными пособиями (например, по общему использованию Unix, языку программирования C и инструментам, таким как Yacc), а другие – более подробными описаниями функций операционной системы. Печатная версия руководства первоначально помещалась в один переплёт, но начиная с PWB/UNIX и 7-го издания Research Unix, она была разделена на два тома, при этом напечатанные страницы руководства составляли том 1. В более поздних версиях документации имитировалась краткость первых страниц руководства. Ричи добавил раздел «Как начать» во введение к третьему изданию, а Лоринда Черри предоставила карманный справочник «Пурпурная карточка» для шестого и седьмого изданий. Версии программного обеспечения назывались по номеру редакции руководства; например, седьмое издание Руководства программиста Unix поставлялось с 7-м изданием или Версией 7 Unix. Для четвертого издания страницы руководства были отформатированы с использованием пакета верстки troff и его набора макросов man (которые были полностью пересмотрены между шестым и седьмым изданиями Руководства, но сначала ограничены, а затем удалены в 2017 году после того, как они были наконец найдены).

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

Формат страниц man по умолчанию — troff, с использованием макропакета man (ориентированного на внешний вид) или mdoc (ориентированного на семантику). Это позволяет преобразовать страницу man в PostScript, PDF и различные другие форматы для просмотра или печати. В некоторых Unix-системах есть пакет для команды man, который позволяет пользователям просматривать страницы руководства с помощью HTML-браузера. Системы, оснащенные groff и man db, должны использовать более качественный собственный HTML-вывод. Программа GNU Emacs WoMan (от "WithOut man") позволяет просматривать страницы man непосредственно из редактора. В 2010 году OpenBSD отказалась от troff в пользу mandoc для форматирования страниц руководства, это специализированный компилятор/форматер для страниц man с нативной поддержкой вывода в PostScript, HTML, XHTML и терминал. Он предназначен для поддержки только подмножества troff, используемого в страницах руководства, а именно макросов mdoc.

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

Несколько веб-сайтов предлагают онлайн-доступ к страницам руководств различных Unix-подобных систем. В феврале 2013 года в сообществе BSD был запущен новый сервис mdoc.su с открытым исходным кодом, который объединил и упростил доступ к man-cgi-скриптам основных современных BSD-проектов через уникальный сервис детерминированного сокращения URL на основе nginx для страниц руководств *BSD. Для Linux был создан сервис man7.org, предоставляющий руководства, специфичные для этой системы. ManKier предлагает более широкий выбор и также интегрирует страницы TLDR.

Планировка

Все страницы руководств следуют общему макету, оптимизированному для отображения на простом текстовом дисплее ASCII, возможно, без какого-либо выделения или управления шрифтом. Набор макросов предоставляет минимальные функции обогащенного текста с директивами для строки заголовка, заголовков разделов, шрифтов (жирный, мелкий или курсивный), абзацев и добавления/уменьшения отступов. Новый язык более семантичен по своей природе и содержит специализированные макросы для большинства стандартных разделов, таких как имя программы, синопсис, имена функций и имена авторов. Эту информацию можно использовать для реализации семантического поиска по руководствам с помощью таких программ, как mandoc. Хотя он также включает директивы для непосредственного управления стилем, ожидается, что специализированные макросы покроют большинство случаев использования. Как проекты mandoc, так и проекты groff считают предпочтительным форматом для новых документов. Хотя страницы руководств, как правило, представляют собой текст, оформленный шрифтом Roman 10 пунктов в troff, это различие обычно несущественно, поскольку страницы руководств просматриваются в терминале (TTY), а не выводятся на бумагу. В результате макрос "мелкий шрифт" используется редко. С другой стороны, терминал поддерживает жирный и курсивный текст через ECMA 48, и groff действительно выдает их по запросу при обнаружении поддерживаемого терминала. Однако BSD mandoc поддерживает только жирный и подчеркнутый (в качестве замены курсива) текст с помощью последовательности возврата каретки и перезаписи, которую необходимо преобразовать в ECMA 48. Некоторые инструменты используются для преобразования документов в менее сложный формат в страницы руководств. Примеры включают GNU's, который принимает вывод и дополнительный контент для создания страницы руководства. Руководство было бы лишь немного полезнее указанного вывода, но для программ GNU это не является проблемой, поскольку texinfo является основной системой документации. Ряд инструментов, включая pandoc, ronn и md2man, поддерживают преобразование из Markdown в страницы руководств. Все эти инструменты выдают формат, поскольку Markdown недостаточно выразителен для соответствия семантическому содержанию. DocBook имеет встроенный конвертер man(7) – ужасного качества, по словам автора mandoc, который написал отдельный конвертер mdoc(7). Страницы руководств обычно написаны на английском языке, но переводы на другие языки могут быть доступны в системе. Известно, что GNU и mandoc ищут локализованные страницы руководств в подкаталогах. Кроме того, некоторые Unix GUI-приложения (особенно те, которые созданы с использованием сред разработки GNOME и KDE) теперь предоставляют документацию для конечных пользователей в HTML и включают встроенные HTML-просмотрщики, такие как yelp, для чтения справки в приложении. Также планируется замена texinfo HTML-системой в Emacs.