Как быстро и правильно создать man-страницу для Linux

Быстрые ссылки

• Страницы man

• pandoc как помощник

• Разделы man-страницы

• Разделы справочника

• Формат man-страницы

• Эффективный рабочий процесс

• Создание вашей man-страницы

• Если вы хотите…

Хотите, чтобы ваша новая программа для Linux выглядела профессионально? Напишите для неё man-страницу. Ниже — самый простой и быстрый способ сделать это, не разбираясь в groff-макросах вручную.

Страницы man

Есть доля правды в старой шутке Unix: «единую команду, которую вам нужно знать, — это man». Страницы man содержат большой объём информации и должны быть первым источником, к которому обращаются при изучении команды.

Предоставление man-страницы для утилиты превращает полезный фрагмент кода в полноценный пакет Linux. Если вы поддерживаете Linux нативно, наличие корректной man-страницы повышает доверие пользователей и упрощает поддержку.

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

less

и отображается пользователю.

Если вы редко создаёте man-страницы, писать их прямо в формате groff непросто: требуется помнить синтаксис макросов, экранирование, форматирование и т. п. Это отвлекает от сути — описания поведения команды.

Вместо борьбы с древними макросами разумно сосредоточиться на содержании и воспользоваться инструментом для преобразования Markdown в формат man.

pandoc как помощник

pandoc читает файлы Markdown и генерирует документы примерно в 40 различных форматах, включая формат man. Это упрощает процесс настолько, что вам не придётся вручную править groff.

Установка pandoc в популярных дистрибутивах:

sudo apt-get install pandoc

sudo dnf install pandoc

sudo pacman -Syu pandoc

После установки вы сможете конвертировать Markdown в man с помощью простой команды, описанной ниже.

Разделы man-страницы

man-страницы состоят из логически организованных разделов. Набор необходимых секций определяется сложностью описываемой команды. Ниже — минимальный набор, который разумно включать почти всегда:

• Name: имя команды и краткая однострочная сводка её назначения.
• Synopsis: краткая схема запуска программы, форматы вызова, параметры командной строки.
• Description: развёрнутое описание поведения.
• Options: список опций и их описание.
• Examples: примеры типичного использования.
• Exit Values: возможные коды возврата и значение каждого.
• Bugs: известные ошибки и ограничения (или ссылка на трекер задач).
• Author: автор(ы).
• Copyright: уведомление об авторском праве и лицензии.

Вы можете не включать все возможные разделы — man-страница не место для многословия. Тем не менее часто встречаются и другие разделы:

• See Also: связанные команды и ресурсы.
• Files: важные файлы, используемые программой.
• Caveats: особенности и подводные камни.
• History: краткая история изменений.

Совет: начинайте с минимального набора и расширяйте по мере необходимости.

Разделы справочника

Вся коллекция man-страниц разделена на цифровые секции, к которым вы привязываете свою страницу:

1. Исполняемые программы (команды shell)
2. Вызовы ядра (system calls)
3. Библиотечные вызовы
4. Специальные файлы
5. Форматы файлов и соглашения (например, “/etc/passwd”)
6. Игры
7. Разное (макропакеты и соглашения, такие как groff)
8. Команды системного администрирования (обычно для root)
9. Рутины ядра

Каждая man-страница должна указывать, к какой секции она относится, и храниться в соответствующей директории (man1, man2, …). Команды и утилиты обычно относятся к секции 1.

Формат man-страницы

Формат groff трудно читать в исходном виде. Markdown — гораздо более понятный и быстрый для написания.

Ниже показаны важные правила и соответствия при написании man-страницы в Markdown:

Передняя часть документа (front matter)

Первые три строки должны начинаться с % (процент) и содержать без ведущих пробелов, но с пробелом после процента, следующие элементы:

• Первая строка: имя команды и номер секции в скобках, например % CMD(1). Имя обычно пишут в верхнем регистре по традиции. Дополнительный текст после имени можно использовать для версии программы — он попадёт в верхнюю/нижнюю колонтитулы страницы.
• Вторая строка: автор(ы). Эти имена автоматически попадут в раздел Authors.
• Третья строка: дата — попадёт в центр футера.

Пример фронтмэтера:

% MS(1)
% Иван Иванов
% 2025-03-01

Имя

В секции Name укажите имя команды, затем короткое описание через « - ». Пример:

# MS - простой демонстрационный поисковик

Синопсис

В секции Synopsis покажите варианты вызова. Обозначения:

• Квадратные скобки [] — необязательные аргументы.
• Эллипсис (…) — повторяемые аргументы.
• Используйте жирный для имени команды и курсив для обязательных параметров по соглашению.

Чтобы принудительно вставить перенос строки без пустой строки, можно использовать завершающий обратный слеш ().

Описание

В Description изложите суть команды: что делает, какие ресурсы использует, какие ограничения. Не превращайте этот раздел в руководство пользователя — краткость и точность важнее.

Опции

В Options перечисляйте опции в виде списка. По соглашению опция помещается в жирный формат, а её описание начинается с двоеточия на следующей строке или располагается в той же строке, если короткое.

Примеры

Включите несколько распространённых примеров использования: один-два базовых и 1–2 более продвинутых. Демонстрация реальных сценариев помогает понять поведение.

Коды возврата

Перечислите возможные коды завершения и их значения — это важно для скриптов и автоматизации.

Ошибки и авторские права

В секции Bugs опишите известные проблемы или укажите ссылку на трекер. В Copyright укажите лицензию (MIT, GPL, Apache и т. п.) и контактные данные.

Эффективный рабочий процесс

Редактируйте man-страницу в вашем любимом редакторе (VS Code, Vim, Nano) — многие редакторы подсвечивают Markdown. Чтобы быстро увидеть результат в формате man без ручной генерации и установки, откройте терминал в директории с файлом и выполните:

pandoc ms.1.md -s -t man | /usr/bin/man -l -

Объяснение ключей:

• -s — standalone: генерирует полную man-страницу (заголовки, колонтитулы).
• -t man — целевой формат man.
• Пайп в man -l - заставляет man читать man-страницу из stdin, не обращаясь к базе man.

Сохраните файл в редакторе, затем в терминале нажмите стрелку вверх и Enter, чтобы быстро повторить команду и проверить изменения. Это даёт циклический workflow: редактировать → сохранить → отобразить → править.

Создание финальной man-страницы и установка

Когда вы готовы создать итоговый man-файл и установить его в систему, выполните:

pandoc ms.1.md -s -t man -o ms.1

Имя файла принято задавать как command.section, например ms.1.

Где искать man-страницы в системе, выясняется командой:

manpath

Типичные пути:

• /usr/share/man — стандартная библиотека системных man-страниц (не редактируйте).
• /usr/local/share/man (обычно символическая ссылка на /usr/local/man) — место для локально установленных man-файлов.
• /usr/local/man — удобный повседневный путь для размещения своих страниц.

Разделы хранятся в поддиректориях man1, man2 и т. д. Если нужной директории нет, создайте её:

sudo mkdir -p /usr/local/man/man1

Скопируйте файл и сожмите его (man ожидает сжатые страницы):

sudo cp ms.1 /usr/local/man/man1
sudo gzip /usr/local/man/man1/ms.1
sudo mandb

После mandb вы сможете вызывать страницу как обычную:

man ms

man найдёт и отобразит вашу страницу как встроенную.

Пример минимальной man-страницы в Markdown

Ниже — пример полного файла ms.1.md, который вы можете использовать как шаблон. Сохраните его и конвертируйте через pandoc.

% MS(1)
% Иван Иванов
% 2025-03-01

# MS - демонстрационная утилита поиска по шаблону

## Synopsis

ms [-i] [-r] *pattern* [*file*...]

## Description

MS ищет строки, соответствующие *pattern*, в указанных *file* или в stdin. По умолчанию поиск чувствителен к регистру. Опция -i делает поиск нечувствительным к регистру. Опция -r включает регулярные выражения.

## Options

-i:
: Игнорировать регистр при поиске.

-r:
: Включить поддержку регулярных выражений POSIX.

## Examples

: Поиск слова "example" в файле:

ms example file.txt

: Поиск нечувствительно к регистру:

ms -i Example file.txt

## Exit Values

: 0 — найдены совпадения; 1 — совпадений нет; 2 — ошибка (например, файл не найден).

## Bugs

: Отсутствует поддержка многобайтовых регулярных выражений в старых версиях libc.

## Author

: Иван Иванов 

## Copyright

: MIT License

Сконвертируйте и проверьте, как описано ранее.

Если вы хотите редактировать groff вручную

pandoc генерирует корректный groff, но можно открыть сгенерированный файл и внести мелкие правки вручную, прежде чем помещать его в директорию man и сжимать. Это полезно при специфическом форматировании или использовании нестандартных макросов.

Когда man-страница нужна, а когда — избыточна

Важно понимать практическую ценность man-страницы:

• Нужна, если вы распространяете программу для Linux и ожидаете, что её будут использовать в терминале, скриптах или паковать в дистрибутивы.
• Не обязательна для внутренних прототипов или GUI-приложений без CLI.

Контрпример: небольшой одноразовый скрипт, используемый только в локальном проекте, не обязательно должен иметь man-страницу; лучше поддерживать README и встроенный help (–help).

Альтернативные подходы

• Использовать встроенный –help/–version для быстрого справочного вывода.
• Документация в README.md и сайт-проект: полезно для веб-пользователей и новичков.
• man в формате troff/groff руками: даёт тонкий контроль, но обычно избыточно.
• Asciidoctor и другие генераторы: подходят, если у вас уже есть конвейер сборки документации.

Выбор зависит от аудитории: администраторы и пакетные менеджеры ценят man; веб-документация удобнее для длинных руководств.

Мини-процедура (SOP) для создания man-страницы — пошагово

1. Создайте файл с именем command.1.md или command.1 (расширение .md помогает редакторам): ms.1.md.
2. Заполните фронтмэтeр (строки с %): имя(верхний регистр), авторы, дата.
3. Напишите разделы: Name, Synopsis, Description, Options, Examples, Exit Values, Bugs, Author, Copyright.
4. Локально проверяйте командой:

pandoc ms.1.md -s -t man | /usr/bin/man -l -

5. Когда готово, экспортируйте в файл:

pandoc ms.1.md -s -t man -o ms.1

6. Создайте (если нужно) директорию /usr/local/man/man1 и скопируйте туда:

sudo mkdir -p /usr/local/man/man1
sudo cp ms.1 /usr/local/man/man1
sudo gzip /usr/local/man/man1/ms.1
sudo mandb

7. Проверьте результат:

man ms

Ролевые чек-листы

Разработчику:

• Написать краткое и точное описание в секции Name.
• Описать все опции и их поведение.
• Добавить несколько рабочих примеров.
• Указать коды возврата.
• Проверить страницу через pandoc → man.

Пакетчику/администратору:

• Убедиться, что файл имеет правильное имя (cmd.N).
• Поместить файл в корректную секцию (man1, man8 и т. д.).
• Сжать gzip и обновить mandb.
• Проверить локализацию и зависимости.

Переводчику документации:

• Сохранять метаданные фронтмэтера.
• Перевести только содержимое; не менять синтаксис Markdown, применяемый pandoc.
• Проверить примеры команд (пути/пользователи) на соответствие локали.

Критерии приёмки

• man ms открывает страницу и отображает заголовок, разделы и футер.
• Примеры в секции Examples выполняются на тестовой машине.
• Коды возврата соответствуют описанию и тестам.
• Страница проходит ревью: понятна, кратка и не содержит орфографических ошибок.

Тестовые случаи и приёмка

• Тест: запуск без аргументов должен показать краткое сообщение об ошибке и вернуть код 2 (см. Exit Values).
• Тест: опция -i должна игнорировать регистр — сравните вывод при поиске разных регистров.
• Тест: проверка формата страницы в man через stdin и после установки (man ms).

Критерии успеха: все тесты зелёные, ман-страница отображается, mandb не выдает ошибок.

Когда подход с pandoc не подходит

• Если вам нужен очень специфический, нетипичный макрос groff, которого pandoc не генерирует — тогда придётся дорабатывать groff вручную.
• Когда требуются сложные макросы для печатных страниц или нестандартное оформление.

В таких случаях можно:

• Генерировать базовую страницу pandoc и вручную доработать groff-файл.
• Писать groff с нуля, если вы хорошо знакомы с макросами.

Ментальные модели и эвристики

• Документируйте поведение, а не реализацию. Пользователь интересуется «что делает» и «как использовать», а не внутренней архитектурой.
• Начинайте с простого: если большинство пользователей используют только --help, начните с краткой man-страницы и расширяйте её.
• Примеры важнее длинных объяснений: короткий пример показывает поведение лучше, чем 200 слов текста.

Безопасность и совместимость

• Не включайте в man-страницу чувствительные данные (пароли, токены). Примеры должны быть безопасны и не содержать реальные секреты.
• Проверяйте совместимость с целевыми версиями libc и sh: некоторые выражения в примерах могут зависеть от конкретного шелла.

Дополнительные советы по локализации

• Если вы переводите man-страницу на другие языки, сохраняйте команды и параметры без перевода, переводите только описательные тексты.
• Даты и форматы дат приводите в формате ISO (YYYY-MM-DD) для однозначности.

Визуальная проверка и удобство чтения

• Используйте короткие предложения и активный залог.
• Разбивайте длинные описания на абзацы и подзаголовки.
• Старайтесь не дублировать информацию: если опция описана в Options, не расписывайте её ещё раз в Description без нужды.

Decision tree для выбора формата документации

flowchart TD
  A[Нужна документация?] -->|Да| B[CLI-утилита]
  A -->|Нет| Z[Только README]
  B --> C{Нужны man?}
  C -->|Для админов/пакетов| D[Да — Написать man]
  C -->|Для веб/новичков| E[README + сайт]
  D --> F[pandoc -> man]
  F --> G[Проверить через man -l -]
  G --> H[Установить в /usr/local/man и mandb]

Краткое резюме

Написание man-страницы не обязательно должно быть сложным. Используйте Markdown и pandoc, чтобы сосредоточиться на содержании. Пройдите простую SOP-последовательность: оформить front matter, написать минимальные разделы, протестировать через man из stdin, экспортировать, установить и обновить базу man.

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