[ новости /+++ | форум | теги | ]

НАЗВАНИЕ

СИНТАКСИС

ОПИСАНИЕ

ПРИСТУПАЯ К РАБОТЕ

1. ОГРАНИЧЕНИЯ TROFF

   "Использование макросов"

   "Передача пробелов в виде параметров"

   "Завершающие строку пробелы (предупреждение)"

   "Escape-последовательности для вывода специальных символов"

2. СТРОЕНИЕ СТРАНИЦЫ РУКОВОДСТВА

   "Шаблон страницы руководства"

3. МАКРОСЫ ЗАГОЛОВКА
4. ВВЕДЕНИЕ В СТРАНИЧНЫЙ И ОБЩИЙ ТЕКСТОВЫЙ ДОМЕНЫ

   "Что в имени тебе моем..."

   "Общий синтаксис"

5. СТРАНИЧНЫЙ ДОМЕН

   "Адреса"

   "Автор"

   "Параметры"

   "Задание конфигурации (только раздел #4)"

   "Модификатор команды"

   "Определенные переменные"

   "Коды ошибок (только раздел #2)"

   "Переменные окружения"

   "Параметры функции"

   "Определение функции"

   "Флаги"

   "Функции (в т.ч. и библиотечные)"

   "Типы функций"

   "Интерактивные команды"

   "Названия"

   "Опции"

   "Пути"

   "Переменные"

   "Ссылки"

6. ОБЩИЙ ТЕКСТОВЫЙ ДОМЕН

   "Макрос AT&T"

   "Макрос BSD"

   "Макрос FreeBSD"

   "Макррос UNIX"

   "Макросы выделения"

   "Выделение угловыми скобками"

   "Выделение квадратными скобками"

   "Выделение двойными кавычками"

   "Выделение круглыми скобками"

   "Выделение одинарными кавычками"

   "Макрос префикса"

   "Макрос обычного текста"

   "Макрос отключения пробелов"

   "Ссылки на раздел"

   "Ссылки и цитаты"

   "Возвращаемые значения (только разделы #2 и #3)"

   "Торговые марки (Акронимы и названия видов)"

   "Расширенные параметры"

7. СТРУКТУРНЫЙ ДОМЕН СТРАНИЦЫ

   "Заголовки секций"

   "Параграфы и расстояние между строками"

   "Сохранение исходного формата"

   "Блоки вывода"

   "Режимы шрифтов (Выделение, Неформатируемый текст и Символьный режим)"

   "Списки и колонки"

8. ПРЕДОПРЕДЕЛЕННЫЕ СТРОКИ
9. ДИАГНОСТИКА
10. ФОРМАТИРОВАНИЕ ПРИ ПОМОЩИ GROFF, TROFF И NROFF
11. ОШИБКИ

ОГРАНИЧЕНИЯ TROFF

Использование макросов

Вообще, макросы troff(1) могут иметь до 9-и параметров, остальные же параметры игнорируются. Многие макросы в -mdoc также могут иметь до 9-и параметров, и в некоторых случаях параметров может быть и больше (См. секцию Sx Расширенные параметры ) . Некоторые макросы обрабатывают параметры в кавычках (см. ниже секцию Sx Передача пробелов в виде параметров ).

Многие макросы из общего текстового или страничного доменов -mdoc особенны тем, что их параметры могут представлять собой имена вызываемых макросов. Это означает, что если один из параметров в списке соответствует имени макроса из общего текстового или страничного доменов и этот макрос является вызываемым, то этот макрос будет исполнен или вызван при обработке. В этом случае перед параметром не ставится `.' (точка), несмотря на то, что это имя макроса. Таким образом, макросы могут быть вложенными; например, макрос необязательных параметров, `.[,] ' может вызвать макросы флагов и параметров `- ' и `file ... ' для указания необязательного флага с параметром:

[-s байтов ]

делается при помощи .[-s байтов ]

Для того, чтобы двухсимвольная строка не обрабатывалась в качестве имени макроса, перед ней надо указать `\&' :

[-s bytes ]

делается при помощи .[\&-s \&bytes ]

Таким образом, в данном случае строки `- ' и `file ... ' не считаются именами макросов. Макросы, чьи списки параметров проверяются на наличие в них имен вызываемых макросов, называются "обрабатываемыми", а макросы, которые могут быть вызваны из параметров, называются "вызываемыми". Это не совсем корректно, с технической точки зрения, так как все макросы обрабатываются и вызываются, но эта терминология используется лишь для разделения двух понятий.  

Передача пробелов в виде параметров

Существует два возможных способа передачи параметра, содержащего пробел. Примечание по реализации К сожалению, наиболее простой и удобный способ передачи пробелов внутри кавычек очень отражался на скорости работы и объемах памяти, используемой AT&T troff. Этот способ не отражается на работе groff, но для совместимости этот способ реализован только для тех макросов, которым это было необходимо:

Задание конфигурации (только секция

Sx СИНТАКСИС раздела 4).

Начало списка (для подпараметра width).

Выделенный текст.

Fn Функции (разделы #2 и #3).

Элементы списков.

Неформатируемый текст.

Символьный текст.

%B

Названия книг.

%J

Названия журналов.

%O

Дополнительная информация об упоминаемом тексте.

%R

Название отчета (в упоминаемом тексте).

%T

Название статьи в книге или журнале.

Одним из способов передачи строки, содержащей пробелы, является использование "жесткого" (или непереносимого) пробела `\
 ,' то есть, пробела, перед которым указан символ `\' Этот метод может использоваться в работе с любым макросом, но у него есть побочный эффект - не совсем корректное выравнивание пробелов в строке. Troff рассматривает "жесткий" пробел так, как любой другой печатный символ, и не может разделить строку для форматирования, как того можно было ожидать. Этот метод можно использовать в работе со строками, которые, в принципе, не должны переноситься на новую строку. Например:

Fn fetch char *str

делается при помощи `.Fn fetch ' char\ *str

Fn fetch char *str

можно сделать и так: `.Fn fetch ' \*qchar *str\*q

Если `\' или кавычки опустить, то макрос `.Fn будет ' иметь три параметра, а результат будет следующим:

Fn fetch char *str

Пример, в котором описано, что происходит, если список параметров превышает длину строки, приведен в секции Sx ЗАМЕЧАНИЯ .

Завершающие строку пробелы (предупреждение)

Escape-последовательности для вывода специальных символов

СТРУКТУРА СТРАНИЦЫ РУКОВОДСТВА

Шаблон страницы руководства

.\" Следующие макросы обязательны для всех страниц руководства
.Dd Месяц, день, год
.Os ОПЕРАЦИОННАЯ_СИСТЕМА [версия/релиз]
.Dt НАЗВАНИЕ_ДОКУМЕНТА [номер_раздела] [том]
.Sh НАЗВАНИЕ
.Nm название
.Nd одна строка с описанием названия
.Sh СИНТАКСИС
.Sh ОПИСАНИЕ
.\" Следующие макросы должны быть раскомментированы
.\" и использованы по необходимости.  Эта сеция справедлива
.\" только для описания возвращаемых значений страниц руководства из секций #2 и #3.
.\" .Sh ВОЗВРАЩАЕМЫЕ ЗНАЧЕНИЯ
.\" Эта секция необходима только для страниц разделов #1, #6, #7 и #8
.\" .Sh ПЕРЕМЕННЫЕ ОКРУЖЕНИЯ
.\" .Sh ФАЙЛЫ
.\" .Sh ПРИМЕРЫ
.\" Следующая секция нужна только для разделов #1, #6, #7 и #8
.\"     (возвращаемые shell-значения команды и
.\"       диагностика fprintf/stderr)
.\" .Sh ДИАГНОСТИКА
.\" Следующая секция есть только в разделах #2 и #3
.\" .Sh ОШИБКИ
.\" .Sh СМ.ТАКЖЕ
.\" .Sh СООТВЕТСТВИЕ
.\" .Sh ИСТОРИЯ
.\" .Sh АВТОРЫ
.\" .Sh ЗАМЕЧАНИЯ

Первыми в шаблоне находятся макросы: (., ., . ) дата документа, операционная система страницы руководства или некоторый источник, для которого разрабатывалась или модифицировалась страница, и заголовок страницы, (в верхнем регистре ) вместе с номером раздела, которому принадлежит страница. Эти макросы однозначно идентифицируют страницу. Они описаны ниже в секции Sx МАКРОСЫ ЗАГОЛОВКА .

Все остальное в шаблоне - заголовки секций (. 

,

МАКРОСЫ ЗАГОЛОВКА

.

Название документа сообщает о том, что данный документ описывает. Оно должно быть написано ПРОПИСНЫМИ БУКВАМИ вследствие некоторых ограничений troff. Номер секции может быть от 1-ого до 8-и, и, если он задан, название тома можно опустить. Название тома может быть произвольным или таким:

AMD    UNIX Ancestral Manual Documents (Документы предыдущих версий)

SMM    UNIX System Manager's Manual (Документы системного администратора)

URMUNIX Reference Manual (Справочное руководство)

PRMUNIX Programmer's Manual (Руководство программиста)

По умолчанию
для секций #1,#6 и #7 принимается том URM для секции #8 - SMM а для секций #2, #3, #4 и #5 - PRM

.операционная_система номер_версии

Название операционной системы должно быть общепринятым сокращением, например, BSD FreeBSD или ATT Номер версии должен быть указан в стандартном формате заданной версии системы, например, 4.3, 4.3+Tahoe, V.3, V.4. Нераспознанные параметры выводятся в нижнем колонтитуле страницы, "как есть". Например, стандартный нижний колонтитул выглядит примерно так:

.BSD 4.3,

.FreeBSD 2.2

или (для местного набора страниц)

.Отдел КБ

По умолчанию `.без ' параметров задан как BSD в машинозависимом файле /usr/share/tmac/mdoc/doc-common На самом деле, это должно автоматически преобразовываться, как в случае с LOCAL Заметьте, что если макрос `.не ' указан, то левый нижний угол страницы будет выглядеть непривлекательно.

.месяц день, год

Дата должна быть написана в стандартном (для англоязычных стран) варианте:

Январь 25, 1989

ВВЕДЕНИЕ В СПРАВОЧНЫЙ И ОБЩИЙ ТЕКСТОВЫЙ ДОМЕНЫ

Что в имени тебе моем...

В первом случае макросы troff(1) сами по себе являются командами; общий синтаксис команд troff:

.Va параметр1 параметр2 ... параметр9

`.- ' это макрос, а все, что следует за ним, - его параметры. Во втором случае при описании команды UNIX используются контекстные макросы; командная строка в секции Sx СИНТАКСИС обычно выглядит так:

filter [-флаг ] вх.файл вых.файл

Здесь, filter - это название команды, заключенная в квадратные скобки строка; -флаг - это необязательный (это указано квадратными скобками) параметр-флаг Согласно терминологии -mdoc вх.файл и вых.файл называются параметрами Создается этот формат при помощи следующих макросов:

.Nm filter
.Op Fl флаг
.Ar вх.файл вых.файл

Третий случай представляет собой взаимодействие первых двух с добавлением некоторых деталей. Аргументы вх.файл и вых.файл из предыдущего примера рассматриваются как операнды или аргументы файла Списки аргументов командной строки могут быть довольно длинными:

make

[-e iknqrstv ] [-D переменная ] [-d флаги ] [-f makefile ] -words [-I каталог ] [-j максимальное_количество_задач ] [переменная=значение ] -words [цель_сборки ... ]

Далее Вы можете рассмотреть команду make и определить аргумент makefile как аргумент флага -f имея в виду, что операнд файла цель_сборки является дополнительным. Такие детали могут предотвратить появление путаницы. Так или иначе, пакет -mdoc не имеет макроса для аргумента к флагу. Вместо этого аргумент макроса `file ... ' используется для такого операнда или аргумента файла, как цель_сборки так же, как и для аргумента к флагу, например, variable Командная строка make состоит из:

.Nm make
.Op Fl eiknqrstv
.Op Fl D Ar переменная
.Op Fl d Ar флаги
.Op Fl f Ar makefile
.Op Fl I Ar каталог
.Op Fl j Ar максимальное_количество_задач
.Op Ar переменная=значение
.Bk -words
.Op Ar цель_сборки ...
.Ek

Макросы `.и ' `.рассматриваются ' в Sx Keeps .  

Общий синтаксис

.sptr, ptr),

то результат будет следующим:

sptr, ptr),

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

.sptr , ptr ) ,

В этом случае результат будет следующим:

sptr , ptr

Теперь пунктуация распознана и выведена в формате, отличном от текстового.

Для того, чтобы убрать специальное значение символа, используйте `\&' Troff является языком макросов, и поэтому возникают проблемы при написании строки, содержащей математические, логические или цитирующие символы:

{+,-,/,*,%,<,>,<=,>=,=,==,&,`,',"}

Проблема заключается в том, что troff может воспринять эти знаки как составляющие команды. Для того, чтобы этого не произошло, рекомендуется обособлять такие знаки при помощи `\&' Типичный синтаксис показан в макросе содержания, приведенном ниже `. '  

ДОМЕН СТРУКТУРЫ СТРАНИЦ

Адреса

Использование: .адрес ...

.addr1

addr1

.addr1

addr1

.addr1 , file2

addr1 , file2

.f1 , f2 , f3:

f1 , f2 , f3

.addr ) ),

addr ) )

Вызов `.без ' аргументов будет ошибочным. Значение `.может ' быть вызвано и обработано другими макросами.  

Автор

Использование: .An имя_автора

.An Joe Author

An Joe Author

.An Joe Author,

An Joe Author ,

.An Joe Author Aq nobody@FreeBSD.ORG

An Joe Author Aq nobody@FreeBSD.ORG

.An Joe Author ) ),

An Joe Author ) ) ,

Макрос `.An может ' быть вызван и обработан. Вызов макроса `.An без ' аргумента приведет к ошибке.  

Параметры

Использование: .аргумент ...

.file ...

file ...

.file1

file1

.file1

file1

.file1 file2

file1 file2

.f1 f2 f3:

f1 f2 f3

.file ) ),

file ) )

Если производится вызов `.file ... ' без аргумента, то читаемое значение равно `file ... ' Макрос `.file ... ' может быть вызван и обработан.  

Задание конфигурации (только раздел #4)

device le0 at scode?

пишется в виде строки: `.device ' le0 at scode? .

Модификатор команд

Определенные переменные

Использование: .определенная_переменная ...

.MAXHOSTNAMELEN

MAXHOSTNAMELEN

.TIOCGPGRP )

TIOCGPGRP

Вызов `.без ' аргумента приведет к ошибке. `.может ' быть вызван и обработан.  

Коды ошибок (только раздел #2)

Использование: .Er КОД_ОШИБКИ ...

.Er ENOENT

Er ENOENT

.Er ENOENT );

Er ENOENT ) ;

.Bq Er ENOTDIR

Bq Er ENOTDIR

Вызов `.Er без ' аргумента приведет к ошибке. Макрос `.Er можно ' вызвать и обработать.  

Переменные окружения

Использование: .аргумент ...

.DISPLAY

DISPLAY

.PATH

PATH

.PRINTER ) ),

PRINTER ) )

Вызов `.без ' аргумента вызовет ошибку. Макрос `.может ' быть вызван и обработан.  

Параметры функции

Использование: .Fa аргумент_функции ...

.Fa d_namlen ) ),

Fa d_namlen ) ) ,

.Fa iov_len

Fa iov_len

Вызов макроса `.Fa без ' аргумента приведет к ошибке. `.Fa может ' быть вызван и обработан.  

Определение функции

Использование: .Fd файл (или определенная функция)

В разделе Sx СИНТАКСИС запрос `.Fd вызывает ' разбиение строки в том случае, если соответствующая функция задана, а разбиения строки все еще не произошло. После этого остаются удобные для работы вертикальные пробелы между предыдущим и последующим вызовом функций.  

Флаги

Использование: .-аргумент ...

.-

-

.-cfv

-cfv

.-cfv

-cfv

.-s v t

-s v t

.--,

--

.-xyz ),

-xyz )

Макрос `.- ' без аргументов возвратит тире, то есть, стандартный stdin/stdout. Если поставить тире, то `.- ' вернет два тире. Макрос `.- ' может быть вызван и обработан.  

Функции (в том числе и библиотечные)

Использование: .Fn [тип] функция [[тип] параметры ... ]

.Fn getchar

getchar ();

.Fn strlen ) ,

strlen () ,);

.Fn \*qint align\*q \*qconst * char *sptrs\*q

int (align const * char *sptrs ,);

Вызов макроса `.Fn без ' параметров приведет к ошибке. Макрос `.Fn может ' быть вызван и обработан, но любой вызов другого макроса приведет к завершению работы `.Fn '

Для функций, которые имеют более восьми параметров (это бывает редко), используются макросы: `.Fo (для ' открытия функции), `.Fc (для ' закрытия функции) и `.Fa (для ' указания на аргументы функции). Например:

.Fo "int res_mkquery"
.Fa "int op"
.Fa "char *dname"
.Fa "int class"
.Fa "int type"
.Fa "char *data"
.Fa "int datalen"
.Fa "struct rrec *newrr"
.Fa "char *buf"
.Fa "int buflen"
.Fc

В результате получается:

Fo int res_mkquery Fa int op Fa char *dname Fa int class Fa int type Fa char *data Fa int datalen Fa struct rrec *newrr Fa char *buf Fa int buflen Fc

Макросы `.Fo и ' `.Fc могут ' быть вызваны и обработаны. В разделе Sx СИНТАКСИС функции описываются с начала строки. Если в разделе Sx СИНТАКСИС представлено более одной функция и не задан тип функции, то произойдет разбиение строки и останется место между названием текущей функции и названием предыдущей. В настоящее время макрос `.Fn не ' проверяет границы слов по длине форматирования строки troff и поэтому может некорректно разбить строку. В ближайшем будущем такой случай будет доработан.  

Типы функций

Использование: .Ft тип ...

.Ft struct stat

struct stat

Макрос `.Ft можно ' вызвать при помощи других макросов.  

Интерактивные команды

Использование: .аргумент ...

.:wq

:wq

.do while {...}

do while {...}

.setenv , unsetenv

setenv , unsetenv

Вызов макроса `.без ' аргумента вызовет ошибку. Макрос `.может ' быть вызван и обработан.  

Названия

`. ' почти идентичны, их различает только описанная выше возможность `. ' запоминать первый аргумент.

Использование: .аргумент ...

.mdoc.sample

mdoc.sample

.\-mdoc

-mdoc

.foo ) ),

foo ) )

.

Макрос `. ' может быть вызван и обработан.  

Опции

Использование: .[опции ... ]

.[[

.[-k ]

] ]

[-k ]

.[-k ) . ]

[-k ]

.[-k kookfile ]

[-k kookfile ]

.[-k kookfile , ]

[-k kookfile ]

.[objfil [corfil ] ]

[objfil [corfil ] ]

.[-c objfil [corfil , ] ]

[-c objfil [corfil ] ]

.[word1 word2]

[word1 word2]

Макросы `.] ' и `.[: '

.Oo
.Op Fl k Ar kilobytes
.Op Fl i Ar interval
.Op Fl c Ar count
.Oc

,- выдают результат: [[-k kilobytes ] [-i interval ] [-c count ] ]

Макросы `.[,] ' `.] ' и `.[могут ' быть вызваны и обработаны.  

Пути

Использование: .путь

./usr/share

/usr/share

./tmp/fooXXXXX )

/tmp/fooXXXXX )

Макрос `.может ' быть вызван и обработан.  

Переменные

Использование: .переменная ...

.count

count

.settimer

settimer

.int *prt ):

int *prt )

.char s ] ) ),

char s ] ) )

При вызове `.без ' аргумента произойдет ошибка. Макрос `.может ' быть вызван и обработан.  

Ссылки

Использование: .man_страничка[1,...,8]

.mdoc

mdoc

.mdoc

mdoc,

.mdoc(7)

mdoc(7)

.mdoc(7)))

mdoc(7))),

Макрос `.может ' быть вызван и обработан. Вызов макроса `.без ' аргумента приведет к ошибке.  

ОБЩИЙ ТЕКСТОВЫЙ ДОМЕН

Макрос AT&T

Использование: .At [v6 | v7 | 32v | V.1 | V.4] ... 

.At

AT&T System

.AT&T System v6 .

AT&T System v6 .

Макрос `.AT&T System ' не вызывается и не обрабатывается. Обычно он использует сразу два аргумента.  

Макрос BSD

Использование: .BSD [версия/релиз] ...

.Bx

BSD

.BSD 4.3 .

BSD 4.3

Макрос `.BSD может ' быть вызван и обработан.  

Макрос FreeBSD

Использование: .Fx версия.релиз ... 

.Fx 2.2 .

Fx 2.2 .

Макрос `.Fx не ' вызывается и не обрабатывается. Обычно он использует два аргумента.  

Макрос UNIX

Использование: .UNIX

.Ux

UNIX

Макрос `.UNIX ' может быть вызван и обработан.  

Макросы выделения

Обособ.       Закрыв. Открыв. действие                Результат .Aq .Ac     .Ao     Обособление угловыми скобками<string>
.Bq     .Bc     .Bo     Обособление квадратными скобками        [string]
.Dq     .Dc     .Do     Обособление двумя единичными кавычками  ``string''
        .Ec     .Eo     Обособление значками XX         XXstringXX
.Pq     .Pc     .Po     Обособление круглыми скобками   (string)
.Ql                     Литературное цитирование                `st' or string
.Qq     .Qc     .Qo     Обособление двойными кавычками  "string"
.Sq     .Sc     .So     Обособление кавычками           `string'

Все макросы обособления, кроме приведенных ниже, могут быть вызваны и обработаны. Все поддерживают пунктуацию, если она представлена одним знаком и разделена пробелами. Макросы обособления проверяют открывающуюся и закрывающуюся пунктуацию на расположение ее в области обособления. Это делает возможным проведение компоновки.

.Ec , .Eo Эти макросы определяют первый аргумент как открывающий,

а второй как закрывающий.

.`Макрос'

литературного цитирования по-разному работает в troff и nroff. Если он форматируется nroff, то он всегда обособлен. Если форматируется в troff, то он обособляется только в том случае, если состоит менее чем из трех символов. Это выполняется для того, чтобы сделать короткие строки более заметными. Макрос приставки

.не может быть вызван, но может быть обработан. Если выполнить команду строки

.( Fa name2

то результат будет следующим: ( Fa name2

Макрос `.(нет ' пробела) производит аналогичное действие.

Примеры обособления:

.Aq Aq

.Aq ctype.h ),

Aq Ar ctype.h ) ,

.Bq Bq

.Bq Greek , French .

Bq Em Greek , French .

.````

.``string abc .''

'' ''

``string abc''

.``'^[A-Z]'''

``'^[A-Z]'''

.`man'

mdoc `man' mdoc

.Qq Qq

.Qq string ) ,

Qq string ) ,

.Qq string ),

Qq string Ns ),

.``

.`string'

' '

`string'

Примером вложенного макроса может служить макрос опций `.[] ' Он был создан на основе вышеперечисленных макросов. Макросы расширенного списка аргументов `. ' и `. ' были также созданы на основе этих функций и могут служить хорошим примером использования пакета макросов -mdoc  

No-[или макроса обычного текста.]

Макрос отключения пробелов

.[-I каталог ]

в результате получается: [-I каталог ]

Замечание: макрос `.всегда ' вызывает макрос `.после ' удаления пробелов, если за ним не следует другой макрос. Макрос `.может ' быть вызван и обработан.  

Ссылки на раздел

.Sx ФАЙЛЫ

Sx ФАЙЛЫ

Ссылки и цитаты

.Rs

Начало ссылок. Вызывает разбиение строки, начинает список ссылок и продолжает его до конца макроса.

.Re

Конец ссылок. Ссылка печатается.

.%A

Имя автора, одно на каждый вызов.

.%B

Название книги.

.%C

Город/издательство.

.%D

Дата.

.%J

Название журнала.

.%N

Номер журнала.

.%O

Дополнительная информация.

.%P

Номер страницы.

.%R

Название отчета.

.%T

Заголовок статьи.

.%V

Том(-а).

Макросы, начинающиеся с `%' , не вызываются и обрабатываются только макросом торговой марки для того, чтобы торговые марки правильно и красиво печатались при выводе их с troffNs/NsXrditroff.  

Возвращаемые значения

Применение: .Rv [-std функция]

`.Rv -std ' atexit создаст текст:

Rv -std atexit

Опция -std применима только для второго и третьего разделов страниц руководства.  

Торговые марки (акронимы и названия их видов)

Использование: .символ ...

.DEC

DEC

.ASCII

ASCII

Макрос `.может ' быть обработан и вызван другими макросами.  

Расширенные параметры

Далее приведен пример использования `. ' совместно с макросом отключения пробела:

.Sm off
.It Xo Sy I Ar операция
.No \en Ar счетчик No \en
.Xc
.Sm on

Получается:

I операция \n счетчик \n

И еще один пример:

.Sm off
.It Cm S No / Ar старый_шаблон Xo
.No / Ar новый_шаблон
.No / Op Cm g
.Xc
.Sm on

Результат:

S / старый_шаблон / новый_шаблон / [g ]

Еще одна область применения макроса `. ' совместно с макросом обособления - проверка значения переменной.

.It Xo
.Ic .ifndef
.Oo \&! Oc Ns Ar переменная
.Op Ar оператор переменная ...
.Xc

Результат

.ifndef [! переменная ] [оператор переменная ... ]

Все вышеперечисленные примеры использовали макрос `. ' в макросе списка аргументов `. ' В первых двух примерах пробелы были убраны; в третьем случае пробелы надо было убрать только в определенной части. Для того, чтобы сделать это, удостоверьтесь, что макросы `. ' и `.

' поставлены именно так, как это описано в третьем примере. Если макрос `. ' не единственный в списке аргументов `. ' то трудно будет определить, как и откуда будут удалены пробелы. В этом случае макрос `.(макрос ' отключения пробелов) не должен оказаться первым или последним макросом в строке. Из 900 страниц руководства (а реально около 1500 страниц), представленных в BSD , только пятнадцать используют макрос `. '  

ДОМЕН СТРУКТУРЫ СТРАНИЦ

 

Заголовки разделов

Первые три макроса заголовков разделов `. 

,

' приведенных ниже, описываются на каждой странице руководства. Остальные заголовки разделов описываются по усмотрению автора. Макрос `. 

может

' иметь до девяти аргументов. Макрос может быть обработан, но его нельзя вызвать.

.

 

НАЗВАНИЕ

Макрос `. 

НАЗВАНИЕ

' является обязательным. Если не указать заголовки, нижние колонтитулы и страничный формат, то макросы не будут использованы и все будет выглядеть неаккуратно. Раздел Sx НАЗВАНИЕ состоит минимум из трех частей. Первая - это макрос названий `. ' который называет сам предмет, описанный на странице руководства. Далее следует макрос описания имени `. - , ' который отделяет название предмета от его описания. Описание, по возможности, должно быть как можно более кратким и ясным, так как на странице недостаточно места для него. .Sh СИНТАКСИС Раздел Sx СИНТАКСИС описывает типичное применение рассматриваемого предмета. Макросы, которые в этом участвуют: `.Nm' , `.Cd' , `.Fn' , (и, возможно, макросы `.Fo' , `.Fc' , `.Fd' , `.Ft' ). Макрос названия функции `.Fn' должен присутствовать во втором и третьем разделах, макрос `. ' требуется в разделах под номерами: 1, 5, 6, 7 и 8. Четвертый раздел требует использования макросов `.Nm' , `.Fd' или `.Cd' Для описания синтаксиса, как показано в примере ниже, могут понадобиться другие макросы:

cat [-benstuv ] [- ] file ...

Были использованы следующие макросы:

.cat

.[-benstuv ]

.[- ]

.file ...

Замечание Макросы `.[,] ' `.- ' и `.file ... ' распознают символ вертикальной черты `' поэтому строка типа:

".[-a | -b ]

,- будет обработана. Troff обычно интерпретирует как специальный символ. Прочтите Sx PREDEFINED STRINGS для того, чтобы использовать символ в других ситуациях. .Sh ОПИСАНИЕ В большинстве случаев первое, что пишется в разделе Sx ОПИСАНИЕ ,- это краткое описание команды, функции или файла с последующим списком опций и пояснений к ним. Для того, чтобы создать такой список, используются макросы `.

' (начало списка), `.

(элемент ' списка) и `.

' (конец списка), см. ниже Sx списки и колонки.

Следующие `. 

-названия

' разделов являются частью страничного формата и должны использоваться в соответствии с контекстом. Они приведены в том порядке, в котором должны находиться в тексте.

.

 

ПЕРЕМЕННЫЕ ОКРУЖЕНИЯ

Раздел Sx ПЕРЕМЕННЫЕ ОКРУЖЕНИЯ описывает все используемые переменные окружения, их поведение и/или использование. .Sh ПРИМЕРЫ Есть несколько способов создавать примеры. Прочтите раздел Sx ПРИМЕРЫ , приведенный ниже. .Sh ФАЙЛЫ Файлы, используемые или созданные предметом описания, должны быть показаны при помощи макроса `.в ' разделе Sx ФАЙЛЫ . .Sh СМ. ТАКЖЕ Ссылки на другие материалы по теме страницы руководства и ссылки на другие страницы должны находиться в разделе Sx СМ. ТАКЖЕ . Перекрестные ссылки указываются при помощи макроса `.. ' Перекрестные ссылки в разделе Sx СМ. ТАКЖЕ должны быть отсортированы по номерам разделов, затем в алфавитном порядке и разделены запятыми. Например:

ls(1), ps(1), group(5), passwd(5).

В этом случае ссылки refer(1) не используются. .Sh СООТВЕТСТВИЕ Если команда, библиотечная функция или файл придерживается определенного стандарта, такого, как St -p1003.2 или St -ansiC , то в данном разделе это должно быть указано. Если команда не соответствует ни одному из стандартов, то ее история должна быть описана в разделе Sx ПРЕДЫСТОРИЯ . .Sh ПРЕДЫСТОРИЯ Любая команда, не соответствующая никаким стандартам, должна быть описана в этом разделе согласно целям ее создания. .Sh АВТОРЫ В этом разделе должны быть указаны все авторы страницы и их помощники. .Sh ДИАГНОСТИКА В данном разделе описана диагностика команды. .Sh СООБЩЕНИЯ ОБ ОШИБКАХ В этом разделе рассматриваются сообщения об ошибках. Макрос `.Er используется ' для написания переменной errno. .Sh ОШИБКИ В этом разделе описываются все выявленные ошибки.  

Параграфы и расстояние между строками.

.

Команда `.

' может быть использована для выделения необходимого пространства. Этот макрос необязателен после макросов `.

 

или

' `. 

и

' до макроса `.

' (Макрос `.

' задает вертикальное расстояние, если указан флаг -compact).

 

Сохранение исходного формата

В данный момент сохраняется только формат слов. Для этого служат макросы `.(начало ' сохранения) и `.(конец ' сохранения). Единственная опция, которая используется `.,- ' это -words Она применяется для того, чтобы избежать неправильных переносов. При задании команды make (см. Sx Что в имени тебе моем... ) , сохранение предотвратило nroff от размещения флага и аргумента в различные строки.  

Блоки вывода

Существует пять типов вывода: вывод строки с отступом `.D1' , вывод строки, начинающейся с заглавной буквы `.

,

' вывод неотформатированного блока (literal), вывод блока, отформатированного по двум границам (filled), а также вывод блока, отформатированного по левой границе (ragged) и использующего макросы `. ' (начало вывода) и `. ' (конец вывода).

.D1 Выводит одну строку с отступом. Этот макрос обрабатывается, но не вызывается. -ldghfstru

Описанное выше было сделано с помощью строки .

-ldghfstru

.

выводит строку с отступом

дословного текста. Макрос `.

также

' используется в этом тексте. Он позволяет делать отступ. По умолчанию установленная ширина шрифта является постоянной. Этот макрос обрабатывается и распознается другими макросами, но не может быть вызван ими.

% ls -ldg /usr/local/bin

Вышеприведенный пример был сделан с помощью строки: .

% ls -ldg /usr/local/bin

. Начало вывода. Макрос вывода `. ' должен использоваться в паре с макросом `. ' Этот вывод может распологаться внутри других выводов. `. ' имеет следующий синтаксис:

".

Вид вывода должен быть одним из четырех следующих и должен иметь указатель величины отступа: `. '

-ragged Дословно воспроизводит текст, форматируя его по левой границе.

-filled Дословно воспроизводит текст форматируя его по обеим границам.

-literal Дословно воспроизводит текст, не форматируя его. Используется для исходных версий или простых текстов.

-file имя_файла Имя файла, следующее за флагом -file считывается и отправляется на вывод. Неформатируемый режим (literal) подразумевает, что установленная ширина tab равна восьми символам. Любая команда troff/NsNm-mdoc будет работать с этим файлом.

-offset строка Если -offset указан для одной из строк, то по ней будут равняться и следующие строки блока:

left Производится выравнивание по существующей левой границе текста.

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

indent Делает отступ на заданную величину или на tab знаков. Значение этого отступа по умолчанию равно отступу вывода `.D1' Установленная величина текущего отступа равна 6-и символам или двум третям дюйма.

indent-two Делает отступ, в два раза больший установленного.

right Этот макрос выравнивает блок по границе, левее правой границы страницы на два дюйма. Макрос нуждается в доработке и, возможно, в troff его работа никогда не будет корректной.

".Ed" Конец экрана.

 

Режимы шрифтов

Существует пять макросов для изменения внешнего вида текста на странице руководства:

.Макрос `.выделяет ' текст. Обычно для этого используют шрифт italic.

Использование: .аргумент ...

.does not does not

.exceed 1024 . exceed 1024

.vide infra ) ) , vide infra ) )

Макрос `.можно ' вызвать и обработать. При вызове `.без ' аргумента происходит ошибка.

.Макрос `.(literal) ' может быть использован для специальных символов, переменных, констант или того, что должно быть отображено так, как это набрано.

Применение: .аргумент ...

.\en \n

.M1 M2 M3; M1 M2 M3

.cntrl-D ), cntrl-D )

.1024 ... 1024 ...

Макрос `.может ' быть вызван и обработан.

.Этот символьный макрос служит, в основном, для написания текста жирным шрифтом.

Использование: .символ ...

.Important Notice Important Notice

Макрос `.можно ' вызвать и обработать.

.Bf Начало режима шрифта. Начало режима шрифта `.Bf должно ' заканчиваться макросом конца режима шрифта `.Ef ' Режимы шрифтов могут быть размещены внутри других макросов режимов шрифтов. `.Bf имеет ' следующий синтакс:

".Bf режим-шрифта

Режим-шрифта должен быть одним из трех следующих: `.Bf '

| -emphasis Это выглядит, как будто макрос `.применили ' ко всему блоку текста.

| -literal Это выглядит, как будто макрос `.применили ' ко всему блоку текста.

| -symbolic Это выглядит, как будто макрос `.применили ' ко всему блоку текста.

".Ef" Конец режима шрифтов.

 

Списки и колонки

Существует несколько типов списков, которые должны начинаться с макроса `.Bl' (начало-списка). Пункты внутри списка указываются при помощи макроса `.It' , и каждый список должен заканчиваться макросом `.El' Списки могут быть размещены внутри таких же списков и выводов. Внутри списков могут быть использованы колонки, но списки внутри колонок ведут себя не всегда адекватно.

Можно добавить, что применяются некоторые атрибуты списков, такие, как: ширина тэга, отступ и компактность (определяется, вставляются ли пустые строки между пунктами списка). Большая часть этого документа была отформатирована при помощи тэгов (-tag ) Тип-списка, использованный для показа типов-списков, - это список `ohang' Этот тип списка очень популярен среди пользователей TeX Следующие типы списков обрабатываются макросом `.Bl' :

-bullet

-item

-enum Эти три типа являются самыми простыми. После того, как макрос `.Bl' запущен, все пункты списка обозначаются строкой, состоящей из макроса `.It' Например, исходный текст для простого списка перечисления будет выглядеть следующим образом:

.Bl -enum -compact
.It
 Пункт 1.
.It
 Пункт 2.
.It
 Пункт 3.
.El

Результат:

1. Пункт 1.
2. Пункт 2.
3. Пункт 3.

Простой список с пунктами, выделенными точками:

.Bl -bullet -compact
.It
Точка 1.
.It
Точка 2.
.El

Результат:

• Точка 1.
• Точка 2.

-tag

-diag

-hang

-ohang

-inset Эти типы списков содержат аргументы, указанные при помощи макроса `.

, ' и создают выделенный блок, который может быть вставлен (inset) в последующий текст, располагаться до (hanged) последующего текста, располагаться над (overhanged) последующим текстом. Этот список был построен при помощи типа-списка `-ohang ' Макрос `.

обрабатывается ' только типами списков: inset, hang и tag и не может быть вызван. Далее следует пример блока, выделенного при помощи типа-списка inset:

Tag Список, построенный при помощи тэгов, - это наиболее распространенный тип-списка, описанный в руководстве, разработанном в Berkeley.

Diag Этот тип-списка создает раздел диагностики и идентичен типу inset, кроме того, что он игнорирует вызываемые макросы.

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

Ohang Выделенные блоки, расположенные над текстом, очень удобны, если свободного места в целом немного.

Inset Выделенные блоки, вставленные в текст, удобны для конвертирования страниц -mdoc в другие форматы.

Далее следует исходный текст описанного выше:

.Bl -inset -offset indent
.It Em Tag
Список, построенный при помощи тэгов,- это наиболее распространенный
тип-списка, используемый в разработанном Berkeley руководстве.
.It Em Diag
Этот тип-списка создает раздел диагностики
и идентичен типу inset, кроме того, что он игнорирует
вызываемые макросы.
.It Em Hang
Выделенные блоки, расположенные перед текстом, используются
по желанию автора.
.It Em Ohang
Выделенные блоки, расположенные над текстом, 
очень удобны при недостатке места для текста.
.It Em Inset
Выделенные блоки, вставленные в текст, удобны
для конвертирования страниц
.Nm -mdoc
в другие форматы.
.El

Ниже приведен текст с двумя выделенными блоками, расположенными до текста:

Блоки выделенные при помощи hang, похожи на списки tag в случае, если блок меньше выделенного для него места.

Более длинные блоки hang "врезаются" в абзац, чего не происходит со списками tag.

Ниже приведен исходный вариант этого текста:

.Bl -hang -offset indent
.It Em Блоки ,
выделенные при помощи hang, похожи на списки
tag, в случае если блок меньше выделенного
для него места.
.It Em Более длинные блоки hang
"врезаются" в абзац, чего не происходит со списками tag.
.El

Нижеследующий список tag использует дополнительный указатель для управления шириной тэга.

SL - время ожидающего режима процесса.

PAGEIN - количество обращений к подкачке.

UID - числовой идентификатор пользователя.

PPID - числовой идентификатор родительского процесса.

Исходный текст:

.Bl -tag -width "PAGEIN" -compact -offset indent
.It SL
время ожидающего режима процесса.
.It PAGEIN -
количество обращений к подкачке.
.It UID -
числовой идентификатор пользователя. 
.It PPID -
числовой идентификатор родительского процесса.
.El

Допустимые указатели ширины:

-width Fl устанавливает ширину, равную ширине флага, указанной по умолчанию. Все вызываемые макросы имеют ширину, указанную по умолчанию. В данном случае установленная ширина `.- ' равнялась десяти символам или приблизительно пяти шестым дюйма.

-width 24n устанавливает ширину, равную 24-м символам или приблизительно двум дюймам. Буква `n' обязательно должна сохраняться.

-width ENAMETOOLONG устанавливает ширину, равную ширине данной строки.

-width \*qint mkfifo\*q тоже устанавливает ширину, равную ширине данной строки.

Если ширина не указана списку tag, то вызывается первый макрос `.

и ' делается попытка определения данной ширины. Если первый аргумент `.It' - это вызываемый макрос, то будет использована ширина этого макроса. В любом случае, если другой предмет списка содержит другой вызываемый макрос, то создается новый вложенный список.

 

ПРЕДОПРЕДЕЛЕННЫЕ СТРОКИ

Следующие символы являются предопределенными и могут использоваться строками troff при помощи последовательности `\*(xx' , где xx - это имя предопределенной строки; или последовательности `\*x' , где x - имя строки. Эти последовательности могут быть использованы в любом месте текста.

Строка        Nroff   Troff

<= Ta <= Ta

>= Ta >= Ta

Rq Ta '' Ta

Lq Ta `` Ta

ua Ta ^ Ta

aa Ta ' Ta

ga Ta ` Ta

q Ta Ta

Pi Ta pi Ta

Ne Ta != Ta

Le Ta <= Ta

Ge Ta >= Ta

Lt Ta < Ta

Gt Ta > Ta

Pm Ta +- Ta

If Ta infinity Ta

Na Ta NaN Ta

Ba Ta | Ta

Замечание
Строка под названием `q' должна быть указана как `\*q' , так как в ее названии только один символ.  

ДИАГНОСТИКА

Возможности отладки -mdoc ограничены, но могут использоваться при нахождении довольно незаметных ошибок, таких, как: конфликт названия аргумента, названия внутреннего регистра и названия макроса. Регистр - это метод хранения информации для troff с именем, состоящим из одного или двух символов. Все регистры в -mdoc являющиеся внутренними для troff и ditroff и имеют названия из двух символов в форме <верхний_регистр><нижний_регистр> так же, как `file ... ' <нижний_регистр><верхний_регистр>, как `aR' ; или <большая или маленькая буква><цифра>, как `C1' И, вдобавок ко всему, troff имеет свои собственные внутренние регистры, названия котрых состоят из двух маленьких символов или из точки и буквы. В одном из примеров в начале файла было показано, как предотвратить определение названия макроса при помощи `\&' Это актуально и для названий внутренних регистров.

Если не пользоваться этим приемом, то последствия будут непредсказуемыми. Иногда некоторые части текста выводятся не там, где ожидалось; это происходит в связи с нераспознаванием типа аргумента в списке аргументов. Узнать, правильно ли указан тип аргумента, можно при помощи макроса отладки `.Db (debug), ' который выводит интерпретацию списка аргументов для большинства макросов. Такие макросы, как `.

' (paragraph), не содержат информации для отладки. Для всех вызываемых макросов рекомендуется использование макроса `.Db '

Использование: .Db [on | off]

Далее следует пример, состоящий из части текста с макросом отладки, расположенным выше и ниже специально созданной ошибки (флаг аргумента указан как `aC' , а не `\&aC' , что необходимо для корректной работы):

.Db on
.Op Fl aC Ar файл )
.Db off

Результат вывода:

DEBUGGING ON
DEBUG(argv) MACRO: `.Op'  Line #: 2
        Argc: 1  Argv: `Fl'  Length: 2
        Space: `'  Class: Executable
        Argc: 2  Argv: `aC'  Length: 2
        Space: `'  Class: Executable
        Argc: 3  Argv: `Ar'  Length: 2
        Space: `'  Class: Executable
        Argc: 4  Argv: `file'  Length: 4
        Space: ` '  Class: String
        Argc: 5  Argv: `)'  Length: 1
        Space: ` '  Class: Closing Punctuation or suffix
        MACRO REQUEST: .Op Fl aC Ar file )
DEBUGGING OFF

В первой строке указывается название вызывающего макроса (в данном случае это `.[)] '

и номер строки, в которой оно находится. Если используется один или более файлов (в особенности, если используется текст из другого файла), то номер строки может быть указан неправильно. Если используется один файл, то строка должна быть указана точно. Во второй строке указывается счетчик аргумента, аргумент (`- ' ) и его длина. Если длина аргумента равна двум символам, то проверяется, выполняется ли он (к сожалению, любой регистр, имеющий ненулевое значение, тоже выполним). В третьей строке выводится пространство, зарезервированное для класса, и тип класса. Ошибка в том, что аргумент aC и не должен быть выполнимым. В четвертой строке указываются классы строки выполняемого аргумента, открывающие и закрывающие пунктуационные знаки. В последней строке указывается полный список аргументов, каким он был считан. В следующем примере `aC' будет указано правильно:

.Db on
.Em An escaped \&aC
.Db off

DEBUGGING ON
DEBUG(fargv) MACRO: `.Em'  Line #: 2
        Argc: 1  Argv: `An'  Length: 2
        Space: ` '  Class: String
        Argc: 2  Argv: `escaped'  Length: 7
        Space: ` '  Class: String
        Argc: 3  Argv: `aC'  Length: 2
        Space: ` '  Class: String
        MACRO REQUEST: .Em An escaped &aC
DEBUGGING OFF

Аргумент `\&aC' имеет ту же длину, равную 2-м, так как `\&' не занимает места, но регистр с названием `\&aC' не был найден и тип был классифицирован как строка.

Другие способы диагностики включают в себя использование определений, и мы не будем на них останавливаться.  

GROFF, TROFF И NROFF

Пакет -mdoc не нуждается в отдельном режиме совместимости с groff.

Пакет убирает разделение страниц, верхние и нижние колонтитулы, формируемые nroff, для удобства чтения руководства в режиме on-line. В groff, использующем -T ascii есть функция вывода количества страниц в конце файла. Свойство nroff удалять страницы делает неудобным распечатку документов, отформатированных им. Можно установить значение регистра `cR' , находящегося в файле /usr/src/share/tmac/doc-nroff, равным нулю для того, чтобы сохранялся предыдущий формат документа.  

ФАЙЛЫ

/usr/share/tmac/tmac.doc - инструкции к пакету макросов.

/usr/share/misc/mdoc.template - шаблон для написания страницы руководства.

/usr/share/examples/mdoc/* - несколько примеров страниц руководства.

 

СМ. ТАКЖЕ

man(1), troff(1), mdoc(7)  

НАЙДЕННЫЕ ОШИБКИ

Пока не доработан автоматический перенос на дефисе флага аргумента, вызывающий непредвиденные ситуации, что описывается в разделе Sx ОПИСАНИЕ (перенос строки на дефисе).

Предопределенные строки не описываются в документации.

Раздел 3f не добавлен к заголовку.

Шрифт `. ' должен быть изменен в разделе Sx НАЗВАНИЕ .

`.Fn должен ' быть проверен на выполнение разбиения очень короткой строки. Иногда он переносит последнюю скобку.

Макросы списков и вывода не всегда делают сохранения.

---

 

Index

НАЗВАНИЕ

СИНТАКСИС

ОПИСАНИЕ

ПРИСТУПАЯ К РАБОТЕ

ОГРАНИЧЕНИЯ TROFF

Использование макросов

Передача пробелов в виде параметров

Завершающие строку пробелы (предупреждение)

Escape-последовательности для вывода специальных символов

СТРУКТУРА СТРАНИЦЫ РУКОВОДСТВА

Шаблон страницы руководства

,

МАКРОСЫ ЗАГОЛОВКА

ВВЕДЕНИЕ В СПРАВОЧНЫЙ И ОБЩИЙ ТЕКСТОВЫЙ ДОМЕНЫ

Что в имени тебе моем...

Общий синтаксис

ДОМЕН СТРУКТУРЫ СТРАНИЦ

Адреса

Автор

Параметры

Задание конфигурации (только раздел #4)

Модификатор команд

Определенные переменные

Коды ошибок (только раздел #2)

Переменные окружения

Параметры функции

Определение функции

Флаги

Функции (в том числе и библиотечные)

Типы функций

Интерактивные команды

Названия

Опции

Пути

Переменные

Ссылки

ОБЩИЙ ТЕКСТОВЫЙ ДОМЕН

Макрос AT&T

Макрос BSD

Макрос FreeBSD

Макрос UNIX

Макросы выделения

No-Op или макроса обычного текста.

Макрос отключения пробелов

Ссылки на раздел

Ссылки и цитаты

Возвращаемые значения

Торговые марки (акронимы и названия их видов)

Расширенные параметры

ДОМЕН СТРУКТУРЫ СТРАНИЦ

Заголовки разделов

,

может

НАЗВАНИЕ

НАЗВАНИЕ

-названия

ПЕРЕМЕННЫЕ ОКРУЖЕНИЯ

Параграфы и расстояние между строками.

или

и

Сохранение исходного формата

Блоки вывода

Режимы шрифтов

Списки и колонки

ПРЕДОПРЕДЕЛЕННЫЕ СТРОКИ

ДИАГНОСТИКА

GROFF, TROFF И NROFF

ФАЙЛЫ

СМ. ТАКЖЕ

НАЙДЕННЫЕ ОШИБКИ

---

Поиск по тексту MAN-ов: 

Партнёры:

Хостинг:

Закладки на сайте Проследить за страницей

Created 1996-2024 by Maxim Chirkov Добавить, Поддержать, Вебмастеру