Определение новых команд Texinfo

Texinfo предоставляет несколько способов определить новые команды:

• Команда Texinfo macro позволяет вам определять новые команды в виде виде произвольной последовательности текста и/или существующих команд Texinfo (включая другие макросы). Макрос может принимать любое число параметров -- фрагментов текста, которые вы передаете при каждом вызове макроса. Кстати, такие макросы не имеют никакого отношения к команде @defmac, которая служит для документирования рассматриваемых в руководстве макросов (ТшрзСызш Стюцшщ Шаблон определения.)
• `@alias' дает удобный способ определения нового имени для существующей команды.
• `@definfoenclose' позволяет вам определять новые команды с настраиваемым видом при выводе в Info.

Определение макросов

Используйте для определения макросов команду Texinfo @macro, как показано:

@macro имя-макроса{парам1, парам2, ...}
текст ... \парам1\ ...
@end macro

Параметры парам1, парам2, ... соответствуют аргументам, передаваемым макросу при последующих вызовах внутри документа (описано в следующем разделе).

Чтобы макрос работал в TeX, имя-макроса должно состоять только из букв и не включать цифр, подчерков, дефисов или других специальных знаков.

Если макрос не нуждается в параметрах, вы можете определить его с пустым списком параметров (`@macro foo {}') или вообще без фигурных скобок (`@macro foo').

В определении тела макросы Texinfo. Кроме того, определение макроса, определяющего другой макрос не работает в TeX из-за ограничений в реализации @macro.

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

Чтобы получить в раскрытии макроса один знак `\', используйте `\\'. Любое другое применение `\' в теле порождает предупреждение.

Переводы строк после строки @macro и перед строкой @end macro игнорируются, то есть не включаются в тело макроса. Все остальные пропуски интерпретируются в соответствии с обычными правилами Texinfo.

Чтобы позволить макросу использоваться рекурсивно, то есть в аргументе вызова самого себя, вы должны определить его с помощью `@rmacro', как показано:

@rmacro rmac
a\arg\b
@end rmacro
...
@rmac{1@rmac{text}2}

Это дает на выходе `a1atextb2b'. При использовании `@macro' вместо `@rmacro', будет выдано сообщение об ошибке.

Вы можете отменить определение макроса foo вызовом @unmacro foo. Отмена еще не определенного макроса не является ошибкой. Например:

@unmacro foo

Вызов макросов

После того как макрос определен (смотрите предыдущий раздел), вы можете использовать (вызывать) его в ваших документах следующим образом:

@имя-макроса {арг1, арг2, ...}

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

@macro foo {p, q}
Вместе: \p\ и \q\.
@end macro
@foo{А, Б}

дает:

Вместе: А и Б.

фигурные скобки, даже если макро не принимает аргументов, так же, как и во всех остальных командах Texinfo. Например:

@macro без-аргументов {}
Здесь нет аргументов.
@end macro
@без-аргументов{}

дает:

Здесь нет аргументов.

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

@имя-макроса {\\\{\}\,}

передаст макросу имя-макроса аргумент `\{},', (что почти наверняка приведет к ошибке).

Если макрос определен с одним аргументом и вызван без фигурных скобок, в качестве аргумента ему будет передан весь остаток строки после имени макроса. Например:

@macro bar {p}
Дважды: \p\ и \p\.
@end macro
@bar ах

дает:

Twice: ах и ах.

Если макрос определен с одним аргументом и вызван с фигурными скобками, в качестве аргумента передается текст в скобках, независимо от запятых. К примеру:

@macro bar {p}
Twice: \p\ и \p\.
@end macro
@bar{а,б}

дает:

Дважды: а,б и а,б.

Подробно о макросах

В связи с неразрешимыми разногласиями в реализациях TeX и makeinfo макросы Texinfo обладают следующими ограничениями.

• Все макросы раскрываются внутри по меньшей мере одной группы TeX. Это означает, что @set и другие команды не будет действовать внутри макроса.
• Макросы, содержащие команду, которая должна находиться на отдельной строке, например условие, нельзя вызывать в середине строки.
• Например:

  
  @end tex
  

• Лучше избегать комментариев в определениях макросов.

`@alias новая=существующая'

Команда `@alias' возможно, оставят результат таким же.

Пишите команду `@alias' на отдельной строке, а после пишите имя новой команды, знак равенства и имя существующей команды. Пропуски вокруг знака равенства игнорируются. Пример:

@alias новая = существующая

Например, если ваш документ содержит ссылки как на книги, так и на другие произведения (скажем, фильмы), вы могли бы захотеть определить макро @moviecite{}, которое делает то же самое, что и обычная команда @cite{}, но также передает дополнительную семантическую информацию. Вы могли бы сделать это так:

@alias moviecite = cite

в Jargon File!)

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

`definfoenclose': Настройка выделения

Вы можете использовать обычные команды TeX внутри блока @iftex ... @end iftex работают только в TeX.

Вы можете использовать команду @definfoenclose внутри блока @ifinfo ... @end ifinfo для определения новых команд для Info с теми же именами, что и новые команды для TeX. @definfoenclose создает новые команды для Info, которые помечают текст, окружая его заданными строками.(12)

Ниже показано, как создать новую @-команду, называемую @phoo, которая заставляет TeX набирать свой аргумент курсивом, а Info --- выводить аргумент между `//' и `\\'.

Для TeX напишите следующее, чтобы приравнять команду @phoo существующей команде @i для курсива:

@iftex
@global@let@phoo=@i
@end iftex

Это определяет @phoo как команду, заставляющую TeX набирать аргумент @phoo курсивом. @global@let говорит TeX приравнять следующий аргумент аргументу, идущему после знака равенства.

Для Info напишите следующее, чтобы программы форматирования Info заключали аргумент между `//' и `\\':

@ifinfo
@definfoenclose phoo,//,\\
@end ifinfo

Пишите команду @definfoenclose в начале строки, а после нее пишите три аргумента, разделенные запятыми (запятые используются в качестве разделителей в строке @node таким же образом).

• Первым аргументом @definfoenclose является имя @-команды без `@';
• второй аргумент -- это начальная строка-разделитель для Info; и
• третий аргумент -- завершающая строка-разделитель.

Два последних аргумента окружают выделяемый текст в Info-файле. Строка-разделитель может содержать пробельные знаки, но они имеют значение, поэтому не вставляйте пропуски, если не хотите, чтобы они появились при выводе. Ни начальный, ни завершающий разделитель не обязателен. Однако, если вы не задаете начальный разделитель, вы должны написать после имени команды две запятые подряд; иначе команды форматирования для Info неправильно воспримут завершающий разделитель как начальный.

После того, как вы определили @phoo и для TeX, и для Info, вы можете написать @phoo{bar} и получить `//bar\\' в Info и курсивное bar в печатном выводе.

Заметьте, что каждое определение применяется для своей форматирующей программы: одно для TeX, другое для Info.

Вот другой пример:

@ifinfo
@definfoenclose headword,,:
@end ifinfo
@iftex
@global@let@headword=@b
@end iftex

Это определяет @headword как команду, которая в Info вставляет двоеточие после аргумента и не вставляет ничего перед ним, а в TeX набирает аргумент жирным шрифтом.