На этой странице описывается макропакет
groff tmac.an
(часто называемый макропакетом
man)
и соглашения по созданию страниц руководства (manual pages).
Этот макропакет должен использоваться разработчиками при
написании страниц руководства по Linux или переносе их с других систем.
Вариант Linux практически полностью совместим с другими версиями этого
макропакета, поэтому с переносом не должно возникнуть проблем (за исключением
NET-2 BSD, использующего совсем другой пакет под названием mdoc; смотрите
mdoc(7)).
Заметьте, что mdoc-страницы руководства по NET-2 BSD могут быть
просмотрены при помощи
groff
путем указания опции
-mdoc
вместо
-man.
Однако, рекомендуется использование
-mandoc,
так как в этом случае формат будет распознан автоматически.
ПРЕАМБУЛА
Первой на странице руководства (после комментариев) должна быть команда
.THзаголовок раздел дата источник документация,
где:
заголовок
Заголовок страницы руководства (например,
MAN).
раздел
Номер раздела, где должна находиться страница руководства (например,
7).
дата
Дата последнего изменения. Hе забывайте изменять эту дату
каждый раз, так как это наиболее простой способ контролировать версии
документа.
source
Источник.
Для задания команд надо использовать что-то вроде:
GNU, NET-2, SLS Distribution, ASPLinux Distribution.
Для системных вызовов используйте версию ядра, с которой Вы работаете, например:
Linux 0.99.11.
Для библиотечных вызовов используйте один из источников:
GNU, BSD 4.3, Linux DLL 4.4.1.
документация
Название руководства (например,
Linux Programmer's Manual).
Заметьте, что mdoc-страницы в BSD начинаются с команды
Dd,
а не с
TH.
Разделы страниц руководства, обычно такие:
1 Команды
Команды, обычно запускаемые пользователем из оболочки.
Формат файла
/etc/passwd
и других, подобных ему, файлов настроек.
6 Игры
7 Макропакеты и соглашения
Описание стандартной "раскладки" файловой системы, сетевых протоколов,
кодов ASCII и других таблиц, данная страница документации и др.
8 Команды управления системой
Команды типа
mount(8),
исполняемые обычно только суперпользователем
root.
9 Процедуры ядра
Это устаревший раздел руководства.
В свое время появилась идея держать документацию о ядре Linux в этом разделе.
Однако, в то время документация о ядре была неполной, и по большей части устаревшей.
Существуют гораздо более удобные источники информации для разработчиков ядра.
РАЗДЕЛЫ
Разделы страниц документации начинаются с команды
.SH,
за которой следует название раздела.
Если название раздела содержит пробелы, то это название
необходимо заключать в двойные кавычки.
Рекомендуется использование стандартных названий секций:
НАЗВАНИЕ, СИНТАКСИС, ОПИСАНИЕ, ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ,
КОД ЗАВЕРШЕНИЯ, ОБРАБОТКА ОШИБОК, ОШИБКИ,
ОПЦИИ, ИСПОЛЬЗОВАНИЕ, ПРИМЕРЫ, ФАЙЛЫ, ПЕРЕМЕННЫЕ ОКРУЖЕНИЯ, СООБЩЕНИЯ ОБ ОШИБКАХ,
БЕЗОПАСНОСТЬ, СООТВЕТСТВИЕ, ПРИМЕЧАНИЯ,
ЗАМЕЧАНИЯ, АВТОРЫ и СМ.ТАКЖЕ.
Пожалуйста, используйте стандартные заголовки там, где это
возможно: подобная однозначность позволяет упростить
понимание предоставленной информации.
Однако, Вы можете использовать и свои заголовки, если считаете,
что Ваше название раздела будет более понятным.
Единственный обязательный раздел -
НАЗВАНИЕ.
Он должен быть первым, и за его заголовком
должна следовать одна строка с описанием программы:
.SH НАЗВАНИЕ
man \- макросы форматирования страниц руководства
Очень важно следовать этому формату, включая обозначение обратного слэша перед
тире, идущего после названия команды. Этот формат используется программой
makewhatis(8)
для создания базы данных кратких описаний программ.
Эта база используется при помощи команд
whatis(1)
и
apropos(1).
Остальные стандартные разделы должны содержать в себе следующее:
СИНТАКСИС
содержит краткое описание команды или интерфейса функции.
В этой секции приводится синтаксис команды и ее параметры (включая опции);
жирный шрифт используется для неизменяемого текста, а наклонный -
для указания параметров, заменяемых конкретными значениями.
Квадратные скобки ([]) указывают на необязательные параметры,
символ | означает несколько возможных вариантов, а многоточие (...)
- то, что параметр может повторяться.
Функциям в этом разделе указываются все необходимые
определения данных и/или директивы
#include,
за которыми следует определение самой функции.
ОПИСАНИЕ
объясняет, что делает команда, функция или формат.
Описывается работа с файлами и стандартным потоком ввода и то, что попадает
в стандартный поток вывода или в стандартный поток ошибок.
В этом разделе можно не описывать детали внутреннего строения функции или команды
и отличия в их реализации, если они не важны для понимания интерфейса.
Кроме того, здесь можно привести пример вызова команды (функции).
Для описания опций используйте секцию
ОПЦИИ.
Если имеется общая для всех описываемых команд часть или сложный набор
подкоманд, то их лучше описывать в секции
ИСПОЛЬЗОВАНИЕ
(а в секции
ОПИСАНИЕ
привести лишь обзор действий).
ВОЗВРАЩЕМОЕ ЗНАЧЕНИЕ
содержит список значений, которые библиотечная
функция возвращает вызвавшему процессу, а также условия
возникновения тех или иных значений.
КОД ЗАВЕРШЕНИЯ
содержит список возможных кодов завершения программы
и условия их возникновения.
ОПЦИИ
содержит список всех возможных опций программы и их
влияние на работу программы.
ИСПОЛЬЗОВАНИЕ
содержит описание внутренней грамматики подъязыка программы.
ПРИМЕРЫ
содержит один или несколько примеров использования данной функции,
файла или команды.
ФАЙЛЫ
содержит список файлов, с которыми работает программа
или функция (файлы конфигурации, пакетные файлы,
а также файлы, с которыми работает сама программа).
Приводится полный путь к файлам, а процесс установки страницы
должен изменять эти пути в соответствии с настройками системы.
Многие программы по умолчанию устанавливаются в /usr/local,
поэтому в исходной версии страницы должен указываться
каталог /usr/local.
ПЕРЕМЕННЫЕ ОКРУЖЕНИЯ
содержит список переменных окружения, влияющих на работу программы
или функции, а также суть этого влияния.
СООБЩЕНИЯ ОБ ОШИБКАХ
содержит описание возможных ошибок и способы их устранения.
Нет необходимости описывать сообщения об ошибках системы или
сигналы тревоги, которые могут возникнуть в процессе работы
любой программы, если только они не влияют на работу Вашей программы.
БЕЗОПАСНОСТЬ
В этой главе рассматриваются вопросы безопасности и следствия
некорректной работы программы. Описаны ситуации, которых следует избегать;
команды, которые могут привести к серьезным
проблемам в системе безопасности, в особенности, если они незаметны.
Описание этих вопросов необязательно выносить в отдельный
раздел: иногда проще поместить эту информацию в другие
разделы, например, в
ОПИСАНИЕ
или
ИСПОЛЬЗОВАНИЕ.
Обязательно включите эту информацию в один из разделов!
СООТВЕТСТВИЕ
содержит ссылки на стандарты или соглашения, которым соответствует
программа или функция.
ПРИМЕЧАНИЯ
содержит различные примечания.
ЗАМЕЧАНИЯ
содержит список ограничений, известных недочетов или несоответствий в описании
и прочих погрешностей, которые могут возникнуть при работе с программой
или функцией.
АВТОР
содержит список авторов документации или программы, чтобы Вы могли
послать им отчет об ошибках в работе программы.
СМ. ТАКЖЕ
содержит список ссылок на другие страницы руководства, так или иначе
связанные с текущей. Список составлен в алфавитном порядке; далее может
следовать список другой документации, связанной с этой страницей.
Обычно это последняя секция.
ШРИФТЫ
Несмотря на то, что в мире UNIX существует много разных соглашений по формату
страниц руководства, наличие нескольких сотен страниц руководства по Linux
привело к созданию некоторых стандартов использования шрифтов:
Параметры функций всегда пишутся курсивом,
даже в секции СИНТАКСИС,
а все остальное пишется жирным шрифтом:
int myfunction(int argc, char **argv);
Имена файлов всегда пишутся курсивом (например,
/usr/include/stdio.h)
за исключением секции СИНТАКСИС, в которой имена включаемых файлов пишутся
жирным шрифтом (например,
#include <stdio.h>).
Для специальных макросов, которые обычно пишутся прописными буквами,
используется жирный шрифт (например,
MAXINT).
Коды ошибок в списке пишутся жирным шрифтом (для списка обычно используется
макрос
.TP).
Ссылки на другие страницы руководства (или на объект описания текущей страницы)
пишутся жирным шрифтом. Если приводится и номер раздела, то он пишется
обычным (Roman) шрифтом без пробелов (например,
man(7)).
Для выбора шрифта используются следующие команды:
.B
Утолщенный шрифт
.BI
Утолщенный и затем наклонный шрифт
(удобно при описании функций)
.BR
Утолщенный и затем обычный шрифт
(удобно при приведении ссылок на другие страницы)
.I
Наклонный шрифт
.IB
Наклонный и затем утолщенный шрифт
.IR
Наклонный и затем обычный шрифт
.RB
Обычный и затем утолщенный шрифт
.RI
Обычный и затем наклонный шрифт
.SB
Сжатый и затем утолщенный шрифт
.SM
Сжатый шрифт (удобен для акронимов)
Раньше у этих команд не могло быть более шести параметров, но реализация GNU
сняла это ограничение (Вы можете сами ограничивать себя шестью параметрами
для обеспечения совместимости).
Параметры разделяются пробелами. Параметры, содержащие пробелы,
заключаются в двойные кавычки.
Все параметры этих команд будут напечатаны слитно, без пробелов,
поэтому команду
.BR
можно использовать для вывода слова жирным шрифтом, за которым
следует знак препинания, выводимый обычным шрифтом.
Если параметров нет, то команда относится к следующей строке текста.
ДРУГИЕ МАКРОСЫ И СТРОКИ
Ниже приведен список других полезных макросов и строковых констант.
Если не указано иное, все макросы вызывают перевод строки
(конец текущей строки текста). Многие из этих макросов задают или используют
"стандартный" отступ. Значение этого "стандартного отступа" может быть задано
в любом макросе при помощи параметра, упоминаемого ниже как
i;
этот параметр может и не применяться. В этом случае
используется текущее значение отступа.
То есть вложенные параграфы с отступом могут использовать то же значение
отступа без его повторного указания.
Макросы обычного параграфа (без отступа) переводят значение отступа в
стандартное значение (0.5 дюйма).
По умолчанию отступ измеряется в энах (ens); в качестве единиц можно использовать
эны (n) и эмы (m), так как это позволяет автоматически подстраиваться
под изменение размера шрифта. (Эм - печатная единица измерения, равная
ширине равностороннего символа (М). Эн - печатная единица измерения, равная
ширине символа, вдвое меньшей высоты(Н)).
Другие ключевые макроопределения:
Обычные параграфы
.LP
То же, что и
.PP
(начало нового параграфа).
.P
То же, что и
.PP
(начало нового параграфа).
.PP
Начинает новый параграф и "сбрасывает" значение стандартного отступа.
Относительный сдвиг границы
.RS i
Начало относительного сдвига левой границы: отодвигает
левую границу текста на
i
вправо (если
i
не упоминается, то используется стандартный отступ).
Новый стандартный отступ устанавливается равным 0.5 дюйма.
В результате выполнения этой команды левая граница
всех последующих параграфов будет сдвинута вправо до
появления соответствующей команды
.RE.
.RE
Завершает относительный сдвиг левой границы и восстанавливает
предыдущее значение стандартного отступа.
Макросы работы с отступами параграфов
.HP i
Начало параграфа с "висячим" отступом
(первая строка параграфа находится на левой границе обычного
параграфа, а остаток параграфа выводится с отступом).
.IP x i
Параграф с отступом и возможным "висячим" тэгом.
Если тэг
x
опущен, то весь параграф будет выведен с отступом
i.
Если же тэг
x
задан, то он будет выведен на левой границе до параграфа (аналогично
.TP,
только тэг находится в самой команде, а не в следующей строке).
Если тэг слишком длинный, то текст после тэга будет опущен на
строку вниз (без потерь или искажений).
В случае возникновения неупорядоченных списков используйте макрос
\(be или \(em в качестве тэга),
а в случае возникновения упорядоченных списков - цифру или букву, за которой следует
точка: это упростит преобразование файла в другие форматы.
.TP i
Начало параграфа с "висячим" тэгом. Тэг задается в следующей строке, но результаты
аналогичны команде
.IP.
Макросы гипертекстовых ссылок
.UR u
Начало гипертекстовой ссылки на URI (URL)
u;
ее окончание указывается при помощи команды
UE.
При создании HTML это начало должно преобразоваться в HTML-тэг
<A HREF="u">.
Правда, есть исключение: если
u
равно специальному значению ":", то никакие гипертекстовые ссылки
не будут создаваться в тексте до появления соответствующей
закрывающей команды
UE
(это позволяет отключить ссылки во фразах типа
LALR(1),
когда формирование ссылок неприемлемо).
Эти гипертекстовые макросы являются нововведением,
и многие утилиты (включая и troff) ничего не делают
с ними, но так как большинство из них просто игнорирует неопределенные
макросы (в худшем случае, вставляет их в результат), поэтому такие макросы можно свободно
вставлять в страницу.
.UE
Окончание гипертекстовой ссылки, заданной командой
UR;
При создании HTML эта команда должна преобразоваться в HTML-тэг
</A>.
.UN u
Создает гипертекстовую ссылку на URL
u;
для этой команды соответствующей команды
UE
не требуется.
При создании HTML эта команда должна преобразоваться в HTML-тэг
<A NAME="u" id="u"> </A>
( указывать необязательно, если не нужна поддержка Mosaic).
Прочие Макросы
.DT
Перевести значения позиций табуляции в стандартные значения (по
0.5 дюйма каждое); эта команда не вызывает перевода
строки.
.PD d
Установить расстояние между параграфами, равное d
(по умолчанию d=40% высоты строки); эта команда не вызывает перевода
строки.
.SS t
Подзаголовок
t
(то же самое, что и
.SH,
но используется в качестве заголовка подраздела внутри раздела).
Предопределенные строки
В пакете
man
предопределены следующие строки:
\*R
Символ регистрации: ®
\*S
Переход к стандартному размеру шрифта
\*(Tm
Символ торговой марки:
\*(lq
Левая угловая двойная кавычка: ``
\*(rq
Правая угловая двойная кавычка: ''
БЕЗОПАСНОСТЬ
Несмотря на то, что технически
man
- это макро-пакет, основанный на troff, на самом деле существует
большое количество других утилит, работающих с файлами man-страниц,
которые не включают в себя всех возможностей troff.
Таким образом, лучше избегать всех экзотических возможностей troff
везде, где это возможно.
Избегайте использования различных препроцессоров troff
(если необходимо, используйте
tbl(1),
но старайтесь использовать команды
IP
и
TP
для двухколоночных таблиц).
Избегайте использования вычислений; многие утилиты не обрабатывают
их. Используйте простые команды, которые легко преобразовывать в другие форматы.
Следующие макросы troff считаются безопасными (во многих
случаях они игнорируются преобразователями форматов):
\ ,.,
ad,
bp,
br,
ce,
de,
ds,
el,
ie,
if,
fi,
ft,
hy,
ig,
in,
na,
ne,
nf,
nh,
ps,
so,
sp,
ti,
tr.
Вы можете использовать и многие escape-последовательности troff,
начинающиеся с \).
Если Вы хотите проставить обратный слэш в тексте, то используйте \e.
Вы можете использоть и другие последовательности, где x или xx -
это любые символы, а N - это цифра, в том числе:
\',
\`,
\-,
\.,
\ ,\%,
\*x,
\*(xx,
\(xx,
\$N,
\nx,
\n(xx,
\fx
и
\f(xx.
Избегайте использования экранирующих последовательностей для вывода графики.
Не используйте необязательный параметр команды
bp
(разрыв страницы).
Используйте только положительные значения для задания
sp
(вертикального сдвига).
Не определяйте макрос
(de)
с тем же именем в данном пакете или пакете mdoc,
в котором этот макрос имеет другое значение;
скорее всего, такие определения будут
проигнорировани.
Каждый положительный отступ
(in)
должен сочетаться с соответствующим отрицательным
отступом (хотя лучше использовать вместо этого
макросы
RS
и
RE
).
Условный оператор
(if,ie)
в качестве условий должен иметь только 't' или 'n'.
Из преобразований
(tr)
должны использоваться только те, которые могут быть проигнорированы.
Изменения шрифтов
(ft
и экранирующие последовательности \f)
должны использоваться только со значениями 1, 2, 3, 4, R, I, B, P или CW
(у команды ft может и не быть параметров).
Если Вы используете другие возможности troff,
то аккуратно проверьте результаты на нескольких утилитах.
После того, как Вы убедитесь в безопасности этой команды,
дайте знать об этом администратору данного документа,
чтобы он мог включить безопасную команду или экранирующую последовательность в этот список.
ЗАМЕЧАНИЯ
Любыми способами включайте полные URL (или URI) в сам текст;
многие утилиты, такие, как
man2html(1),
могут автоматически преобразовывать их в ссылки.
Вы также можете использовать новый макрос
UR
для создания ссылок на сопутствующую информацию.
Если Вы используете URL, то используйте полную форму
(например, <http://www.kernelnotes.org>) для того, чтобы утилиты
могли их автоматически найти.
Утилиты, обрабатывающие подобные файлы, должны открыть файл
и рассмотреть первый непустой символ. Точка (.) или апостроф (')
в начале файла означают файл в формате troff (man или mdoc).
Левая угловая скобка (<) означает файл в формате SGML/XMSL
(например, HTML или Docbook). Все остальное должно считаться
простым ASCII-текстом (например, результатом работы "catman").
Многие страницы начинаются с символов "\" , за которыми
следуют пробелы и список символов, определяющих, как должна
обрабатываться страница.
Для совместимости с не-troff конверторами мы рекомендуем избегать
использования препроцессоров, кроме
tbl(1),
который определяется Linux автоматически.
Однако, Вы можете поместить в данный документ сходную информацию для того, чтобы
Ваша страница могла обрабатываться другими системами (с меньшими
возможностями).
Ниже определены типы препроцессоров, запускаемые этими символами:
Многие макросы описывают форматирование (например, тип шрифта и расстояния) вместо
разметки семантики содержания (например, этот текст является ссылкой на другую
страницу) в отличие от других форматов типа mdoc и DocBook
(даже в HTML больше семантических меток).
По этой причине сложнее преобразовывать формат
man
в другой формат, сохраняя информационную насыщенность нового формата
и автоматическую вставку ссылок.
Если Вы будете задавать безопасные команды, описанные выше,
то в будущем автоматически перейти в другой формат Вам будет гораздо легче.
Макрос
TX
из Sun не реализован.
АВТОРЫ
---
Джеймс Кларк (James Clark <[email protected]>) написал собственно макропакет.
---
Рикард Е. Фэйт (Rickard E. Faith <[email protected]>) написал исходную версию этой страницы.
---
Дженс Швейхардт (Jens Schweikhardt <[email protected]>) написал Linux Man-Page Mini-HOWTO
(ставший исходным вариантом этой страницы руководства).
---
Дэвид А. Вилер (David A. Wheeler <[email protected]>) внес серьезные изменения в эту
страницу, добавив подробную информацию о разделах и макросах.
