.Dd December 1, 2015 (1) .Dt LS 1 .Sh NAME (2) .Nm ls .Nd list directory contents .Sh SYNOPSIS (3) .Nm (4) .Op Fl -libxo (5) .Op Fl ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1, (6) .Op Fl D Ar format (7) .Op Ar (8) .Sh DESCRIPTION (9) For each operand that names a .Ar file of a type other than directory, .Nm displays its name as well as any requested, associated information. For each operand that names a .Ar file of type directory, .Nm displays the names of files contained within that directory, as well as any requested, associated information.
Глава 11. Справочник
Этот перевод может быть устаревшим. Для того, чтобы помочь с переводом, пожалуйста, обратитесь к Сервер переводов FreeBSD.
Содержание
11.1. Введение
Справочник, часто сокращаемый до man-страниц, изначально задумывались как легкодоступные напоминания о синтаксисе команд, деталях драйверов устройств или форматах конфигурационных файлов. Со временем они стали крайне полезным справочным материалом для быстрого ознакомления прямо из командной строки для пользователей, системных администраторов и программистов.
Хотя они предназначены скорее как справочные материалы, а не учебные руководства, разделы EXAMPLES в manual pages часто содержат подробные примеры использования.
Страницы Справочника обычно отображаются интерактивно с помощью команды man(1). Когда пользователь вводит man ls, выполняется поиск страницы Справочника, соответствующей ls. Первый найденный результат отображается.
11.2. Разделы
Страницы справочника (man-страницы) сгруппированы по разделам. Каждый раздел содержит man-страницы для определённой категории документации:
| Номер раздела | Категория |
|---|---|
1 | Общие команды |
2 | Системные вызовы |
3 | Функции библиотек |
4 | Интерфейсы ядра |
5 | Форматы файлов |
6 | Игры |
7 | Разное |
8 | Системный администратор |
9 | Разработчик ядра |
11.3. Язык разметки
Для man-страниц использовались различные формы разметки и программы отображения. FreeBSD использовала groff(7) и более новую mandoc(1). Большинство существующих man-страниц FreeBSD, а также все новые, используют разметку в формате mdoc(7). Это простая построчная разметка, обладающая достаточной выразительностью. В основном она семантическая: части текста помечаются по их назначению, а не по тому, как они должны выглядеть при отображении. Существует некоторая разметка, основанная на внешнем виде, которую обычно лучше избегать.
Исходный код страницы справочника обычно интерпретируется и отображается на экране в интерактивном режиме. Исходные файлы могут быть обычными текстовыми файлами или сжатыми с помощью gzip(1) для экономии места.
Страницы справочника также могут быть преобразованы в другие форматы, включая PostScript для печати или генерации PDF. См. man(1).
11.3.1. Разделы Справочника
Страницы справочника состоят из нескольких стандартных разделов. Каждый раздел имеет заголовок в верхнем регистре, а разделы для определённого типа man-страниц следуют в строго определённом порядке. Для man-страниц категории 1 (Общие команды) разделы идут в следующем порядке:
| Название Раздела | Описание |
|---|---|
NAME (ИМЯ) | Название команды |
SYNOPSIS (СИНТАКСИС) | Формат опций и аргументов |
DESCRIPTION (ОПИСАНИЕ) | Описание назначения и использования |
ENVIRONMENT (ОКРУЖЕНИЕ) | Настройки окружения, влияющие на работу |
EXIT STATUS (СТАТУС ВЫХОДА) | Коды ошибок, возвращаемые при завершении |
EXAMPLES (ПРИМЕРЫ) | Примеры использования |
COMPATIBILITY (СОВМЕСТИМОСТЬ) | Совместимость с другими реализациями |
SEE ALSO (СМ. ТАКЖЕ) | Перекрестная ссылка на связанные страницы руководства |
STANDARDS (СТАНДАРТЫ) | Совместимость со стандартами, такими как POSIX |
HISTORY (ИСТОРИЯ) | История реализации |
BUGS (ИЗВЕСТНЫЕ ОШИБКИ) | Известные ошибки |
AUTHORS (АВТОРЫ) | Люди, которые создали команду или написали справочную страницу. |
Некоторые разделы являются необязательными, и сочетание разделов для конкретного типа справочной страницы может различаться. Примеры наиболее распространённых типов приведены далее в этой главе.
11.3.2. Макросы
Разметка mdoc(7) основана на макросах. Строки, начинающиеся с точки, содержат макрокоманды, каждая длиной в две или три буквы. Например, рассмотрим эту часть man-страницы ls(1):
| 1 | Определены Дата документа (.Dd) и Название документа (.Dt). |
| 2 | Для раздела NAME определяется Заголовок раздела (.Sh). Затем определяется Имя (.Nm) команды и Описание имени (.Nd) в одну строку. |
| 3 | Начинается раздел SYNOPSIS (.Sh). В этом разделе описываются параметры командной строки и аргументы, которые принимаются. |
| 4 | Имя (.Nm) уже определено, и его повторение здесь просто отображает заданное значение в тексте. |
| 5 | Отображается необязательный флаг (.Op Fl) -libxo. Макрос Fl добавляет тире в начало флагов, поэтому в руководстве он отображается как --libxo. |
| 6 | Отображается длинный список необязательных флагов, состоящих из одного символа. |
| 7 | Определён необязательный флаг -D. Если указан флаг -D, за ним должен следовать аргумент. Аргумент представляет собой формат — строку, которая указывает ls(1), что и как отображать. Подробности о строке формата приведены далее на странице руководства. |
| 8 | Определен последний необязательный аргумент. Поскольку для аргумента не указано имя, используется значение по умолчанию file …. |
| 9 | Заголовок раздела (.Sh) для раздела DESCRIPTION определен. |
При отображении с помощью команды man ls результат выводится на экран следующим образом:
LS(1) FreeBSD General Commands Manual LS(1)
NAME
ls - list directory contents
SYNOPSIS
ls [--libxo] [-ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1,] [-D format]
[file ...]
DESCRIPTION
For each operand that names a file of a type other than directory, ls
displays its name as well as any requested, associated information. For
each operand that names a file of type directory, ls displays the names
of files contained within that directory, as well as any requested,
associated information.Необязательные значения указаны в квадратных скобках.
11.3.3. Руководство по разметке
Язык разметки mdoc(7) не является очень строгим. Для ясности и согласованности проект FreeBSD Documentation добавляет некоторые дополнительные рекомендации по стилю:
- Только первая буква макросов пишется с заглавной буквы
Всегда используйте заглавную букву для первого символа макроса и строчные буквы для остальных символов.
- Начинайте новые предложения с новых строк
Начинайте новое предложение с новой строки, не начинайте его на той же строке, что и существующее предложение.
- Обновите
.Ddпри внесении значительных изменений в справочную страницу Дата документа сообщает читателю, когда страница руководства была последний раз обновлена. Важно обновлять её при внесении значительных изменений в страницы руководства. Незначительные правки, такие как исправления орфографии или пунктуации, которые не влияют на использование, могут быть сделаны без обновления
.Dd.- Приведите примеры
Показывайте читателю примеры, когда это возможно. Даже простые примеры ценны, потому что то, что тривиально для автора, не обязательно тривиально для читателя. Хорошей целью являются три примера. Простой пример демонстрирует минимальные требования, серьезный пример показывает реальное использование, а углубленный пример демонстрирует неочевидную или нестандартную функциональность.
- Включить лицензию BSD
Включите лицензию BSD в новые руководства. Предпочтительная лицензия доступна в Руководстве коммиттера.
11.3.4. Приемы Разметки
Добавьте пробел перед пунктуацией на строке с макросами. Пример:
.Sh SEE ALSO .Xr geom 4 , .Xr boot0cfg 8 , .Xr geom 8 , .Xr gptboot 8
Обратите внимание, как запятые в конце строк .Xr размещены после пробела. Макрос .Xr ожидает два параметра: имя внешней страницы руководства и номер раздела. Пробел отделяет пунктуацию от номера раздела. Без пробела внешние ссылки будут некорректно указывать на разделы 4, или 8,.
11.3.5. Важные макросы
Здесь будут показаны некоторые очень распространённые макросы. Для большего количества примеров использования см. mdoc(7), groff_mdoc(7) или выполните поиск реальных примеров в каталогах /usr/share/man/man*. Например, чтобы найти примеры макроса .Bd (Begin display):
% find /usr/share/man/man* | xargs zgrep '.Bd'11.3.5.1. Организационные Макросы
Некоторые макросы используются для определения логических блоков страницы руководства.
| Организационные Макро | Используйте |
|---|---|
| Заголовок раздела. За ним следует название раздела, традиционно записанное в верхнем регистре. Можно рассматривать их как названия глав. |
| Подзаголовок раздела.
За ним следует название подраздела.
Используется для разделения раздела |
| Начало списка (Begin list). Начать перечень элементов. |
| Конец списка (End List). |
| Начало отображения (Begin display). Начать специальную область текста, например, область с отступом. |
| Завершить отображение (End display). |
11.3.5.2. Встроенные макросы
Многие макросы используются для разметки текста внутри строк.
| Встроенный макрос | Используйте |
|---|---|
| Имя (Name). При первом использовании вызывается с именем в качестве параметра, затем используется без параметра для отображения уже определенного имени. |
| Путь к файлу (Path to a file). Используется для обозначения имен файлов и путей к каталогам. |
11.4. Пример структуры страницы руководства
Этот раздел демонстрирует минимально желаемое содержание man-страниц для нескольких распространённых категорий руководств.
11.4.1. Раздел 1 или 8 — Команда
Предпочтительная базовая структура для раздела 1 или 8 — Команда:
.Dd August 25, 2017 .Dt EXAMPLECMD 8 .Os .Sh NAME .Nm examplecmd .Nd "command to demonstrate section 1 and 8 man pages" .Sh SYNOPSIS .Nm .Op Fl v .Sh DESCRIPTION The .Nm utility does nothing except demonstrate a trivial but complete manual page for a section 1 or 8 command. .Sh SEE ALSO .Xr exampleconf 5 .Sh AUTHORS .An Firstname Lastname Aq Mt flastname@example.com
11.4.2. Раздел 4 — Драйверы устройств
Предпочтительная базовая структура для раздела 4 — драйверы устройств:
.Dd August 25, 2017 .Dt EXAMPLEDRIVER 4 .Os .Sh NAME .Nm exampledriver .Nd "driver to demonstrate section 4 man pages" .Sh SYNOPSIS To compile this driver into the kernel, add this line to the kernel configuration file: .Bd -ragged -offset indent .Cd "device exampledriver" .Ed .Pp To load the driver as a module at boot, add this line to .Xr loader.conf 5 : .Bd -literal -offset indent exampledriver_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides an opportunity to show a skeleton or template file for section 4 manual pages. .Sh HARDWARE The .Nm driver supports these cards from the aptly-named Nonexistent Technologies: .Pp .Bl -bullet -compact .It NT X149.2 (single and dual port) .It NT X149.8 (single port) .El .Sh DIAGNOSTICS .Bl -diag .It "flashing green light" Something bad happened. .It "flashing red light" Something really bad happened. .It "solid black light" Power cord is unplugged. .El .Sh SEE ALSO .Xr example 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 49.2 . .Sh AUTHORS .An Firstname Lastname Aq Mt flastname@example.com
11.4.3. Раздел 5 — Файл конфигурации
Предпочтительная базовая структура для раздела 5 — файл конфигурации:
.Dd August 25, 2017 .Dt EXAMPLECONF 5 .Os .Sh NAME .Nm example.conf .Nd "config file to demonstrate section 5 man pages" .Sh DESCRIPTION .Nm is an example configuration file. .Sh SEE ALSO .Xr example 8 .Sh AUTHORS .An Firstname Lastname Aq Mt flastname@example.com
11.5. Тестирование
Проверка новой страницы руководства может быть непростой задачей. К счастью, существуют инструменты, которые могут помочь в этом. Некоторые из них, например man(1), не ищут в текущем каталоге. Хорошей практикой является добавление префикса ./ к имени файла, если новая страница руководства находится в текущем каталоге. Также можно использовать абсолютный путь.
Используйте линтер mandoc(1) для проверки на ошибки парсинга:
% mandoc -T lint ./mynewmanpage.8Используйте textproc/igor для проверки страниц Справочника:
% igor ./mynewmanpage.8Еще один полезный инструмент — textproc/vale. Он не поддерживает синтаксис mdoc(7), но обработанную страницу руководства можно прочитать из стандартного ввода:
% man ls | valetextproc/vale обладает высокой степенью настраиваемости. Рекомендуется ознакомиться с его документацией.
Используйте man(1) для проверки конечного результата ваших изменений:
% man ./mynewmanpage.8Вы можете использовать col(1) для фильтрации вывода man(1) и удаления backspace-символов перед загрузкой результата в ваш любимый редактор для проверки орфографии:
% man ./mynewmanpage.8 | col -b | vim -R -Проверка орфографии с использованием полнофункциональных словарей рекомендуется и может быть выполнена с помощью textproc/hunspell или textproc/aspell в сочетании с textproc/en-hunspell или textproc/en-aspell соответственно. Например:
% aspell check --lang=en --mode=nroff ./mynewmanpage.811.6. Примеры страниц Справочника для использования в качестве шаблонов
Некоторые страницы Справочника могут служить подробными примерами.
| Страница Справочника | Путь к расположению исходного кода |
|---|---|
/usr/src/bin/cp/cp.1 | |
/usr/src/share/man/man4/vt.4 | |
/usr/src/usr.sbin/cron/crontab/crontab.5 | |
/usr/src/sbin/geom/class/part/gpart.8 |
Изменено: 20 сентября 2025 г. by Vladlen Popolitov