The OpenNET Project / Index page

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

Интерактивная система просмотра системных руководств (man-ов)

 ТемаНаборКатегория 
 
 [Cписок руководств | Печать]

mdoc.samples (7)
  • mdoc.samples (7) ( FreeBSD man: Макропакеты и соглашения )
  • >> mdoc.samples (7) ( Русские man: Макропакеты и соглашения )
  • mdoc.samples (7) ( Linux man: Макропакеты и соглашения )

  • BSD mandoc
     

    НАЗВАНИЕ

    mdoc.samples - - примеры написания страниц руководства BSD при помощи -mdoc  

    СИНТАКСИС

    man mdoc.samples  

    ОПИСАНИЕ

    В данном файле приведены примеры написания страниц руководства BSD при помощи макро-пакета -mdoc который является зависимым от контекста и домена пакетом форматирования текста troff(1). Его предок, пакет -man7, задавал только расположение текста на странице, оставляя работу со шрифтами на авторскую доработку. В -mdoc формат страницы определяется структурным доменом страницы состоящим из макросов для заголовков текста, секций, блоков вывода и списков. Особенно это касается макросов, определяющих физическое положение текста на отформатированной странице. В дополнение к структурному домену страницы существуют еще два домена: страничный домен и общий текстовый домен. Общий текстовый домен содержит макросы, выполняющие задачи выделения текста. Страничный домен содержит набор макросов, предоставляющих пользователю (в стандартной форме вывода) команды, функции и соответствующие файлы BSD . Макросы в страничном домене работают с названиями команд, их параметрами и опциями, названиями и параметрами функций, именами файлов, переменными, ссылками на другие страницы и т.п. Эти элементы доменов имеют большую ценность как для автора документа, так и для будущего пользователя. Есть надежда, что такая стандартизация всего набора страниц руководства обеспечит более простое их преобразование для будущих утилит формирования документации.

     

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

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

    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

    Пакет -mdoc ставит перед собой цель упростить процесс написания страниц руководства. Теоретически автор не должен знать тонкостей troff(1) для использования -mdoc однако, существует несколько ограничений, которые обойти невозможно, и лучше их не использовать. Надо добавить, что этот пакет не работает быстро.  

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

    Как и в troff(1), макрос может быть вызван указанием `.' (точки) в начале строки, за которой следует двухсимвольное название макроса. За ним могут следовать параметры макроса, разделенные пробелами. Именно точка в начале строки заставляет troff(1) считать следующие два символа именем макроса. Для того, чтобы поместить `.' (точку) в начало строки в ином, отличном от запуска макроса контексте, укажите перед `.' (точкой) escape-последовательность `\&' Эта последовательность означает пробел с нулевой шириной и никогда не выводится.

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

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

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

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

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

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

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

    Иногда в качестве параметра макроса необходимо указать один или несколько пробелов. Это бывает нужно для игнорирования лимита из девяти параметров или для макросов, которым необходим строгий порядок расположения параметров в строке. Например, макрос функции `.Fn определяет, ' что первый его параметр - название функции, а все остальные - ее параметры. В ANSI C параметры функции указываются в списке, заключенном в скобки, и каждый параметр бывает, как минимум, строкой из двух слов. Например, Fa int foo .

    Существует два возможных способа передачи параметра, содержащего пробел. Примечание по реализации К сожалению, наиболее простой и удобный способ передачи пробелов внутри кавычек очень отражался на скорости работы и объемах памяти, используемой 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 ЗАМЕЧАНИЯ .

     

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

    Troff может не распознать пробелы в конце строки. Неплохо удалять все пробелы, находящиеся в конце строк. Если возникнет необходимость поставить пробел в конце строки, то лучше это сделать при помощи непереносимого пробела и escape-символа `\&' (Например, `string\\&' ).  

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

    Специальные символы, такие, как `\n' , указываются при помощи замены символа `\' на `\e' (например, `\en' ) для того, чтобы сохранить в тексте обратный слэш.  

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

    "Тело" страницы руководства можно легко создать при помощи базового шаблона, находящегося в файле /usr/share/misc/mdoc.template Несколько примеров страниц руководства можно найти в каталоге /usr/share/examples/mdoc

     

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

    .\" Следующие макросы обязательны для всех страниц руководства
    .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 МАКРОСЫ ЗАГОЛОВКА .

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

    ,

    ) из которых Sx НАЗВАНИЕ , Sx СИНТАКСИС и Sx ОПИСАНИЕ являются обязательными. Заголовки секций описаны в разделе Sx СТРУКТУРНЫЙ ДОМЕН СТРАНИЦЫ после описания 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

     

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

     

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

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

    В первом случае макросы 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 .  

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

    Страничный домен макросов и общий текстовый домен макросов имеют одинаковый синтаксис, но есть ряд небольших различий: `.file ... ' `.- ' `. ' и `.различаются ' только, когда вызываются без аргументов; `.Fn и ' `.определяют ' порядок своих аргументов в списках, а макросы `.[и] ' `.Fn имеют ' ограничения глубины вложенных вызовов макросов. Все макросы содержания должны распознавать и поддерживать пунктуацию, оставляя пробел перед знаком. Если запрос делается в такой форме:

    .sptr, ptr),

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

    sptr, ptr),

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

    .sptr , ptr ) ,

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

    sptr , ptr

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

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

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

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

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

     

    Адреса

    Макрос адреса определяет структуру адреса в форме addr1[,addr2[,addr3]].

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

    .addr1
    addr1
    .addr1
    addr1
    .addr1 , file2
    addr1 , file2
    .f1 , f2 , f3:
    f1 , f2 , f3
    .addr ) ),
    addr ) )

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

    Автор

    Макрос `.An используется ' для указания имени автора документа или страницы руководства. Любые аргументы, стоящие после имени, считаются пунктуационными знаками.

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

    .An Joe Author
    An Joe Author
    .An Joe Author,
    An Joe Author ,
    .An Joe Author Aq [email protected]
    An Joe Author Aq [email protected]
    .An Joe Author ) ),
    An Joe Author ) ) ,

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

    Параметры

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

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

    .file ...
    file ...
    .file1
    file1
    .file1
    file1
    .file1 file2
    file1 file2
    .f1 f2 f3:
    f1 f2 f3
    .file ) ),
    file ) )

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

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

    Пример использования макроса `.можно ' найти в config(8) Этот макрос использует двойные кавычки.

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

     

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

    модификатор команд идентичен команде `.- ' (флаг), за исключением того, что макрос `.не ' требует тире перед каждым аргументом. Обычно флаги отмечаются предшествующим им тире, но некоторые команды не используют этот прием. Модификаторы команд можно описать и совместно с интерактивными командами, такими, как команды редактирования. См. Sx Flags .  

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

    Переменная, которая задана во вложеном файле, определена макросом `. '

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

    .MAXHOSTNAMELEN
    MAXHOSTNAMELEN
    .TIOCGPGRP )
    TIOCGPGRP

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

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

    Макрос кодов ошибок `.Er определяет ' коды возвращаемых ошибок для второго раздела библиотечных функций. Во втором примере, приведенном ниже, показано, как `.Er используется ' совместно с `.Bq макросом ' общего текстового домена.

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

    .Er ENOENT
    Er ENOENT
    .Er ENOENT );
    Er ENOENT ) ;
    .Bq Er ENOTDIR
    Bq Er ENOTDIR

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

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

    Макрос `.задает ' переменные окружения.

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

    .DISPLAY
    DISPLAY
    .PATH
    PATH
    .PRINTER ) ),
    PRINTER ) )

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

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

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

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

    .Fa d_namlen ) ),
    Fa d_namlen ) ) ,
    .Fa iov_len
    Fa iov_len

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

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

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

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

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

    Флаги

    Макрос `.- ' поддерживает разбиение командной строки и требует указания тире до флага `-'

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

    .-
    -
    .-cfv
    -cfv
    .-cfv
    -cfv
    .-s v t
    -s v t
    .--,
    --
    .-xyz ),
    -xyz )

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

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

    Макрос .Fn создан по правилам ANSI C.
    Использование: .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 и поэтому может некорректно разбить строку. В ближайшем будущем такой случай будет доработан.  

    Типы функций

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

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

    .Ft struct stat
    struct stat

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

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

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

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

    .:wq
    :wq
    .do while {...}
    do while {...}
    .setenv , unsetenv
    setenv , unsetenv

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

    Названия

    Макрос `. ' используется для заголовков или подзаголовков. Его особенностью является запоминание первого аргумента, с которым он был вызван, что обычно бывает названием страницы. При вызове макроса `. ' без аргумента он возвращается с этим первоначальным значением, что облегчает работу автора. Замечание: во втором и третьем разделах страниц руководства имя функции в секции Sx NAME пишется с использованием макроса `. ' а в остальных секциях и других разделах страниц руководства используется макрос `.Fn ' Для интерактивных команд, таких, как `while' в csh(1), используется макрос `. ' Макросы `.и '

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

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

    .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 ' может быть вызван и обработан.  

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

    Принцип выделения идентичен принципу цитирования. Объект, подлежащий выделению, помещается между двумя символами, такими, как кавычки. В этом документе для цитирования и выделения используются почти одна и та же пунктуация. Для указания на обособление используются макросы, оканчивающиеся буквой `q' А так как они могут использоваться на протяжении текста, то в эту область может попасть и объект цитирования (или наоборот, в объект цитирования попадет объект, подлежащий выделению), поэтому внутри можно использовать макрос цитирования, прописанный в одной строке. Поэтому для каждого объекта обособления можно еще использовать два макроса: открывающий и закрывающий - они оканчиваются строчными буквами `o' и `c' соответственно.

    Обособ.       Закрыв. Открыв. действие                Результат .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 ФАЙЛЫ
    Sx ФАЙЛЫ

     

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

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

    .Rs
    Начало ссылок. Вызывает разбиение строки, начинает список ссылок и продолжает его до конца макроса.
    .Re
    Конец ссылок. Ссылка печатается.
    .%A
    Имя автора, одно на каждый вызов.
    .%B
    Название книги.
    .%C
    Город/издательство.
    .%D
    Дата.
    .%J
    Название журнала.
    .%N
    Номер журнала.
    .%O
    Дополнительная информация.
    .%P
    Номер страницы.
    .%R
    Название отчета.
    .%T
    Заголовок статьи.
    .%V
    Том(-а).

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

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

    Макрос `.Rv форматирует ' текст для раздела Sx ВОЗВРАЩАЕМЫЕ ЗНАЧЕНИЯ .

    Применение: .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-ов: 




    Партнёры:
    PostgresPro
    Inferno Solutions
    Hosting by Hoster.ru
    Хостинг:

    Закладки на сайте
    Проследить за страницей
    Created 1996-2024 by Maxim Chirkov
    Добавить, Поддержать, Вебмастеру