man(7) | Miscellaneous Information Manual | man(7) |
man - макросы для форматирования справочных страниц
groff -Tascii -man файл
...
groff -Tps -man файл ...
man [раздел] имя
В этой справочной странице описывается макет макросов groff an.tmac (часто называемый макетом макросов man). Данный пакет макросов должен использоваться разработчиками для написания или переноса справочных страниц в Linux. Он относительно совместим с другими версиями этого пакета макросов, так что перенос справочных страниц не должен быть большой проблемой (кроме выпуска NET-2 BSD, в котором используется полностью другой пакет макросов mdoc; смотрите mdoc(7)).
Заметим, что справочные страницы NET-2 BSD mdoc можно использовать с groff просто указав параметра -mdoc вместо -man. Однако рекомендуется использовать параметр -mandoc, так как это включает автоматическое определение какой пакет макросов использовать.
Соглашения, которые нужно соблюдать при написании справочных страниц для пакета Linux man-pages смотрите в man-pages(7).
Первой командой в справочной странице (после комментариев, то есть строк, которые начинаются с .\") должна быть
Описание аргументов команды TH смотрите в man-pages(7).
Заметим, что страницы, отформатированные под BSD mdoc, начинаются с команды Dd, а не TH.
Разделы начинаются с макроса .SH, за которым следует название заголовка.
Единственным обязательным заголовком является ИМЯ, оно должно быть первым разделом и снабжаться однострочным описанием программы на следующей строке:
Чрезвычайно важно следовать этому формату, и ставить наклонную черту влево перед одиночным минусом, который указывается после названия объекта. Этот синтаксис используется программой mandb(8) при создании базы данных кратких описаний для команд whatis(1) и apropos(1) (описание синтаксиса раздела ИМЯ смотрите в lexgrog(1)).
Список разделов, которые могут присутствовать в справочной странице, смотрите в man-pages(7).
Команды для выбора начертания шрифта:
Traditionally, each command can have up to six arguments, but the GNU implementation removes this limitation (you might still want to limit yourself to 6 arguments for portability's sake). Arguments are delimited by spaces. Double quotes can be used to specify an argument which contains spaces. For the macros that produce alternating type faces, the arguments will be printed next to each other without intervening spaces, so that the .BR command can be used to specify a word in bold followed by a mark of punctuation in Roman. If no arguments are given, the command is applied to the following line of text.
Below are other relevant macros and predefined strings. Unless noted otherwise, all macros cause a break (end the current line of text). Many of these macros set or use the "prevailing indent". The "prevailing indent" value is set by any macro with the parameter i below; macros may omit i in which case the current prevailing indent will be used. As a result, successive indented paragraphs can use the same indent without respecifying the indent value. A normal (nonindented) paragraph resets the prevailing indent value to its default value (0.5 inches). By default, a given indent is measured in ens; try to use ens or ems as units for indents, since these will automatically adjust to font size changes. The other key macro definitions are:
Эти макросы поддерживаются в GNU Troff начиная с версии 1.20 (2009-01-05) и в Heirloom Doctools Troff начиная с версии 160217 (2016-02-17).
В пакете man есть следующие предопределённые строки:
Хотя технически man и является пакетом макросов troff, большое количество других инструментов обработки файлов справочных страниц не реализуют все свойства 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.
You may also use many troff escape sequences (those sequences beginning with \). When you need to include the backslash character as normal text, use \e. Other sequences you may use, where x or xx are any characters and N is any digit, include: \', \`, \-, \., \", \%, \*x, \*(xx, \(xx, \$N, \nx, \n(xx, \fx, and \f(xx. Avoid using the escape sequences for drawing graphics.
Do not use the optional parameter for bp (break page). Use only positive values for sp (vertical space). Don't define a macro (de) with the same name as a macro in this or the mdoc macro package with a different meaning; it's likely that such redefinitions will be ignored. Every positive indent (in) should be paired with a matching negative indent (although you should be using the RS and RE macros instead). The condition test (if,ie) should only have 't' or 'n' as the condition. Only translations (tr) that can be ignored should be used. Font changes (ft and the \f escape sequence) should only have the values 1, 2, 3, 4, R, I, B, P, or CW (the ft command may also have no parameters).
Если кроме этих возможностей вы используете какие-то другие, то внимательно проверяйте результат на нескольких инструментах. После положительной проверки дополнительной возможности, напишите об этом сопровождающему этого документа о безопасной команде или последовательности, которая будет вставлена в этот список.
/usr/share/groff/[*/]tmac/an.tmac
/usr/man/whatis
Всегда включайте полные URL (или URI) в сам текст; некоторые инструменты, например man2html(1), могут автоматически преобразовывать их в гипертекстовые ссылки. Для обозначения ссылок также вы можете использовать макросы UR и UE. При добавлении URL используйте полный URL (например, http://www.kernel.org) , чтобы инструменты могли автоматически найти URL.
Tools processing these files should open the file and examine the first nonwhitespace character. A period (.) or single quote (') at the beginning of a line indicates a troff-based file (such as man or mdoc). A left angle bracket (<) indicates an SGML/XML-based file (such as HTML or Docbook). Anything else suggests simple ASCII text (e.g., a "catman" result).
Many man pages begin with '\" followed by a space and a list of characters, indicating how the page is to be preprocessed. For portability's sake to non-troff translators we recommend that you avoid using anything other than tbl(1), and Linux can detect that automatically. However, you might want to include this information so your man page can be handled by other (less capable) systems. Here are the definitions of the preprocessors invoked by these characters:
Большинство макросов служат для форматирования (например, тип шрифта и интервал), а не для маркировки семантического содержания (например, что текст — ссылка на другую страницу), если сравнивать с форматами mdoc и DocBook (даже в HTML больше семантической маркировки). Это усложняет создание формата man для разных носителей, чтобы выдать непротиворечивый результат для определённого носителя и автоматически вставить перекрестные ссылки. Использование безопасного подмножества, описанного выше, должно упростить автоматизацию перехода между разными форматами ссылок в будущем.
Макрос Sun TX не реализован.
apropos(1), groff(1), lexgrog(1), man(1), man2html(1), groff_mdoc(7), whatis(1), groff_man(7), groff_www(7), man-pages(7), mdoc(7)
Русский перевод этой страницы руководства был сделан aereiae <aereiae@gmail.com>, Alexey <a.chepugov@gmail.com>, Azamat Hackimov <azamat.hackimov@gmail.com>, Dmitriy S. Seregin <dseregin@59.ru>, Dmitry Bolkhovskikh <d20052005@yandex.ru>, ITriskTI <ITriskTI@gmail.com>, Max Is <ismax799@gmail.com>, Yuri Kozlov <yuray@komyakino.ru>, Иван Павлов <pavia00@gmail.com> и Малянов Евгений Викторович <maljanow@outlook.com>
Этот перевод является бесплатной документацией; прочитайте Стандартную общественную лицензию GNU версии 3 или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ.
Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте электронное письмо на man-pages-ru-talks@lists.sourceforge.net.
5 февраля 2023 г. | Linux man-pages 6.03 |