Распространяемые на данный момент программы, имеющие отношение к
Texinfo, включают фрагменты GNU Emacs, а также отдельные программы (в
том числе makeinfo, info, texindex и
`texinfo.tex'). Эти программы свободны; это значит, что
каждый может использовать и распространять на свободной основе.
Программы, имеющие отношение к Texinfo, не являются общественным
достоянием; на них распространяется авторское право, и на их
распространение существуют ограничения, но эти ограничения разработаны
так, чтобы позволить все, что хороший благонамеренный гражданин может
захотеть. Что не разрешается, так это пытаться мешать другим и далее
совместно пользоваться любой версией этих программ, которые они могли бы
от вас получить.
А именно, мы хотим убедиться, что у вас есть право распространять копии программ, имеющих отношение к Texinfo, что вы получаете исходный код или можете получить его, если захотите, что вы можете изменять эти программы или использовать их части в новых свободных программах и что вы знаете, что вы можете все это делать.
Чтобы убедиться, что каждый имеет такие права, мы должны запретить вам лишать кого-либо этих прав. Например, если вы распространяете копии программ, имеющих отношение к Texinfo, вы должны предоставить получателям все права, которыми обладаете вы сами. Вы обязаны убедиться, что они тоже получат или смогут получить исходный код. И вы должны сообщить им об их правах.
Также, для нашей собственной защиты, мы хотим удостовериться, что все понимают, что гарантий на программы, имеющие отношение к Texinfo, нет. Если эти программы модифицируются и передается кем-то еще, мы хотим, чтобы получатели знали, что то, что у них есть -- это не то, что распространяем мы, чтобы любые проблемы, созданные другими, не отразились на нашей репутации.
Точные условия лицензий для распространяемых на данный момент программ, имеющих отношение к Texinfo, находятся в поставляемой с ними Универсальной Общественной Лицензии GNU.
Texinfo(1) -- это система создания документации, которая использует единый входной файл для производства как интерактивной информации, так и распечатки. Это означает, что вместо написания двух разных документов, одного для интерактивной информации, а другого для печатного произведения, вам нужно написать только один. Следовательно, при внесении изменений вам нужно будет отредактировать только один документ.
Мы рады получить ваши предложения по улучшению системы Texinfo и сообщения об ошибках как для программ, так и для документации. Пожалуйста, посылайте их по адресу bug-texinfo@gnu.org. Вы можете получить последнюю версию Texinfo на ftp://ftp.gnu.org/gnu/texinfo/ и с зеркал по всему миру.
При описании ошибок, пожалуйста, включайте достаточно информации, чтобы сопроводители могли воспроизвести проблему. Вообще говоря, это означает:
Если вы сомневаетесь, необходимы ли какие-то сведения или нет, включайте их. Лучше включить слишком много, чем пропустить что-то важное.
Особо приветствуются готовые исправления; если возможно, пожалуйста, делайте их с помощью `diff -c' (@xref{Top,, Overview, @external{diffutils}, Comparing and Merging Files}) и включайте описание ваших изменений для журнала `ChangeLog' (@xref{Change Log,,, @external{emacs}, Руководство по GNU Emacs}).
При посылке сообщения, если возможно, не кодируйте и не разбивайте его; гораздо проще обращаться с простым текстовым сообщением, даже большим, чем с многими маленькими. Удобный способ упаковки нескольких и/или двоичных файлов для электронной почты предоставляет GNU shar.
Используя Texinfo, вы можете создавать печатный документ с обычными для книг свойствами, включая главы, разделы, перекрестные ссылки и именные указатели. Из этого же исходного Texinfo-файла вы можете создать интерактивный, управляемый меню Info-файл с нодами, меню, перекрестными ссылками и именными указателями. Кроме того, из этого же исхдного файла вы можете создать HTML-файл для просмотра с помощью Web-броузера. Хорошими примерами Texinfo-файлов служат Руководство по GNU Emacs и данное руководство.
Чтобы получить печатный документ, вы пропускаете исходный Texinfo-файл через форматирующую программу TeX (но язык Texinfo сильно отличается от plain TeX, обычного языка TeX). Она создаст DVI-файл, который вы сможете распечатать в виде книги или отчета (see section Форматирование и печать твердой копии).
Для получения Info-файла вам нужно обработать Texinfo-файл с помощью
программы @command{makeinfo} или команды Emacs
texinfo-format-buffer. Вы сможете установить созданный Info-файл
в дерево системы Info, (see section Установка Info-файла).
Чтобы сделать HTML-файл, обработайте ваш исходный Texinfo-файл с помощью
makeinfo, используя ключ @option{--html}. Вы можете (к примеру)
установить результат на вашем Web-сайте.
Если вы программист и хотели бы внести свой вклад в проект GNU,
реализовав дополнительные выходные форматы для Texinfo, это было бы
великолепно. Но, пожалуйста, не пишите отдельный транслятор texi2foo
для вашего любимого формата foo! Это трудный путь выполнения этой
задачи, он создает дополнительную работу для дальнейшего сопровождения,
так как язык Texinfo постоянно расширяется и обновляется. Вместо этого,
лучшим вариатом будет изменить makeinfo так, чтобы она
генерировала вывод в новом формате, как сейчас она делает для Info и
HTML.
TeX работает практически со всеми принтерами; а Info -- почти с любым типом терминалов; HTML-вывод работает практически со всеми web-броузерами. Поэтому практически все пользователи компьютернов могут применять Texinfo.
Исходный Texinfo-файл -- это простой ASCII-файл, содержащий текст и @-команды (слова, начинающиеся с `@'), сообщающие форматирующим и подготавливающим к печати программам, что нужно делать. Вы можете редактировать Texinfo-файл любым текстовым редактором; но особенно удобно будет использовать GNU Emacs, так как он имеет специальный режим, называемый режимом Texinfo, предоставляющий многие возможности специально для Texinfo. (See section Использование режима Texinfo.)
Перед написанием Texinfo-файлов вам стоит ознакомиться с тем, что такое ноды, меню, перекрестные ссылки и прочее, например, читая данное руководство.
Вы можете использовать Texinfo для создания как интерактивной информации, так и печатных руководств, кроме того, Texinfo распространяется свободно. Поэтому Texinfo -- это официальный формат документации для утилит и библиотек проекта GNU. Подробная информация доступна на странице документации GNU.
Время от времени выдвигаются предложения генерировать традиционные страницы man Unix из исходников на Texinfo. Скорее всего, это никогда не будет поддерживаться, поскольку страницы man имеют очень строгий условный формат. Простого расширения @command{makeinfo} для поддержки формата troff было бы недостаточно. Создание хорошей страницы man, следовательно, требует совершенно иного исходного текста, в отличие от типичного применения Texinfo -- создания хорошего руководства пользователя и справочного руководства. Поэтому создание страниц man не совмещается с целью Texinfo -- не документировать одну и ту же информацию несколькими способами для разных выходных форматов. Вы также можете просто написать страницу man саму по себе.
Если вы хотите поддерживать страницы man, может оказаться полезной программа @command{help2man}; она генерирует традиционную страницу man из вывода программы по ключу `--help'. Фактически, в настоящее время она применяется для генерации страниц man для самих программ Texinfo. Это свободная программа, написанная Бренданом О'Ди и доступная на http://www.ozemail.com.au/~bod/help2man.tar.gz.
Info-файл -- это Texinfo-файл, отформатированный таким образом, чтобы
его можно было использовать с программой просмотра документации Info.
(makeinfo и texinfo-format-buffer -- две команды,
преобразующие Texinfo-файл в Info-файл.)
Info-файлы разделены на секции, называемые нодами, в каждой из которых рассмотрена одна тема. Каждая нода имеет имя и содержит как текст, предназначенный для чтения пользователем, так и указатели на другие ноды, различаемые по именам. Программа Info отображает в каждый момент одну ноду и предоставляет команды, с помощью которых пользователь может передвигаться к другим родственным нодам.
Каждая нода Info может содержать любое число дочерних нод, описывающих подтемы рассматриваемой в ноде темы. Имена дочерних нод перечислены в меню родительской ноды; это позволяет передвигаться к одной из дочерних нод, используя определенные команды Info. Обычно Info-файл организован подобно книге. Если нода находится на логическом уровне главы, то дочерние ноды находятся на уровне разделов; дочерние ноды разделов находятся, соответственно, на уровне подразделов.
Все дочерние и родительские ноды связаны в двунаправленную цепочку указателей `Next' и `Previous' (`Следующая' и `Предыдущая'). Указатель `Next' предоставляет связь со следующим разделом, а `Previous' -- с предыдущим. Это означает, что все ноды на уровне разделов одной главы связаны вместе. Как правило, порядок нод в этой цепочке такой же, как и порядок дочерних нод в родительском меню. Каждая дочерняя нода хранит указатель на родительскую ноду под именем `Up' (`Вверх'). Последний потомок не имеет указателя `Next', а первый потомок указывает на родителя и в качестве `Previous', и `Up'.(2)
Организация Info-файла по типу книги, с главами и разделами, -- это только вопрос соглашения, а не необходимое условие. Указатели `Up', `Previous' и `Next' могут указывать на любые ноды, а меню также может содержать любые другие ноды. Таким образом, структура нод может быть произвольным направленным графом. Но обычно для понятности лучше следовать структуре глав и разделов печатной книги или отчета.
Кроме меню и указателей `Next', `Previous' и `Up' Info предоставляет указатели другого рода, называемые ссылками, которые могут появляться в любом месте текста. Как правило, это лучший способ представлять ссылки, не попадающие в иерархическую структуру.
Обычно вы разрабатываете документ так, чтобы ноды соответствовали структуре глав и разделов печатной версии. Но иногда это не подходит для обсуждаемого материала. Тогда Texinfo использует отдельные команды для задания структуры нод и структуры разделов печатной версии.
Обычно вы начинаете просмотр Info-файла с ноды, называемой по соглашению `Top'. Эта нода содержит лишь краткий обзор целей файла и большое меню, через которое можно получить доступ к остальной части файла. Из этой ноды вы можете просмотреть файл последовательно ноду за нодой или перейти к конкретной ноде, перечисленной в главном меню, или найти в именных указателях непосредственно ту ноду, которая содержит нужную вам информацию. Кроме того, при использовании самостоятельной программы Info вы можете задать определенные пункты меню в командной строке (see section `Top' in Info).
Если вы хотите прочитать Info-файл последовательно, как печатное руководство, вы можете постоянно нажимать SPC или получить Info-файл целиком продвинутой командой Info g *. (See Info file `info', node `Expert'.)
Файл `dir' в каталоге `info' служит отправной точкой для системы Info в целом. Из него вы можете перейти к первым (`Top') нодам каждого документа во всей системе Info.
Если вы хотите сослаться на Info-файл в URI, вы можете использовать (неофициальный) синтаксис, пример которого приведен ниже. Это работает только с Emacs/W3, к примеру:
info:///usr/info/emacs#Dissociated%20Press info:emacs#Dissociated%20Press info://localhost/usr/info/emacs#Dissociated%20Press
Сама программа @command{info} не следует по URI любого вида.
Texinfo-файл может быть отформатирован и набран для печати книги или руководства. Чтобы сделать это, вам понадобится TeX, мощная и сложная программа компьютерного набора, написанная Дональдом Кнутом.(3)
Книга, основанная на Texinfo, подобна любой другой набранной печатной книге: у нее может быть титульный лист, страница с информацией об авторских правах, содержание и предисловие, а также главы, нумерованные или ненумерованные разделы и подразделы, заголовки страниц, перекрестные ссылки, сноски и именные указатели.
Вы можете использовать Texinfo для написания книги, даже не замышляя преобразовать ее в интерактивный вид. Вы можете использовать Texinfo для написания повести или даже печатного меморандума, хотя последние не рекомендуется, так как для этого намного лучше подходит электронная почта.
TeX -- программа верстки общего назначения. С Texinfo поставляется файл `texinfo.tex', который содержит информацию (определения или макросы), которую TeX использует при наборе Texinfo-файла. (`texinfo.tex' сообщает TeX как переводить @-команды Texinfo в команды TeX, которые он уже может обработать для создания набранного документа.) `texinfo.tex' содержит спецификации для печати документа. Вы можете получить последнюю версию файла `texinfo.tex' по адресу ftp://ftp.gnu.org/gnu/texinfo.tex.
Чаще всего документы печатают на страницах размером 8.5 на 11 дюймов
(216мм на 280мм, это размер по умолчанию), но вы также
можете печатать на страницах размером 7 на 9.25 дюймов (178мм на
235мм, размер @smallbook) или на европейском формате A4
(@afourpaper). (See section Печать "маленьких" книг, а
также section Печать на формате A4.)
Вы можете изменить размер печатной версии, изменяя параметры в файле `texinfo.tex'. Помимо размера, вы можете изменить стиль форматирования; например, изменить размеры шрифтов и сами используемые шрифты, размеры отступов абзацев, степень разбиения слов при переносах и другие параметры. Изменяя установки, вы можете сделать книгу величественной, старомодной и серьезной, или легкомысленной, молодой и веселой.
TeX распространяется свободно. Он написан на языке WEB, расширении языка Паскаль, и может быть скомпилирован из текстов на Паскале или Си (с применением программы перевода, поставляемой вместе с TeX). (See section `Режим TeX' in Руководство по GNU Emacs, для получения информации о TeX.)
TeX -- очень мощная программа и имеет много возможностей. Но ввиду того, что Texinfo-файл должен предоставлять информацию и на текстовых терминалах, и в виде книги, набор форматирующих команд, поддерживаемых Texinfo, был по необходимости ограничен.
See section Как получить TeX.
Команды Texinfo, сообщающие TeX, каким образом нужно набирать
печатное руководство, а makeinfo и texinfo-format-buffer
--- как создать Info-файл, начинаются с символа `@'; они
называются @-командами. Например, @node -- это команда,
указывающая начало ноды, а @chapter -- указывающая начало
главы.
Обратите внимание: Все @-команды за исключением
@TeX{}должны набираться строчными буквами.
@-команды Texinfo составляют строго ограниченный набор конструкций. Строгое ограничение позволяет понимать Texinfo-файлы как TeX, так и командам, создающим Info-файлы. Вы можете просмотреть Info-файлы на любом алфавитно-цифровом терминале и распечатать вывод TeX на многих типах принтеров.
Вы должны писать @-команды в отдельной строке или внутри предложения в зависимости от их действия и принимаемых аргументов(4):
@noindent с начала отдельной строки.
(@noindent отменяет отступ для начала абзаца в следующей
строке.)
@chapter с начала строки с последующими
аргументами, в данном случае названием главы, в конце строки.
(@chapter создает названия глав.)
@dots{} где вы хотите, обычно внутри
предложения. (@dots{} вставляет многоточие ...)
@code{код}, где вы хотите (но
обычно внутри предложения) с аргументом, в данном случае код,
заключенным в фигурные скобки. (@code отмечает программный
код.)
@example на отдельной строке; текст тела
пишите на последующих строках; пишите завершающую команду @end,
в данном случае @end example, на отдельной строке после текста
тела. (@example ... @end example делает отступы и
набирает текст тела в виде примера.) Обычно определяющие среду команды,
подобные этой, можно писать с отступом, но в сложных и
трудноопределяемых обстоятельствах дополнительные промедутки на входе
производят лишние промежутки на выводе, поэтому будьте внимательны.
Как правило, команды, встречающиеся внутри текста, нужно использовать с
фигурными скобками, но команды, записываемые на отдельной строке, не
нужно. Исключение составляют неалфавитные команды, такие как
@:: они не требуют скобок.
По мере появления у вас опыта в использовании Texinfo, вы быстро научитесь, как писать разные команды: различные способы написания команд позволяют легче писать и читать Texinfo-файлы, чем если бы все команды следовали единому синтаксису. (Подробности о синтаксисе @-команд смотрите в section Синтаксис @-команд.)
Этот раздел описывает общие соглашения, применяемые во всех документах Texinfo.
@noindent на отдельной строке.
@iftex и
@end iftex, то она появится только в печатной версии; в этой
области вы можете использовать команды из plain TeX, которые
недоступны в Info. Аналогично, если вы отметите область командами
@ifinfo и @end ifinfo, то она появится только в
Info-файле; в этой области вы сможете использовать команды Info,
недоступные в TeX. То же и для @ifhtml ... @end ifhtml,
@ifnothtml ... @end ifnothtml, @ifnotinfo ...
@end ifnotinfo, @ifnottex ... @end ifnottex.
See section Условно видимый текст.
Внимание: Не используйте символы табуляции в Texinfo-файлах! В TeX применяются шрифты переменной ширины, а это значит, что вы не сможете обеспечить правильное действие табуляции в каждом случае. Поэтому TeX воспринимает символы табуляции как один пробел, а это не похоже на табуляцию. Кроме того,
makeinfoне предпринимает никаких особых действий для символов табуляции, таким образом, вставляя их на вход, вы можете получить что-то, чего не ожидали.Чтобы избежать этой проблемы, режим Texinfo заставляет GNU Emacs вставлять несколько пробелов, когда вы нажимаете клавишу TAB.
Вы также можете запустить в Emacs функцию
untabify, чтобы превратить в области все символы табуляции в пробелы.
Вы можете писать в Texinfo-файле комментарии, которые не появятся ни в
Info-файле, ни в печатном руководстве, используя команду
@comment (ее можно сокращать как @c). Такие комментарии
предназначены для человека, пересматривающего Texinfo-файл. Весь текст
в строке после @comment или @c является комментарием.
(Чаще всего вы можете написать @comment или @c в
середине строки, и только текст, следующий за этими командами не
появится в результате; но некоторые команды, например @settitle
и @setfilename действуют на всю строку. Вы не можете
использовать @comment или @c в строке, начинающейся с
такой команды.)
Вы можете написать большие куски текста, которые не появятся ни в
Info-файле, ни в печатном руководстве, используя команды @ignore
и @end ignore. Пишите каждую из этих команд с начала отдельной
строки. Текст, заключенный между двумя этими командами, не появляется
при выводе. Таким образом, вы можете использовать @ignore и
@end ignore для написания комментариев. Часто @ignore и
@end ignore применяют, чтобы ограничить фрагмент разрешения на
копирование, относящийся к исходному тексту Texinfo, но не к Info-файлу
или печатному руководству.
По соглашению, имена Texinfo-файлов заканчиваются расширением `.texinfo', `.texi', `.txi' или `.tex'. Предпочтительны длинные расширения, так как они яснее показывают читающему природу файла. Короткие расширения нужны для систем, которые не умеют обращаться с длинными именами файлов.
Чтобы получился Info-файл или печатное руководство, Texinfo-файл должен начинаться такими строками:
\input texinfo @setfilename имя-info-файла @settitle название-руководства
За этим началом следует содержимое файла, и вы должны завершить Texinfo-файл такой строкой:
@bye
Строка `\input texinfo' велит TeX загрузить файл `texinfo.tex', который сообщает TeX, как переводить @-команды Texinfo в команды набора TeX. (Обратите внимание на использование обратной косой черты, `\'; это является правильным для TeX.) Строка `@setfilename' задает имя Info-файла и велит TeX открывать вспомогательные файлы. Строка `@settitle' задает название печатного руководства для заголовков страниц.
Строка @bye в конце файла сообщает форматирующим программам, что
файл пройден целиком и нужно остановить форматирование.
Обычно вы будете использовать не этот, довольно скудный формат, а будете включать в начало Texinfo-файла строки start-of-header и end-of-header (начало-заголовка и конец-заголовка), например так:
\input texinfo @c -*- texinfo -*- @c %**start of header @setfilename имя-info-файла @settitle название-руководства @c %**end of header
`-*- texinfo -*-' в первой строке заставляет Emacs переключиться в режим Texinfo, когда вы хотите редактировать файл.
Строки @c, окружающие строки `@setfilename' и
`@settitle', не обязательны, но понадобятся, если вы захотите
запустить TeX или Info только для части файла. (See section Начало заголовка, для большей информации.)
Кроме того, обычно вы будете снабжать Texinfo-файл титульным листом, именными указателями и другими элементами. Но необходимый минимум, который может понадобиться для коротких документов, -- это лишь три строки в начале и одна в конце.
Вообще говоря, Texinfo-файл содержит что-нибудь еще кроме минимально необходимых начала и конца -- обычно он состоит из шести частей:
@ifinfo и @end ifinfo, чтобы форматирующие программы
помещали его только в Info-файл.
@titlepage и @end titlepage. Название и страница с
информацией об авторских правах появляется только в печатном
руководстве.
@bye на отдельной
строке.
Вот завершенный, но очень короткий Texinfo-файл из шести частей. Первые три части файла, от `\input texinfo' до `@end titlepage', кажутся более запугивающими, чем они есть на самом деле. Большая часть материала -- это стандартный шаблон; когда вы пишите руководство, просто вставьте в этот сегмент названия для него. (See section Начало Texinfo-файла.)
Текст примера далее содержит отступ; комментарии не содержат. Полный файл, без комментариев, показан в section Пример Texinfo-файла.
Заголовок не появляется ни в Info-файле, ни в печатном документе. В нем устанавливаются различные параметры, включая имя Info-файла и название, используемое в заголовках печатной версии.
\input texinfo @c -*-texinfo-*- @c %**start of header @setfilename sample.info @settitle Пример документа @setchapternewpage odd @c %**end of header
Сегмент с обзорным описанием и авторскими правами не появляется в печатном документе.
@ifinfo
Это короткий пример законченного Texinfo-файла.
Copyright @copyright{} 1990 Free Software Foundation, Inc.
@end ifinfo
Сегмент с титульным листом и авторскими правами не появляется в Info-файле.
@titlepage
@sp 10
@comment Заголовок печатается крупным шрифтом
@center @titlefont{Пример заголовка}
@c Две следующие команды начинают страницу с информацией об
@c авторских правах
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1990 Free Software Foundation, Inc.
@end titlepage
Нода `Top' содержит главное меню Info-файла. Так как в печатном руководстве вместо меню используется содержание, главное меню появляется только в Info-файле.
@node Top, First Chapter, , (dir) @comment имя-ноды, следующая, предыдущая, вверх
@menu
* Первая глава:: Первая и единственная глава в
этом примере.
* Указатель понятий:: В этом указателе есть два элемента.
@end menu
Сегмент тела включает весь текст документа, кроме именных указателей и содержания. В этом примере показана нода и глава, содержащая нумерованный перечень.
@node Первая глава, Указатель понятий, Top, Top
@comment имя-ноды, следующая, предыдущая, вверх
@chapter Первая глава
@cindex Пример элемента именного указателя
Это содержимое первой главы.
@cindex Другой пример элемента именного указателя.
Это нумерованный перечень.
@enumerate
@item
Это первый пункт.
@item
Это второй пункт.
@end enumerate
Команды @code{makeinfo} и @code{texinfo-format-buffer}
преобразуют Texinfo-файлы, такие как этот, в Info-файлы;
а @TeX{} форматирует печатное руководство.
Последний сегмент включает команды для создания именного указателя в
отдельной ноде и ненумерованной главе и для создания содержания; в нем,
также, есть команда @bye, которая отмечает конец
документа.
@node Указатель понятий, , Первая глава, Top @unnumbered Указатель понятий @printindex cp @contents @bye
Так выглядит содержание первой главы примера:
Это содержание первой главы.
Это нумерованный перечень.
- Это первый пункт.
- Это второй пункт.
Команды
makeinfoиtexinfo-format-bufferпреобразуют Texinfo-файлы, такие как этот, в Info-файлы; а TeX форматирует печатное руководство.
Ричард М. Столмен изобрел формат Texinfo, написал его первые процессоры и создал первую редакцию данного руководства. Роберт Дж. Чассел много пересматривал и дополнял руководство, начиная с издания 1.1. Брайн Фокс был ответственен за самомстоятельный дистрибутив Texinfo до версии 3.8 и написал отдельные программы @command{makeinfo} и @command{info}. Карл Берри делал обновления для Texinfo 3.8 и последующих выпусков, начиная с издания 2.22.
Мы благодарны всем, кто помог нам улучшить работу, особенно Франсуа Пинарду, и Девиду Д. Зуну, которые без устали записывали ошибки и неясные места и сообщали нам о них; мы особо благодарны Мелиссе Вайссхаус за ее частые и нередко скучные обзоры похожих изданий. Неутомимые Эли Зарецкий и Андреас Шваб предоставили бесчисленное множество заплат. Зак Вайнберг сделал невозможное, реализовав синтаксис макросов в `texinfo.tex'. Десятки других предоставили заплаты и предложения, они с благодарностью упомянуты в файле `ChangeLog'. Наши ошибки -- это только наши ошибки.
Немного истории: в CMU, в семидесятых Брайн Рейд разработал программу и
формат, называемый Scribe, для разметки документов для печати. Для
введения команд он использовал знак @, как и Texinfo, и старался
описывать содержимое документа, а не форматирование.
Тем временем люди из MIT создали еще один, не сильно отличающийся формат, называемый Bolio. Потом он стал использовать TeX в качестве языка набора: это BoTeX.
BoTeX можно было использовать только как язык разметки для печатных документов, но не интерактивных документов. Ричард Столмен (RMS) работал как над Bolio, так и над BoTeX. Он также разработал замечательный формат интерактивной справки, называемый Info, и объединил затем BoTeX и Info в Texinfo, язык разметки для текста, предназначенный для чтения и интерактивно, и в напечатанной версии.
Вы можете редактировать Texinfo-файл любым текстовым редактором, выбранным вами по вашему усмотрению. Texinfo-файл никак не отличается от любого другого ASCII-файла. Однако, при установке GNU Emacs вы получаете возможность воспользоваться специальным режимом, называемым режимом Texinfo, который снабжает вас командами Emacs и дополнительными средствами, которые могут сильно облегчить вашу работу.
Эта глава описывает только особенности режима Texinfo GNU Emacs. Здесь не рассматриваются все возможности языка форматирования документов Texinfo. Если вы читаете это руководство с самого начала, вы, вероятно, захотите быстро пролистать эту главу и вернуться к ней уже после изучения разделов, где язык форматирования документов Texinfo описывается более детально.
Режим Texinfo дает вам специальные возможности для работы с Texinfo-файлами:
@node.
Вероятно, две наиболее полезных возможности -- это возможность быстрой вставки часто используемых @-команд и возможность создания меню и указателей на ноды.
В большинстве случаев команды режима Text работают в режиме Texinfo
точно так же, как бы они работали и в самом режиме Text. В режиме
Texinfo к основным возможностям редактора GNU Emacs добавляется
дополнительный набор инструментов и команд редактирования. Основное
различие между режимом Text и режимом Texinfo касается заполнения
текста. Переменная, отвечающая за разделение абзацев, и таблица
синтаксиса переопределяются в режиме Texinfo так, чтобы команды Texinfo,
которые должны стоять в своих собственных строках, не были включены в
другие абзацы. Поэтому команда M-q (fill-paragraph)
перезаполняет абзацы, но не смешивает команды, требующие своей строки,
со смежными абзацами.
Кроме того, режим Texinfo устанавливает переменную page-delimiter
равной значению texinfo-chapter-level-regexp; по умолчанию, это
регулярное выражение, совпадающее с командами определения глав и их
аналогов, таких как приложения. С таким значением разделителя страницы
вы можете переходить от одного заголовка главы к другому с помощью
команд C-x ] (forward-page) и C-x [
(backward-page) и сужать буфер до текста главы с помощью команды
C-x p (narrow-to-page). (@xref{Страницы,,, @external{emacs}, Руководство по GNU Emacs}, для более подробного
описания команд, работающих со страницами.)
Вы можете называть Texinfo-файл так, как пожелаете, но по соглашению в
качестве расширения следует выбрать одно из этих: `.texinfo',
`.texi', `.txi' или `.tex'. Для использования
предпочтительно более длинное расширение, так как оно однозначно
определяет тип файла. Более короткое расширение необходимо использовать
в тех случаях, когда операционная система ограничивает длину имени
файла. GNU Emacs автоматически входит в режим Texinfo, если вы
обратитесь к файлу с расширением `.texinfo', `.txi' или
`.texi'. Кроме того, Emacs переходит в режим Texinfo, если в теле
файла в его первой строке присутствует текст `-*- texinfo -*-'.
Если вы находитесь в другом режиме и желаете переключиться в режим
Texinfo, выполните команду M-x texinfo-mode.
Естественно, как и другие возможности Emacs, режим Texinfo может быть расширен и настроен так, как вы этого пожелаете. В частности, очень легко изменить привязку ключей. Здесь описываются сделанные по умолчанию или стандартные привязки ключей.
Режим Texinfo дает возможность быстро вставлять часто используемые @-команды в буфер редактирования. Вы можете использовать эти команды для уменьшения времени набора команд.
Чтобы вызвать команды вставки, следует дважды набрать C-c и затем нажать первый символ @-команды:
@code{} и поместить точку между фигурными скобками.
@dfn{} и поместить точку между фигурными скобками.
@end и попытаться добавить правильно следующее слово,
такое как `example' или `table'. (Эта команда не может
правильно обрабатывать вложенные списки, зато вставляет слово, наиболее
соответствующее предшествующему списку).
@item и поместить точку в начале следующей
строки.
@kbd{} и поместить точку между фигурными скобками.
@node и добавить строку комментария, перечисляющую
последовательность нод `Next', `Previous' и `Up'. Оставить точку после
@node.
@noindent и поместить точку в начале следующей строки.
@samp{} и поместить точку между фигурными скобками.
@table, затем вставить SPC и поместить точку
после SPC.
@var{} и поместить точку между фигурными скобками.
@example и поместить точку в начале следующей строки.
{} и поместить точку между фигурными скобками.
Для того, что бы вставить команду, такую как
@code{...} вокруг существующего слова, надо
установить точку перед этим словом и ввести последовательность C-u
1 C-c C-c c. Это облегчает редактирование уже существующего обычного
текста. Величина параметра, следующего за C-u, сообщает Emacs
сколько слов после точки следует заключить между фигурными скобками:
`1' -- только одно слово, `2' -- два слова и так далее.
Используйте отрицательное число, чтобы заключить между скобками
предыдущее слово или слова. Если вы оставите параметр неопределенным,
то Emacs вставит строку с @-командой и поместит точку между фигурными
скобками. Это сработает только для тех @-команд, которые действуют на
слово или на слова внутри одной строки, вроде @kbd и
@var.
Этот набор команд вставки был создан после анализа частоты, с которой различные @-команды используются в Руководстве по GNU Emacs и в Руководстве по GDB. Если вы желаете добавить ваши собственные команды быстрой вставки, вы можете привязать к ключу макрос клавиатуры, использовать сокращение или расширить код в `texinfo.el'.
C-c C-c C-d (texinfo-start-menu-description) -- это
команда быстрой вставки, действие которой отличается от действия других
команд вставки. Она вставляет название ноды или заголовок главы в месте
для описания в пункте меню. (Пункт меню состоит из трех частей: имени
пункта меню, имени ноды и описания. Требуется только имя ноды, но
описание сильно помогает объяснить, о чем говорится в разделе
описываемой ноды. See section Составные части меню.)
Чтобы использовать texinfo-start-menu-description, установите
точку в строку пункта меню, и введите C-c C-c C-d. Команда ищет и
копирует заголовок, который сопутствует имени ноды и вставляет этот
заголовок как описание; затем устанавливает курсор в начале вставленного
текста, так что вы можете отредактировать это текст. Эта функция не
вставляет заголовок, если данный пункт меню уже содержит
описание.
Эта команда только помогает при создании описаний; она не делает всей работы. Вы должны отредактировать вставленный текст, так как при создании заголовка обычно используют те же слова, что используются в имени ноды, но полезное описание использует другие слова.
Вы можете визуализировать структуру разделов Texinfo-файла, используя
команду C-c C-s (texinfo-show-structure). Эта команда
показывает структуру разделов Texinfo-файла, перечисляя строки, которые
начинаются с @-команд, а именно, с команд @chapter,
@section и подобных. Эта команда создает такую же структуру,
какую представляет из себя оглавление. Эти строки отображаются в другом
буфере, называемом `*Occur*'. В том буфере вы можете установить
курсор на одной из этих строк и воспользоваться для перехода к
соответствующему разделу в Texinfo-файле последовательностью C-c
C-c (occur-mode-goto-occurrence).
@chapter, @section, и подобные строки
Texinfo-файла.
Если вы вызываете texinfo-show-structure с префиксным аргументом,
набирая C-u C-c C-s, это перечислит не только строки с
@-командами, такими как @chapter, @section и подобными,
но также и строки @node. Вы можете использовать
texinfo-show-structure с префиксным аргументом для того, чтобы
проверить, являются ли указатели `Next', `Previous' и `Up' в строке
@node правильными.
Часто, когда вы работаете над руководством, вам будете нужна только
структура текущей главы. В этом случае вы можете выделить область
буфера, структура которой вам нужна, используя команду C-x n n
(narrow-to-region), и texinfo-show-structure будет
действовать только в этой области. Чтобы снова увидеть весь буфер,
следует использовать C-x n w (widen). (@xref{Сужение, , ,@external{emacs}, Руководство по GNU Emacs}, для получения детальной
информации.)
Помимо предоставления команды визуализации структуры документа,
texinfo-show-structure, режим Texinfo устанавливает значение
переменной разделителя страницы таким образом, чтобы она соответствовала
@-командам уровня глав. Это дает вам возможность использовать команды
C-x ] (forward-page) и C-x [ (backward-page)
для перемещения вперед и назад по главам, а команду C-x p
(narrow-to-page) -- для сужения до главы. @xref{Страницы, , , @external{emacs}, Руководство по GNU Emacs}, для получения
дополнительной информации.
В режиме Texinfo доступны команды для автоматического создания или
обновления меню и указателей на ноды. Эти команды называются
"update"-командами (командами обновления), потому что их основное
применение -- обновление Texinfo-файла после его редактирования; но вы
можете использовать их, чтобы вставить указатели `Next', `Previous' и
`Up' в строку @node, если их там еще нет, или создать меню в
файле, в котором его пока нет.
Если вы не пользуетесь командами обновления, то вам придется набирать меню и указатели на ноды вручную, а это утомительное занятие.
Вы можете использовать следующие команды обновления, чтобы
Вы можете использовать эти команды для обновления всех нод и меню в выделенной области или во всем Texinfo-файле.
Команды обновления работают только со стандартными Texinfo-файлами,
которые имеют такую же структуру, как и книги. В таких файлах, строка с
командой, объявляющей начало раздела, должна следовать сразу после
каждой строки @node, если только это не строка @node для
ноды `Top'. (Строка с командой описания структуры глав -- это
строка, начинающаяся с @chapter, @section или с другой
подобной команды.)
Вы можете вставить строку с командой описания структуры глав либо вслед
за строкой @node, либо в строке, которая следует после одиночной
строки комментария @comment, либо после одиночной строки
@ifinfo. Вы не можете вставить между строкой @node и
строкой с командой описания структуры глав больше одной строки; и
вставить вы можете только строку @comment или строку
@ifinfo.
Команды, которые действуют на весь текст в буфере, требуют, чтобы вслед
за нодой `Top' следовала нода с командой @chapter или с
эквивалентной по уровню командой. Команды обновления меню не будут
создавать основное или главное меню для Texinfo-файла, который имеет
ноды только уровня @chapter! Команды обновления меню создают
меню только внутри нод для нод более низкого уровня. Чтобы
создать меню глав, вы должны предоставить ноду `Top'.
Команды обновления меню удаляют пункты меню, которые относятся к другим Info-файлам, так как они не относятся к внутренним нодам текущего буфера. Это недостаток этих команд. Вместо пунктов меню вы можете использовать перекрестные ссылки на другие Info-файлы. Ни одна из команд обновления не затрагивает перекрестные ссылки.
В режиме Texinfo существует пять наиболее часто используемых команд
обновления: две из них -- для обновления всех указателей нод или меню в
пределах одной ноды; две -- для обновления всех указателей нод или меню
во всем файле; и одна команда, texinfo-master-menu, предназначена
для создания основного или главного меню для всего файла и (что не
является обязательным свойством этой команды) для обновления каждой ноды
и каждого меню во всем Texinfo-файле.
Команда texinfo-master-menu является основной
командой:
texinfo-master-menu требуется, чтобы
Texinfo-файл содержал ноду `Top' и по крайней мере еще одну уровнем
ниже.
После обширного редактирования Texinfo-файла вы можете ввести следующую
команду:
C-u M-x texinfo-master-menu или C-u C-c C-u mЭта команда полностью обновляет все ноды и меню за один проход.
Остальные основные команды обновления выполняют работу меньшего объема и предназначены для человека, который обновляет ноду и меню в процессе создания Texinfo-файла.
Далее перечислены оставшиеся основные команды обновления:
@node).
Если указатели `Next', `Previous' и `Up' уже были в строке
@node, то старые указатели удаляются и на их место помещаются
обновленные. При запуске этой команды с аргументом (с префиксным
аргументом, C-u, при интерактивном вызове), команда действует на
все строки @node в выделенной области.
texinfo-make-menu обновляет существующее меню,
описания из этого меню включается в новое. Это достигается с помощью
копирования описаний пунктов существующего меню в те пункты нового меню,
которые имеют те же имена нод. Если пункты меню различаются, то
описания в новое меню не копируются.
texinfo-all-menus-update
обновляет его; но она не создает новое главное меню, если его не
существует. (Для этого используйте команду
texinfo-master-menu.)
При работе над документом, в котором главное меню не нужно, можно
сделать следующее:
C-u C-c C-u C-a или C-u M-x texinfo-all-menus-updateЭто модифицирует все ноды и меню.
Переменная texinfo-column-for-description определяет позицию, по
которой выровнены описания меню. По умолчанию она равна 32, хотя часто
бывает полезно уменьшить ее до 24. Вы можете установить эту переменную
с помощью команды M-x edit-options, (@xref{Edit Options, , Editing Variable Values, @external{emacs}, Руководство по GNU Emacs})
или с помощью команды M-x set-variable (@xref{Examining, , Examining and Setting Variables, @external{emacs}, Руководство по GNU
Emacs}).
Также, команда texinfo-indent-menu-description может
использоваться, чтобы выровнять существующие описания меню по
определенной позиции. И наконец, если вы пожелаете, то вы можете
использовать команду texinfo-insert-node-lines, чтобы вставить в
файл недостающие строки @node. (See section Другие команды обновления, для дополнительной информации.)
Чтобы использовать команды обновления, вы должны организовать Texinfo-файл иерархически, с главами, разделами, подразделами и так далее. Когда вы создаете иерархию руководства, не `спускайтесь' больше чем на один уровень за один раз: вслед за нодой `Top' должна начинаться глава, и ни в коем случае не раздел; вслед за главой следует раздел, но не подраздел. Однако, вы можете за один раз "подняться" на любое число уровней, например от подраздела до главы.
Каждая строка @node за исключением строки для ноды `Top'
должна сопровождаться строкой с командой структурирования вроде
@chapter, @section или @unnumberedsubsec.
Каждая комбинация (строка @node)/(строка команды
структурирования) должна выглядеть подобно этой:
@node Комментарии, Минимум, Соглашения, Обзор @comment node-name, next, previous, up @section Комментарии
Или подобно этой (без строки @comment):
@node Комментарии, Минимум, Соглашения, Обзор @section Комментарии
В этом примере, `Комментарии' -- это имя и ноды, и раздела. Следующая
нода называется `Минимум', а предыдущая называется `Соглашения'. Раздел
`Комментарии' находится внутри ноды `Обзор', которая определена как
указатель`Up'. (Вместо строки @comment вы можете также вписать
строку @ifinfo.)
Если файл имеет ноду `Top', то она должна назваться `top' или `Top' и быть первой нодой в файле.
Команды обновления меню создают меню разделов внутри главы, меню подразделов внутри раздела и так далее. Это означает, что если вы хотите получить меню глав, у вас должна быть нода `Top'.
Команда @command{makeinfo} может создать Info-файл из иерархически
организованного Texinfo-файла, в котором отсутствуют указатели `Next',
`Previous' и `Up'. Как следствие этого, если вы уверены, что ваш
Texinfo-файл будет отформатирован с помощью @command{makeinfo}, команды
обновления меню вам не нужны. (See section Создание Info-файла, для более
детальной информации о makeinfo.) Однако, и @command{makeinfo},
и команды texinfo-format-... требуют, чтобы вы вставили в
файл меню.
Кроме пяти основных команд обновления, режим Texinfo дает доступ к несколько менее часто используемым командам обновления:
@node перед @chapter @section,
и другими командами структурирования, если они отсутствуют.
При запуске с аргументом (с префиксным аргументом, C-u, при
интерактивном вызове), команда texinfo-insert-node-lines не
только вставляет строки @node, но также вставляет и названия
глав или разделов в качестве имен соответствующих нод. Кроме того, она
вставляет названия в качестве имен нод в уже существующие строки
@node, не имеющие имен. Так как имена нод должны быть более
краткими, чем названия разделов или глав, вы должны вручную
отредактировать вставленные имена.
Например, для того, чтобы выделить весь буфер и везде вставить строки
@node и названия, следует сделать это:
C-x h C-u M-x texinfo-insert-node-linesЭта команда вставляет в качестве имен нод в строках
@node
названия разделов; команда texinfo-start-menu-description
(see section Быстрая вставка часто используемых команд.)
вставляет названия как описания пунктов меню -- это разные действия.
Однако в обоих случаях вы должны отредактировать вставленный текст.
texinfo-multiple-files-update описана в приложении о
включаемых файлах.
See section texinfo-multiple-files-update.
texinfo-indent-menu-description выравнивает каждое описание в
каждом меню в выделенной области. Однако, эта команда не выравнивает
вторые и последующие строки многострочного описания.
texinfo-sequential-node-update
последовательно обновляет все ноды в области.
Режим Texinfo обеспечивает отдельные команды для форматирования части или всего Texinfo-файла для Info. Часто, когда вы пишете документ, вы хотите отформатировать только часть файла -- то есть некую область.
Вы можете использовать команду texinfo-format-region или
makeinfo-region, чтобы отформатировать область:
Вы можете использовать команду texinfo-format-buffer или
makeinfo-buffer для того, чтобы отформатировать весь буфер:
Например, после создания Texinfo-файла вы можете набрать следующее:
C-u C-c C-u m или C-u M-x texinfo-master-menu
Это модифицирует все ноды и меню. Затем наберите следующее, чтобы создать Info-файл:
C-c C-m C-b или M-x makeinfo-buffer
Для того, чтобы могли работать TeX или команды форматирования для
Info, в заголовке файла должна быть строка @setfilename.
See section Создание Info-файла, для более подробного описания форматирования для Info.
Набор и печать Texinfo-файла -- процесс многоступенчатый, в котором вы
сначала создаете файл для печати (называемый DVI-файлом) и затем
печатаете его. Кроме того, вы можете также создавать именные указатели.
Чтобы сделать это, вы должны выполнить команду @command{texindex} после
первичного выполнения команды @command{tex}; а затем выполнить команду
@command{tex} снова. Или следует выполнить команду @command{texi2dvi},
которая сама автоматически создает именные указатели.
(see section Форматирование с помощью texi2dvi).
Часто, когда вы пишете документ, вы хотите вывести на печать только
часть файла, чтобы увидеть, как она будет выглядеть. Для этой цели вы
можете использовать команду texinfo-tex-region или похожие
команды. Используйте команду texinfo-tex-buffer, чтобы
отформатировать весь буфер.
texinfo-tex-region. Команда texinfo-tex-region не
запускает @command{texindex} автоматически; она только выполняет команду
@command{tex}. Вы должны запустить команду texinfo-tex-region во
второй раз после сортировки необработанного именных указателей командой
@command{texindex}. (Обычно, когда форматируют область, именные
указатели не формируют; это делается только для всего буфера. Сейчас,
когда существует команда @command{texi2dvi}, обсуждаемая команда
практически не нужна.)
texinfo-tex-buffer или texinfo-tex-region.
Для того, чтобы команда texinfo-tex-region или
texinfo-tex-buffer сработала, файл должен начинаться со
строки `\input texinfo' и должен включать строку @settitle.
Файл должен заканчиваться командой @bye, набранной в отдельной
строке. (Когда вы используете команду texinfo-tex-region, вы
должны окружить @settitle строками start-of-header и
end-of-header.)
See section Форматирование и печать твердой копии, для подробного описания других команд для TeX, вроде
tex-show-print-queue.
Каждый набор команд режима Texinfo имеет привязки по умолчанию, начинающиеся с одних ключей. Все команды, созданные специально для режима Texinfo, начинаются с C-c. Ключи отчасти мнемонические.
Команды вставки вызываются с помощью набора двух C-c и затем первого символа вставляемой @-команды. (Вероятно правильнее было бы для мнемоничности использовать C-c C-i, от `custom insert', но C-c C-c набирается гораздо быстрее.)
C-c C-c c Вставить `@code'.
C-c C-c d Вставить `@dfn'.
C-c C-c e Вставить `@end'.
C-c C-c i Вставить `@item'.
C-c C-c n Вставить `@node'.
C-c C-c s Вставить `@samp'.
C-c C-c v Вставить `@var'.
C-c C-c { Вставить фигурные скобки.
C-c C-c ]
C-c C-c } Перейти за пределы огражденного скобками участка.
C-c C-c C-d Вставить название раздела для ноды
в месте для описания в пункте меню.
Команда texinfo-show-structure часто используется внутри суженной
области.
C-c C-s Перечислить все заголовки.
Команда texinfo-master-menu создает главное меню; может
использоваться для того, чтобы модифицировать каждую ноду и каждое меню
в файле.
C-c C-u m M-x texinfo-master-menu
Создать или обновить главное меню.
C-u C-c C-u m С C-u в качестве префиксного
аргумента, сначала создать или обновить
все ноды и обычные меню, а затем
создать главное меню.
Команды обновления указателей вызываются при наборе C-c C-u и
затем или C-n для texinfo-update-node, или C-e для
texinfo-every-node-update.
C-c C-u C-n Обновить ноду. C-c C-u C-e Обновить все ноды в буфере.
Команды обновления меню вызываются при наборе C-c C-u, и затем или
C-m для texinfo-make-menu, или C-a для
texinfo-all-menus-update. Чтобы обновить и ноды, и меню в одно и
то же время, перед набором командной последовательности C-c C-u
C-a наберите C-u.
C-c C-u C-m Создать или обновить меню.
C-c C-u C-a Создать или обновить все
меню в буфере.
C-u C-c C-u C-a С префиксным аргументом C-u,
сначала создать или обновить все ноды,
а затем создать или обновить все меню.
Команды форматирования для Info, которые написаны на языке Emacs Lisp, вызываются при наборе C-c C-e и затем или C-r для выделенной области, или C-b для всего буфера.
Команды форматирования для Info, которые написаны на Си и основаны на программе @command{makeinfo}, вызываются при наборе C-c C-m и затем или C-r для выделенной области, или C-b для всего буфера.
Использование команды texinfo-format...:
C-c C-e C-r Форматировать область. C-c C-e C-b Форматировать буфер.
Использование @command{makeinfo}:
C-c C-m C-r Форматировать область. C-c C-m C-b Форматировать буфер. C-c C-m C-l Обновить выходной буферmakeinfo. C-c C-m C-k Прекратить выполнениеmakeinfo.
Команды набора и печати через TeX вызываются при наборе
последовательности C-c C-t и затем другой управляющей
последовательности: C-r для texinfo-tex-region, C-b
для texinfo-tex-buffer и так далее.
C-c C-t C-r Выполнить TeX для области.
C-c C-t C-b Выполнить @command{texi2dvi} для буфера.
C-c C-t C-i Выполнить @command{texindex}.
C-c C-t C-p Напечатать DVI-файл.
C-c C-t C-q Показать очередь заданий на принтер.
C-c C-t C-d Удалить задание из очереди заданий на принтер.
C-c C-t C-k Прекратить выполнение команды форматирования в TeX.
C-c C-t C-x Выйти из приостановленного задания
форматирования в TeX.
C-c C-t C-l Обновить выходной буфер.
Для вызова остальных команд обновления нет стандартных ключей, потому что они используются редко.
M-x texinfo-insert-node-lines
Вставить пропущенные строки @node
в области. С префиксным аргументом C-u,
использует названия разделов, как имена нод.
M-x texinfo-multiple-files-update
Обновить документ, состоящий из нескольких файлов.
С префиксным аргументом C-u 2, создать или
обновить все ноды или меню во всех файлах документа.
M-x texinfo-indent-menu-description
Выровнять описания.
M-x texinfo-sequential-node-update
Вставить указатели на ноды в строгой
последовательности.
В начале Texinfo-файла должна предоставляться определенная информация, вроде имени файла и названия документа.
Обычно начальная информация Texinfo-файла состоит из четырех частей:
@ifinfo и @end ifinfo, чтобы программа форматирования
поместила это сообщение в Info-файл.
@titlepage и @end
titlepage. Титульный лист и страница с информацией об авторских правах
появляется только при печати руководства. Также, по желанию вы можете включить условия распространения и отказ от предоставления гарантий для программы. Информация об условиях распространения и гарантиях обычно следует за введением или включается в первую главу руководства.
Так как текст сообщения об авторских правах и условий распространения для документа Texinfo (в отличие от условий распространения для программы) находится в частях, которые появляется либо только в Info-файле, либо только в печатном руководстве, эту информацию следует дублировать.
В следующем примере показано что следует вставить в начало Texinfo-файла.
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename имя-texinfo-файла
@settitle название-руководства
@setchapternewpage odd
@c %**end of header
@ifinfo
Этот файл описывает ...
(C) обладатель авторских прав, год
Предоставляется разрешение ...
@end ifinfo
@c Этот пример иллюстрирует только один из
@c двух методов формирования титульного листа.
@titlepage
@title название-печатного-руководства
@subtitle подзаголовок-если-нужен
@subtitle второй-подзаголовок
@author автор
@c Со следующих двух команд начинается страница
@c с информацией об авторских правах.
@page
@vskip 0pt plus 1filll @copyright{} год
обладатель авторских прав
Опубликовано ...
Предоставляется разрешение ...
@end titlepage
@node Top, Обзор, , (dir)
@ifinfo
В этом документе описывается ...
Этот документ соответствует версии ...
программы ...
@end ifinfo
@menu
* Авторские права:: Ваши права и возможности.
* Первая глава:: Начало ...
* Вторая глава:: ...
...
...
@end menu
@node Первая глава, Вторая глава, top, top
@comment node-name, next, previous, up
@chapter Первая глава
@cindex Вхождения именных указателей для первой главы
Texinfo-файл начинается по крайней мере с трех строк, которые
предоставляют необходимую информацию для Info и TeX. Это строка
\input texinfo, строка @settitle и строка
@setfilename. Если вы хотите, чтобы TeX отформатировал
только часть Texinfo-файла, вы должны вставить строки @settitle
и @setfilename между строк start-of-header и end-of-header.
Таким образом, начало Texinfo-файла выглядит так:
\input texinfo @c -*- texinfo -*- @setfilename пример.info @settitle Пример оформления документа
или так:
\input texinfo @c -*- texinfo -*- @c %**start of header @setfilename Пример.info @settitle Пример оформления документа @c %**end of header
Каждый Texinfo-файл, если его предполагается обрабатывать с помощью низкоуровневых процедур форматирования TeX, должен начинаться со строки подобной этой:
\input texinfo @c -*- texinfo -*-
Эта строка служит для двух целей:
Вставьте строку start-of-header второй строкой в Texinfo-файле. За
строкой start-of-header следуют строки, начинающиеся с команд
@setfilename и @settitle, а иногда с команд
@smallbook или @footnotestyle. Заголовок замыкается
строкой end-of-header (see section Окончание заголовка).
С помощью этих строк вы можете форматировать часть Texinfo-файла для Info или для выдачи на печать.
Строка start-of-header выглядит следующим образом:
@c %**start of header
Странная последовательность знаков `%**' должна гарантировать, что никакой другой комментарий не будет случайно перепутан с первой строкой заголовка.
@setfilenameЧтобы Texinfo-файл можно было отформатировать с помощью @command{makeinfo} или TeX, он должен содержать следующую строку:
@setfilename имя-info-файла
Команду @setfilename следует вставлять в начале строки, затем
нужно вставить имя Info-файла. Не следует писать на этой строке
что-либо еще; все, что следует после этой команды, рассматривается как
имя Info-файла, даже то, что в ином другом случае воспринималось бы как
комментарий.
Строка @setfilename определяет имя создаваемого при
форматировании выходного файла. Это имя должно отличаться от имени
Texinfo-файла. Существуют два соглашения для выбора имени файла, вы
можете или удалить из имени файла расширение (такое как `.texi'),
или заменять расширение на `.info'. При создании HTML-файлов
@command{makeinfo} заменяет любое расширение на `html' или
добавляет `.html', если у заданного файла нет расширения.
Некоторые операционные системы не поддерживают длинные имена файлов. У вас могут возникнуть проблемы даже тогда, когда имя файла достаточно коротко. Это происходит, потому что программа форматирования Info-файлов разбивает длинный файл на более короткие и дает им имена путем добавления в конец префиксов `-1', `-2', ..., `-10', `-11' и так далее. (See section Создание тегов и разбиение файлов.) Таким образом получаются имена файлов вроде `texinfo.info-10', которые для некоторых систем являются слишком длинными; так что подобные файлы лучше назвать `texinfo', а не `texinfo.info'. Когда программа @command{makeinfo} выполняется на операционных системах вроде MS-DOS, которые налагают серьезные ограничения на длину имен файла, то она иногда будет укорачивать первоначальное имя файла, чтобы обеспечить для суффиксов достаточно места, производя таким образом файлы с названиями вроде `texin-10', `gcc.i12' и так далее.
Команды форматирования для Info игнорируются, если они находятся перед
строкой @setfilename, именно поэтому самая первая строка в файле
(строка \input) не появляется при выводе.
Строка @setfilename не производит никакого вывода при
форматировании руководства с помощью TeX, но несмотря на это она
необходима: она открывает вспомогательные файлы для именных указателей,
перекрестных ссылок и другие вспомогательные файлы, используемые
Texinfo, а также считывает файл `texinfo.cnf', если он присутствует
в системе (see section Подготовка к применению TeX).
@settitleЧтобы из Texinfo-файла можно было создать печатное руководство, он должен содержать следующую строку:
@settitle Заголовок
Команда @settitle вставляется в начале строки, а за ней на этой
же строке следует заголовок. Она сообщает TeX заголовок, который
следует печатать вверху и внизу страницы. Больше в этой строке ничего
писать не следует; все что находится в этой строке, даже комментарий,
становится заголовком.
По традиции, когда TeX форматирует Texinfo-файл для двусторонней
печати, заголовок печатается вверху на левых (четных) страницах, а
название текущей главы -- вверху на правых (нечетных) страницах.
(TeX получает название каждой главы из команды @chapter).
Внизу страницы ничего не печатается.
Даже если вы печатаете в одностраничном стиле, TeX ищет строку с
командой @settitle, если вы включаете название документа в
заголовок.
Команда @settitle должна предшествовать всему, что производит
действительный вывод в TeX.
Хотя заголовок в команде @settitle обычно тот же самый, что и
заголовок на титульном листе, это никак не влияет на то, что печатается
на титульном листе. Таким образом, эти два заголовка не обязаны
совпадать; заголовок в команде @settitle может быть сокращенной
или расширенной версией названия, печатаемого на титульном листе.
(See section @titlepage.)
TeX печатает заголовки страниц только для того текста, который
следует в Texinfo-файле после команды @end titlepage или
находится после команды @headings, которая включает печать
заголовков. See section Команда @headings, для
более детальной информации.
Вы также можете, если желаете, создать ваши собственные заголовки страниц. Для более детальной информации смотрите section Заголовки страниц.
@setchapternewpageВ официально изданной книге текст обычно печатается на обеих сторонах бумаги, главы начинаются на правых страницах, и правые страницы имеют нечетные номера. Но в коротких докладах текст часто печатается только на одной стороне бумаги. Также в коротких докладах главы иногда не начинаются на новых страницах, а печатаются на той же самых странице, где был конец предшествующей главы, и отделяются от него небольшим вертикальным отступом.
Вы можете использовать команду @setchapternewpage с различными
аргументами, чтобы определить, как TeX должен начинать главы и должен
ли он форматировать текст для печати на одной или на обеих сторонах
бумаги (односторонняя или двусторонняя печать).
Пишите команду @setchapternewpage в начале строки, далее
добавьте соответствующий аргумент.
Например, вы хотите, чтобы все главы начинались с новой нечетной страницы:
@setchapternewpage odd
С помощью команды @setchapternewpage вы можете выбрать одну из
трех альтернатив:
@setchapternewpage off
@headings double. Для
дополнительной информации смотрите section Команда @headings.)
@setchapternewpage on
@setchapternewpage odd
В Texinfo нет команды @setchapternewpage even.
Вы можете переопределить или изменить действие команды
@setchapternewpage на заголовки с помощью команды
@headings. See section Команда @headings.)
В начале руководства или книги страницы не нумеруются; например, в книгах не нумеруются титульный лист и страница с информацией об авторских правах. В соответствии с соглашениями страницы содержания нумеруются римскими цифрами и выпадают из нумерации остальной части документа.
Так как Info-файл не имеет страниц, то команда
@setchapternewpage не влияет на него.
Мы рекомендуем вообще не включать команду @setchapternewpage в
исходный текст вашего руководства, так как желаемый вывод не
определяется внутренне документом. Вместо этого, если вам не нравится
вариант по умолчанию (нет пустых строк, на всех страницах одинаковые
заголовки), используйте ключ @option{--texinfo} для команды
@command{texi2dvi}, чтобы указать, какой вывод вы хотите.
Texinfo-процессоры могут вставить несколько пробелов перед началом
абзаца в первой его строке, выделяя таким образом этот абзац. Вы можете
использовать команду @paragraphindent, чтобы определить величину
отступа. Пишите команду @paragraphindent в начале строки,
сопровождая ее параметром `asis' или числом, как здесь:
@paragraphindent отступ
Отступ делается в соответствии со значением числа отступ:
asis
Значение переменной отступ по умолчанию равно `asis'.
@paragraphindent игнорируется при выводе в формате HTML.
Вставляйте команду @paragraphindent перед или вскоре после
строки end-of-header в начале Texinfo-файла. (Если вы вставите команду
между строк start-of-header и end-of-header, то команды форматирования
области будут делать для абзацев указанный отступ.)
Особенность команд texinfo-format-buffer и
texinfo-format-region в том, что они не делают отступ (и не
заполняют текст) в тех абзацах, которые содержат команды @w или
@*. See section Перезаполнение абзацев, для получения дальнейшей
информации.
@exampleindent: отступы в блоках
Texinfo-процессоры делают отступ в каждой строке блоков @example
и подобных ему. Для задания этого отступа вы можете использовать
команду @exampleindent. Пишите команду @exampleindent
на отдельной строке, а после нее указывайте число или `asis':
@exampleindent отступ
Отступ делается в соответствии со значением параметра отступ:
asis
Значение отступа по умолчанию равно пяти. @exampleindent
игнорируется при выводе в HTML.
Пишите команду @exampleindent перед или немного после строки,
end-of-header, завершающей заголовок Texinfo-файла. (Если вы напишете
эту команду между строк start-of-header и end-of-header, команды
форматирования области будут делать в примерах указанный отступ.)
Заканчивайте заголовок строкой end-of-header. Эта строка выглядит следующим образом:
@c %**end of header
Если в заголовке файла, между строк start-of-header и end-of-header, вы
вставляете команду @setchapternewpage, TeX будет
форматировать область в соответствии с этой командой. Точно так же,
если вы включаете между строк start-of-header и end-of-header команду
@smallbook, TeX будет форматировать область в формате
"маленькая книга".
See section Начало заголовка.
Титульный лист и страница с информацией об авторских правах появляются только в печатной копии руководства; поэтому та же самая информация должна быть вставлена в секцию, которая появляется только в Info-файле. Эта секция обычно содержит краткое описание содержания Info-файла, уведомление об авторских правах и правах на распространение.
Уведомление об авторских правах должно выглядеть так:
(C) обладатель-авторских-прав, год
и находиться на отдельной строке.
Стандартный текст уведомления содержится в приложении к этому руководству; смотрите section Разрешения на копирование для Info, для получения полной версии текста.
Текст условий распространения появляется в Info-файле перед первой нодой. Это означает, что читатель не видит этот текст при чтении файла с использованием Info, если только он не использует продвинутую команду Info g*.
Название руководства и имя автора обычно печатаются на титульном листе.
Иногда на титульном листе также печатается информация об авторских правах; обычно же информация об авторских правах печатается на обратной стороне титульного листа. Титульный лист и страница с информацией об авторских правах появляются в печатном руководстве, но не в Info-файле. Из-за этого возможно использование некоторых малопонятных команд TeX, которые не могут использоваться в Info-файле. Кроме того, эта часть начала Texinfo-файла содержит текст условий распространения, который появится в печатном руководстве.
Вы можете захотеть включить информацию вида титульного листа в вывод в
простом текстовом формате. Просто поместите любой такой начальный
материал между @ifinfo и @end ifinfo; @command{makeinfo}
включит его в простой текстовый вывод. Этого не будет видно в
программах чтения Info.
See section Разрешение на копирование на титульном листе, стандартный текст условий распространения.
@titlepage
Начинайте материал для титульного листа и последующей страницы с
информацией об авторских правах с команды @titlepage, занимающей
всю первую строку, и заканчивайте строкой с командой @end
titlepage.
Команда @end titlepage, начинает новую страницу и включает
нумерацию страниц. (See section Заголовки страниц, для
дополнительной информации). Весь материал, который вы хотите разместить
на ненумерованных страницах, должен быть помещен между командами
@titlepage и @end titlepage. Вы можете создать в этом
месте содержание с помощью команды @setcontentsaftertitlepage
(see section Создание содержания).
Используйте команду @page, чтобы вставить в пределах области,
очерченной командами @titlepage и @end titlepage, разрыв
страницы и создать таким образом больше одной ненумерованной страницы.
Так как создается страница с информацией об авторских правах. (Вероятно
команду @titlepage лучше было бы назвать
@titleandadditionalpages, но это слишком длинно!)
Когда вы пишете руководство по компьютерной программе, вы должны указать
на титульном листе версию программы, к которой применимо данное
руководство. Если руководство изменяется чаще, чем программа, или
независимо от нее, вы должны также включить номер редакции(5). Это
помогает читателям понимать, которое руководство для какой версии
программы. (Первая нода также должна содержать эту информацию; смотрите
section @top.)
Texinfo предоставляет два основных метода для создания титульного листа.
Один метод использует команды @titlefont, @sp и
@center, чтобы создать титульный лист, в котором
слова на странице центрируется.
Второй метод использует команды @title, @subtitle и
@author, чтобы создать титульный лист с черными линейками под
названием и именем автора и текстом подзаголовка, прижатыми к правому
краю страницы. При использовании этого метода, вы не определяете
никакого форматирования для титульного листа. Вы задаете желаемый
текст, а Texinfo делает форматирование.
Вы можете использовать один из методов или комбинировать их; смотрите последующие разделы.
Для чрезвычайно простых случаев
в Texinfo есть команда @shorttitlepage, которая принимает
единственный аргумент, название. Аргумент набирается на отдельной
странице, а затем следует чистая страница.
@titlefont, @center и @sp
Чтобы создать титульный лист для печатного документа, вы можете
использовать команды @titlefont, @sp и @center.
(Это первый из двух методов для создания титульного листа в
Texinfo.)
Используйте команду @titlefont, чтобы выбрать больший шрифт,
подходящий для названия. Вы можете использовать @titlefont
больше одного раза, если у вас особенно длинное название.
Например:
@titlefont{Texinfo}
Используйте команду @center в начале строки, чтобы
отцентрировать текст в этой строке. Например:
@center @titlefont{Texinfo}
центрирует название, которым в этом примере является "Texinfo", напечатанное шрифтом для названий.
Используйте команду @sp, чтобы вставить вертикальный пробел.
Например:
@sp 2
Это вставляет две незаполненные строки на напечатанной странице.
(See section @sp n: Вставка пустых строк, более подробную информацию о команде
@sp.)
Шаблон для этого способа выглядит так:
@titlepage
@sp 10
@center @titlefont{имя-руководства-при-печати}
@sp 2
@center подзаголовок-если-есть
@sp 2
@center автор
...
@end titlepage
Промежутки в примере такие, что текст вмещается на странице формата 8.5 на 11 дюймов.
@title, @subtitle и @author
Вы можете использовать команды @title, @subtitle и
@author для создания титульного листа, в котором вертикальный и
горизонтальный интервал делаются для вас автоматически. Это отличается
от метода, описанного выше, в котором команда @sp является
необходимой для настройки вертикальных пропусков.
Пишите команды @title, @subtitle и @author в
начале строки, далее за ними в этих же строках должны следовать
заголовок, подзаголовок и автор, соответственно.
Команда @title создает строку, в которой название прижимается к
левому краю страницы и печатается более крупным, чем обычно, шрифтом.
Название подчеркивается черной линейкой. Допустима только одинарная
строка; нельзя использовать команду @*, чтобы разбить название
на две строки. Чтобы иметь возможность работать с длинными названиями,
вам может показаться полезным использовать обе команды @title и
@titlefont; смотрите заключительный пример в этом разделе.
Команда @subtitle набирает подзаголовок шрифтом обычного размера
и прижимает его к правому краю страницы.
Команда @author печатает шрифтом среднего размера имя автора или
авторов в левой части страницы недалеко от нижнего края титульного
листа. Имена подчеркиваются черной линейкой, которая тоньше, чем та,
что подчеркивает заголовок. (Черная линейка появляется только в том
случае, если вслед за строкой команды @author следует строка
команды @page.)
Есть два способа применения команды @author: вы можете ввести
имя или имена на остающейся части строки, которая начинается с
@author:
@author Джейн Смит и Джон До
или вы можете ввести имена одно над другим, используя две (или больше)
команды @author:
@author Джейн Смит @author Джон До
(Только нижнее имя подчеркивается черной линейкой.)
Шаблон для этого метода выглядит так:
@titlepage @title имя-руководства-при-печати @subtitle подзаголовок-если-есть @subtitle второй-подзаголовок @author автор @page ... @end titlepage
Вы можете также комбинировать метод @titlefont, описанный в
предыдущем разделе и метод @title, описанный в этом. Это может
быть полезно, если у вас есть очень длинное название. Вот пример из
реальной жизни:
@titlepage
@titlefont{GNU Software}
@sp 1
@title for MS-Windows and MS-DOS
@subtitle Edition @value{edition} for Release @value{cd-edition}
@author by Daniel Hagerty, Melissa Weisshaus
@author and Eli Zaretskii
(Такое использование @value объясняется в section Пример применения @value.)
В соответствии с международным соглашением, текст уведомления об авторских правах для книги должен находиться или на титульном листе, или на обратной стороне титульного листа. Текст этого уведомления должен включать год и название организации или имя человека, кому принадлежат авторские права.
Когда текст авторского права печатается на обратной стороне титульного
листа, эта страница обычно не нумеруется. Значит, текст уведомления об
авторских правах должен писаться в Texinfo между команд
@titlepage и @end titlepage.
Используйте команду @page, чтобы разорвать страницу. Для того,
чтобы сдвинуть текст уведомления об авторских правах и остальной текст
на странице с информацией об авторских правах, вы можете написать после
команды @page несколько таинственную строку, выглядящую так:
@vskip 0pt plus 1filll
Это команда TeX, которая не поддерживается командами форматирования
для Info. Команда @vskip вставляет вертикальный пропуск.
Команда `0pt plus 1filll' заставляет TeX создать такой
вертикальный пропуск, чтобы сместить последующий текст к нижнему краю
страницы. Обратите внимание на использование трех `l' в слове
`filll', это правильно в TeX.
В печатном руководстве команда @copyright{} создает знак
охраны авторских прав -- `c' внутри круга. (В Info этот знак
воспроизводится как `(C)'.) Уведомление об авторских правах имеет
официально утвержденную форму записи:
(C) обладатель-авторских-прав, год
Принято помещать информацию о том, как получить руководство, сразу после уведомления об авторских правах перед разрешением на распространение руководства.
Разрешение на распространение должно быть записано здесь, а так же в
сегменте обзора между @ifinfo и @end ifinfo сразу после
заголовка, так как этот текст появляется только в печатном руководстве,
а текст из блока `ifinfo' появляется только в Info-файле.
See section Пример разрешений, стандартный текст разрешений.
Команда @end titlepage, занимающая целую строку, не только
отмечает конец титульного листа и страницы с информацией об авторских
правах, но и заставляет TeX создавать заголовки и номера страниц.
Как уже было сказано, Texinfo имеет два стандартных формата заголовков
страниц, один для документов, которые печатаются на одной стороне
каждого листа бумаги (односторонняя печать), и другой для документов,
которые печатаются с обеих сторон каждого листа (двусторонняя печать).
(See section @setchapternewpage.) Вы можете
задать эти форматы различными способами:
@setchapternewpage до команд титульного листа и затем написать
команду @end titlepage, с которой уже начнется создание
заголовков страниц в желаемом вами стиле. (See section @setchapternewpage.)
@headings, чтобы
предотвратить создание заголовков страниц или начинать их создание для
или односторонней или двусторонней печати. (Пишите команду
@headings сразу после команды @end titlepage.
See section Команда @headings, для дополнительной
информации.)
Большинство документов форматируются в стандартном одностороннем или
двустороннем формате. Для печати в двустороннем формате используется
команда @setchapternewpage odd, а односторонняя печать
производится, если команда @setchapternewpage не задана.
@headings
Команда @headings используется редко. Она задает вид верхних и
нижних заголовков страниц. Обычно этим управляет команда
@setchapternewpage. Команда @headings нужна вам только
в том случае, если команда @setchapternewpage делает не то, что
вам нужно, или если вы хотите выключить предопределенные заголовки
страниц до определения ваших собственных. Пишите команду
@headings сразу после команды @end titlepage.
Вы можете использовать @headings так:
@headings off
@headings single
@headings double
@headings on
@headings on и @headings double являются синонимами.
@headings singleafter
@headings doubleafter
single или double, соответственно,
после текущей выводимой страницы.
@headings on
single, если
`@setchapternewpage on', и double в противном случае.
Например, предположим, что вы вставили команду @setchapternewpage
off перед командой @titlepage, чтобы заставить TeX начинать
новую главу на той же самой странице, где закончилась предыдущая. Эта
команда также заставляет TeX набирать заголовки страниц для
односторонней печати. Чтобы TeX форматировал для двусторонней
печати, напишите после @end titlepage команду @headings
double.
Вы можете совсем запретить формирование заголовков страниц путем
вставки команды @headings off на отдельной строке сразу после
строки с командой @end titlepage, как показано:
@end titlepage @headings off
Команда @headings off перекрывает действие команды @end
titlepage, которая в противном случае заставила бы TeX печатать
заголовки страниц.
Также, вы можете задать собственный стиль верхних и нижних заголовков. See section Заголовки страниц, для более подробной информации.
Нода `Top' -- это нода, с которой вы входите в Info-файл.
Нода `Top' должна содержать краткое описание Info-файла и большое главное меню для доступа ко всему Info-файлу. Это помогает читателю понять, какая информация содержится в данном Info-файле. Кроме того, вы должны указать версию программы, к которой применим этот Info-файл, или по меньшей мере номер редакции Info-файла.
Содержимое ноды `Top' должно появляться только в Info-файле и не должно
печататься, поэтому заключайте его между команд @ifinfo и
@end ifinfo. (TeX не печатает ни строки @node, ни
меню; они появляются только в Info-файле. То есть, строго говоря, вам
не нужно заключать эти части их между команд @ifinfo и
@end ifinfo, но проще всего все же сделать это. See section Условно видимый текст.)
Иногда вам нужно будет вставить команду структурирования @top,
содержащую название документа, сразу после строки @node Top
(See section @top, для более детальной
информации).
Например, нода `Top' данного руководства содержит в начале команду
описания структуры глав @top, краткое описание, номер редакции
документа и версию программы. И все это выглядит следующим
образом:
... @end titlepage @ifnottex @node Top, Копирование, , (dir) @top Texinfo Texinfo --- это система документации... Это версия ... ... @end ifnottex @menu * Копирование:: Ваши права. * Обзор:: Коротко о Texinfo. ... @end menu
Указатели `Previous' и `Up' в ноде `Top' обычно ссылаются на каталог верхнего уровня всей системы Info, который называется `(dir)'. Нода `Next' ссылается на первую ноду, которая следует сразу за главным меню; обычно это разрешение на копирование, введение или первая глава.
Главное меню -- это подробное меню, содержащее ссылки на все ноды в файле.
Главное меню заключается между команд @menu и @end menu
и не появляется в печатном руководстве.
Как правило, главное меню делится на части.
@detailmenu перед первым пунктом и @end detailmenu после
последнего, иначе в работе @command{makeinfo} возникнут проблемы.
Каждая часть меню может быть представлена строкой описания. Если строка не начинается со звездочки, она не будет восприниматься как пункт меню. (See section Написание меню, для более детальной информации.)
Например, главное меню этого руководства выглядит следующим образом (но в нем гораздо больше пунктов):
@menu
* Копирование:: Ваши права.
* Обзор:: Коротко о Texinfo.
* Режим Texinfo:: Как использовать режим Texinfo.
...
...
* Указатель команд и переменных::
* Указатель понятий:: Меню, охватывающее все темы.
@detailmenu
--- Полный список нод ---
Обзор Texinfo
* Описание ошибок:: Посылка эффективных сообщений об
ошибках.
* Использование Texinfo:: Создание обычной печатной книги или
Info-файла.
...
...
Использование режима Texinfo
* Обзор режима Texinfo:: Как режим Texinfo может вам помочь.
...
...
@end detailmenu
@end menu
Если Texinfo-файл имеет раздел, содержащий "Универсальную Общественную Лицензию", разрешение на распространение и отказ от предоставления гарантий для документируемого программного обеспечения, этот раздел обычно следует после ноды `Top'. Универсальная Общественная Лицензия --- это юридический документ, который очень важен для программного обеспечения Проекта GNU. Он дает вам и другим людям уверенность в том, что право на использование и распространение данного программного обеспечения у вас не отнимут.
После информации о копировании и распространении и отказа от предоставления гарантий следует введение или первая глава руководства.
Хотя введение не является обязательной частью Texinfo-файла, присутствие
его в документе очень полезно. В идеальном случае во введении должно
быть кратко и ясно изложено, о чем рассказывается в данном Texinfo-файле
и кому он может быть интересен. Вообще говоря, введение следует после
информации о разрешениях на распространение, хотя иногда некоторые люди
помещают эту часть в документе раньше. Обычно введение помещается в
ненумерованном разделе (созданном командой @unnumbered).
(See section @unnumbered и @appendix.)
В конце Texinfo-файла должны быть команды для создания именных
указателей и (обычно) содержаний, подробного и обзорного. Он также
должен включать команду @bye, помечающую последнюю
обрабатываемую TeX строку.
Например:
@node Указатель понятий, ,Указатель переменных, Top @c имя-ноды, следующая, предыдущая, вверх @unnumbered Указатель понятий @printindex cp @contents @bye
Напечатать именной указатель -- значит включить его в руководство или
Info-файл. Это не делается автоматически, потому что в Texinfo-файле вы
используете команду @cindex или другие команды, создающие
вхождения именного указателя; они только собирают исходные данные для
создания указателя. Чтобы создать именной указатель, вы должны
поместить в том месте документа, где вы хотите его увидеть, команду
@printindex. Кроме этого, при создании печатного руководства вы
должны запустить программу, называемую @command{texindex}
(see section Форматирование и печать твердой копии), которая сортирует исходные данные и записывает
сортированный именной указатель в файл. Именно этот файл используется
для печати именного указателя.
В Texinfo предопределены шесть различных типов именных указателей: указатель понятий, указатель функций, указатель переменных, указатель клавиш, указатель программ и указатель типов данных (see section Предопределенные именные указатели). Каждый указатель имеет двухбуквенное имя: `cp', `fn', `vr', `ky', `pg' и `tp'. Вы можете объединить указатели или поместить их в разные разделы (see section Объединение именных указателей); вы также можете определить свои именные указатели (see section Определение новых именных указателей).
Команда @printindex принимает в качестве аргумента двухбуквенное
имя именного указателя, читает соответствующий файл с сортированным
указателем и форматирует указатель соответствующим образом.
Команда @printindex не создает заголовка главы для именного
указателя. Следовательно, перед командой @printindex вы должны
написать подходящую команду создания главы или раздела (обычно
@unnumbered), чтобы указатель имел заголовок и был упомянут в
содержании. Перед командой @unnumbered пишите строку
@node.
Например:
@node Указатель переменных, Указатель понятий, Указатель функций, Top @comment имя-ноды, следующая, предыдущая, вверх @unnumbered Указатель переменных @printindex vr @node Указатель понятий, , Указатель переменных, Top @comment имя-ноды, следующая, предыдущая, вверх @unnumbered Указатель понятий @printindex cp
Читателям нравится, когда указатель понятий расположен последним в
книге, потому что тогда его легче найти. Наличие только одного
указателя также помогает читателям, так как тогда них у есть только одно
место для поиска (see section @synindex)
Команды @chapter, @section и другие команды
структурирования предоставляют необходимые сведения для создания
содержания, но не приводят к действительному появлению содержания в
руководстве. Чтобы сделать его, вы должны использовать команды
@contents и/или @summarycontents.
@contents
@heading, не
появляются в содержании.)
@shortcontents
@summarycontents
@summarycontents -- синоним @shortcontents; две эти
команды совершенно одинаковы.)
Создают короткое или, иначе говоря, обзорное содержание, в котором
перечисляются только главы (и приложения, и ненумерованные главы).
Разделы, подразделы и подподразделы пропускаются. Короткое содержание
требуется только для больших руководств, в дополнение к полному
содержанию.
Обе команды для содержаний нужно писать на отдельной строке. Команды
для содержаний автоматически создают заголовок в начале первой страницы
содержания, поэтому не включайте перед ними никаких команд для описания
структуры глав, таких как @unnumbered.
Так как в Info-файлах вместо содержания используются меню, команды
форматирования для Info игнорируют команды для вывода содержаний. Но
содержания включаются в вывод в простом текстовом формате (создаваемом
командой makeinfo --no-headers).
Команды печати содержания можно помещать как в самом конце файла после
всех именных указателей (смотрите предыдущий раздел), непосредственно
перед командой @bye (смотрите следующий раздел), или недалеко от
начала файла, после @end titlepage (see section @titlepage).
Преимущество первого способа в том, что вывод содержания всегда
соответствует истине, потому что он отражает только что сделанные
изменения. Преимущество второго в том, что содержание печатается в
правильном месте, так что вам не нужно переорганизовывать DVI-файл или
перетасовывать бумагу. Однако команды для печати содержания в начале
документа игнорируются при выводе на стандартный вывод.
Как автор, вы можете поместить команды для печати содержания где вы
предпочитаете. Но если вы просто печатаете руководство, вы можете
пожелать напечатать содержание после титульного листа даже если автор
поместил команды для печати содержания в конец документа (как в случае
большинства существующих документов Texinfo). Вы можете сделать это
задав @setcontentsaftertitlepage и/или
@setshortcontentsaftertitlepage. Первое печатает только главное
содержание после @end titlepage; второе печатает и краткое, и
полное содержание. В любом случае любые последующие команды
@contents или @shortcontents игнорируются (если только
@end titlepage не была встречена вообще).
Вам нужно включать команды @set...contentsaftertitlepage в
начале документа (сразу после @setfilename, например). Или,
если вы пользуетесь @command{texi2dvi} (see section Форматирование с помощью @code{texi2dvi}), вы можете использовать его ключ @option{--texinfo} для
задания этого вообще без изменения исходного файла. Например:
texi2dvi --texinfo=@setshortcontentsaftertitlepage foo.texi
@bye Завершение файла
Команда @bye прекращает форматирование в TeX или Info. Все,
что следует в файле после команды @bye, невидимо для
форматирующих команд. Команда @bye должна находиться на
отдельной строке.
Вы можете, если хотите, писать заметки после строки @bye. Эти
заметки не будут форматироваться и не появятся ни в Info-файле, ни в
печатном руководстве, как если бы текст после @bye был помещен
внутри блока @ignore ... @end ignore. Вы также
можете написать после строки @bye список локальных переменных.
See section Использование списка локальных переменных, для подробных сведений.
Команды описания структуры глав разделяют документ на иерархию глав, разделов, подразделов и подподразделов. Эти команды создают большие заголовки, а также предоставляют сведения для составления содержания печатного руководства (see section Создание содержания).
Команды описания структуры глав не создают структуры Info-нод, поэтому
обычно вы должны помещать команду @node непосредственно перед
каждой командой описания структуры глав (see section Ноды). Единственный
случай, когда вы, вероятно, будете использовать команды описания
структуры глав, не описывая структуру нод, -- это если вы пишите
документ, не содержащий перекрестных ссылок, и который никогда не будет
преобразован в формат Info.
Вряд ли вам когда-нибудь придется писать Texinfo-файл, предназначенный только для чтения в виде Info-файла, но не печатного документа. Если же вам пришлось, все равно имеет смысл использовать команды описания структуры глав для создания заголовка в начале каждой ноды, но вам не обязательно это делать.
Обычно Texinfo-файл организован подобно книге с главами, разделами, подразделами и так далее. Такую структуру можно изобразить в виде дерева (или даже дерева, направленного сверху вниз) с корнем наверху и уровнями, соответствующими главам, разделам, подразделам и подподразделам.
Ниже приведена диаграмма, изображающая Texinfo-файл из трех глав, каждая из которых имеет два раздела.
Вершина
|
-------------------------------------
| | |
Глава 1 Глава 2 Глава 3
| | |
-------- -------- --------
| | | | | |
Раздел Раздел Раздел Раздел Раздел Раздел
1.1 1.2 2.1 2.2 3.1 3.2
В Texinfo-файле с такой структурой начало Главы 2 выглядит таким образом:
@node Глава 2, Глава 3, Глава 1, top @chapter Глава 2
Команды описания структуры глав рассмотрены в последующих разделах;
команды @node и @menu -- в последующих
главах. (See section Ноды, и section Меню.)
Команды описания структуры глав делятся на четыре группы или серии, каждая из которых содержит команды описания структур, соответствующих иерархическому уровню глав, разделов, подразделов и подподразделов.
Эти четыре группы составляют: серия @chapter, серия
@unnumbered, серия @appendix и серия @heading.
Каждая команда создает заголовки, выглядящие по-разному на напечатанной странице и в Info-файле; только некоторые команды создают заголовки, которые будут перечислены в содержании печатной книги или руководства.
@chapter и @appendix создает нумерованные
или перечисленные по буквам вхождения как в теле печатного произведения,
так и в его содержании.
@unnumbered создает ненумерованные вхождения как в
теле печатного произведения, так и в его содержании. Команда
@top, имеющая особое значение, является членом этой серии
(see section @top).
@heading создает ненумерованные заголовки, которые
не появляются в содержании. Команды создания заголовка никогда не
начинают новую страницу.
@majorheading дает результат, похожий на результат
применения команды @chapheading, но делает больший вертикальный
пропуск перед заголовком.
@setchapternewpage, то
@chapter, @unnumbered, и @appendix начинают
новую страницу в печатном руководстве; команда @heading не
начинает.Вот четыре группы команд описания структуры глав:
| Не начинают новую страницу | |||
| Нумерованные | Ненумерованные | Нумерованные или перечисленные по буквам | Ненумерованные |
| В содержании | В содержании | В содержании | Нет в содержании |
@top | @majorheading
| ||
@chapter | @unnumbered | @appendix |
@chapheading
|
@section | @unnumberedsec | @appendixsec |
@heading
|
@subsection | @unnumberedsubsec |
@appendixsubsec | @subheading
|
@subsubsection | @unnumberedsubsubsec |
@appendixsubsubsec | @subsubheading
|
@top
Команда @top -- это специальная команда, которую вы используете
после строки `@node Top' в начале Texinfo-файла. Команда
@top сообщает форматирующей программе @command{makeinfo}, какая
нода является нодой `Top', чтобы @command{makeinfo} могла использовать
эту ноду в качестве корневой, если в вашем руководстве применяются
неявные указатели. Ее результат при наборе такой же, как при применении
@unnumbered (see section @unnumbered и @appendix). Для подробной информации смотрите section Команда @top.
Нода @top и ее меню (если оно есть) обычно окружается в условную
конструкцию @ifnottex, чтобы они появлялись только при выводе в
выводе Info и HTML, но не TeX.
@chapter
Команда @chapter обозначает главу в документе. Пишите эту
команду в начале строки и за ней название главы на той же
строке.
Например, данная глава в этом руководстве озаглавлена
"Структура глав"; строка @chapter выглядит так:
@chapter Структура глав
В TeX, команда @chapter создает в документе главу и задает
название этой главы. Глава автоматически получает номер.
В Info, команда @chapter создает название на отдельной строке и
строку звездочек под ним. Таким образом, в Info предыдущий пример дает
такой вывод:
Структура глав **************
Texinfo также предоставляет команду @centerchap; она аналогична
@unnumbered, но центрирует свой аргумент в печатном выводе.
Обычно такой стиль не рекомендуется к использованию в Texinfo.
@unnumbered и @appendix
Используйте команду @unnumbered для создания в печатном
руководстве главы без какого-либо номера. Используйте команду
@appendix для создания в печатном руководстве приложения,
помеченного буквой, а не числом.
При выводе в Info-файл команды @unnumbered и @appendix
действуют эквивалентно @chapter: заголовок печатается на
отдельной строке, а под ним печатается строка звездочек.
(See section @chapter.)
Чтобы создать приложение или ненумерованную главу, напишите в начале
строки команду @appendix или @unnumbered, а после нее на
той же строке -- название, как бы вы написали при создании главы.
@majorheading, @chapheading
Команды @majorheading и @chapheading помещают в тело
документа заголовки, подобные заголовкам глав.
Однако, эти команды не говорят TeX создавать нумерованные заголовки или вхождения в содержании, а также начинать в печатном руководстве новую страницу.
В TeX, команда @majorheading создает больший вертикальный
пропуск перед заголовком, чем команда @chapheading, но в
остальном эти команды одинаковы.
В Info, команды @majorheading и @chapheading
эквивалентны @chapter: заголовок печатается на отдельной строке,
и под ним печатается строка звездочек. (See section @chapter.)
@section
В печатном руководстве, команда @section обозначает нумерованный
раздел внутри главы. Заголовок раздела появляется в содержании. В Info
команда @section делает для сегмента текста заголовок,
подчеркнутый символами `='.
Данный раздел озаглавлен с помощью команды @section следующим
образом:
@section @code{@@section}
Чтобы создать раздел, напишите команду @section в начале строки,
и после нее название раздела на той же строке.
Таким образом,
@section Это раздел
дает в Info
Это раздел ==========
@unnumberedsec, @appendixsec, @heading
Команды @unnumberedsec, @appendixsec и @heading
--- это эквиваленты команды @section для, соответственно,
ненумерованных разделов, приложений и заголовков. (See section @section.)
@unnumberedsec
@unnumberedsec может применяться внутри ненумерованной
или обычной главы или приложения для создания ненумерованного
раздела.
@appendixsec
@appendixsection
@appendixsection -- более длинный вариант написания
@appendixsec; эти команды являются синонимами.
Команда @appendixsec или @appendixsection по соглашению
используется только внутри приложений.
@heading
@heading везде, где захотите, для
создания заголовка, подобного заголовку раздела, который не появится в
содержании.@subsection
Подразделы соотносятся с разделами так же, как разделы с главами.
(See section @section.) В Info заголовки подразделов
подчеркиваются символами `-'. Например,
@subsection Это подраздел
дает
Это подраздел -------------
В печатном руководстве подразделы вносятся в содержание и нумеруются до третьего уровня глубины.
@subsection
Команды @unnumberedsubsec, @appendixsubsec и
@subheading -- это эквиваленты команды @subsection для,
соответственно, ненумерованных разделов, приложений и заголовков.
(See section Команда @subsection.)
В Info команды, подобные @subsection, создают заголовок,
подчеркнутый строкой дефисов. В печатном руководстве, команда
@subheading создает заголовок, как для подраздела, за
исключением того, что он не нумеруется и не вносится в содержание.
Аналогично, команда @unnumberedsubsec создает ненумерованный
заголовок, как для подраздела, а команда @appendixsubsec ---
заголовок, подобный заголовку подраздела, помеченный буквой и числами;
заголовки, создаваемые обеими этими командами, вносятся в содержание.
Команды Texinfo для описания структуры глав четвертого, нижнего уровня --- это команды, начинающиеся с `subsub'. Они включают:
@subsubsection
@subsection.) В печатном
руководстве заголовки подподразделов вносятся в содержание и нумеруются
до четвертого уровня.
@unnumberedsubsubsec
@appendixsubsubsec
@subsubheading
@subsubheading применяется везде, где вам нужен
маленький заголовок, который не вносится в содержание. В Info такие
заголовки выглядят так же, как и заголовки простых
подподразделов.В Info заголовки подподразделов подчеркиваются строкой точек. Например,
@subsubsection Это подподраздел
дает
Это подподраздел ................
@raisesections и @lowersections
Команды @raisesections и @lowersections повышают и
понижают иерархический уровень глав, разделов, подразделов и подобных
сегментов. Команда @raisesections меняет разделы на главы,
подразделы на разделы и так далее. Команда @lowersections
меняет главы на разделы, разделы на подразделы и так далее.
Команда @lowersections полезна, если вы хотите включить текст,
записанный в отдельном или самостоятельном Texinfo-файле, в виде
внутреннего, включаемого файла. Если вы напишите эту команду в начале
файла, все команды @chapter будут отформатированы, как если бы
они были командами @section, все команды @section будут
отформатированы как команды @subsection, и так далее.
@raisesections увеличивает уровень команды в иерархии
структурирования глав на один:
Изменяет на
@subsection @section,
@section @chapter,
@heading @chapheading,
etc.
@lowersections уменьшает уровень команды в иерархии
структурирования глав на один:
Изменяет на
@chapter @section,
@subsection @subsubsection,
@heading @subheading,
etc.
Команда @raisesections или @lowersections изменяет
только те команды описания структуры, которые идут в исходном
Texinfo-файле после нее. Пишите команды @raisesections и
@lowersections на отдельной строке.
Команда @lowersections отменяет действие @raisesections
и наоборот. Как правило, эти команды используются следующим образом:
@lowersections @include somefile.texi @raisesections
Если не написать @raisesections, все последующие разделы в вашем
документе будут на уровень ниже.
Повторное применение этих команд продолжает поднимание или опускание иерархического уровня, на один каждый раз.
Попытка подняться выше уровня глав дает снова команды для глав, попытка спуститься ниже уровня подподразделов дает снова команды для подподразделов.
Ноды -- это первичные сегменты Texinfo-файла. Сами по себе они не налагают иерархической или иной другой структуры на файл. Ноды содержат указатели на ноды, которые отсылают к другим нодам, и меню, являющиеся списками нод. Команды перемещения в Info могут привести вас к ноде по указателю на нее или к ноде, перечисленной в меню. Указатели на ноды и меню обеспечивают некую структуру в Info-файлах, как главы, разделы, подразделы и подобные фрагменты обеспечивают структуру в печатных книгах.
Команды для нод и меню и команды описания структуры глав независимы друг от друга в техническом смысле:
Вы можете использовать указатели на ноды и меню, чтобы создать Info-файл с любой структурой, какой захотите; вы можете написать Texinfo-файл так, что его вывод в формате Info будет иметь другую структуру, нежели его печатный вывод. Однако, прктически все Texinfo-файлы наисаны так, что структура вывода в Info соответствует структуре печатного вывода. Делать иначе было бы неудобно и непонятно для читателя.
Обычно печатный вывод структурирован в виде древовидной иерархии, в которой главы являются более крупными членами, и от них ответвляются разделы. Аналогично, указатели на ноды и меню организуются так, чтобы создать совпадающую структуру при выводе в Info.
Здесь приведена копия показанной ранее диаграммы, которая изображает Texinfo-файл с тремя главами, каждая из которых содержит три раздела.
"Корень" находится в вершине диаграммы, а "листья" внизу. Традиционно подобные диаграммы изображаются именно таким образом; они иллюстрируют дерево, направленное сверху вниз. По этой причине корневая нода называется `Top' (Первая), а указатели `Up' (Вверх) переносят вас ближе к корню.
Вершина
|
-------------------------------------
| | |
Глава 1 Глава 2 Глава 3
| | |
-------- -------- --------
| | | | | |
Раздел Раздел Раздел Раздел Раздел Раздел
1.1 1.2 2.1 2.2 3.1 3.2
Полная форма команды для начала Главы 2 выглядела бы так:
@node Глава 2, Глава 3, Глава 1, Top @comment node-name, next, previous, up
Эта строка @node говорит, что данная нода называется "Глава
2", следующая нода называется "Глава 3", предыдущая нода называется
"Глава 1", а верхняя нода называется "Top". Вы можете не писать все
эти имена нод, если ваш документ организован иерархически
(see section Создание указателей с помощью @command{makeinfo}), но связь между указателями
сохраняется.
Пожалуйста, обратите внимание: `Next' ссылается на следующую ноду на том же иерархическом уровне руководства, не обязательно на следующую ноду в Texinfo-файле. В Texinfo-файле, последующие ноды могут находиться на более нижнем уровне: ноды уровня разделов чаще всего следуют за нодами уровня глав, для примера. Указатели `Next' и `Previous' ссылаются на ноды того же иерархического уровня. (Нода `Top' представляет исключение из этого правила. Так как нода `Top' является единственной нодой на своем уровне, то ее указатель `Next' ссылается на первую последующую ноду, которая почти всегда является главой или нодой уровня глав.)
Чтобы перейти к разделам 2.1 и 2.2, используя Info, вам понадобится меню внутри Главы 2. (See section Меню.) Вы должны написать меню непосредственно перед началом Раздела 2.1, как показано ниже:
@menu
* Разд. 2.1:: Описание этого раздела.
* Разд. 2.2::
@end menu
Напишите ноду для раздела 2.1 так:
@node Разд. 2.1, Разд. 2.2, Глава 2, Глава 2
@comment node-name, next, previous, up
В формате Info указатели `Next' и `Previous' обычно ведут к другим нодам того же уровня -- от главы к главе или от раздела к разделу (иногда, как показано, `Previous' ссылается на верхнюю ноду); указатель `Up', как правило, ведет к ноде верхнего уровня (ближе к первой ноде (`Top'); меню приводит к нодам более низкого уровня (ближе к `листьям'). (Перекрестная ссылка может указывать на ноду любого уровня; смотрите section Перекрестные ссылки.)
Обычно команда @node и команды описания структуры глав
используются вместе, как и команды добавления вхождений в именные
указатели. (Вы можете написать после строки @node строку
комментария, который напомнит вам, какой указатель куда
указывает.)
Ниже приведено начало главы данного руководства, озаглавленной
"Завершение Texinfo-файла". Тут показана строка @node, за
которой идет строка комментария, строка @chapter и затем строки
для именных указателей.
@node Завершение файла, Структурирование, Начало файла, Top @comment node-name, next, previous, up @chapter Завершение Texinfo-файла @cindex Завершение Texinfo-файла @cindex Texinfo-файл, завершение @cindex Файл, завершение
@node
Нода -- это сегмент текста, начинающийся с команды @node
и продолжающийся до следующей команды @node. Определение ноды
отличается от определения главы или раздела. Глава может включать
разделы, а раздел -- подразделы, но нода не может содержать подноды;
текст ноды продолжается только до следующей команды @node в
файле. Нода обычно содержит только одну команду для описания структуры
глав, ту, что идет после строки @node. С другой стороны, в
печатном выводе ноды применяются только для перекрестных ссылок, так что
глава или раздел может содержать любое число нод. На самом деле, глава
обычно включает несколько нод, по одной на каждый раздел, подраздел и
подподраздел.
Чтобы создать ноду, напишите команду @node в начале строки и за
ней четыре ее аргумента, разделенные запятыми, в конце той же строки.
Первый аргумент обязателен: это имя данной ноды. Последующие аргументы
--- это имена для указателей `Next', `Previous' и `Up', в таком порядке;
они могут быть опущены, если ваш документ организован иерархически
(see section Создание указателей с помощью @command{makeinfo}).
Вы можете вставлять пробелы перед каждым именем, если хотите. Вы должны писать имя ноды и имена указателей `Next', `Previous' и `Up' на одной строке, иначе программы форматирования не смогут их правильно обработать. (See Info file `info', node `Top', для получения подробной информации о нодах в Info.)
Обычно сразу после строки @node вы будете писать строку с одной
из команд описания структуры глав -- например, строку @section
или @subsection. (See section Типы команд описания структуры.)
Пожалуйста, обратите внимание: Команды обновления в режиме Texinfo для GNU Emacs работают только с такими Texinfo-файлами, в которых после строк
@nodeнаписаны строки описания структуры глав. See section Требования для обновления.
TeX использует строки @node для определения имен перекрестных
ссылок. Поэтому вы должны писать строки @node в Texinfo-файле,
предназначенном для форматирования для печати, даже если вы не
намереваетесь форматировать его для Info. (Перекрестные ссылки, такие
как в конце этого предложения, создаются командой @xref и
родственными с ней командами; смотрите section Перекрестные ссылки.)
Имя ноды служит для ее идентификации. Указатели позволяют вам достичь других нод и состоят из имен этих нод.
Как правило, указатель `Up' содержит имя ноды, в меню которой упомянута данная нода. Указатель `Next' содержит имя ноды, следующей после данной в этом меню, а указатель `Previous' -- имя ноды, написанной в меню перед данной. Когда ноды `Previous' и `Up' совпадают, оба указателя ссылаются на одну ноду.
Обычно первой нодой Texinfo-файла является нода `Top', а ее указатели `Up' и `Previous' ссылаются на файл `dir', который содержит главное меню для всей системы Info.
Сама нода `Top' содержит главное или мастер-меню руководства. Также в ноду `Top' полезно включить краткое описание этого руководства. See section Первая нода, чтобы узнать, как писать первую ноду Texinfo-файла.
Даже если вы явно записываете все указатели, это не означает, что вы можете писать ноды в исходном Texinfo-файле в произвольном порядке! Так как TeX обрабатывает файл последовательно, не обращая внимания на указатели на ноды, вы должны писать ноды в том порядке, в каком вы желаете их видеть в печатном выводе.
@node
Простейший способ написать строку @node -- написать в начале
строки команду @node и затем имя ноды, как показано здесь:
@node имя-ноды
Если вы пользуетесь GNU Emacs, вы можете использовать для вставки имен указателей команды обновления ноды, предоставляемые режимом Texinfo; или вы можете не заботиться об указателях в Texinfo-файле и предоставить программе @command{makeinfo} вставить их в создаваемый ей Info-файл. (See section Использование режима Texinfo, и section Создание указателей с помощью @command{makeinfo}.)
Или вы можете вставить указатели `Next', `Previous' и `Up' сами. Если вы делаете так, вы можете счесть полезным использовать команду режима Texinfo C-c C-c n. Эта команда вставляет строку `@node' и строку комментария, перечисляющего имена указателей на ноды в нужном порядке. Такая строка комментария особенно полезна, если вы не совсем освоились с Texinfo.
Шаблон для полной формы строки ноды с указателями `Next', `Previous' и `Up' выглядит следующим образом:
@node имя-ноды, следующая, предыдущая, вверх
Если вы хотите, то можете вообще не писать строки @node в первом
наброске и затем использовать команду texinfo-insert-node-lines,
которая создаст их за вас. Однако мы не рекомендуем такую практику.
Лучше давать ноде имя тогда же, когда вы пишите ее текст, чтобы вы могли
легко создавать перекрестные ссылки. Большое число перекрестных ссылок
--- это особенно важная отличительная черта хорошего Info-файла.
После того, как вы вставили строку @node, вы должны сразу
написать @-команду для главы или раздела и вставить имя этой главы.
Потом (и это важно!) напишите несколько вхождений для именных
указателей. Обычно вы сможете найти по крайней мере два, а часто даже
четыре или пять способов сослаться на ноду из именного указателя.
Используйте их все. Это позволит людям намного легче найти данную
ноду.
@nodeВот три рекомендации:
@node
Вот несколько требований, предъявляемых к строкам @node:
@chapter выглядит
следующим образом:
@node chapter, unnumbered & appendix, makeinfo top, Структурирование
@section @code{@@chapter}
@findex chapter
@code{@@unnumberedsec}, @code{@@appendixsec},
@code{@@heading}
Имя соответствующей ноды:
unnumberedsec appendixsec heading
Первой нодой Texinfo-файлой, за исключением включаемых файлов (see section Включаемые файлы), является нода Top. Первая нода содержит главное меню документа и его краткий обзор. (see section Обзор в ноде Top).
Первая нода (которая должна называться `top' или `Top') должна
содержать в качестве указателя `Up' имя ноды в другом файле, в котором
есть меню, ведущее к данному файлу. Имя файла пишется в круглых
скобках. Если файл должен быть установлен непосредственно в
файл-каталог Info, пишите в качестве родителя первой ноды `(dir)';
это сокращение для `(dir)top', указывающее на первую ноду в файле
`dir', которая содержит главное меню для всей системы Info.
Например, в этом руководстве строка @node Top выглядит так:
@node Top, Копирование, , (dir)
(Вы можете использовать команды обновления Texinfo или утилиту @command{makeinfo}, чтобы вставить эти указатели автоматически.)
Не делайте `(dir)' `Предыдущей' нодой первой ноды, так как это приводит к непонятному для пользователей поведению программы: если вы находитесь в первой ноде и нажимаете клавишу DEL, чтобы вернуться назад, вы перейдете к середине какого-то другого вхождения файла `dir', не имеющего никакого отношения к тому, что вы читали.
See section Установка Info-файла, для большей информации об установке Info-файла в каталог `info'.
@top
Специальная команда @top была создана для использования со
строкой @node Top. Команда @top сообщает программе
@command{makeinfo}, что здесь помещена первая нода файла. Она
предоставляет сведения, необходимые @command{makeinfo}, чтобы
автоматически вставлять указатели на ноды. Пишите команду @top
в начале строки сразу после строки @node Top. На оставшейся
части той же строки напишите заглавие.
В Info команда @top выводит на отдельной строке заголовок и
строку звездочек под ним.
В TeX и texinfo-format-buffer, команда @top -- это
просто синоним команды @unnumbered. Обе эти форматирующие
программы не требуют наличия команды @top и не делают для нее
ничего особеного. Если вы пользуетесь этими программами форматирования,
то можете использовать после строки @node Top команды
@chapter или @unnumbered. Вы также можете писать
@chapter или @unnumbered при использовании команд
обновления Texinfo для создания или обновления указателей и меню.
Вы можете помочь читателям, написав в первой ноде обзор, после строки
@top и перед главным меню. В Info этот обзор появится
непосредственно перед главным меню. В печатном руководстве этот обзор
появится на отдельной странице.
Если вы не хотите, чтобы в печатном руководстве обзор выводился на
отдельной странице, вы можете заключить всю первую ноду, включая строки
@node Top и @top или другие команды для разделов, между
командами @ifinfo и @end ifinfo. Это предотвратит
появление всего этого текста в печатном выводе. (see section Условно видимый текст). Вы можете повторить краткое описание из первой
ноды внутри блока @iftex ... @end iftex в начале
первой главы, для тех, кто читает печатное руководство. Это сберегает
бумагу и может выглядеть красивее.
В обзоре вы должны написать номер версии программы, к которой относится
это руководство. Это поможет читателю проследить, какое руководство
написано для какой версии программы. Если руководство меняется чаще,
чем сама программа, или независимо от нее, вы также должны включить
номер редакции для руководства. (Титульный лист тоже должен содержать
эти сведения: смотрите section @titlepage.)
Программа @command{makeinfo} умеет автоматически определять указатели на ноды для иерархически организованных файлов.
Если вы пользуетесь этой возможностью, вам не нужно писать указатели
`Next', `Previous' и `Up' после имени ноды. Однако, вы должны писать
команды для задания структуры разделов, такие как @chapter или
@section, на строке, идущей сразу после укороченной строки
@node (можно лишь написать строку комментария).
Кроме того, после строки @node в ноде `Top' вы должны написать
строку, начинающуюся командой @top, чтобы обозначить первую ноду
файла. See section @top.
Наконец, вы должны написать имя каждой ноды (кроме ноды `Top') в меню одним или несколькими иерархическими уровнями выше, чем уровень данной ноды.
Эта способность @command{makeinfo} вставлять указатели на ноды освобождает вас от необходимости создания и обновления меню и указателей вручную или с помощью команд режима Texinfo. (See section Обновление нод и меню.)
@anchor: Определение произвольных назначений для ссылок
Маркер -- это позиция в вашем документе, помеченная так, что на
нее могут указывать перекрестные ссылки, в точности так же, как на ноды.
Вы можете создать маркер, написав команду @anchor и задав ему
метку в виде обычного аргумента в фигурных скобках. Например:
Это @anchor{х-место}место помечено.
...
@xref{х-место,,место}.
дает:
Это место помечено. ... Смотрите [место], страница 1.
Как вы видите, команда @anchor сама не дает вывода. В этом
примере определен маркер `х-место' непосредственно перед словом `место'.
Вы можете сослаться на него позже с помощью команды @xref или
другой команды для перекрестных ссылок, как показано. See section Перекрестные ссылки, подробности о командах для создания перекрестных ссылок.
Лучше всего помещать команды @anchor непосредственно перед
позицией, на которую вы хотите сослаться; тогда при переходе к маркеру
взгляд читателя будет перенесен к нужному фрагменту текста. Вы можете
помещать команду @anchor на отдельной строке, если это послужит
облегчению чтения исходного текста. Пробелы после команды
@anchor всегда игнорируются.
Имена маркеров и нод не должны конфликтовать. Иногда маркеры и ноды
имеют схожее значение; например, в самостоятельной программе Info,
команда goto-node принимает в качестве аргумента как имя ноды,
так и имя маркера. (See section `goto-node' in GNU Info.)
Меню содержат указатели на подчиненные ноды.(6) В Info вы можете использовать меню для перехода к этим нодам. В печатных руководствах меню не нужны и не появляются в них.
По соглашению, меню помещается в конце ноды, так как читатель может не увидеть текст, следующий после меню. Более того, в ноде, содержащей меню, не должно быть много текста. Если у вас есть много текста и меню, переместите большую часть текста, кроме нескольких строк, в новую подноду. Иначе читатель, имеющий терминал, неспособный отобразить сразу много строк, может пропустить меню и связанный с ним текст. На практике лучше помещать меню в пределах двадцати строк в начале ноды.
Короткий отрывок текста перед меню может выглядеть некрасиво в печатном
руководстве. Чтобы избежать этого, вы можете написать меню рядом с
началом его ноды и поместить после него строку @node, а затем
строку @heading между командами @ifinfo и @end
ifinfo. При этом меню, строка @node и заголовок появятся
только в Info-файле, но не в печатном документе.
Например, два предыдущих абзаца были написаны после меню, строки
@node и заголовка. В исходном файле это выглядит так:
@menu * Размещение меню:: * Написание меню:: * Части меню:: * Менее беспорядочный пункт меню:: * Пример меню:: * Другие Info-файлы:: @end menu @node Размещение меню, Написание меню, , Меню @ifinfo @heading Меню должны быть в коротких нодах @end ifinfo
Texinfo-файл для данного документа содержит более дюжины примеров применения этой процедуры. Один из них находится в начале этой главы, другой -- в начале section Перекрестные ссылки.
Меню состоит из команды @menu, стоящей на отдельной строке,
последующих пунктов меню или строк комментариев к ним и команды
@end menu на отдельной строке.
Описание меню выглядит так:
@menu
Более объемные куски текста
* Файлы:: Все об обращении с файлами.
* Множества:: Множество буферов; редактирование
нескольких файлов одновременно.
@end menu
Каждая строка в меню, начинающаяся с `* ', является пунктом меню. (Обратите внимание на пробел после звездочки.) В меню может появиться и строка, не начинающаяся с `* '. Такая строка -- это не пункт меню, а комментарий, который появляется в Info-файле. В примере выше строка `Более объемные куски текста' является строкой комментария меню; две строки, начинающиеся с `* ' -- пункты меню. Пробелы в меню сохраняются как есть; это позволяет вам форматировать меню по вашему желанию.
Пункт меню состоит из трех частей, необходимой является только вторая:
Шаблон пункта меню выглядит следующим образом:
* название-пункта-меню: имя-ноды. описание
После названия пункта меню должно следовать одно двоеточие, а после имени ноды -- символ табуляции, запятая, точка или символ новой строки.
В Info, пользователь выбирает ноду командой m (Info-menu).
Название пункта меню -- это то, что пользователь вводит после
команды m.
В третьей части пункта меню пишется описывающая фраза или предложение. Названия пунктов и имена нод часто бывают короткими; описание же объясняет пользователю, о чем говорится в этой ноде. Хорошее описание дополняет имя ноды, а не просто повторяет его. Описание может находиться на двух или более строках; в этом случае некоторые авторы предпочитают делать отступ во второй строке, тогда как другие предпочитают выравнивать ее по первой (и по остальным) строкам. Здесь выбор за вами.
Если название пункта меню и имя ноды одинаковы, вы можете написать имя сразу после звездочки и пробела в начале строки и поставить после имени два двоеточия.
Например, пишите
* Имя:: описание
вместо
* Имя: Имя. описание
Вам стоит использовать имя ноды как название пункта меню везде, где это возможно, так как это уменьшит количество ненужного текста в меню.
В Texinfo меню выглядит так:
@menu * название пункта меню: имя ноды. Короткое описание. * Имя ноды:: Эта форма предпочтительна. @end menu
Это дает:
* menu: * название пункта меню: имя ноды. Короткое описание. * Имя ноды:: Эта форма предпочтительна.
Пример, как вы можете увидеть это в Texinfo-файле:
@menu
Более объемные куски текста
* Файлы:: Все об обращении с файлами.
* Множества: Буферы. Множество буферов; редактирование
нескольких файлов одновременно.
@end menu
Это дает:
* menu:
Более объемные куски текста
* Файлы:: Все об обращении с файлами.
* Множества: Буферы. Множество буферов; редактирование
нескольких файлов одновременно.
В этом примере меню имеет два пункта. `Файлы' -- это одновременно и название пункта меню, и имя ноды, на которую ссылается этот пункт. `Множества' -- это название пункта меню; он ссылается на ноду, называемую `Буферы'. Строка `Более объемные куски текста' является комментарием; она присутствует в меню, но не является его пунктом.
Так как ни для ноды `Файлы', ни для ноды `Буферы' не указано имени файла, они должны быть именами нод в том же Info-файле (see section Ссылки на другие Info-файлы).
Вы можете создать пункт меню, который позволит пользователю перейти к ноде в другом Info-файле, написав в круглых скобках имя файла непосредственно перед именем ноды. В этом случае вы должны использовать формат пункта меню с тремя частями, что избавит пользователя от необходимости вводить имя файла.
Формат выглядит следующим образом:
@menu * название-первого-пункта:(файл)нода. описание * название-второго-пункта:(файл)другая-нода. описание @end menu
Например, для ссылки непосредственно на ноды `Схема текста' и `Перепривязка' в Руководстве по Emacs, вы написали бы такое меню:
@menu
* Схема текста: (emacs)Режим Outline. Основной режим для
редактирования структуры текста.
* Перепривязка: (emacs)Перепривязка. Как переопределить
значение ключа.
@end menu
Если вы не указали имя ноды, а только имя файла, то Info предполагает, что это ссылка на первую (`Top') ноду.
Файл `dir', в котором содержится главное меню для системы Info, перечисляет в этом меню только имена файлов. Оно переносит вас непосредственно к первой ноде каждого документа Info. (See section Установка Info-файла.)
Например:
* Info: (info). Система просмотра документации.
* Emacs: (emacs). Расширяемый, самодокументированный
текстовый редактор.
(Каталог верхнего уровня `dir' системы Info -- не Texinfo-, а Info-файл, но пункты меню выглядят одинаково в обоих типах файлов.)
Команды обновления режима Texinfo в GNU Emacs работают только с нодами текущего буфера, а значит вы не можете использовать их для создания меню, ссылающихся на другие файлы. Вы должны писать такие меню сами.
Перекрестные ссылки используются, чтобы указать читателю на другие части того же или другого Texinfo-файла. В Texinfo перекрестные ссылки могут указывать на ноды и маркеры.
Часто, хоть и не всегда, печатный документ нужно разрабатывать так, чтобы его можно было читать последовательно. Людей утомляет пролистывать вперед и назад, чтобы найти информацию, которая должна быть предоставлена им по мере необходимости.
Однако, в любом документе некоторые сведения могут быть слишком подробными в текущем контексте или мало относящими к нему; используйте для предоставления доступа к такой информации перекрестные ссылки. Кроме того, интерактивная система справок не похожа на роман; немногие читают такие документы последовательно от начала до конца. Напротив, люди ищут то, что им нужно. По этой причине такие произведения должны содержать много перекрестных ссылок, чтобы помочь читателям найти сведения, которые они могли не еще читать.
В печатном руководстве перекрестные ссылки выражаются в виде ссылок на страницы, если только это не ссылка на другое руководство, в этом случае перекрестная ссылка называет это руководство.
В Info, перекрестная ссылка выражается в виде вхождения, по которому вы можете перейти с помощью команды Info `f'. (See Info file `@external{info', node `Help-Adv'}.)
Различные команды, работающие с перекрестными ссылками, используют ноды
(или маркеры, see section @anchor: Определение произвольных назначений для ссылок) для определения позиции,
на которую указывает ссылка. Это очевидно в Info, где перекрестная
ссылка переносит вас к указанной позиции. TeX также использует ноды
для определения назначения перекрестной ссылки, но его действия не столь
очевидны. Когда TeX генерирует DVI-файл, он записывает номер
страницы каждой ноды и использует эти номера при создании перекрестных
ссылок. Таким образом, если вы пишете руководство, предназначенное
только для печати, и которое не будет использоваться интерактивно, вы
тем не менее должны писать строки @node для указания мест, на
которые вы будете делать перекрестные ссылки.
Существует четыре команды для перекрестных ссылок:
@xref
@ref
@xref для Info; в печатном руководстве дает только перекрестную
ссылку без предшествующего слова `Смотрите'.
@pxref
@inforef
(Команда @cite используется для создания ссылок на книги и
руководства, для которых нет соответствующего Info-файла, и,
следовательно, нет ноды, на которую можно сослаться. See section @cite{ссылка}.)
Команда, создающая перекрестную ссылку, требует только один аргумент, имя ноды, на которую указывает ссылка. Но эта команда может содержать до четырех дополнительных аргументов. Используя эти аргументы, вы можете предоставить имя ссылки для Info, описание темы или название раздела для печатного вывода или название другого печатного руководства.
Вот простой пример перекрестной ссылки:
@xref{имя ноды}.
что дает
*Note Имя ноды::.
и
Смотрите Раздел nnn [имя ноды], стр. ppp.
Вот пример полной перекрестной ссылки из пяти частей:
@xref{имя ноды, имя перекрестной ссылки, тема, имя-Info-файла,
печатное руководство}, для подробной информации.
что дает
*Note имя перекрестной ссылки: (имя-Info-файла)имя ноды, для подробной информации.
в Info и
Смотрите раздел "тема" в печатном руководстве, для подробной информации.
в печатной книге.
Пять возможных аргументов для перекрестной ссылки включают:
Шаблон полной перекрестной ссылки с пять аргументами выглядит так:
@xref{имя-ноды, имя-перекрестной-ссылки,
тема-или-раздел, имя-info-файла,
название-печатного-руководства}.
Перекрестные ссылки с одним, двумя, четырьмя и пятью аргументами описаны
отдельно после @xref.
Пишите имя ноды в перекрестной ссылке точно так же, как написано в
строке @node, включая те же заглавные буквы; иначе программы
форматирования могут не найти эту ссылку.
Вы можете написать в абзаце команду, создающую перекрестную ссылку, но
помните, как Info и TeX форматируют вывод каждой из них: пишите
@xref в начале предложения; пишите @pxref только внутри
круглых скобок и так далее.
@xref
Команда @xref создает перекрестную ссылку в начале предложения.
Команды форматирования для Info преобразуют ее в перекрестную ссылку
Info, которую может использовать команда Info `f' для перенесения
вас непосредственно к другой ноде. Команды набора TeX превращают ее
в ссылку на страницу или на другую книгу или руководство.
Чаще всего перекрестная ссылка Info выглядит так:
*Note имя-ноды::.
или так
*Note имя-перекрестной-ссылки: имя-ноды.
В TeX перекрестная ссылка выглядит так:
Смотрите раздел номер-раздела [имя-ноды], стр. страница.
или так
Смотрите раздел номер-раздела [название-или-тема], стр. страница.
Команда @xref не выводит точку или запятую для окончания
перекрестной ссылки ни в Info-файле, ни при печати. Вы должны сами
поставить точку или запятую; иначе Info не распознает конец перекрестной
ссылки. (Команда @pxref действует иначе. See section @pxref.)
Пожалуйста, обратите внимание: после закрывающей фигурной скобки
@xrefобязана стоять точка или запятая. Это необходимо для завершения перекрестной ссылки. Эта точка или запятая появятся при выводе, как в Info-файле, так и в печатном руководстве.
@xref должна ссылаться на ноду Info по имени. Используйте
@node для определения ноды (see section Как писать строку @node).
После @xref идут несколько аргументов в фигурных скобках,
разделенные запятыми. Пробельные символы перед запятыми и после них
игнорируются.
Перекрестная ссылка требует только имя ноды; но она может содержать до четырех дополнительных аргументов. Каждый из этих вариантов производит перекрестные ссылки, выглядящие несколько по-разному.
Пожалуйста, обратите внимание: запятые разделяют аргументы в перекрестной ссылке; избегайте включения их в названия разделов или другие части, чтобы программы форматирования не приняли их за разделители.
@xref с одним аргументом
Простейшая форма @xref принимает один аргумент, имя другой ноды
в том же Info-файле. Программы форматирования для Info производят
вывод, который программы чтения могут использовать для перехода по
ссылке; TeX производит вывод, показывающий вам номер раздела и
страницы.
Например,
@xref{Тропические бури}.
дает
*Note Тропические бури::.
и
Смотрите раздел 3.1 [Тропические бури], стр. 24.
(Заметьте, что в этом примере после закрывающей фигурной скобки стоит точка.)
Вы можете написать после перекрестной ссылки дополняющую фразу, как здесь:
@xref{Тропические бури}, для подробной информации.
что дает
*Note Тропические бури::, для подробной информации.
и
Смотрите раздел 3.1 [Тропические бури], стр. 24, для подробной информации.
(Заметьте, что в этом примере после закрывающей фигурной скобки написана запятая, а после дополняющей фразы стоит точка.)
@xref с двумя аргументамиЕсли заданы два аргумента, второй используется как имя перекрестной ссылки в Info, тогда как первый так же является именем ноды, на которую указывает эта ссылка.
Шаблон выглядит так:
@xref{имя-ноды, имя-перекрестной-ссылки}.
Например,
@xref{Электрические эффекты, Молния}.
дает:
*Note Молния: Электрические эффекты.
и
Смотрите раздел 5.2 [Электрические эффекты], стр. 57.
(Заметьте, что в этом примере после закрывающей фигурной скобки стоит точка, и что печатается имя ноды, а не имя перекрестной ссылки.)
Вы можете написать после перекрестной ссылки дополняющую фразу, как здесь:
@xref{Электрические эффекты, Молния}, для подробной информации.
что дает
*Note Молния: Электрические эффекты, для подробной информации.
и
Смотрите раздел 5.2 [Электрические эффекты], стр. 57, для подробной информации.
(Заметьте, что в этом примере после закрывающей фигурной скобки написана запятая, а после дополняющей фразы стоит точка.)
@xref с тремя аргументамиТретий аргумент замещает имя ноды в выводе TeX. Третий аргумент должен быть названием раздела в печатном выводе или объявлять тему, обсуждаемую в этом разделе. Часто вам стоит писать название с заглавной буквы, чтобы его было легче читать напечатанным. Используйте третий аргумент, когда имя ноды не подходит по синтаксису или по смыслу.
Помните, что нельзя ставить точку внутри названия или темы раздела для перекрестной ссылки или внутри любой другой части команды. Программы форматирования делят перекрестные ссылки на аргументы в соответствии с запятыми; запятая внутри названия или другой части разобьет ее на два аргумента. В ссылке вы должны писать названия вроде "Облака, дымка и туман" без запятых.
Также, не забывайте ставить после закрывающей фигурной скобки
@xref запятую или точку для завершения перекрестной ссылки. В
последующих примерах после завершающей запятой идет дополняющая фраза.
Шаблон выглядит так:
@xref{имя-ноды, имя-перекрестной-ссылки,
название-или-тема}.
Например,
@xref{Электрические эффекты, Молния, Гром и молния},
для деталей.
дает
*Note Молния: Электрические эффекты, для деталей.
и
Смотрите раздел 5.2 [Гром и молния], стр. 57, для деталей.
Если третий аргумент задан, а второй пуст, то третий служит и для того, и для другого. (Заметьте, как две последовательные запятые помечают пустой второй аргумент.)
@xref{Электрические эффекты, , Гром и молния}, для деталей.
дает
*Note Гром и молния: Электрические эффекты, для деталей.
и
Смотрите раздел 5.2 [Гром и молния], стр. 57, для деталей.
Фактически, часто лучше всего писать перекрестные ссылки лишь с одним аргументом, если имя ноды и название раздела совпадают, или с первым и третьим аргументами, если имя ноды и название раздела различны.
Вот несколько примеров из The GNU Awk User's Guide:
@xref{Sample Program}.
@xref{Glossary}.
@xref{Case-sensitivity, ,Case-sensitivity in Matching}.
@xref{Close Output, , Closing Output Files and Pipes},
for more information.
@xref{Regexp, , Regular Expressions as Patterns}.
@xref с четырьмя и пятью аргументамиЧетвертый аргумент в перекрестной ссылке задает имя другого Info-файла, отличного от файла, где появляется ссылка, а пятый аргумент задает название для печатного руководства.
Помните, что после закрывающей фигурной скобки @xref должна
стоять запятая или точка для завершения перекрестной ссылки. В
последующих примерах после завершающей запятой идет дополняющая фраза.
Шаблон таков:
@xref{имя-ноды, имя-перекрестной-ссылки,
название-или-тема, имя-info-файла,
название-печатного-руководства}.
Например,
@xref{Электрические эффекты, Молния, Гром и молния, погода,
Введение в метеорологию}, для деталей.
дает
*Note Молния: (погода)Электрические эффекты, для деталей.
Имя Info-файла заключается в круглые скобки и предшествует имени ноды.
В печатном руководстве эта ссылка выглядит так:
Смотрите раздел "Гром и молния" в книге Введение в метеорологию, для деталей.
Название печатного руководства набирается курсивом; в ссылке нет номера страницы, так как TeX не может знать, на какую страницу она указывает, если это ссылка на другое руководство.
Часто вы будете опускать второй аргумент при использовании длинной
версии @xref. В этом случае в качестве имени ссылки в Info
будет использоваться третий аргумент, описание темы.
Шаблон выглядит так:
@xref{имя-ноды, , название-или-тема, имя-info-файла,
название-печатного-руководства}, для деталей.
что дает
*Note название-или-тема: (имя-info-файла)имя-ноды, для деталей.
и
Смотрите раздел название-или-тема в книге название-печатного-руководства, для деталей.
Например,
@xref{Электрические эффекты, , Гром и молния,
погода, Введение в метеорологию}, для деталей.
дает
*Note Гром и молния: (погода)Электрические эффекты, для деталей.
и
Смотрите раздел "Гром и молния" в книге Введение в метеорологию, для деталей.
В редких случаях вы можете захотеть сослаться на другой Info-файл в пределах одного печатного руководства -- когда несколько Texinfo-файлов объединяются в одном запуске TeX, но создают раздельные Info-файлы. В этом случае вам нужно указать только четвертый аргумент, но не пятый.
В перекрестной ссылке вы всегда должны называть ноду. Это значит, что
для ссылки на все руководство вы должны обозначить ноду `Top', написав
ее в качестве первого аргумента команды @xref. (Это отличается
от способа, которым вы пишите пункты меню; смотрите section Ссылки на другие Info-файлы.) В то же время, чтобы
предоставить осмысленную тему или название для перекрестной ссылки
(вместо слова `Top'), вы должны написать подходящий третий аргумент для
команды @xref.
Таким образом, чтобы создать перекрестную ссылку на Руководство по GNU Make, напишите:
@xref{Top, , Обзор, make, Руководство по GNU Make}.
что дает
*Note Обзор: (make)Top.
и
Смотрите раздел "Обзор" в книге Руководство по GNU Make.
`Top' в этом примере является именем первой ноды, а `Обзор' --- названием первого раздела этого руководства.
@ref
@ref практически та же команда, что и @xref, за
исключением того, что она не пишет `смотрите' в печатном выводе, а пишет
только саму ссылку. Поэтому она удобна в последней части предложения.
Например,
Для получения большей информации смотрите @ref{Ураганы}.
дает
Для получения большей информации смотрите *Note Ураганы::.
и
Для получения большей информации смотрите раздел 8.2 [Ураганы], стр. 123.
Команда @ref иногда приводит авторов к изложению своих мыслей в
такой форме, которая подходит для печатного руководства, но в формате
Info смотрится неудачно. Помните, что ваши читатели будут использовать
как печатный формат, так и формат Info.
Например,
Морские волны описаны в @ref{Ураганы}.
дает
Морские волны описаны в разделе 6.7 [Ураганы], стр. 72.
в печатном документе, и следующее в Info:
Морские волны описаны в *Note Ураганы::.
Осторожно: Вы должны ставить точку, запятую или правую круглую скобку сразу после команды
@refс двумя или более аргументами. Иначе Info не найдет конец перекрестной ссылки и попытка перейти по ссылке завершится неуспехом. В качестве общего правила, вы должны писать точку или запятую после каждой команды@ref. Это смотрится лучше всего как в печатном выводе, так и в Info.
@pxref
Команда для перекрестных ссылок в круглых скобках, @pxref, почти
эквивалентна @xref, но вы можете использовать ее только
внутри круглых скобок, и вы не ставите запятую или точку после
закрывающей фигурной скобки команды. Эта команда отличается от
@xref с двух сторон:
Так как один тип форматирования автоматически вставляет завершающую
пунктуацию, а другой не вставляет, вы должны использовать @pxref
только внутри круглых скобок, как часть другого предложения.
Кроме того, вы не должны сами ставить знаки препинания после ссылки, как
вы делаете для @xref.
@pxref разработана так, чтобы вывод выглядел правильно как в
напечатанном виде, так и в Info-файле. В печатном руководстве после
перекрестной ссылки в круглых скобках не должна стоять запятая или
точка; такая пунктуация неправильна. Но в Info-файле, после
перекрестной ссылки должна идти подходящая пунктуация, чтобы Info могла
распознать конец ссылки. @pxref избавляет вас от необходимости
использования сложных методов поставить ограничитель в одной форме и не
ставить в другой.
С одним аргументом, перекрестная ссылка в круглых скобках выглядит так:
... бури причиняют наводнения (@pxref{Ураганы}) ...
что дает
... бури причиняют наводнения (*Note Ураганы::) ...
и
... бури причиняют наводнения (смотрите раздел 6.7 [Ураганы], стр. 72) ...
С двумя аргументами, перекрестная ссылка в круглых скобках выглядит так:
... (@pxref{имя-ноды, имя-перекрестной-ссылки})
...
что дает
... (*Note имя-перекрестной-ссылки: имя-ноды.) ...
и
... (смотрите раздел nnn [имя-ноды], стр. ppp) ...
@pxref можно передать до пяти аргументов, в точности, как и
@xref (see section Команда @xref).
Пожалуйста, обратите внимание: Используйте
@pxrefтолько для перекрестных ссылок в круглых скобках. Не пытайтесь использовать@pxrefв качестве дополнения в предложении. Это будет смотреться плохо либо в Info-файле, либо в печатном выводе, либо и там, и там.Также, перекрестные ссылки в круглых скобках смотрятся лучше всего в конце предложения. Хотя вы можете написать их в середине предложения, такое расположение нарушит течение текста.
@inforef
@inforef используется для перекрестных ссылок на Info-файлы, для
которых нет печатных руководств. Даже в печатном руководстве
@inforef создает ссылку, направляющую пользователя к Info-файлу.
Эта команда принимает два или три аргумента в следующем порядке:
Разделяйте аргументы запятыми, как и в @xref. Также, вы должны
завершить ссылку запятой или точкой после `}', как вы делаете для
@xref.
Шаблон таков:
@inforef{имя-ноды, имя-перекрестной-ссылки,
имя-info-файла},
Таким образом,
@inforef{Эксперт, Продвинутые команды Info, info},
для дальнейшей информации.
дает
*Note Продвинутые команды Info: (info)Эксперт, для дальнейшей информации.
и
Смотрите Info-файл `info', нода `Эксперт', для дальнейшей информации.
Аналогично,
@inforef{Эксперт, , info}, для дальнейшей информации.
дает
*Note (info)Эксперт::, для дальнейшей информации.
и
Смотрите Info-файл `info', нода `Эксперт', для дальнейшей информации.
Обратной к @inforef является команда @cite, которая
используется для ссылки на печатное произведение, не существующее в
форме Info. See section @cite{ссылка}.
@uref{url[, отображаемый-текст]}
@uref производит ссылку на унифицированный указатель ресурса
(url). Она принимает один обязательный аргумент, собственно url, и два
необязательных, которые определяют отображаемый текст. При выводе в
HTML @uref создает ссылку, по которой можно проследовать.
Второй аргумент, если он задан, -- это отображаемый текст (по умолчанию это сам url); при выводе в Info или DVI показывается также и url.
С другой стороны, третий аргумент, если он задан, -- это тоже отображаемый текст, но тогда url не выводится в любом формате. Это полезно, если текст сам по себе дает хорошую ссылку, как в man-странице. Если задан третий аргумент, то второй игнорируется.
Вот простая форма с одним аргументом, где url является и назначением, и текстом ссылки:
Официальный ftp-сайт GNU --- это @uref{ftp://ftp.gnu.org/gnu}.
дает:
Официальный ftp-сайт GNU --- это ftp://ftp.gnu.org/gnu.
Вот пример формы с двумя аргументами:
Официальный
@uref{ftp://ftp.gnu.org/pub/gnu, ftp-сайт GNU}
содержит программы и тексты.
дает
Официальный ftp-сайт GNU содержит программы и тексты.
то есть, в Info это выглядит так:
Официальный ftp-сайт GNU (ftp://ftp.gnu.org/gnu) содержит программы и тексты.
а в HTML так:
Официальный <a href="ftp://ftp.gnu.org/gnu">ftp-сайт GNU</a> содержит программы и тексты.
Пример формы с третьим аргументом:
Программа @uref{http://example.org/man.cgi/1/ls,,ls(1)} ...
дает это:
Программа http://example.org/man.cgi/1/ls ...
и в HTML:
Программа <a href="http://example.org/man.cgi/1/ls">ls(1)</a> ...
Чтобы просто обозначить url, не создавая ссылки, по которой можно
перейти, используйте команду @url (see section @url{унифицированный-указатель-ресурса}).
Некоторые предпочитают писать url в недвусмысленном формате:
<URL:http://машина/путь>
Если хотите, вы можете использовать такую форму во входном файле. Мы не считаем необходимым загромождать вывод дополнительными `<URL:' и `>', так как все программы, пытающиеся обнаруживать url в тексте, должны находить их без `<URL:', если они хотят быть полезными.
В Texinfo вы можете пометить слова и фразы множеством способов. Программы форматирования Texinfo используют эту информацию, чтобы определить, как выделить данный текст. Вы можете указать, например, что какое-то слово является определением, метасинтаксической переменной или символом, используемым в программе. Вы также можете несколькими способами обозначить логическое ударение.
В Texinfo есть команды для обозначения того, на какой именно вид
объектов ссылается фрагмент текста. Например, метасинтаксические
переменные помечаются командой @var, а программный код ---
командой @code. Так как фрагменты текста помечаются командами,
говорящими, объектами какого сорта они являются, легко изменить способ
обработки такого текста программами форматирования Texinfo. (Texinfo
--- язык смысловой разметки, а не верстки.)
Например, в печатном руководстве программный код показывается
равноширинным шрифтом; @code велит TeX набирать данный текст
этим шрифтом. Но можно было бы легко поменять способ, которым TeX
выделяет код, так, чтобы использовался другой шрифт, и это изменение не
затронет способ выделения примеров пользовательского ввода с клавиатуры.
Если бы в теле файла использовались непосредственные команды набора, и
вы решили сделать такое изменение, вам пришлось бы проверить каждое
вхождение, чтобы убедиться, что вы меняете вид кода, а не чего-то
другого, что не должно меняться.
Команды выделения могут применяться для извлечения из файла полезной информации, такой как списки функций или имена файлов. Можно, например, написать программу (или макрос клавиатуры) на языке Emacs Lisp, которая вставляла бы вхождение именного указателя после каждого абзаца, содержащего слова или фразы, помеченные определенной командой. Вы могли бы сделать это для того, чтобы составить указатель функций, если вы еще не написали вхождений.
Эти команды служат для множества целей:
@code{пример-кода}
@kbd{символы-клавиатуры}
@key{название-клавиши}
@samp{текст}
@var{метасинтаксическая-переменная}
@env{переменная-среды}
@file{имя-файла}
@command{команда}
@option{ключ}
@dfn{термин}
@cite{ссылка}
@acronym{аббревиатура}
@url{унифицированный-указатель-ресурса}
@email{почтовый-адрес[, отображаемый-текст]}
@code{пример-кода}
Используйте команду @code, чтобы обозначить текст, являющийся
фрагментом программы и состоящий из полных синтаксических лексем.
Заключайте этот текст в фигурные скобки.
Таким образом, вы должны применять @code для выражений в
программе, названий переменных или функций, используемых в программе,
или ключевых слов языка программирования.
Используйте @code для имен команд командных языков, похожих на
языки программирования, таких как Texinfo. Например, @code и
@samp записаны в исходном Texinfo-файле как
`@code{@@code}' и `@code{@@samp}', соответственно.
Менять регистр слова внутри команды @code, когда оно стоит в
начале предложения, неправильно. Большинство компьютерных языков
регистрозависимы. В Си, например, Printf отличается от
идентификатора printf и, скорее всего, является его неправильной
записью. Даже в языках, не учитывающих регистр букв, пользователя
смутит различное написание идентификаторов. Выберите одно написание и
придерживайтесь его всегда. Если вы не хотите начинать предложение с
имени команды, написанного строчными буквами, вам нужно перестроить
предложение.
В печатном руководстве @code заставляет TeX набирать аргумент
в стиле печатной машинки (равноширинным шрифтом). В Info-файле, она
велит командам форматирования для Info окружать текст одиночными
кавычками.
Например,
Используйте @code{ediff-files} для сравнения двух файлов.
дает в печатном руководстве следующее:
Используйте
ediff-filesдля сравнения двух файлов.
и такое в Info-файле:
Используйте `ediff-files' для сравнения двух файлов.
Вот несколько случаев, для которых предпочтительно не использовать
@code:
@command).
@option).
@samp, а не @code. В таком случае
следует выбирать более приятный для глаз вариант.
@env).
goto-char, вам следует использовать @samp.
@code, например, когда вы объясняете, какие буквы или печатные
знаки могут использоваться в именах функций. (Применяйте
@samp.) Также вы не должны применять @code для
обозначения текста, рассматриваемого, как ввод для программы, если этот
входной текст не написан на языке, похожем на язык программирования.
Например, не нужно использовать @code для команд GNU Emacs,
вводимых с клавиатуры (используйте вместо этого @kbd), хотя вы
можете использовать @code для имен функций Emacs Lisp, которые
вызываются этими командами.
Поскольку @command, @option, and @env были
внесены в язык относительно недавно, возможно применение @code
или @samp для имен команд, ключей и переменных среды. Новые
команды позволяют выражать разметку более точно, но от использования
старых команд нет действительного вреда, и конечно, давно написанные
руководства используют их.
@kbd{символы-клавиатуры}
Используйте команду @kbd для символов ввода, которые печатает
пользователь. Например, чтобы сослаться на символы M-a,
напишите
@kbd{M-a}
а чтобы сослаться на символы M-x shell, напишите
@kbd{M-x shell}
Команда @kbd дает в Info такой же результат, как и
@code, но в печатном руководстве она по умолчанию выводит другим
шрифтом (наклонным равноширинным, вместо обычного равноширинного), так
что пользователи могут отличить символы, которые предполагается вводить,
от тех, что выводит компьютер.
Так как команда @kbd применяется в разных руководствах
по-разному, вы можете управлять переключением шрифта для нее с помощью
команды @kbdinputstyle. Эта команда не влияет на вывод Info.
Пишите ее в начале строки с одним одним из этих слов в качестве
аргумента:
@kbd тот же шрифт, что и
для @code.
@kbd другой шрифт только внутри блоков
@example или в подобных случаях.
@kbd отличающийся шрифт.
Вы можете вставлять другие @-команды внутри фигурных скобок команды
@kbd. Вот, например, способ оформить команду, которая можно
было бы более подробно описать как "нажмите `r' и затем клавишу
RET":
@kbd{r @key{RET}}
Это дает: r RET
Вы также используете команду @kbd, если выписываете вводимые
буквы по одной; например:
Чтобы дать команду @code{logout},
напечатайте символы @kbd{l o g o u t @key{RET}}.
Это дает:
Чтобы дать команду
logout, напечатайте символы l o g o u t RET.
(Этот пример показывает также, что вы можете добавить для ясности пробелы. Если вы действительно хотите упомянуть пробел как один из вводимых символов напишите для него @key{SPC}.)
@key{название-клавиши}
Используйте команду @key для общепринятых названий клавиш на
клавиатуре, как например здесь:
@key{RET}
Вы можете использовать команду @key внутри аргумента команды
@kbd, когда последовательность вводимых символов содержит одну
или более клавиш, имеющих название.
Например, чтобы получить C-x ESC, вы написали бы:
@kbd{C-x @key{ESC}}
Вот список рекомендуемых названий клавиш:
- SPC
- Пробел
- RET
- Возврат каретки
- LFD
- Перевод строки (однако, так как большинство современных клавиатур не имеют клавиши "Перевод строки", было бы лучше называть этот символ C-j.
- TAB
- Табуляция
- BS
- Забой
- ESC
- Выход
- DEL
- Удаление
- SHIFT
- Shift
- CTRL
- Control
- META
- Meta
Есть тонкости в обращении со словами вроде `meta' или `ctrl', которые
являются названиями клавиш-модификаторов. При упоминании символа, в
котором используется клавиша-модификатор, такого как Meta-a,
используйте просто команду @kbd, не используйте @key; но
если вы ссылаетесь на клавишу-модификатор саму по себе, используйте
команду @key. Например, пишите `@kbd{Meta-a}', чтобы
получить Meta-a и `@key{META}', чтобы получить META.
@samp{текст}
Используйте команду @samp для обозначения текста, являющегося
буквальным примером или `образцом' последовательности символов в файле,
строке, образце, etc. Заключайте этот текст в фигурные скобки.
Аргумент выводится в одиночных кавычках как в Info-файле, так и в
печатном руководстве; кроме того, в печатном руководстве он печатается
равноширинным шрифтом.
Чтобы найти совпадения с @samp{foo} в конце строки, используйте
регулярное выражение @samp{foo$}.
дает
Чтобы найти совпадения с `foo' в конце строки, используйте регулярное выражение `foo$'.
Всякий раз, когда вы говорите об одиночных символах, используйте
@samp, если @kbd и @key не более подходят к
ситуации. Также, вы можете использовать @samp для полных
выражений на Си и для полных команд оболочки -- в этом случае
@samp часто выглядит лучше, чем @code. В основном,
@samp -- это вариант для всего, что не покрывается
@code, @kbd или @key.
Включайте знаки препинания в фигурные скобки, только если они являются частью задаваемой строки. Пишите знаки препинания вне фигурных скобок, если они являются частью английского текста@transnote{Или текста на каком-нибудь другом языке.}, окружающего строку. В нижеследующем предложении, например, запятые и точки находятся вне фигурных скобок:
В английском гласными являются @samp{a}, @samp{e}, @samp{i},
@samp{o}, @samp{u} и иногда @samp{y}.
Это дает:
В английском гласными являются `a', `e', `i', `o', `u' и иногда `y'.
@var{метасинтаксическая-переменная}
Используйте команду @var для обозначения метасинтаксических
переменных. Метасинтаксическая переменная -- это нечто,
обозначающее другой фрагмент текста. Например, вы должны использовать
метасинтаксическую переменную в документации функции для описания
передаваемых этой функции аргументов.
Не используйте @var для имен конкретных переменных в языках
программирования. Они являются определенными именами из программы,
поэтому для них правильным будет использовать @code
(see section @code{пример-кода}). Например, переменная Emacs Lisp
texinfo-tex-command -- не метасинтаксическая переменная; она
правильно форматируется с использованием @code.
Также не используйте @var для переменных среды; для них
необходима команда @env (смотрите следующий раздел).
Действие @var в Info-файле -- изменить регистр аргумента на
верхний; в печатном руководстве и HTML -- выводить аргумент наклонным
шрифтом.
Например,
Чтобы удалить файл @var{имя-файла},
напечатайте @samp{rm @var{имя-файла}}.
дает
Чтобы удалить файл имя-файла, напечатайте `rm имя-файла'.
(Заметьте, что @var может появиться внутри @code,
@samp, @file, etc.)
Пишите метасинтаксические переменные полностью строчными буквами, без пробелов, и используйте дефисы, чтобы облегчить чтение. Таким образом, исходный Texinfo-текст для иллюстрации того, как начинать руководство в Texinfo, выглядит так:
\input texinfo
@@setfilename @var{имя-info-файла}
@@settitle @var{название-руководства}
Это дает:
\input texinfo @setfilename имя-info-файла @settitle название-руководства
В некоторых стилях документации метасинтаксические переменные показывают в угловых скобках, например:
..., напечатайте rm <имя-файла>
Однако этот стиль не используется в Texinfo. (Вы можете, конечно, если
хотите, изменить исходный код `texinfo.tex' и команд форматирования
для Info, чтобы они выводили в формате <...>.)
@env{переменная-среды}
Используйте команду @env для обозначения переменных среды,
используемых во многих операционных системах, включая GNU. Не
используйте ее для метасинтаксических переменных; вместо этого
используйте @var (смотрите предыдущий раздел).
@env по действию эквивалентна @code. Например:
Переменная среды @env{PATH} задает путь поиска для команд.
дает
Переменная среды @env{PATH} задает путь поиска для команд.
@file{имя-файла}
Используйте команду @file для обозначения текста, являющегося
именем файла, буфера или каталога, или именем ноды в Info. Вы также
можете использовать эту команду для окончаний имен файлов. Не
используйте @file для символов в языке программирования;
используйте @code.
На данный момент @file по действию эквивалентна @samp.
Например,
Файлы @file{.el} находятся
в каталоге @file{/usr/local/emacs/lisp}.
дает
Файлы `.el' находятся в каталоге `/usr/local/emacs/lisp'.
@command{имя-команды}
Используйте команду @command для обозначения имен команд, таких
как @command{ls} или @command{cc}.
@command по своему действию эквивалентна @code.
Например:
Команда @command{ls} печатает список содержимого каталога.
дает
Команда @command{ls} печатает список содержимого каталога.
Вы должны писать название программы шрифтом для обычного текста, если вы употребляете его как новое слово английского языка, например `Emacs' или `Bison'.)
При написании полного вызова команды оболочки, как `ls -l', вам
следует использовать либо @samp, либо @code по своему
усмотрению.
@option{имя-ключа}
Используйте команду @option для обозначения ключей командной
строки, например @option{-l}, @option{--version} или
@option{--output=имя-файла}.
@option по действию эквивалентна @samp. Например:
Ключ @option{-l} выдает длинный список.
дает
Ключ @option{-l} выдает длинный список.
В таблицах ключи выглядят лучше, если размечать их с помощью
@code.
@dfn{термин}
Используйте команду @dfn для обозначения вводимого или
определяемого термина. Применяйте эту команду только в тех отрывках,
чья цель -- ввести термин, который будет использоваться впоследствии,
или с которым читатель должен быть знаком. Просто первое упоминание
термина не заслуживает @dfn. Эта команда выводит курсивом в
печатном руководстве и в двойных кавычках в Info-файле.
Например:
Избавление от файла называется @dfn{удалением}.
дает
Избавление от файла называется удалением.
Как правило, предложение, содержащее определяемый термин, должно быть его определением. Это предложение не обязано явно говорить, что оно является определением, но должно содержать информацию определения --- оно должно прояснять значение термина.
@cite{ссылка}
Используйте команду @cite для названий книг, для которых нет
сопутствующего Info-файла. Эта команда выводит курсивом в печатном
руководстве и в двойных кавычках в Info-файле.
Если книга написана в Texinfo, лучше использовать команды перекрестных
ссылок, чтобы читатель мог легко перейти по такой ссылке в Info.
See section Команда @xref.
@acronym{аббревиатура}
Используйте команду @acronym для аббревиатур, записанных
полностью заглавными буквами, таких как @acronym{NASA}. Аббревиатура
задается в качестве единственного аргумента в фигурных скобках, например
как `@acronym{NASA}'. По соображениям стиля или для
определенной аббревиатуры вы можете предпочесть использовать точки, как
здесь: `@acronym{Ф.Б.Р.}'.
В TeX и HTML аргумент печатается несколько уменьшенным шрифтом. В Info или простом текстовом выводе эта команда ничего не меняет.
@url{унифицированный-указатель-ресурса}
Используйте команду @url для обозначения унифицированных
указателей ресурсов в World Wide Web. Она аналогична @file,
@var, etc. и служит только для целей разметки. Она не создает
ссылку, по которой вы можете перейти в HTML-выводе (для этого
используйте команду @uref, see section @uref{url[, отображаемый-текст]}). Эта
команда полезна для url, не существующих на самом деле. Например:
Например, это мог бы быть url
@url{http://host.example.org/path}.
что дает:
Например, это мог бы быть url http://host.example.org/path.
@email{адрес[, отображаемый-текст]}
Используйте команду @email для обозначения адреса электронной
почты. Она принимает один обязательный аргумент, адрес, и один
необязательный, отображаемый текст (по умолчанию это сам адрес).
В Info и TeX адрес показывается в угловых скобках после заданного
отображаемого текста. В HTML, @email создает ссылку
`mailto', которая обычно вызывает окно составления письма.
Например:
Присылайте сообщения об ошибках по адресу
@email{bug-texinfo@@gnu.org}. Присылайте предложения по
@email{bug-texinfo@@gnu.org, тому же адресу}.
дает
Присылайте сообщения об ошибках по адресу bug-texinfo@gnu.org. Присылайте предложения по тому же адресу.
Обычно Texinfo изменяет шрифт для пометки слов в тексте в соответствии с
категорией, к которой принадлежат эти слова; примером этого служит
команда @code. Чаще всего это лучший способ пометки слов.
Однако, иногда вы можете захотеть выделить текст, не указывая его
категорию. В Texinfo для этого есть две команды. Также, в Texinfo есть
несколько команд для задания шрифта, которым TeX будет набирать
текст. Эти команды не затрагивают Info, и только одна из них, команда
@r, имеет обычное употребление.
@emph{текст} и @strong{текст}
Команды @emph и @strong используются для обозначения
логического ударения; @strong сильнее. В печатном выводе
@emph производит курсив, а @strong дает
жирный шрифт.
Например,
@quotation
@strong{Осторожно:} @samp{rm * .[^.]*} удаляет @emph{все}
файлы в каталоге.
@end quotation
дает в печатном выводе следующее:
Осторожно: `rm * .[^.]*' удаляет все файлы в каталоге.
и следующее в Info:
*Осторожно*: `rm * .[^.]*' удаляет _все_
файлы в каталоге.
Команда @strong используется редко, за исключением случаев,
когда нужно пометить нечто, являющееся в действительности
типографическим элементом, таким как слово `Осторожно' в предыдущем
примере.
В Info-файле, @emph окружает текст символами подчеркивания,
`_', а @strong помещает вокруг текста звездочки.
Осторожно: Не используйте
@strongсо словом `Note'; Info ошибочно примет это за перекрестную ссылку. Используйте вместо этого фразы вроде Please note или Caution.
@sc{текст}: Шрифт маленьких заглавных буквИспользуйте команду `@sc', чтобы получить текст, набранный в печатном выводе и в HTML шрифтом маленьких заглавных букв, а в Info-файле напечатанный заглавными буквами. Пишите желаемый текст строчными буквами в фигурных скобках, как здесь:
@sc{acm} и @sc{ieee} --- технические сообщества.
Это дает:
ACM и IEEE -- технические сообщества.
TeX набирает маленькие заглавные буквы так, чтобы буквы на странице не `выскакивали на вас'. Это облегчает чтение текста, набранного маленькими заглавными буквами по сравнению с набранным полностью в верхнем регистре, но обычно все-таки лучше использовать обычный текст смешанного регистра. Команды форматирования Info выводят текст маленьких заглавных букв в верхнем регистре. В HTML текст выводится заглавными буквами, и для его отображения используется меньший шрифт.
Если текст внутри фигурных скобок команды @sc в верхнем
регистре, TeX набирает его ПОЛНЫМИ ЗАГЛАВНЫМИ БУКВАМИ. Используйте
полные заглавные буквы умеренно или не используйте вообще; поскольку
бессмысленно помечать командой @sc текст, набранный полностью
заглавными буквами, @command{makeinfo} предупреждает о таких случаях.
Вы также можете применять шрифт маленьких заглавных букв для жаргонных слов, таких как ATO (слово из NASA, обозначающее `abort to orbit').
Есть некие тонкости в использовании шрифта маленьких заглавных букв с жаргонными словами, вроде CDR; это слово применяется в программировании на Лиспе. В таком случае вы должны использовать шрифт маленьких заглавных букв, когда это слово относится ко второму и последующим элементам списка (CDR списка), но должны использовать `@code', когда это слово относится к имени функции Лиспа с таким же написанием.
Texinfo предоставляет четыре команды, изменяющие шрифт в печатном
руководстве, но не влияющие на Info-файл. @i устанавливает
курсив (в некоторых версиях TeX используется наклонный шрифт),
@b устанавливает жирный шрифт, @t устанавливает
равноширинный шрифт в стиле печатной машинки, используемый
@code, а @r устанавливает романский шрифт, обычный
шрифт, которым печатается весь текст. Все четыре команды действуют на
следующий за ними аргумент, заключенный в фигурные скобки.
Частое применение находит только команда @r: в примерах программ
вы можете использовать команду @r для перевода комментариев из
равноширинного шрифта в романский. Это смотрится лучше в печатном
выводе.
Например,
@lisp
(+ 2 2) ; @r{Складывает два и два.}
@end lisp
дает
(+ 2 2) ; Складывает два и два.
По возможности избегайте использования трех остальных команд для шрифтов. Если вам понадобилась одна из них, это скорее всего указывает на пробел в языке Texinfo.
Цитаты и примеры -- это фрагменты текста, состоящие из одного или более полных абзацев, которые выделяются среди остального текста и обрабатываются особо. Обычно для них делается отступ.
В Texinfo вы всегда начинаете цитату или пример, написав @-команду в
начале отдельной строки, и завершаете написанием команды @end
также в начале отдельной строки. Скажем, вы начинаете пример, записывая
с новой строки команду @example, и завершаете написанием команды
@end example на отдельной строке так же в ее начале.
Вот команды для цитат и примеров, рассмотренные подробнее в следующих разделах:
@quotation
@example
@smallexample
@example,
только в TeX эта команда набирает текст более мелким шрифтом для
формата @smallbook, меньшего, чем формат 8.5 на 11
дюймов.
@lisp
@example, но специально для иллюстрации кода на Лиспе.
Текст печатается равноширинным шрифтом и смещается вправо, но не
заполняется.
@smalllisp
@lisp, что и @smallexample для
@example.
@display
@smalldisplay
@display, что и @smallexample для
@example.
@format
@display (текст не заполняется, шрифт не изменяется), но
отступ не делается.
@smallformat
@format, что и @smallexample для
@example.
Внутри перечисленных конструкций можно использовать команду
@exdent для отмены смещения строки вправо.
Команды @flushleft и @flushright служат для выравнивания
незаполненного текста по левому или правому полю.
После перечисленных конструкций можно использовать команду
@noindent для предотвращения смещения вправо последующего
текста как нового абзаца.
Для выделения примера или цитаты вы можете использовать с одной из
вышеперечисленных конструкций команду @cartouche, которая
нарисует вокруг них рамку с закругленными углами. See section Рисование рамок вокруг примеров.
@quotationТекст цитаты обрабатывается как обычно за следующими исключениями:
Это пример текста, написанного между командами
@quotationи@end quotation. Команда@quotationчаще всего применяется для обозначения того, что данный фрагмент текста взят из другого (настоящего или гипотетического) печатного произведения.
Пишите команду @quotation на отдельной строке. Эта строка
исчезнет при выводе. Отмечайте конец цитаты строкой, начинающейся
командой @end quotation и не содержащей ничего больше. Строка
@end quotation также не выводится. Таким образом, такой
текст:
@quotation Это нечто. @end quotation
дает при выводе
Это нечто.
@example
Команда @example применяется для обозначения примера, не
являющегося частью текущего текста, например компьютерного вывода и
ввода.
Это пример текста, записанного между командой@exampleи командой@end example. В этом тексте сделаны отступы, но не сделано заполнение. В печатном руководстве этот фрагмент текста набран равноширинным шрифтом, и существенно наличие дополнительных пробелов и пустых строк. В Info-файле аналогичный результат достигается смещением каждой строки на пять позиций вправо.
Пишите команду @example в начале отдельной строки. Отмечайте
конец примера командой @end example также записанной в начале
отдельной строки.
Например,
@example mv foo bar @end example
дает
mv foo bar
Строки, содержащие @example и @end example, не
выводятся. Чтобы вывод смотрелся хорошо, вы должны поместить пустую
строку перед командой @example и другую после @end
example. Заметьте, что все пустые строки внутри блока @example
появятся при выводе.
Внимание: Не используйте символы табуляции внутри текста примера (и вообще в Texinfo-файлах)! TeX воспринимает символы табуляции как один пробел, и это не похоже на табуляцию. Это проблема TeX. (Если необходимо, вы можете использовать M-x untabify в Emacs для превращения всех символов табуляции в области в пробелы.)
Примеры часто находятся, говоря логически, "в середине" абзаца, и
текст, следующий после примера, не должен смещаться вправо. Команда
@noindent предотвращает отступ во фрагменте текста, как в новом
абзаце.
(Для примеров, включенных в предложение, а не отделенных от
предшествующего и последующего текста, применяется команда
@code. See section @code{пример-кода}.)
@noindent
Пример или другое включение может разбить абзац на сегменты. Обычно
форматирующие программы делают в тексте, следующем после примера,
отступ, как в начале нового абзаца. Однако вы можете предотвратить это,
написав перед этим текстом команду @noindent в начале отдельной
строки.
Например:
@example
Это пример
@end example
@noindent
В этой строке нет отступа. Как вы видите, начало этой строки
смещено до предела влево, как и в следующей строке. (Весь пример
целиком заключен между @code{@@display} и @code{@@end display}.)
дает при выводе
Это примерВ этой строке нет отступа. Как вы видите, начало этой строки смещено до предела влево, как и в следующей строке. (Весь пример целиком заключен между@displayи@end display.)
При точной настройке числа пустых строк в выводе Info, помните, что
строка, содержащая @noindent, не производит пустую строку, как и
строка @end example.
В исходном Texinfo-файле этого руководства перед каждой строкой,
говорящей `дает', написана строка с командой @noindent.
Не пишите фигурные скобки после команды @noindent; они не
обязательны, так как @noindent используется вне абзаца
(see section Синтаксис @-команд).
@lisp
Для примеров на Лиспе используется команда @lisp. Она является
синонимом команды @example.
Это пример текста, написанного между командами@lispи@end lisp.
Используйте команду @lisp вместо @example, чтобы
сохранить информацию о природе примера. Это полезно, например, если вы
пишите функцию, вычисляющую весь Лисп-код в Texinfo-файле. После этого
вы можете использовать Texinfo-файл в качестве библиотеки
Лиспа.(7)
Отмечайте конец блока @lisp командой @end lisp,
записанной на отдельной строке.
@small...
Кроме обычных команд @example и @lisp в Texinfo
определены "маленькие" команды в стиле примера. Это команды
@smalldisplay, @smallexample, @smallformat и
@smalllisp. Все они разработаны для использования вместе с
командой @smallbook, заставляющей TeX выводить печатную книгу
в формате 7 на 9.25 дюймов, а не в обычном формате 8.5 на 11.
В TeX, команды @small... набирают текст для маленького
формата @smallbook более мелким шрифтом, чем для формата 8.5 на
11 дюймов. Следовательно, многие примеры, содержащие длинные строки,
умещаются на более узкой странице формата @smallbook без
необходимости укорочения. Обе команды набирают текст шрифтом обычного
размера, когда вы форматируете для формата размером 8.5 на 11 дюймов; на
самом деле, в этой ситуации команды @small... определены
эквивалентными соответствующим командам без small.
В Info команды @small... эквивалентны соответствующим
командам без small.
Помечайте конец блока @small... парной командой @end
small.... Например, пишите для @smallexample парную ей
@end smallexample.
Вот пример тектса, написанный маленьким шрифтом, используемым командами
@smallexample и @smalllisp:
Команды @small... облегчают подготовку руководств меньшего
формата, избавляя вас от необходимости ручного редактирования примеров
таким образом, чтобы они умещались на более узких страницах.
Обычно печатный документ смотрится лучше, если вы используете в главе
только одну из команд, к примеру, или @example, или
@smallexample. Как можно реже используйте оба формата
вперемежку.
See section Печать "маленьких" книг, для получения подробной
информации о команде @smallbook.
@display и @smalldisplay
Команда @display начинает текст, подобный примеру. Она похожа
на команду @example, только команда @display не
использует в печатном руководстве равноширинный шрифт. На самом деле,
она не задает никакого шрифта, то есть текст выводится тем же шрифтом,
каким бы он выводился без команды @display.
Это пример текста, написанного между командами@displayи@end display. Команда@displayделает в тексте отступы, но не заполняет его.
Texinfo также предоставляет команду @smalldisplay, которая
похожа на @display но использует в формате @smallbook
меньший шрифт. See section Команды блоков @small....
@format и @smallformat
Команда @format похожа на команду @example за
исключением того, что @format не сужает поля.
Это пример текста,
написанного между командами
@format и @end format.
Как вы видите
из этого примера, команда
@format не заполняет текст.
Texinfo также предоставляет команду @smallformat, которая похожа
на @format, но использует в формате @smallbook меньший
шрифт. See section Команды блоков @small....
@exdent: Отмена отступа в строке
Команда @exdent убирает все отступы, которые могут появиться в
строке. Эта команда пишется в начале строки и действует только на
текст, следующий за ней на той же строке. Не заключайте текст в
фигурные скобки. В печатном руководстве текст на строке @exdent
выводится романским шрифтом.
@exdent обычно применяется в примерах. Таким образом,
@example Эта строка написана после команды @@example. @exdent В этой строке отменен отступ. Эта строка написана после строки с отмененным отступом. @@end example идет на следующей строке.
дает
Эта строка написана после команды @example. В этой строке отменен отступ. Эта строка написана после строки с отмененным отступом. @end example идет на следующей строке.
На практике команда @exdent применяется редко. Обычно отступ отменяется
завершением примера и возвратом к обычной ширине страницы.
@flushleft и @flushright
Команды @flushleft и @flushright выравнивают концы строк по
левому и правому краю страницы, но не заполняют текст. Эти команды пишутся на
отдельных строках, без фигурных скобок. Действие команд @flushleft и
@flushright прекращается командами @end flushleft и @end
flushright, написанными на отдельных строках.
Например,
@flushleft Этот текст прижат влево. @end flushleft
дает
Этот текст прижат влево.
@flushright создает тип отступов, часто используемый для обратного
адреса в письмах. Например,
@flushright
Вот пример текста, прижатого
вправо. Команда @code{@flushright}
смещает каждую строку к правому краю, но
оставляет левые концы неровными.
@end flushright
дает
Вот пример текста, прижатого
вправо. Команда @flushright
смещает каждую строку к правому краю, но
оставляет левые концы неровными.
Команда @cartouche рисует в печатном руководстве рамку с
закругленными углами вокруг своего содержимого. Вы можете использовать
эту команду для большего выделения примера или цитаты. Например, вы
можете написать руководство, в котором какой-нибудь тип примеров
окружается рамкой для заострения внимания читателя.
@cartouche влияет только на печатное руководство; она не играет
роли в других выходных форматах.
Например,
@example @cartouche % pwd /usr/local/share/emacs @end cartouche @end example
заключает пример из двух строк в рамку с закругленными углами в печатном руководстве.
В печатном руководстве этот пример выглядит следующим образом:
% pwd /usr/local/lib/emacs/info
В Texinfo есть несколько способов создать перечень или таблицу. Перечни могут быть простыми или нумерованными, в таблицах из двух колонок можно выделить элементы первой колонки; поддерживаются также таблицы с многими колонками.
Texinfo автоматически делает отступы в тексте перечней или таблиц и нумерует перечни, если это необходимо. Последнее свойство полезно, если вы изменяете перечень, так как вам не придется перенумеровывать его вручную.
Нумерованные перечни и таблицы начинаются подходящей @-командой в
начале строки и завершаются соответствующей командой @end,
написанной на отдельной строке. Команды для таблиц также требуют, чтобы
вы написали информацию о стиле форматирования на той же строке, где
находится начинающая @-команда.
К примеру, нумерованный перечень начинается командой @enumerate
и завершается командой @end enumerate. Начинайте простой
перечень командой @itemize, за которой следует форматирующая
команда, например @bullet, и завершайте командой @end
itemize.
Перед каждым пунктом перечня пишите команду @item или
@itemx.
Вот пример простого перечня различных видов таблиц и перечней:
Это нумерованный перечень с теми же пуктами::
А это двухколоночная таблица с теми же пунктами и их @-командами:
@itemize
@enumerate
@table
@ftable
@vtable
@itemize: создание простых перечней
Команда @itemize создает последовательность абзацев с отступами;
на левом поле выводится "горошина" или другой значок в начале каждого
абзаца, для которого такой значок нужен.
Начинайте простой перечень, записывая команду @itemize в начале
строки. После этой команды пишите символ или команду Texinfo, создающую
значок. Обычно после @itemize вы будете писать @bullet,
но вы также можете использовать @minus или любую команду или
знак, превращающийся в Info-файле в одиночный знак. Если вы не хотите
меток вообще, используйте @w. (Когда вы пишите команду-значок,
такую как @bullet или @minus, после команды
@itemize, вы можете опустить `{}'.) Если вы не
указываете команду для создания значка, по умолчанию используется
@bullet.
Пишите текст самих абзацев после @itemize вплоть до строки,
содержащей команду @end itemize.
Перед каждым абзацем, для которого нужен значок на поле, пишите строку,
содержащую только команду @item. После @item можно
писать другой текст.
Обычно вы должны помещать перед командой @item пустую строку.
Это создаст пустую строку в Info-файле. (TeX в любом случае вставит
между строк подходящий пропуск.) За исключением случаев, когда пункты
очень короткие, пустые строки улучшают внешний вид перечня.
Ниже приведен пример использования команды @itemize и
порождаемый им вывод. @bullet создает в Info символ `*', а
в TeX круглую точку ("горошину").
@itemize @bullet @item Какой-то текст. @item Какой-то другой текст. @end itemize
Это дает:
- Какой-то текст.
- Какой-то другой текст.
Простые перечни можно включать в другие перечни. Вот перечень, помеченный дефисами, включенный в перечень, помеченный "горошинами":
@itemize @bullet @item Первый пункт. @itemize @minus @item Внутренний пункт. @item Второй внутренний пункт. @end itemize @item Второй внешний пункт. @end itemize
Это дает:
- Первый пункт.
- Внутренний пункт.
- Второй внутренний пункт.
- Второй внешний пункт.
@enumerate: создание нумерованных перечней
Команда @enumerate похожа на @itemize (see section @itemize: создание простых перечней), только помечает пункты последовательными целыми
числами или буквами, а не "горошинами".
Пишите команду @enumerate в начале строки. Эта команда не
требует аргумента, но ей можно передать в качестве параметра число или
букву. Без аргумента, @enumerate начинает перечень с номера
`1'. С числовым аргументом, например `3', она начинает
перечень с этого номера. С аргументом в виде строчной или прописной
буквы, например `a' или `A', она начинает перечень с этой
буквы.
Пишете текст нумерованного перечня так же, как и текст простого:
помещайте команду @item на отдельной строке перед началом
каждого абзаца, который должен быть пронумерован. Не пишите другого
текста на строке, начинающейся с @item.
Между пунктами перечня вам стоит помещать пустые строки. Как правило это облегчает чтение Info-файла.
Вот пример использования @enumerate без аргумента:
@enumerate @item Глубинные причины. @item Поверхностные причины. @end enumerate
Это дает:
Вот пример с аргументом 3:
@enumerate 3 @item Предрасполагающие причины. @item Подталкивающие причины. @item Увековечивающие причины. @end enumerate
Это дает:
Ниже приведен краткий обзор возможностей. Обзор составлен в виде
перечня с использованием @enumerate с аргументом
a.
@enumerate
Без аргумента, создает нумерованный перечень начиная с номера 1.
@enumerate положительное-целое
С числовым (положительным) аргументом, начинает нумерованный перечень с
заданного номера. Вы можете использовать это для продолжения перечня,
прерванного другим текстом.
@enumerate прописная-буква
С аргументом в виде прописной буквы, начинает перечень, в котором пункты
помечаются буквами начиная с заданной.
@enumerate строчная-буква
С аргументом в виде строчной буквы, начинает перечень, в котором пункты
помечаются буквами начиная с заданной.Вы также можете делать вложенные нумерованные перечни, подобные схеме текста.
Команда @table похожа на @itemize (see section @itemize: создание простых перечней), но позволяет задать название или заголовок для
каждого пункта. Эта команда используется для создания двухколоночных
таблиц и особенно полезна для глоссариев, пояснений и обзоров ключей
командной строки.
Пишите команду @table в начале строки и на той же строке пишите
ее аргумент, который является "обозначающей" командой Texinfo, такой
как @code, @samp, @var, или @kbd
(see section Обозначение определений, команд, etc.). Хотя обычно этим командам нужно задавать
аргумент в фигурных скобках, в данном случае вы должны писать имя
команды без аргумента, так как аргумент предоставит команда
@item. Эта команда применяется к тексту, идущему в первой
колонке каждого пункта, и определяет стиль выделения этого текста.
Например, если вы напишете @code, то текст первой колонки будет
выделяться командой @code.
Вы также можете предпочесть использовать в качестве аргумента для
@table команду @asis. Команда @asis ничего не
делает; если вы примените ее после @table, TeX и команды
форматирования для Info будут выводить текст первых колонок не производя
выделение ("как есть").
(Команда @table может работать и другими командами, не
перечисленными здесь. Однако вы можете использовать только те команды,
которые обычно принимают аргументы в фигурных скобках.)
Начинайте каждый пункт таблицы командой @item в начале строки.
На той же строке где и @item пишите текст первой колонки. На
следующих строках пишите текст второй колонки. (Для пустого вхождения
второй колонки вам ничего не нужно печатать.) Вы можете писать столько
строк иллюстративного текста, сколько захотите, даже несколько абзацев.
Но только текст из строки с командой @item будет помещен в
первую колонку, включая все сноски.
Обычно перед строкой @item стоит помещать пустую строку. Это
создаст пустую строку в Info-файле. За исключением случаев, когда
пункты очень короткие, пустые строки смотрятся лучше.
В приведенной ниже таблице текст первой колонки выделяется с помощью
команды @samp.
@table @samp
@item foo
Это текст для
@samp{foo}.
@item bar
Текст для @samp{bar}.
@end table
Это дает:
Если вы хотите описать два или более именованных пункта одним блоком
текста, используйте команду @itemx. (See section @itemx.)
@ftable и @vtable
Команды @ftable и @vtable действуют так же, как и
команда @table, за исключением того, что @ftable
автоматически вносит каждый пункт в первой колонке в указатель функций,
а @vtable -- в указатель переменных. Это упрощает задачу
создания именных указателей. В именной указатель вносятся только пункты
из той строки, где написана команда @item, и именно в той форме,
в какой они записаны в этой строке. See section Именные указатели, для получения подробной информации об именных
указателях.
Начинайте таблицу из двух колонок, использующую @ftable или
@vtable, написав в начале строки эту @-команду и, на той же
строке, команду Texinfo, такую как @code, точно так же, как вы
написали бы для команды @table. Завершайте таблицу командой
@end ftable или @end vtable на отдельной строке.
Пример использования @table смотрите в предыдущем разделе.
@itemx
Используйте в таблице команду @itemx, когда для одного пункта у
вас есть два или более вхождения в первой колонке, каждое из которых
должно появиться на отдельной строке. Команда @itemx может
применяться для всех вхождений, кроме первого; @itemx всегда
должна идти после команды @item. Команда @itemx
действует точно так же, как и @item, но не создает
дополнительного вертикального пропуска над текстом первой колонки.
Например,
@table @code @item upcase @itemx downcase Две эти команды принимают в качестве аргумента символ или строку и возвращают соответствующий символ или строку в верхнем (нижнем) регистре. @end table
Это дает:
upcase
downcase
(Обратите также внимание, этот пример иллюстрирует многострочный поясняющий текст в двухколоночной таблице.)
Команда @multitable позволяет создавать таблицы с произвольным
числом колонок, каждая из которых имеет нужную вам ширину.
Вы определяете ширину колонок в самой строке @multitable и
пишите каждую строку самой таблицы после команды @item, разделяя
колонки командой @tab. Наконец, @end multitable
завершает таблицу. Подробности описаны в следующих разделах.
Вы можете задать ширину колонок многоколоночной таблицы двумя способами:
долей от длины строки или строкой--прототипом. Одновременное применение
двух этих методов не поддерживается. В обоих случаях ширины всех
колонок задаются в той же строке, где записана команда
@multitable.
@columnfractions и десятичные числа (предположительно меньшие
единицы) после команды @multitable, как здесь:
@multitable @columnfractions .33 .33 .33Доли не обязательно должны давать в сумме точно 1.0, как например эти. Это позволяет вам создавать таблицы, которые не требуют полной длины строки. Вы можете писать первой цифрой ноль, если хотите.
@multitable
самое длинное вхождение для каждой колонки, заключенное в фигурные
скобки. Например:
@multitable {текст для первой колонки} {для второй колонки}
Тогда первая колонка будет иметь ширину набранной строки `текст
для первой колонки', а вторая -- ширину `для второй колонки'.
Вхождения прототипа не обязательно должны появиться в самой таблице.
Хотя в этом примере мы использовали простой текст, вхождения прототипа
могут содержать команды Texinfo; вероятно, особенно полезны будут
команды вроде @code.
После команды для @multitable, задающей ширину колонок (смотрите
предыдущий раздел), вы начинаете каждую строку в теле таблицы командой
@item и разделяете вхождения колонок командой @tab.
Разрывы строк не обрабатываются особо в теле таблицы, и вы можете при
необходимости разбивать входные строки в исходном файле.
Вот полный пример таблицы из нескольких колонок (текст из Руководства по GNU Emacs, @xref{Разделение окон, , , @external{emacs}, Руководство по The GNU Emacs}):
@multitable @columnfractions .15 .45 .4
@item Ключ @tab Команда @tab Описание
@item C-x 2
@tab @code{split-window-vertically}
@tab Разделить выбранное окно на два,
находящихся одно над другим.
@item C-x 3
@tab @code{split-window-horizontally}
@tab Разделить выбранное окно на два,
находящихся одно рядом с другим.
@item C-Mouse-2
@tab
@tab На строке режима или полосе прокрутки окна,
разделить это окно.
@end multitable
дает:
| Ключ | Команда | Описание |
| C-x 2 | split-window-vertically
| Разделить выбранное окно на два, находящихся одно над другим. |
| C-x 3 | split-window-horizontally
| Разделить выбранное окно на два, находящихся одно рядом с другим. |
| C-Mouse-2 | На строке режима или полосе прокрутки окна, разделить это окно. |
Используя Texinfo, вы можете создавать именные указатели без необходимости ручной сортировки и упорядочения. Вхождения в именном указателе перечисляются в алфавитном порядке, вместе с информацией о том, где найти рассмотрение каждого вопроса. В печатном руководстве эта информация заключается в номерах страниц. В Info-файле это пункт меню, ведущий в первой ноде, где было внесено это вхождение.
Texinfo предоставляет несколько предопределенных видов именных указателей: указатель функций, указатель переменных, указатель понятий и другие. Вы можете объединять именные указатели или использовать их по другому назначению, отличному от обычного. Если вы захотите, вы можете определить свои собственные именные указатели.
Когда вы создаете вхождения именного указателя, вам стоит помнить о том, что люди могут искать что-то по разному. Разные люди думают о разных словах, когда они что-нибудь ищут. Хороший именной указатель перечисляет вхождения по всем различным словам, которые люди могут использовать для поиска. Например, один читатель может считать очевидным, что двухбуквенные названия именных указателей должны быть перечислены как "Именные указатели, двухбуквенные названия", так как фраза "Именной указатель" -- это общее понятие. Но другой читатель может помнить об особом понятии о двухбуквенных названиях и пытаться найти эту тему как "Двухбуквенные названия именных указателей". Хороший указатель предоставит оба вхождения и поможет обоим читателям.
Так же, как и верстка, составление именных указателей -- это профессиональное искусство, требующее высокой квалификации,тонкости которого непонятны, пока вам самим не доведется им заняться.
See section Меню-указатели и печать именных указателей, для получения информации о печати именных указателей в конце книги или создании меню-указателей в Info-файле.
Texinfo предоставляет шесть предопределенных именных указателей:
Не в каждом руководстве нужны все шесть, большинство использует два или
три из них. В этом руководстве два именных указателя: указатель понятий
и указатель @-команд (который на самом деле является указателем
функций, но назван в заголовке указателем команд). Два или более
указателя могут быть объединены в один при помощи команды
@synindex или @syncodeindex. See section Объединение именных указателей.
Данные для составления именного указателя исходят от многих команд, вносящих вхождения, разбросанных по всему исходному Texinfo-файлу. Каждая команда добавляет одно вхождение в некоторый именной указатель; после форматирования указатель будет сообщать номер страницы или имя ноды в качестве ссылки.
Вхождение указателя состоит из вносящей это вхождение команды, расположенной в начале строки, за которой на оставшейся части строки следует само вхождение.
Например, этот раздел начинается следующими пятью вхождениями для указателя понятий:
@cindex Добавление вхождений именных указателей @cindex Вхождения именных указателей @cindex Именные указатели, вхождения @cindex Определение вхождений именных указателей @cindex Создание вхождений именных указателей
Каждый из предопределенных именных указателей имеет свою команду для
добавления вхождений; для указателя функций это @findex и так
далее.
Вхождения указателя понятий состоят из текста. Наилучшим способом написать именной указатель будет выбирать вхождения короткие, но ясные. Если это возможно, вхождения будут смотрятся лучше, если писать каждое слово с не заглавной буквы, а так, как оно писалось бы в предложении. (Пишите с заглавной буквы имена собственные и аббревиатуры, которые всегда должны писаться заглавными буквами.) Эти соглашения об использовании заглавных букв мы применяем в большинстве именных указателей в руководствах GNU.
Если вам не удается сделать вхождение кратким и при этом ясным, сделайте его более длинным и ясным, а не коротким и непонятным. Если многие вхождения состоят из нескольких слов, именной указатель может смотреться лучше, если вы будете использовать другое соглашение: писать первое слово каждого вхождения с заглавной буквы. Но не пишите с заглавной буквы регистрозависимые названия, такие как имена функций Лиспа или Си или команды оболочки, это может быть синтаксической ошибкой.
Какого бы соглашение об использовании заглавных букв вы не придерживались, пожалуйста, придерживайтесь его постоянно!
Вхождения в других именных указателях, не в указателе понятий, -- это имена символов языков программирования или названия программ; эти названия обычно регистрозависимы, поэтому используйте заглавные и строчные буквы так, как требуется.
По умолчанию вхождения указателя понятий печатаются маленьким романским
шрифтом, а вхождения других указателей -- маленьким шрифтом,
используемым командой @code. Вы можете изменить вид части
вхождения с помощью обычных команд Texinfo, например @file для
имен файлов и @emph для обозначения логического ударения
(see section Пометка слов и фраз).
Предопределены шесть команд добавления вхождения к именному указателю:
@cindex понятие
@findex функция
@vindex переменная
@kindex клавиша
@pindex программа
@tindex тип данных
Внимание: Не используйте двоеточия в тексте вхождения. В Info двоеточие отделяет название пункта меню от имени ноды, поэтому двоеточие в самом вхождении введет Info в заблуждение. See section Составные части меню, для получения большей информации о структуре пунктов меню.
На самом деле вы не обязаны использовать предопределенные именные
указатели по их обычному назначению. Например, предположим, что вы
хотите перечислить некоторые макросы препроцессора Си. Вы можете
поместить их в указатель функций вместе с настоящими функциями, просто
записывая для них команду @findex; затем, при печати "Указателя
функций" как ненумерованной главы, вы можете дать ему название
"Указатель функций и макросов", и с точки зрения читателя все будет
согласовано. Или вы могли бы поместить макросы вместе с типами данных,
записывая для них команду @tindex и потом дав этому указателю
подходящее название, чтобы читатель вас понял. (See section Меню-указатели и печать именных указателей.)
Иногда вы можете пожелать объединить два разных именных указателя, например указатели функций и понятий, возможно, потому что один из них получится слишком маленьким, если поместить его отдельно, и это будет смотреться довольно неудачно.
Вы можете поместить функции в указатель понятий, записывая для них
команду @cindex вместо команды @findex, и создать
согласованное руководство, напечатав указатель понятий под заголовком
`Указатель понятий и функций' и не печатая `Указатель функций' вовсе; но
это ненадежный метод. Он работает, только если ваш документ никогда не
включается как часть в другой документ, который разрабатывался с
отдельным указателем функций; если же вам придется включить его в такой
документ, то функции из вашего документа и из другого не будут собраны
вместе. Кроме того, чтобы названия функций печатались в указателе
понятий правильным шрифтом, вы должны будете заключить каждую из них
между фигурными скобками команды @code.
@syncodeindex
Когда вы хотите объединить указатели понятий и функций в один, вы должны
перечислять функции с помощью команды @findex, а понятия с
помощью команды @cindex, и использовать команду
@syncodeindex для перенаправления вхождений указателя функций в
указатель понятий.
Команда @syncodeindex принимает два аргумента: название именного
указателя, подлежащего перенаправлению, и название указателя, в который
он перенаправляется. Шаблон выглядит так:
@syncodeindex источник назначение
Для этой цели именным указателям присвоены двухбуквенные названия:
Пишите команду @syncodeindex до или вскоре после строки
end-of-header в начале Texinfo-файла. Например, чтобы объединить
указатель функций с указателем понятий, напишите следующее:
@syncodeindex fn cp
Это приведет к тому, что все вхождения, предназначенные для указателя функций, войдут вместо этого в указатель понятий.
Для объединения указателей переменных и функций с указателем понятий напишите следующее:
@syncodeindex vr cp @syncodeindex fn cp
Команда @syncodeindex помещает все вхождения из
указателя-`источника' (перенаправляемого именного указателя)
напечатанными шрифтом @code, заменяя шрифт, используемый по
умолчанию для именного указателя, в который перенаправлены вхождения
этого. Таким образом, если вы перенаправили имена функций из указателя
функций в указатель понятий, все они будут напечатаны шрифтом
@code, как и ожидалось.
@synindex
Команда @synindex делает почти то же самое, что и команда
@syncodeindex, но не помещает вхождения из источника со шрифтом
@code; вместо него она использует романский шрифт. Таким
образом, вы должны использовать @synindex, когда перенаправляете
указатель понятий в указатель функций.
See section Меню-указатели и печать именных указателей, для получения информации о печати именного указателя в конце книги или создании меню-указателей в Info-файле.
В дополнение к предопределенным именным указателям, вы можете сами
определять именные указатели с помощью команд @defindex и
@defcodeindex. Эти команды создают новые @-команды для
добавления вхождения к именному указателю, которыми вы помечаете
вхождения. Команда @defindex используются следующим
образом:
@defindex название
Название именного указателя должно быть словом из двух букв, таким как `au'. Например:
@defindex au
Здесь определяется новый именной указатель, называемый `au'. В то
же время создается новая команда добавления к указателю,
@auindex, которую вы можете использовать для создания вхождений
в именной указатель. Новая команда добавления к указателю используется
точно так же, как и предопределенные команды.
Например, вот заголовок раздела, за которым следует вхождение указателя понятий и два вхождения указателя `au'.
@section Познавательная семантика @cindex Схемы кинестетических отображений @auindex Джонсон, Марк @auindex Лакоф, Джордж
(Очевидно, в данном примере `au' служит сокращением слова
"author" (автор).) Texinfo конструирует новую команду добавления к
именному указателю, приписывая к названию указателя строку `index';
таким образом, определение именного указателя `au' приводит к
автоматическому созданию команды @auindex.
Для печати именного указателя используйте команду @printindex,
как и для предопределенных именных указателей. Например:
@node Author Index, Subject Index, , Top @unnumbered Авторы @printindex au
Команда @defcodeindex похожа на @defindex, но печатает
вхождения шрифтом @code, а не романским. То есть она создает
аналог команды @findex, а не @cindex
Вы должны определять новые именные указатели внутри или сразу после
строки Texinfo-файла end-of-header, до любой команды @synindex
или @syncodeindex (see section Заголовок Texinfo-файла).
Texinfo предоставляет несколько команд для вставки символов, имеющих в Texinfo особое значение, таких как фигурные скобки, и для других графических элементов, не совпадающих с простыми литерами, которые вы можете напечатать.
К ним относятся:
`@' и фигурные скобки являются в Texinfo специальными символами. Чтобы вставить эти символы так, чтобы они появились в тексте, вы должны помещать перед ними `@', чтобы уберечь Texinfo от неправильной их интерпретации.
Не помещайте после этих команд фигурные скобки, они не нужны.
@@ обозначает один символ `@' при выводе как на печать,
так и в Info.
Не пишите после команды @@ фигурные скобки.
@{ обозначает один символ `{' при выводе как на печать,
так и в Info.
@} обозначает один символ `}' при выводе как на печать,
так и в Info.
Не пишите после команд @{ и @} фигурные скобки.
Последующие разделы описывают команды, которые управляют разного рода пробелами внутри или вокруг предложений.
В зависимости от того, стоит ли точка или восклицательный или вопросительный знак в середине или в конце предложения, в печатном руководстве после них вставляется меньший или больший пробел. Поскольку не всегда можно определить, когда точка завершает предложение, а когда используется для сокращения, в некоторых обстоятельствах требуются специальные команды. Обычно Texinfo может догадаться, как обрабатывать точки, так что вам необязательно использовать специальные команды; просто вводите точки так же, как если бы вы использовали печатную машинку, то есть ставьте два пробела после точки, вопросительного или восклицательного знака, завершающего предложение.
Используйте команду @: после точки, вопросительного или
восклицательного знака или двоеточия, после которых не должен стоять
дополнительный пробел. Например, используйте @: после точек,
завершающих сокращения и не стоящих в конце предложения.
Например,
S.o.p.@: состоит из трех частей ... S.o.p. состоит из трех частей ...
дает следующее. Если вы внимательно приглядитесь к напечатанному результату, то увидите во второй строке несколько больший пробел после `s.o.p.'.
S.o.p. состоит из трех частей ...
S.o.p. состоит из трех частей ...
(Кстати, `s.o.p.' -- это сокращение от "Standard Operating Procedure" (стандартная процедура действий).)
@: не влияет на вывод Info. Не пишите фигурные скобки после
@:.
Используйте @. вместо точки, @! вместо
восклицательного знака и @? вместо вопросительного знака в
конце предложения, заканчивающегося отдельной заглавной буквой. Иначе
TeX сочтет эту букву сокращением и не вставит правильный пробел для
конца предложения. Вот пример:
Дать это M.I.B. и M.E.W@. Также, дать это R.J.C@. Дать это M.I.B. и M.E.W. Также, дать это R.J.C.
дает нижеследующее. Если вы внимательно приглядитесь к напечатанному результату, то увидите в первой строке несколько больший пробел после `W'.
Дать это M.I.B. и M.E.W. Также, дать это R.J.C.
Дать это M.I.B. и M.E.W. Также, дать это R.J.C.
При выводе в Info-файл @. эквивалентна просто `.';
аналогично для @! и @?.
Командам Texinfo @: и @. даны именно такие имена,
чтобы они хорошо работали с командами Emacs для перемещения по
предложениям. (@pxref{Предложения,,, @external{emacs}, Руководство по
GNU Emacs}).
Не пишите фигурные скобки после любой из этих команд.
Обычно TeX сворачивает повторяющиеся пробельные символы (пробел, табуляция и новая строка) в один пробел. Вывод для Info, с другой стороны, сохраняет пропуски такими, как вы их напечатали, только заменяет перевод строки на пробел; именно поэтому важно помещать два пробела в конце предложений в документах Texinfo.
Иногда вы можете захотеть действительно вставить несколько пробелов
подряд для примера (что делает ваша программа с несколькими введенными
пробелами) или просто для улучшения внешнего вида заголовков перечней.
Texinfo поддерживает три команды: @SPACE,
@TAB и @NL, каждая из которых вставляет на
выходе один пробел. (Здесь @SPACE представляет символ
`@', за которым идет пробел, то есть `@ ', а TAB и
NL представляют символы табуляции и символ конца строки, то есть
когда `@' стоит последним на строке.)
Например,
Пример@ @ @ @ с пробелами.
дает
Пример с пробелами.
Другие возможные применения @SPACE реализует команда
@multitable (see section Таблицы из многих колонок).
Не пишите фигурные скобки после любой из этих команд.
@dmn{размер}: Форматирование размеров
Иногда вам может понадобиться написать `12pt' или
`8.5in' с маленьким пробелом или без пробела между числом и
сокращенным названием единицы измерения. Для этого вы можете
использовать команду @dmn. Встретив эту команду, TeX
вставляет точно необходимый для правильного набора пропуск; команды
форматирования Info не вставляют пробела совсем, так как он не требуется
в Info-файле.
Чтобы применить команду @dmn, напишите число и сразу после него,
без промежуточного пробела, @dmn, а затем единицу измерения в
фигурных скобках. Например,
Формат A4 имеет ширину 8.27@dmn{in}.
дает
Формат A4 имеет ширину 8.27in.
Не все придерживаются этого стиля. Некоторые предпочитают писать в
Texinfo-файле `8.27 in.@:' или `8.27 дюймов' вместо
`8.27@dmn{in}'. Однако, в таких случаях форматирующие программы
могут разорвать строку между числом и единицей измерения, поэтому
используйте @w (see section @w{текст}: Предотвращение разрывов строк). Также, если вы пишите точку после
сокращения в середине предложения, вы должны написать после нее
`@:', чтобы TeX не вставил дополнительный пробел, как показано
здесь. See section Незавершение предложения.
Ниже приведена таблица команд, предоставляемых Texinfo для вставки
плавающих акцентов. Команды с небуквенными именами не требуют фигурных
скобок вокруг аргумента (которым считается следующий символ).
(Исключение: @, требует фигурные скобки вокруг
аргумента.) Это сделано для того, чтобы исходный текст было читать как
можно удобнее, так как символы с акцентами очень часты в некоторых
языках.
Многоточие (последовательные точки) набирается не как строка
точек, поэтому для многоточия в Texinfo используется специальная
команда. Команда @bullet также является специальной. После
каждой из этих команд пишется пара фигурных скобок, `{}', без
пробела между именем команды и скобками. (Вы должны писать с этими
командами фигурные скобки, потому что вы можете использовать их сразу
после другого текста; при отсутствии скобок форматирующие программы
могут запутаться. See section Синтаксис @-команд, для
дальнейшей информации.)
@dots{} (...) и @enddots{} (@enddots{})
Используйте команду @dots{} для создания многоточия, то есть
трех точек подряд, с подходящими пробелами между ними, как здесь:
`...'. Не пишите во входном файле просто три точки; это сработает
при выводе в Info-файл, но в печатном руководстве создаст неправильные
пробелы между точками.
Аналогично, команда @enddots{} создает многоточие, завершающее
предложение (четыре точки)@enddots{}
Вот многоточие: ... Вот три точки подряд: ...
В печатном выводе три точки подряд расположены ближе друг к другу, чем точки в многоточии.
@bullet{} (*)
Используйте команду @bullet{} для создания большой круглой
точки ("горошины") или наиболее похожего символа. В Info используется
звездочка.
Вот "горошина": *
Если вы используете @bullet в @itemize, вам не нужно
печатать фигурные скобки, так как их предоставит @itemize.
(See section @itemize: создание простых перечней.)
Лого `TeX' набирается особым образом, и для него требуется @-команда. Символ охраны авторских прав, `(C)', также является специальным. После каждой из этих команд пишется пара фигурных скобок, `{}', без пробела между именем команды и скобками.
@TeX{} (TeX)
Используйте команду @TeX{} для вывода `TeX'. В печатном
руководстве это особое лого, отличающееся от трех простых букв. В Info
оно выглядит как `TeX'. Команда @TeX{} уникальна среди
других команд Texinfo тем, что в ней есть заглавные буквы `T' и
`X'.
@copyright{} ((C))
Используйте команду @copyright{} для вывода `(C)'. В
печатном руководстве это `c' в круге, а в Info это
`(C)'.
@pounds{} (@pounds{}): Фунты стерлингов
Используйте команду @pounds{} для вывода `@pounds{}'. В
печатном руководстве это символ, обозначающий фунт стерлингов. В Info
это `#'. Символы других денежных единиц, к сожалению, недоступны.
@minus{} (-): Вставка знака минус
Используйте команду @minus{} для вывода знака минус. В
равноширинном шрифте это один дефис, но в пропорциональном шрифте это
обычно символ с длиной знака минус -- немного длиннее дефиса, но короче
em-тире:
`-' это знак минус, созданный командой `@minus{}',
`-' это дефис, созданный с помощью символа `-',
`---' это em-тире для текста.
В равноширинном шрифте, используемом Info, @minus{} аналогичен
дефису.
Вы не должны применять @minus{} внутри блока @code или
@example, потому что в равноширинном шрифте, который они
используют, не делается различий по ширине.
Когда вы используете @minus для задания значка, начинающего
каждый пункт перечня, вам не нужно печатать фигурные скобки
(see section @itemize: создание простых перечней).
@math: Вставка математических выражений
Вы можете записать короткие математические выражения с помощью команды
@math. Пишите выражение в фигурных скобках, как здесь:
@math{(a + b)(a + b) = a^2 + 2ab + b^2}
Это дает в TeX следующее:
(a + b)(a + b) = a^2 + 2ab + b^2
и следующее в Info:
(a + b)(a + b) = a^2 + 2ab + b^2
Таким образом, команда @math не влияет на вывод Info.
Для сложных математических выражений вы также можете использовать TeX напрямую (see section Непосредственный вызов команд программы форматирования). Когда вы используете TeX непосредственно, не забывайте писать математические выражения между одинарными или двойными символами `$' (знаками доллара), как необходимо.
В Texinfo, код часто иллюстрируется примерами, ограниченными командами
@example и @end example или @lisp и @end
lisp. В таких примерах вы можете обозначить результат вычисления или
раскрытия с помощью `=>' или `==>'.
Аналогично, есть команды для вставки знаков, обозначающих печатаемый
вывод, сообщения об ошибках, эквивалентность выражений и позицию
точки.
Команды вставки графических знаков необязательно использовать внутри примера, но чаще всего бывает так. После каждой команды для вставки графического знака следует пара фигурных скобок.
@result{} указывает на результат выражения.
@expansion{} показывает результат раскрытия макроса.
@print{} обозначает печатаемый вывод.
@error{} обозначает, что последующий текст -- это сообщение
об ошибке.
@equiv{} обозначает точную эквивалентность двух форм.
@point{} показывает позицию точки.@result{} (=>): Обозначение вычисления
Используйте команду @result{} для обозначения результата
вычисления выражения.
Команда @result{} отображается как `=>' в Info и
как `=>' в печатном выводе.
Таким образом, следующий пример:
(cdr '(1 2 3))
=> (2 3)
можно прочитать как "(cdr '(1 2 3)) при вычислении дает (2
3)".
@expansion{} (==>): Обозначение раскрытия
Когда выражение является вызовом макроса, оно раскрывается в новое
выражение. Вы можете обозначить результат раскрытия с помощью команды
@expansion{}.
Команда @expansion{} отображается в Info как `==>', а в
печатном выводе как `==>'.
Например, следующее
@lisp
(third '(a b c))
@expansion{} (car (cdr (cdr '(a b c))))
@result{} c
@end lisp
дает
(third '(a b c))
==> (car (cdr (cdr '(a b c))))
=> c
что можно прочитать так:
(third '(a b c))раскрывается в(car (cdr (cdr '(a b c)))); результат вычисления этого выражения равенc.
Часто, как в этом случае, пример смотрится лучше, если для команд
@expansion{} и @result{} сделан отступ в пять
пробелов.
@print{} (-|): Обозначение печатаемого вывода
Иногда выражение печатает что-то во время исполнения. Вы можете
обозначить печатаемый вывод с помощью команды @print{}.
Команда @print{} отображается в Info как `-|', а в
печатном выводе как `-|'.
В следующем примере печатаемый текст обозначен с помощью `-|', а результат выражения идет на следующей строке.
(progn (print 'foo) (print 'bar))
-| foo
-| bar
=> bar
В исходном Texinfo-файле этот пример записан следующим образом:
@lisp
(progn (print 'foo) (print 'bar))
@print{} foo
@print{} bar
@result{} bar
@end lisp
@error{} (error-->): Обозначение сообщения об ошибке
Фрагмент кода может вызвать сообщение об ошибке, когда вы его
вычисляете. Вы можете обозначить сообщение об ошибке с помощью команды
@error{}.
Команда @error{} отображается в Info как `error-->', а в
печатном выводе как `error-->'.
Таким образом,
@lisp
(+ 23 'x)
@error{} Wrong type argument: integer-or-marker-p, x
@end lisp
дает
(+ 23 'x) error--> Wrong type argument: integer-or-marker-p, x
Это обозначает, что когда вы вычисляете выражение, печатается сообщение об ошибке:
Wrong type argument: integer-or-marker-p, x
сама строка `error-->' не является частью сообщения об ошибке.
@equiv{} (==): Обозначение эквивалентности
Иногда два выражения выдают одинаковый результат. Вы можете обозначить
точную эквивалентность двух форм с помощью команды
@equiv{}.
Команда @equiv{} отображается в Info как `==', а в
печатном выводе как `=='.
Таким образом,
@lisp
(make-sparse-keymap) @equiv{} (list 'keymap)
@end lisp
дает
(make-sparse-keymap) == (list 'keymap)
Это обозначает, что вычисление (make-sparse-keymap) дает тот же
результат, что и вычисление (list 'keymap).
@point{} (-!-): Обозначение точки в буфереИногда вам может понадобиться показать пример текста в буфере Emacs. В таких примерах действует соглашение включать все содержимое рассматриваемого буфера между двух строк из дефисов, содержащих имя этого буфера.
Вы можете использовать команду `@point{}', чтобы показать позицию точки в тексте буфера. (Символ точки, конечно, не является частью текста буфера; он обозначает место между двумя символами, где находится точка.)
Команда @point{} отображается в Info как `-!-', а в
печатном выводе как `-!-'.
Следующий пример показывает содержимое буфера `foo' до и после
вычисления Лисп-команды, вставляющей слово измененное.
---------- Buffer: foo ---------- Это -!-содержимое foo. ---------- Buffer: foo ----------
(insert "измененное ")
=> nil
---------- Buffer: foo ----------
Это измененное -!-содержимое foo.
---------- Buffer: foo ----------
В исходном Texinfo-файле этот пример был записан так:
@example
---------- Buffer: foo ----------
Это @point{}содержимое foo.
---------- Buffer: foo ----------
(insert "измененное ")
@result{} nil
---------- Buffer: foo ----------
Это измененное @point{}содержимое foo.
---------- Buffer: foo ----------
@end example
Сноски нужны для справок, дополняющих или поясняющих основной текст.(8)
В Texinfo сноски создаются командой @footnote. Сразу за
командой следует открывающая фигурная скобка, потом текст сноски, и за
ним закрывающая фигурная скобка. Сноски могут быть произвольной длины
(при необходимости сноски разбиваются по страницам), но обычно они
бывают короткими. Вот шаблон:
обычный текст@footnote{текст сноски}
Как здесь показано, команда @footnote должна следовать сразу
после поясняемого текста; иначе знак сноски может появиться на новой
строке.
Например, после этой фразы вставлен образец сноски(9); в исходном Texinfo-файле это выглядит так:
...образец сноски@footnote{Это пример
сноски.}; в исходном Texinfo-файле...
В печатном руководстве или книге знак сноски -- это маленькое приподнятое число; текст сноски появляется внизу страницы под горизонтальной чертой.
В Info знак сноски -- это номер сноски в круглых скобках, например: `(1)'. После знака сноски следует перекрестная ссылка к тексту сноски.
В HTML файле, знаки сноски изображаются как маленькие приподнятые числа, служащие гиперссылками к тексту сноски.
Кстати, сноски в аргументе команды @item внутри таблиц должны
быть на той же строке, что и @item (как правило).
See section Создание таблиц из двух колонок.
В Info есть два стиля отображения сносок, которые определяют, где появится текст сноски:
--------- Сноски --------- (1) Это пример сноски.
File: texinfo.info Node: Overview-Footnotes, Up: Overview (1) Обратите внимание, первый слог в``Texinfo'' произносится как ``тек'', а не ``текс''. ...
Texinfo-файл может быть отформатирован в Info-файл с любым стилем сносок.
Используйте команду @footnotestyle для задания стиля сносок в
Info-файле. Пишите эту команду с начала отдельной строки с последующим
аргументом, `end' или `separate', для помещения сносок
соответственно в конце ноды или в отдельной ноде.
Например,
@footnotestyle end
или
@footnotestyle separate
Пишите команду @footnotestyle перед строкой end-of-header или
немного после, в начале Texinfo-файла. (Если вы поместите команду
@footnotestyle между строк start-of-header и end-of-header,
команды форматирования области будут использовать заданный стиль
сносок.)
Если вы не задали стиль сносок, команды форматирования будут
использовать стиль по умолчанию. На данный момент команды
texinfo-format-buffer и texinfo-format-region используют
стиль `separate', а @command{makeinfo} -- стиль `end'.
В этой главе есть две сноски.
Вы можете вставить рисунок из внешнего файла с помощью команды
@image:
@image{имя-файла, [ширина], [высота]}
Аргумент имя-файла является обязательным, и имя не должно содержать расширения, потому что разные обработчики поддерживают разные форматы:
@example).
Необязательные аргументы ширина и высота задают размер для масштабирования изображения (они игнорируются при выводе в формате Info). Если они оба не заданы, рисунок представляется в естественном размере (заданном в самом файле); если задан только один, второй пропорционально масштабируется; и если заданы оба, то рассматриваются оба, что возможно исказит первоначальный рисунок, изменив отношение его сторон.
Аргументы ширина и высота могут быть заданы с помощью правильных размеров TeX, а именно:
Например, следующая команда масштабирует файл `ridt.eps' до одного дюйма по вертикали и пропорционально по горизонтали:
@image{ridt,,1in}
Чтобы @image работала с TeX, нужно установить файл
`epsf.tex' в таком месте, где TeX может его найти. (Стандартное
место -- `texmf/tex/generic/dvips/epsf.tex', где texmf
--- это корень дерева каталогов TeX.) Этот файл включен в
дистрибутив Texinfo и доступен на ftp://tug.org/tex/epsf.tex.
@image можно использовать как внутри строки, так и для
выделенных рисунков. Поэтому, если вы намереваетесь сделать рисунок
выделенным, убедитесь, что вы оставили перед этой командой пустую
строку, иначе вывод наползет на предшествующий текст.
Обычно Texinfo-файл обрабатывается и TeX, и одной из команд форматирования для Info. Иногда в том или в другом выходном файле разрывы строк, абзацев или страниц оказываются в `неправильных' местах. Вы должны убедиться, что текст выглядит хорошо как в печатном руководстве, так и в Info-файле.
Например, в печатном руководстве страница может быть разбита в середине примера, что неудобно; чтобы предотвратить это, вы можете сохранить целостность фрагмента текста, используя команды группирования, которые удерживают текст от разделения между двумя страницами. Напротив, вы можете захотеть принудительно разбить страницу там, где обычно это не случается. К счастью, подобные проблемы возникают нечасто. Если они все же возникли, используйте команды создания или предотвращения разрывов.
Команды разрыва создают или разрешают разрывы строк и абзацев:
@*
@sp n
@-
@hyphenation{пе-ре-но-сы слова}
Команды предотвращения разрыва строки сохраняют целостность текста в пределах одной строки:
@w{текст}
Команды разбиения на страницы относятся только к печатному руководству, так как в Info-файлах нет страниц.
@page
@group
@need тысячные дюйма
@*: Разрыв строки
Команда @* принудительно разрывает строку в печатном руководстве
и в документе Info.
Например,
Эта строка @* разбита @*в двух местах.
дает
Эта строка разбита в двух местах.
(Заметьте, что пробел после первой команды @* перенесен на
следующую строку.)
Команда @* часто используется на странице с информацией об
авторских правах:
Это редакция 2.0 документации Texinfo,@* для Texinfo ...
в этом примере команда @* запрещает TeX некрасиво
растягивать строку по всей странице.
Обратите внимание: Не пишите фигурные скобки после команды
@*, они не нужны.Не пишите в конце абзаца, содержащего команды
@*команду@refill; это приведет к перезаполнению абзаца после разбиения строк и потере результата разбиения.
@- и @hyphenation: ПереносыХотя алгоритм переносов в TeX обычно работает довольно хорошо, время от времени он пропускает полезные точки переноса. (Или, намного реже, делает неправильный перенос.) Тогда, для документов с необычным словарем или при окончательной доводке печатного издания, вы можете захотеть помочь TeX. В Texinfo для этого предусмотрены две команды:
@-
@-.
@hyphenation{пе-ре-но-сы слова}
@hyphenation{ма-ну-скрипт ма-ну-скрип-ты}
TeX использует заданные таким образом точки переноса, только если
слова точно совпадают, поэтому вы должны перечислить все необходимые
варианты.
В документах Info переносы не используются, а значит эти команды не имеют значения для них.
@w{текст}: Предотвращение разрывов строк
Конструкция @w{текст} выводит текст и запрещает
разрывы строк внутри текста.
Вы можете использовать команду @w, чтобы запретить TeX
автоматически переносить длинное название, имя или фразу, которые
оказались близко к концу строки. Например:
Вы можете скопировать программы GNU с
@w{@samp{ftp.gnu.org}}.
дает
Вы можете скопировать программы GNU с `ftp.gnu.org'.
Вы также можете использовать @w для получения неразрывного
пробела:
Ни одна из форматирующих программ не станет разбивать строку на
этом@w{ }пробеле.
@sp n: Вставка пустых строк
Строка, начинающаяся с @sp n и не содержащая ничего
больше, создает n пустых строк в печатном руководстве и в
Info-файле. @sp также принудительно обрывает абзац. Например,
@sp 2
создает две пустых строки.
Команда @sp чаще всего применяется в титульном листе.
@page: Переход на новую страницу
Строка, содержащая только @page, начинает новую страницу в
печатном руководстве. Эта команда не играет роли для Info-файлов, так
как они не разбиваются на страницы. Команда @page часто
применяется на титульном листе в Texinfo-файле для начала страницы с
информацией об авторских правах.
@group: Предотвращение разрывов страниц
Команда @group (на отдельной строке) применяется внутри
конструкции @example или подобной для начала неделимой
вертикальной группы, появляющейся в печатном документе целиком на одной
странице. Группа завершается строкой, содержащей только @end
group. Две эти команды сами по себе не производят никакого вывода и не
играют роли в Info-файле.
Хотя команда @group в принципе должна работать во многих
контекстах, ее текущая реализация работает надежно только внутри блоков
@example и его вариантов и внутри @display,
@format, @flushleft и @flushright. See section Цитаты и примеры. (Все эти команды имеют общую черту -- каждая входная
строка дает одну строку на выходе.) В других контекстах команда
@group может привести к ненормальному распределению
вертикального свободного места.
Это требование означает, что вы должны писать:
@example @group ... @end group @end example
где команды @group и @end group расположены между
командами @example и @end example.
Команда @group чаще всего применяется, если нужно сохранить
фрагмент текста целиком на одной странице. В этом руководстве по
Texinfo более 100 примеров содержат текст, заключенный между
@group и @end group.
Если вы забудете закончить группу, то при запуске TeX вы можете
получить странные и непонятные сообщения об ошибках. Это происходит,
потому что TeX продолжает пытаться поместить остаток Texinfo-файла на
одну страницу и не выдает ошибок, пока не обработает довольно
значительный кусок текста. Хорошим практическим правилом будет поискать
пропущенную команду @end group, если вы получаете от TeX
непонятные сообщения.
@need mils: Предотвращение разрывов страниц
Строка, содержащая только @need n, начинает в печатном
руководстве новую страницу, если на текущей странице осталось места
меньше, чем n мил (тысячных долей дюйма). Не пишите фигурные
скобки вокруг аргумента n. Команда @need n не имеет
значения в Info-файлах, так как они не разбиваются на страницы.
Перед этим абзацем написана команда @need, сообщающая TeX,
что нужно начать новую страницу, если на текущей осталось меньше 800 мил
(восьми десятых дюйма). Это выглядит так:
@need 800 Перед этим абзацем написана ...
Команда @need полезна для предотвращения появления изолированных
строк (то есть строк, оказавшихся единственными в конце страницы).
Команда @deffn и другие команды для определений позволяют
вам описывать функции, переменные, макросы, команды, пользовательские
параметры, специальные формы и другие объекты в едином формате.
В Info-файле, определение вызывает появление в начале первой строки
определения категории объекта -- `Функция', `Переменная' или другой, за
которой идет имя объекта и его аргументы. В печатном руководстве, эта
команда велит TeX печатать имя объекта и его аргументы с левого края,
а название его категории -- с правого. В обоих выходных форматах для
тела определения делается отступ. Также, имя объекта вносится в
соответствующий именной указатель: @deffn вносит имя в указатель
функций, @defvr в указатель переменных и так далее.
Руководство не должно и не может содержать более одного определения для
заданного имени. Приложение, содержащее обзор, должно использовать
@table, а не команды определений.
Команда @deffn используется для определений объектов, похожих на
функции. Чтобы записать определение с помощью @deffn, напишите
команду @deffn в начале строки и продолжите строку категорией
объекта, именем объекта и его аргументами (если они есть). Потом
напишите тело определения на последующих строках. (Вы можете вставлять
в тело примеры.) И наконец, завершайте определение командой @end
deffn, записанной на отдельной строке. (Другие команды для определений
придерживаются того же формата.)
Шаблон определения выглядит так:
@deffn категория имя аргументы... тело-определения @end deffn
Например,
@deffn Команда forward-word счетчик
Эта команда перемещает точку вперед на столько слов, сколько задано
аргументом @var{счетчик} (или назад, если @var{счетчик}
отрицателен). ...
@end deffn
дает
Пишите название категории с заглавной буквы. Если название категории содержит пробелы, как, скажем, `Интерактивная команда', заключайте его в фигурные скобки. Например:
@deffn {Интерактивная команда} isearch-forward
...
@end deffn
Иначе второе слово будет ошибочно принято за имя объекта.
Некоторые команды для определений имеют более общий смысл, чем другие.
Команда @deffn, например, -- это общая команда для функций и
похожих объектов: для объектов, которые могут принимать аргументы.
Когда вы используете эту команду, вы задаете категорию, к которой
принадлежит данный объект. Команда @deffn предлагает три
предопределенных специализированных варианта, @defun,
@defmac и @defspec, которые задают для вас категории
"Функция", "Макро" и "Специальная форма", соответственно. (В
Лиспе специальной формой называется объект, во многом похожий на
функцию.) Команда @defvr также сопровождается несколькими
предопределенными специализированными вариантами для описания конкретных
типов переменных.
Шаблон для специализированного определения, такого как @defun,
похож на шаблон общего определения, за исключением того, что вам не
нужно задавать категорию:
@defun имя аргументы... тело-определения @end defun
Таким образом,
@defun buffer-end флаг
Эта функция возвращает @code{(point-min)}, если @var{флаг}
меньше 1, и @code{(point-max)} в противном случае.
...
@end defun
дает
See section Пример определения функции, для получения более подробного
примера определения функции, включающего использование @example
внутри определения.
Другие специализированные команды работают подобно @defun.
Некоторые объекты принимают необязательные или повторяющиеся аргументы, которые можно обозначить характерным знаком, использующим квадратные скобки и многоточие. Например, специальная форма часто разбивает свой список аргументов на отдельные аргументы более сложным образом, чем прямолинейная функция.
Аргумент, заключенный в квадратные скобки является необязательным.
Таким образом, фраза `[аргумент]' означает,
что аргумент необязателен. Аргумент, после которого стоит
многоточие, является необязательным и может быть повторен несколько раз.
Таким образом, `аргумент...' обозначает ноль или более
аргументов. Круглые скобки используются когда несколько аргументов
сгруппированы в дополнительные уровни структуры списка в языке Лисп.
Вот, к примеру, строка @defspec для воображаемой специальной
формы:
В этом примере аргументы from и to являются необязательными, но должны либо оба присутствовать, либо оба отсутствовать. Если они присутствуют, также может быть задан inc. Эти аргументы сгруппированы с аргументом var в один список, чтобы отличить их от body, который включает все остальные элементы формы.
В исходном Texinfo-файле эта строка @defspec записана следующим
образом (за исключением того, что он не была разбита на две строки, как
в этом примере).
@defspec foobar (@var{var} [@var{from} @var{to}
[@var{inc}]]) @var{body}@dots{}
Эта функция вносится в указатель команд и переменных под именем `foobar'.
Чтобы создать две или более `первые' строки, напишите после первой
строки @deffn строку, начинающуюся с @deffnx. Команда
@deffnx работает в точности, как и @deffn, но не создает
дополнительный вертикальный пропуск между ней и предыдущей строкой.
Например,
@deffn {Интерактивная команда} isearch-forward
@deffnx {Интерактивная команда} isearch-backward
Две эти команды аналогичны, за исключением ...
@end deffn
дает
Каждая команда для определений имеет форму с `x': @defunx,
@defvrx, etc.
Форма с `x' действует так же, как и @itemx; смотрите section @itemx.
Texinfo предоставляет более дюжины команд для определений; все они описаны в этом разделе.
Команды для определений автоматически вносят имя объекта в
соответствующий именной указатель: например, @deffn,
@defun и @defmac вносят имена функций в указатель
функций; @defvr и @defvar вносят имена переменных в
указатель переменных.
Хотя последующие примеры иллюстрируют преимущественно Лисп, эти команды могут быть использованы и для других языков программирования.
В этом разделе рассматриваются команды для описания функций и похожих объектов:
@deffn категория имя аргументы...
@deffn -- это общая команда для функций, интерактивных
команд и похожих объектов, которые могут принимать аргументы. Вы должны
выбрать термин для описания категории, к которой принадлежит
определяемый объект; например, если объект является функцией, то можно
использовать категорию "Функция". Команда @deffn записывается
в начале строки, а после нее на той же строке пишутся категория
определяемого объекта, имя объекта и его аргументы, если таковые
имеются. Завершайте определение с помощью @end deffn на
отдельной строке.
Например, вот определение:
@deffn Команда forward-char nchars
Переместить точку назад на @var{nchars} символов.
@end deffn
Этот пример показывает довольно сжатое определение "команды",
называемой forward-char, с одним аргументом, nchars.
@deffn печатает имена аргументов, таких как nchars,
курсивом или заглавными буквами, как при использовании @var,
потому что мы думаем об этих именах, как о метасинтаксических переменных
--- они обозначают значения действительных аргументов. Внутри текста
описания, чтобы сослаться на значение аргумента, пишите имя аргумента с
явной командой @var. В примере выше мы использовали таким
образом `@var{nchars}'.
Шаблон для @deffn выглядит так:
@deffn категория имя аргументы... тело-определения @end deffn
@defun имя аргументы...
@defun -- это команда для определений функций.
@defun эквивалентна команде `@deffn Функция ...'.
Например,
@defun set символ новое-значение
Изменить значение символа @var{символ} на
@var{новое-значение}.
@end defun
показывает довольно сжатое определение функции set с аргументами
символ и новое-значение. Имена аргументов в строке
@defun автоматически выводятся курсивом или заглавными буквами,
как если бы они были заключены в @var. Завершайте определение с
помощью @end defun на отдельной строке.
Шаблон таков:
@defun имя-функции аргументы... тело-определения @end defun
@defun создает вхождение в указателе функций.
@defmac имя аргументы...
@defmac -- это команда для определений макросов.
@defmac эквивалентна `@deffn Макро ...' и работает
подобно @defun.
@defspec имя аргументы...
@defspec -- это команда для определений специальных
форм. (В Лиспе специальной формой называется объект, во многом похожий
на функцию, see section `Special Forms' in GNU Emacs Lisp Reference Manual.) @defspec эквивалентна `@deffn {Специальная
форма} ...' и работает подобно @defun.
Ниже перечислены команды для определений переменных и похожих объектов:
@defvr категория имя
@defvr -- это общая команда для определений объектов,
схожих с переменными -- объектов, в которых записано значение. Вы
должны выбрать термин для описания категории определяемого объекта; это
может быть, например, "Переменная", если объект является переменной.
Пишите команду @defvr в начале строки и, за ней на той же
строке, категорию объекта и его имя.
Пишите название категории с заглавной буквы, как заголовок. Если
название категории содержит пробелы, как например "Пользовательский
параметр", заключайте его в фигурные скобки. Иначе второе слово будет
ошибочно принято за имя объекта. Например,
@defvr {Пользовательский параметр} fill-column
Эта локальная переменная задает максимальную
ширину заполненных строк.
...
@end defvr
Завершайте определение с помощью @end defvr на отдельной строке.
Шаблон таков:
@defvr категория имя тело-определения @end defvr
@defvr создает для имени вхождение в указателе переменных.
@defvar имя
@defvar -- это команда для определений переменных.
@defvar эквивалентна команде `@defvr Переменная ...'.
Например:
@defvar kill-ring ... @end defvarШаблон таков:
@defvar имя тело-определения @end defvar
@defvar создает для имени вхождение в указателе
переменных.
@defopt имя
@defopt -- это команда для определений
пользовательских параметров, то есть переменных, предназначенных
для изменения пользователем по его вкусу; их много в Emacs
(see section `Переменные' in Руководство по GNU Emacs).
@defopt эквивалентна `@defvr {Пользовательский параметр}
...' и работает подобно @defvar.
Команда @deftypefn и ее варианты предназначены для описания
функций в языках, в которых вы должны объявлять типы переменных и
функций, таких как Си и Си++.
@deftypefn категория тип-данных имя аргументы...
@deftypefn -- это общая команда для определений функций
и похожих объектов, которые могут принимать аргументы и имеют тип.
Команда @deftypefn пишется в начале строки, и за ней на той же
строке следуют название категории описываемого объекта, тип
возвращаемого им значения, имя этого объекта и его аргументы, если
таковые имеются.
Например,
@deftypefn {Библиотечная функция} int foobar
(int @var{foo}, float @var{bar})
...
@end deftypefn
(где текст перед "...", показанный выше как две строки, на самом
деле был бы в настоящем Texinfo-файле на одной строке) дает в Info
следующее:
-- Библиотечная функция: int foobar (int FOO, float BAR) ...В печатном руководстве, это дает:
Это означает, что
foobar является "библиотечной функцией",
которая возвращает int, а ее аргументы -- это foo
(int) и bar (float).
Имена аргументов, которые вы пишете в @deftypefn, не передаются
неявно @var -- так как действительные имена аргументов в
@deftypefn обычно разбросаны между именами типов данных и
ключевыми словами, и Texinfo не может найти их без вашей помощи. Вместо
этого вы должны явно писать @var вокруг имен аргументов. В
примере выше, имена аргументов -- это `foo' и `bar'.
Вот шаблон для @deftypefn:
@deftypefn категория тип-данных имя аргументы ... тело-определения @end deftypefnЗаметьте, что если категория или тип-данных занимает более одного слова, они должны быть заключены в фигурные скобки, чтобы стать одним аргументом. Если вы описываете процедуру в языке, в котором есть пакеты, таком как Ада, вам стоит использовать
@deftypefn способом, несколько
противоречащим описанным в предыдущих абзацах соглашениям.
Например:
@deftypefn stacks private push
(@var{s}:in out stack;
@var{n}:in integer)
...
@end deftypefn
(Аргументы @deftypefn показаны разбитыми на три строки, но в
действительном Texinfo-файле должны быть одной строкой.) В этом случае
процедура классифицируется как принадлежащая к пакету stacks, а
не как `процедура', и ее тип описывается как private. (Имя этой
процедуры push, а ее аргументы -- это s и n.)
@deftypefn создает для имени вхождение в указателе
функций.
@deftypefun тип-данных имя аргументы...
@deftypefun -- это специализированная команда для
определений функций в языках с контролем типов. Эта команда
эквивалентна `@deftypefn Функция ...'.
Таким образом,
@deftypefun int foobar (int @var{foo}, float @var{bar})
...
@end deftypefun
дает в Info следующее:
-- Функция: int foobar (int FOO, float BAR) ...и следующее печатном руководстве:
Вот шаблон:
@deftypefun тип имя аргументы... тело-определения @end deftypefun
@deftypefun создает для имени вхождение в указателе
функций.
Переменные в языках с контролем типов обрабатываются методом, похожим
метод для функций в таких языках. See section Функции в языках с контролем типов. Общая
команда для определений @deftypevr соответствует
@deftypefn, а специализированная команда @deftypevar
соответствует @deftypefun.
@deftypevr категория тип-данных имя
@deftypevr -- это общая команда для определений
объектов, похожих на переменные в языках с контролем типов -- объектов,
в которых записано значение. Вы должны выбрать термин для описания
категории определяемого объекта; это может быть, например,
"Переменная", если объект является переменной.
Команда @deftypevr записывается в начале строки, и за ней на той
же строке следуют название категории описываемого объекта, тип данных и
имя этого объекта.
Например:
@deftypevr {Глобальный флаг} int enable
...
@end deftypevr
дает в Info следующее:
-- Глобальный флаг: int enable ...и следующее в печатном руководстве:
Шаблон такой:
@deftypevr категория тип-данных имя тело-определения @end deftypevr
@deftypevr создает для имени вхождение в указателе
переменных.
@deftypevar тип-данных имя
@deftypevar -- это специализированная команда для
определений переменных в языках с контролем типов. @deftypevar
эквивалентна `@deftypevr Переменная ...'.
Например:
@deftypevar int fubar ... @end deftypevarдает в Info следующее:
-- Переменная: int fubar ...и следующее в печатном руководстве:
Шаблон такой:
@deftypevar тип-данных имя тело-определения @end deftypevar
@deftypevar создает для имени вхождение в указателе
переменных.
Здесь приведены команды для форматирования описаний абстрактных объектов, таких, какие используются в объектно-ориентированном программировании. Класс -- это определенный тип абстрактных объектов. Экземпляр класса -- это конкретный объект, имеющий тип этого класса. Переменная экземпляра -- это переменная, принадлежащая классу, но имеющая в каждом экземпляре свое собственное значение.
В определении, если имя класса на самом деле является именем,
определенным для класса в программной системе, вы должны окружать его
@code, иначе в печатном руководстве оно будет напечатано шрифтом
для обычного текста.
@defcv категория класс имя
@defcv -- это общая команда для определений переменных,
связанных с классами а объектно-ориентированном программировании. После
команды @defcv следуют три аргумента: категория определяемого,
класс, к которому оно принадлежит и его имя. Таким образом,
@defcv {Параметр класса} Window border-pattern
...
@end defcv
показывает, как вы могли бы написать первую строку определения параметра
класса border-pattern для класса Window.
Шаблон выглядит так:
@defcv категория класс имя ... @end defcv
@defcv создает вхождение в указателе переменных.
@defivar класс имя
@defivar -- это команда для определений переменных
экземпляров в объектно-ориентированном программировании.
@defivar эквивалентна `@defcv {Переменная экземпляра}
...'
Шаблон выглядит так:
@defivar класс имя-переменной-экземпляра тело-определения @end defivar
@defivar создает вхождение в указателе переменных.
@deftypeivar класс тип-данных имя
@deftypeivar -- это команда для определений
типизированных переменных экземпляра в объектно-ориентированном
программировании. Она похожа на @defivar, но добавляет параметр
тип-данных для указания типа этой переменной экземпляра.
@deftypeivar создает вхождение в указателе переменных.
@defop категория класс имя аргументы...
@defop -- это общая команда для определений элементов,
которые похожи на методы в объектно-ориентированном программировании.
Такие элементы принимают аргументы, как функции, но связаны с конкретным
классом объектов.
Например, в некоторых системах есть конструкции, называемые
обертками, которые связаны с классами, как и методы, но действуют
во многом подобно макросам, а не как функции. Вы можете использовать
@defop Обертка для описания одного из них.
Иногда полезно различать методы и операции. Вы можете думать об
операциях, как об описании для метода. Таким образом, оконная система
может указать, что все классы окон имеют метод, называемый
expose; вы могли бы сказать, что оконная система определяет
операцию expose для окон вообще. Как правило, у операции есть
имя, а также образец аргументов; все методы, реализующие операцию,
должны принимать одинаковые аргументы, так как приложения, использующие
эту операцию, используют ее, не зная, какой метод ее реализует.
Часто более полезным оказывается документировать операции, а не методы.
Например, разработчики оконных приложений должны знать об операции
expose, но не обязаны быть в курсе, имеет ли данный класс окон
собственный метод для реализации этой операции. Для описания этой
операции, вы могли бы написать:
@defop Операция windows exposeКоманда
@defop записывается в начале строки, и за ней на той же
строке следуют общее название категории операции, имя класса этой
операции, ее имя и аргументы, если таковые имеются.
Вот шаблон:
@defop категория класс имя аргументы... тело-определения @end defop
@defop создает вхождение, такое как `expose для
windows', в указателе функций.
@deftypeop категория класс тип-данных имя аргументы...
@deftypeop -- это команда определения для
типизированных операций в объектно-ориентированном программировании.
Она похожа на @defop, но в ней лобавлен параметр
тип-данных для указания типа возвращаемого значения метода.
@deftypeop создает вхождение в указателе функций.
@defmethod класс имя аргументы...
@defmethod -- это команда для определений методов в
объектно-ориентированном программировании. Метод -- это разновидность
функции, которая реализует операцию для конкретного класса объектов и
его подклассов.
В Лисп-машине методы на самом деле были функциями, но обычно их
определяли с помощью defmethod.
@defmethod эквивалентна `@defop Метод ...'. Эта
команда записывается в начале строки, и за ней на той же строке следуют
имя класса этого метода, имя этого метода и его аргументы, если таковые
имеются.
Например,
@defmethod bar-class bar-method argument
...
@end defmethod
показывает определение метода, называемого bar-method, класса
bar-class. Этот метод принимает один аргумент.
Шаблон таков:
@defmethod класс имя-метода аргументы... тело-определения @end defmethod
@defmethod создает вхождение, такое как `bar-method для
bar-class', в указателе функций.
@deftypemethod класс тип-данных имя аргументы...
@deftypemethod -- это команда для определений методов в
объектно-ориентированных языках с контролем типов, таких как Си++ и
Java. Она похожа на команду @defmethod, но в ней добавлен
параметр тип-данных для задания типа возвращаемого методом
значения.
Здесь приведены команды для типов данных:
@deftp категория имя атрибуты...
@deftp -- это общая команда для типов данных. Эта
команда пишется в начале строки, и за ней на той же строке следуют
название категории, имя этого типа данных (слово вроде int или
float) и затем имена атрибутов объектов этого типа. Таким
образом, вы можете использовать эту команду для описания int или
float, в этом случае вы могли бы использовать в качестве
категории слова тип данных. (Тип данных является категорией
определенных объектов, предназначенной для решения, какие операции можно
с ними производить.)
Например, в Лиспе, парой называется некий тип данных, и объект
этого типа имеет два гнезда, называемых CAR и CDR. Вот как вы
могли бы написать первую строку определения для пары.
@deftp {Тип данных} пара car cdr
...
@end deftp
Вот шаблон:
@deftp категория имя-типа атрибуты... тело-определения @end deftp
@deftp создает вхождение в указателе типов данных.
Когда вы пишете определение с использованием @deffn,
@defun или одной из других команд для определений, пожалуйста,
используйте аргументы, указывающие свой смысл, как аргумент
счетчик для функции forward-word. Также, если имя
аргумента содержит имя его типа, позаботьтесь, чтобы аргумент в
действительности был этого типа.
Определение функции использует команды @defun и @end
defun. Имя этой функции следует сразу после команды @defun, а
за ним на той же строке пишется список параметров.
Вот определение из @ref{Calling Functions,,,@external{elisp}, The GNU Emacs Lisp Reference Manual}.
- Function: apply function &rest arguments
applycalls function with arguments, just likefuncallbut with one difference: the last of arguments is a list of arguments to give to function, rather than a single argument. We also say that this list is appended to the other arguments.
applyreturns the result of calling function. As withfuncall, function must either be a Lisp function or a primitive function; special forms and macros do not make sense inapply.(setq f 'list) => list (apply f 'x 'y 'z) error--> Wrong type argument: listp, z (apply '+ 1 2 '(3 4)) => 10 (apply '+ '(1 2 3 4)) => 10 (apply 'append '((a b c) nil (x y z) nil)) => (a b c x y z)An interesting example of using
applyis found in the description ofmapcar.
В исходном Texinfo-файле, этот пример выглядит так::
@defun apply function &rest arguments
@code{apply} calls @var{function} with
@var{arguments}, just like @code{funcall} but with one
difference: the last of @var{arguments} is a list of
arguments to give to @var{function}, rather than a single
argument. We also say that this list is @dfn{appended}
to the other arguments.
@code{apply} returns the result of calling
@var{function}. As with @code{funcall},
@var{function} must either be a Lisp function or a
primitive function; special forms and macros do not make
sense in @code{apply}.
@example
(setq f 'list)
@result{} list
(apply f 'x 'y 'z)
@error{} Wrong type argument: listp, z
(apply '+ 1 2 '(3 4))
@result{} 10
(apply '+ '(1 2 3 4))
@result{} 10
(apply 'append '((a b c) nil (x y z) nil))
@result{} (a b c x y z)
@end example
An interesting example of using @code{apply} is found
in the description of @code{mapcar}.@refill
@end defun
В этом руководстве данная функция перечислена в указателе команд и
переменных под именем apply.
Обычные переменные и пользовательские параметры описываются в похожем формате, за исключением того, что переменные и параметры не принимают аргументов.
Иногда полезно иметь различающийся текст в разных выходных форматах. Например, вы можете использовать условные команды, чтобы указать разный текст для печатного руководства и для Info-файла.
Условные команды не могут быть вложенными.
Условные команды делятся на следующие категории:
Команда @ifinfo начинает блок текста, который должен
игнорироваться TeX при наборе печатного руководства. Этот блок
появится только в Info-файле. Команда @ifinfo должна
встречаться на отдельной строке; завершайте блок текста, предназначенный
только для Info, строкой, содержащей одну команду @end ifinfo.
В начале Texinfo-файла, разрешения на копирование для Info заключены в
блок, помеченный командами @ifinfo и @end ifinfo.
(See section Обзор и разрешения на копирование для Info.)
Команды @iftex и @end iftex похожи на команды
@ifinfo и @end ifinfo, только они задают текст,
появляющийся в печатном руководстве, но не в Info-файле. Точно так же
команды @ifhtml и @end ifhtml задают текст, появляющийся
только при выводе в формате HTML.
Например,
@iftex Этот текст появится только в печатном руководстве. @end iftex @ifinfo Этот текст появится только в Info. @end ifinfo @ifhtml А этот только в HTML. @end ifhtml
Пример выше выдает следующую строку: Этот текст появится только в печатном руководстве. А этот только в HTML.
Заметьте, что вы видите только одну из двух строк; которую именно, зависит от того, читаете ли вы Info или печатную версию этого руководства.
Вы можете пометить фрагмент текста, который должен появляться при выводе
во всех форматах, кроме некоторого формата, задаваемого одной из
следующих @ifnot... команд:
@ifnothtml ... @end ifnothtml @ifnotinfo ... @end ifnotinfo @ifnottex ... @end ifnottex
(Команды @ifnot... и @end на самом деле нужно писать
на отдельных строках.)
Если вывод производится не в заданном формате, то блок включается в выходной файл. Иначе он игнорируется.
Блоки, ограниченные этими командами, содержат обычный исходный код
Texinfo, как в блоке @iftex, а не непосредственные команды
программы форматирования, как в блоке @tex (see section Непосредственный вызов команд программы форматирования).
Внутри области, ограниченной @iftex и @end iftex, вы
можете вставлять некоторые обычные команды TeX. Info игнорирует эти
команды, так как они находятся в той части файла, которую читает только
TeX. Вы можете писать команды TeX, как вы писали бы их в обычном
TeX-файле, но заменяя используемый TeX символ `\' символом
`@'. Например, в секции Texinfo-файла @titlepage вы
можете использовать команду TeX @vskip для форматирования
страницы с информацией об авторских правах. (Команда @titlepage
автоматически заставляет Info игнорировать область, точно так же, как
команда @iftex.)
Однако многие особенности, присущие plain TeX, не будут работать, потому что они перекрываются средствами Texinfo.
Вы можете полностью перейти в режим plain TeX и использовать символ
`\' в командах TeX, пометив область командами @tex и
@end tex. (Команда @tex также заставляет Info
игнорировать область, подобно команде @iftex.) Единственное
исключение состоит в том, что символ @ все еще начинает команду,
чтобы @end tex была правильно распознана.
Вот, для примера, математическое выражение, записанное в формате plain TeX:
@tex
$$ \chi^2 = \sum_{i=1}^N
\left (y_i - (a + b x_i)
\over \sigma_i\right)^2 $$
@end tex
Вывод этого примера появится только в печатном руководстве. Если вы читаете это в Info, вы не увидите уравнения, которое будет выведено в печатном руководстве. В печатном руководстве выражение, написанное выше выглядит так:
Аналогично, вы можете использовать @ifhtml ... @end ifhtml
для ограничения области, которую нужно включить только при выводе в
формате HTML, и @html ... @end html для ограничения
области, написанной непосредственно на HTML (опять же, за исключением
@, так же служащего сигнальным символом, чтобы команда
@end могла быть распознана.)
@set, @clear и @value
Вы можете указать программам форматирования Texinfo, какие части
Texinfo-файла нужно форматировать, а какие пропустить, используя команды
@set, @clear, @ifset и @ifclear.
Кроме того, вы можете использовать команду @set флаг,
чтобы установить значение флага равным строке символов, и команду
@value{флаг}, чтобы вставить эту строку в текст. Вы
можете использовать @set, например, для установки даты и
вставлять эту дату в несколько мест Texinfo-файла с помощью
@value.
@ifset и @ifclear
Когда флаг установлен, текст между соответствующими командами
@ifset флаг и @end ifset будет отформатирован.
Если флаг сброшен, программы форматирования Texinfo не
форматируют текст.
Используйте команду @set флаг для включения, или
установки флага; имя флага может быть любым одиночным
словом, содержащим буквы, цифры, дефисы или подчерки.
@set флаг
Пишите условно форматируемый текст между командами @ifset
флаг и @end ifset следующим образом:
@ifset флаг условный-текст @end ifset
Например, вы можете создать один документ, у которого есть два варианта, скажем, `маленькое' и `большое' руководство:
Вы можете использовать эту машину для выкапывания кустов, не повреждая их. @set большое @ifset большое Она также способна выкапывать взрослые деревья. @end ifset Не забудьте быстро пересадить ...
В этом примере, текст между @ifset большое и @end ifset
будет отформатирован, потому что флаг большое установлен.
Используйте команду @clear флаг для выключения, или
сброса флага. Сбрасывание флага противоположно установке.
Команда выглядит следующим образом:
@clear флаг
Пишите эту команду на отдельной строке.
Когда флаг сброшен, команды форматирования Texinfo не
форматируют текст между @ifset флаг и @end ifset;
этот текст игнорируется и не появляется ни в печатном руководстве, ни в
выводе Info.
Например, если вы сбросили флаг в предыдущем примере, написав команду
@clear большое после команды @set большое (но до
условного текста), то команды форматирования Texinfo проигнорируют текст
между @ifset большое и @end ifset. Этот текст не
появится в форматированном выводе; и в Info, и в печатном руководстве вы
увидите только строки, говорящие "Вы можете использовать эту машину для
выкапывания кустов, не повреждая их. Не забудьте быстро пересадить
...".
Если флаг сброшен командой @clear флаг, то текст между
соответствующими парами команд @ifset флаг и @end
ifset будет отформатирован. Но если флаг установлен с помощью
@set флаг, то команды форматирования не форматируют
текст между командами @ifclear и @end ifclear; они
игнорируют этот текст. Команда @ifclear выглядит следующим
образом:
@ifclear флаг
Кратко, существуют такие команды:
@set флаг
@clear флаг
@ifset флаг
@end ifset.
Если флаг сброшен, предписать командам форматирования Texinfo
игнорировать текст до следующей команды @end ifset.
@ifclear флаг
@end ifclear.
Если флаг сброшен, предписать командам форматирования Texinfo
игнорировать текст до следующей команды @end ifclear.
@set и @value
Вы можете использовать команду @set для установки значения
флага, которое потом может быть получено командой @value. Флаг
--- это идентификатор; для наилучших результатов используйте в имени
флага только буквы и цифры, но не `-' или `_' -- они
сработают в некоторых контекстах, но не всегда, из-за ограничений в
TeX. Значение -- это просто цепочка знаков, остаток строки ввода.
Команда @set записывается подобным образом:
@set foo Это строка.
Этот пример устанавливает значение флага foo равным "Это
строка.".
Программы форматирования Texinfo замещают команду
@value{флаг} строкой, в значение которой установлен
флаг. Таким образом, если foo установлен, как показано
выше, то программы форматирования Texinfo преобразуют
@value{foo}
в строку
Это строка.
Вы можете писать команду @value внутри абзаца, но команду
@set вы должны писать на отдельной строке.
Если вы напишите команду @set следующим образом:
@set foo
не задавая строку, то значением foo будет пустая строка.
Если вы очищаете ранее установленный флаг командой @clear
флаг, последующая команда @value{флаг} будет неверна, и
строка заменяется сообщением об ошибке: `{Значение "флаг" не
задано}'.
Например, если вы установили foo так:
@set насколько очень, очень, очень
то программы форматирования преобразуют
Сегодня @value{насколько} сырой день.
в строку
Сегодня очень, очень, очень сырой день.
Если вы напишите
@clear насколько
то программы форматирования преобразуют
Сегодня @value{насколько} сырой день.
в строку
Сегодня {Значение "насколько" не задано} сырой день.
@value
Вы можете использовать команду @value, чтобы уменьшить
количество мест в тексте, которые вам нужно изменить при внесении в
руководство исправлений или дополнений. Здесь показано, как это сделано
в Руководстве по GNU Make:
@set EDITION 0.35 Beta @set VERSION 3.63 Beta @set UPDATED 14 августа 1992 @set UPDATE-MONTH август 1992
@ifinfo, для тех, кто читает
Texinfo-файл:
Это редакция @value{EDITION},
последние исправления @value{UPDATED},
@cite{Руководства по GNU Make}
для @code{make} версии @value{VERSION}.
@title GNU Make
@subtitle Программа управления перекомпиляцией
@subtitle Редакция @value{EDITION}, ...
@subtitle @value{UPDATE-MONTH}
(На обложке книги, дата, сообщающая месяц и год выпуска, смотрится более
уместно, чем показывающая кроме этого также и число.)
Это редакция @value{EDITION},
последние исправления @value{UPDATED},
@cite{Руководства по GNU Make}
для @code{make} версии @value{VERSION}.
После форматирования руководства текст в первой секции @ifinfo
выглядит следующим образом:
Это редакция 0.35 Beta `Руководства по GNU Make', последние исправления 14 августа 1992, для `make' версии 3.63 Beta.
Когда вы исправляете руководство, измените только значения флагов; нет необходимости переписывать три секции.
В Texinfo есть некоторая поддержка для документов, написанных не на английском языке, хотя в этой области еще предстоит сделать значительную работу.
Для получения перечня различных акцентов и специальных символов, поддерживаемых Texinfo, смотрите section Вставка акцентов.
@documentlanguage cc: Задание языка документа
Команда @documentlanguage объявляет язык текущего документа.
Пишите ее на отдельной строке, после нее пишите двухсимвольный код языка
ISO-639 (перечень ниже). Если у вас есть документ на нескольких языках,
предполагается, что вы можете использовать ее несколько раз, для
объявления каждого изменения языка. Если эта команда не написана, по
умолчанию используется значение en, английский язык.
В настоящее время эта команда игнорируется при выводе в Info и HTML. В TeX, она считывает файл `txi-cc.tex' (если он существует). Эти файлы переопределяют различные английские слова, используемые в выводе TeX, такие как `Chapter', `See' и так далее.
Было бы неплохо, если бы эти команды изменяли также представление TeX
о текущих образцах переносов (с помощью примитива TeX
\language), но, к сожалению, пока это не реализовано.
@documentencoding enc: Задание входной кодировки
Команда @documentencoding объявляет входную кодировку документа.
Пишите ее на отдельной строке, после нее пишите правильное описание
кодировки, такое как `ISO-8859-1'.
На данный момент это используется только при выводе makeinfo в
формате HTML. Если задана кодировка документа код, она
используется в теге `<meta>' в секции `<head>':
<meta http-equiv="Content-Type" content="text/html; charset=код">
Texinfo предоставляет несколько способов определить новые команды:
@defmac, которая служит для документирования рассматриваемых в
руководстве макросов (see section Шаблон определения.)
Используйте для определения макросов команду Texinfo @macro, как
показано:
@macro имя-макроса{парам1, парам2, ...}
текст ... \парам1\ ...
@end macro
Параметры парам1, парам2, ... соответствуют аргументам, передаваемым макросу при последующих вызовах внутри документа (описано в следующем разделе).
Чтобы макрос работал в TeX, имя-макроса должно состоять только из букв и не включать цифр, подчерков, дефисов или других специальных знаков.
Если макрос не нуждается в параметрах, вы можете определить его с пустым списком параметров (`@macro foo {}') или вообще без фигурных скобок (`@macro foo').
В определении тела макроса может содержаться большинство команд
Texinfo, в том числе и определенные ранее макросы. Вызовы еще не
определенных макросов запрещены; таким образом, невозможно создать
взаимно рекурсивные макросы 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 и @command{makeinfo} макросы Texinfo обладают следующими ограничениями.
@ifinfo
@macro ctor {name, arg}
@macro \name\
нечто подразумевающее \arg\
@end macro
@end macro
@end ifinfo
@tex
\gdef\ctor#1{\ctorx#1,}
\gdef\ctorx#1,#2,{\def#1{нечто подразумевающее #2}}
@end tex
Команда `@alias' определяет новую команду, которая действует точно так же, как существующая. Это полезно для определения дополнительных разметочных имен, которые сохранят семантическую информацию на входе, хотя и, возможно, оставят результат таким же.
Пишите команду `@alias' на отдельной строке, а после пишите имя новой команды, знак равенства и имя существующей команды. Пропуски вокруг знака равенства игнорируются. Пример:
@alias новая = существующая
Например, если ваш документ содержит ссылки как на книги, так и на
другие произведения (скажем, фильмы), вы могли бы захотеть определить
макро @moviecite{}, которое делает то же самое, что и обычная
команда @cite{}, но также передает дополнительную
семантическую информацию. Вы могли бы сделать это так:
@alias moviecite = cite
Макросы не всегда имеют тот же эффект из-за капризов разбора аргументов. Кроме того, определять псевдонимы намного проще, чем макросы. Так что эта команда не избыточна. (Она также интенсивно применялась в Jargon File!)
Псевдонимы не должны быть рекурсивными, прямо или косвенно.
Вы можете использовать обычные команды TeX внутри блока
@iftex ... @end iftex для создания ваших собственных
выделяющих команд для Texinfo. Самый простой способ достичь этого ---
приравнять ваши команды уже существующим, например командам, выводящим
курсивом. Такие новые команды работают только в TeX.
Вы можете использовать команду @definfoenclose внутри блока
@ifinfo ... @end ifinfo для определения новых команд
для Info с теми же именами, что и новые команды для TeX.
@definfoenclose создает новые команды для Info, которые помечают
текст, окружая его заданными строками.(10).}
Ниже показано, как создать новую @-команду, называемую @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 неправильно воспримут завершающий разделитель как начальный.
После того, как вы определили @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
набирает аргумент жирным шрифтом.
Есть три основные команды оболочки для создания печатного руководства из Texinfo-файла: одна для преобразования Texinfo-файла в печатаемый файл, вторая для сортировки именных указателей и третья для печати отформатированного документа. Когда вы используете эти команды, вы можете работать непосредственно из оболочки операционной системы или из оболочки внутри GNU Emacs.
Если вы пользуетесь GNU Emacs, вы можете использовать вместо команд оболочки команды, предоставляемые режимом Texinfo. Кроме трех команд для форматирования файла, сортировки именных указателей и печати результата, режим Texinfo предоставляет привязки ключей для команд центрирования буфера вывода, показа очереди печати и удаления задания из очереди печати.
Для форматирования Texinfo-файлов используется программа для набора, называемая TeX. TeX -- это очень мощная программа подготовки печатных документов и, если ее правильно использовать, работает исключительно хорошо. (See section Как получить TeX, для информации о том, как получить TeX.)
Команды makeinfo, texinfo-format-region и
texinfo-format-buffer читают в Texinfo-файле те же самые
@-команды, что и TeX, но обрабатывают их иначе для создания
Info-файла; смотрите section Создание Info-файла.
tex и texindex
Форматируйте Texinfo-файл с помощью команды оболочки tex,
за которой стоит имя Texinfo-файла. Например:
tex foo.texi
TeX создаст DVI-файл, а также несколько вспомогательных файлов, содержащих сведения об именных указателях, перекрестных ссылках и другие. DVI-файл (от DeVice Independent, то есть независимый от устройства) можно напечатать практически на любом виде печатающих устройств (смотрите следующие разделы).
Форматирующая команда tex сама по себе не сортирует именные
указатели, она записывает файл с несортированными данными для
указателей. (Команда texi2dvi автоматически создает именные
указатели; see section Форматирование с помощью texi2dvi.) Чтобы создать печатный именной указатель после
прогона команды tex, сначала вам понадобится для работы
сортированный указатель. Команда texindex сортирует именные
указатели. (Исходный файл `texindex.c' поставляется как часть
стандартного дистрибутива Texinfo, кроме того, его можно найти в других
местах.)
Форматирующая команда tex выдает несортированные файлы именных
указателей с именами, подчиняющимися стандартному соглашению: имя вашего
главного входного файла с удаленным расширением `.tex' (или другим,
see section `tex invocation' in Web2c), за которым следуют две буквы
имени указателя. Например, необработанные выходные файлы с именными
указателями для входного файла `foo.texinfo' назывались бы
`foo.cp', `foo.vr', `foo.fn', `foo.tp',
`foo.pg' и `foo.ky'. Это в точности те аргументы, которые
нужно передать texindex.
Вместо явного задания всех файлов с несортированными именными указателями, вы можете использовать `??' в качестве шаблона оболочки и дать команду в такой форме:
texindex foo.??
Эта команда запустит texindex для всех файлов с несортированными
указателями, включая те, которые вы определили сами с помощью
@defindex или @defcodeindex. (Вы также можете выполнить
`texindex foo.??', даже если существуют файлы, называемые похожим
образом, с двухбуквенным расширением, такие как `foo.el'. Команда
texindex сообщает о таких файлах, но игнорирует их.)
Для каждого заданного файла texindex создает файл с сортированным
именным указателем, имя которого получается добавлением `s' к концу
имени входного файла. Команда @printindex ищет файлы с такими
именами (see section Меню-указатели и печать именных указателей). texindex не изменяет
исходный файл.
После того, как вы отсортировали именные указатели, вам нужно снова
запустить форматирующую команду tex для Texinfo-файла. Это
создаст DVI-файл, на этот раз с соответствующими действительности
вхождениями именных указателей.
Наконец, вам может понадобиться запустить tex еще один раз, чтобы
получить правильные номера страниц в перекрестных ссылках.
Кратко, вот процесс из пяти шагов:
tex для вашего Texinfo-файла. Это создаст DVI-файл (с
неопределенными перекрестными ссылками и без именных указателей) и
исходные файлы (с двухбуквенными расширениями) с именными указателями.
texindex для исходных файлов с именными указателями.
Это создаст соответствующие файлы (с трехбуквенными расширениями) с
сортированными указателями.
tex для вашего Texinfo-файла. Это заново создаст
DVI-файл, на этот раз с именными указателями и определенными
перекрестными ссылками, но номера страниц для перекрестных ссылок,
оставшиеся с последнего раза, как правило неверны.
tex последний раз. На этот раз для перекрестных ссылок
записываются правильные номера страниц.
Или это процесс из одного фага: запустите texi2dvi (see section Форматирование с помощью texi2dvi).
Вам не нужно запускать texindex каждый раз после запуска
tex. Если вы не этого не сделали, то при следующем запуске
форматирующая команда tex будет использовать файлы с
сортированными именными указателями, оставшиеся от прошлой работы
texindex. Обычно это подходит в процессе отладки.
Иногда вы можете захотеть напечатать документ, хотя знаете, что он
неполный, или напечатать только одну главу документа. В таком случае
обычные вспомогательные файлы, которые создает TeX, и предупреждения,
которые он выдает, когда перекрестные ссылки неверны, только мешают. Вы
можете избежать их появления с помощью команды @novalidate,
которую вы должны дать до команды @setfilename
(see section @setfilename). Таким образом, начало
вашего файла могло бы выглядеть примерно так:
\input texinfo @novalidate @setfilename myfile.info ...
@novalidate также выключает проверку в makeinfo, как ее
ключ --no-validate (see section Проверка указателей).
texi2dvi
Команда texi2dvi автоматически запускает tex и
texindex столько раз, сколько необходимо для создания DVI-файла с
сортированными именными указателями и всеми разрешенными перекрестными
ссылками. Она упрощает последовательность tex ---
texindex -- tex -- tex, описанную в предыдущем
разделе.
Чтобы запустить texi2dvi для входного файла `foo.texi',
сделайте следующее (где `prompt$ ' это приглашение вашей оболочки):
prompt$ texi2dvi foo.texi
Как показано в этом примере, имена входных файлов для texi2dvi
должны включать любое расширение (`.texi', `.texinfo', etc.).
Под MS-DOS и, возможно, в других обстоятельствах вам может понадобиться
запускать `sh texi2dvi foo.texi', а не полагаться на то, что
операционная система запустит для сценария `texi2dvi' оболочку.
Пожалуй, наиболее полезный ключ для texi2dvi -- это
`--texinfo=команда'. Он вставляет команду на отдельной
строке после @setfilename во временной копии входного файла
перед запуском TeX. С ним, вы можете задать различные форматы
печати, такие как @smallbook (see section Печать "маленьких" книг),
@afourpaper (see section Печать на формате A4) или @pageparams
(see section @pagesizes [ширина][, высота]: Произвольный размер страниц), не меняя в действительности исходный текст
документа. (Вы также можете сделать это для всей системы с помощью
`texinfo.cnf'; see section Подготовка к применению TeX).
Для получения списка ключей запустите `texi2dvi --help'.
lpr -dТочная команда для печати DVI-файла зависит от вашей системы, но обычно это `lpr -d'. Эта команда принимает имя DVI-файла без расширения или с расширением `.dvi'. (Если это команда `lpr', вы должны включать `.dvi'.)
Следующих команд, например, будет (может быть) достаточно для сортировки именных указателей, форматирования и печати Руководства по Bison:
tex bison.texinfo texindex bison.?? tex bison.texinfo lpr -d bison.dvi
(Помните, что команды оболочки могут быть другими в вашей системе; но это чаще всего используемые версии.)
При использовании сценария оболочки texi2dvi, вам нужно просто
напечатать:
texi2dvi bison.texinfo lpr -d bison.dvi
lpr -- это стандартная программа в системах Unix, но она обычно
отсутствует в MS-DOS/MS-Windows. Некоторые сетевые пакеты могут
поставляться с программой, называемой lpr, но их возможности
обычно ограничены посылкой файлов по сети на сервер печати, и обычно они
не поддерживают ключ `-d'. Если вы насколько невезучи, что
работаете на одной из этих систем, у вас есть несколько альтернативных
способов напечатать DVI-файлы:
lpr или ее
имитацию. Если вы можете это сделать, то сможете печатать DVI-файлы
точно так, как описано выше.
lpr, поставляемая с вашим сетевым программным
обеспечением, имеет специальные ключи для посылки файла в конкретную
очередь, как здесь:
lpr -Qdvi -hprint.server.domain bison.dvi
dvilj для подробного описания этих инструментов.
Когда DVI-файл преобразован в формат, который ваш принтер понимает
непосредственно, вы можете послать его на соответствующий порт, как
правило это `PRN'.
Вы можете исполнить команды форматирования и печати из подчиненной оболочки GNU Emacs. Чтобы создать в Emacs оболочку, напечатайте M-x shell. В этой оболочке вы можете форматировать и печатать документ. See section Форматирование и печать твердой копии, для подробностей.
Вы можете переключиться в буфер оболочки и из него во время работы
tex и редактировать что-то еще. Если вы форматируете длинный
документ на медленной машине, это может быть очень удобно.
Вы можете также использовать texi2dvi из оболочки Emacs.
Например, так можно применить texi2dvi для форматирования и
печати книги Использование и перенос GNU CC из оболочки в Emacs:
texi2dvi gcc.texinfo lpr -d gcc.dvi
Режим Texinfo предоставляет несколько предопределенных команд, привязанных к ключам, для форматирования и печати с TeX. Они включают команды для сортировки именных указателей, просмотра очереди печати, уничтожения форматирующего задания и центрирования буфера, в котором происходят эти действия.
texi2dvi для текущего буфера.
texinfo-tex-region.
texinfo-tex-region
или texinfo-tex-buffer.
texinfo-show-tex-print-queue).
texinfo-tex-region или texinfo-tex-buffer, или
любой другой процесс, работающий в буфере оболочки Texinfo.
Таким образом, обычная последовательность команд для форматирования буфера выглядит, как показано ниже (с комментариями справа):
C-c C-t C-b Запустить texi2dvi для буфера.
C-c C-t C-p Напечатать DVI-файл.
C-c C-t C-q Показать очередь принтера.
Команды форматирования с TeX в режиме Texinfo запускают в Emacs
подоболочку, называемую `*tex-shell*'. Команды
texinfo-tex-command, texinfo-texindex-command и
tex-dvi-print-command работают в этой оболочке.
Вы можете наблюдать за работой команд в буфере `*tex-shell*', переключаться в него и из него и использовать буфер `*tex-shell*' как любой другой буфер оболочки.
Команды печати и форматирования зависят от нескольких переменных. Их значения по умолчанию:
Переменная Значение по умолчанию
texinfo-texi2dvi-command "texi2dvi"
texinfo-tex-command "tex"
texinfo-texindex-command "texindex"
texinfo-delete-from-print-queue-command "lprm"
texinfo-tex-trailer "@bye"
tex-start-of-header "%**start"
tex-end-of-header "%**end"
tex-dvi-print-command "lpr -d"
tex-show-queue-command "lpq"
Вы можете изменить значения этих переменных с помощью команды M-x edit-options (see section `Editing Variable Values' in Руководство по GNU Emacs), команды M-x set-variable (see section `Examining and Setting Variables' in Руководство по GNU Emacs) или вашего файла инициализации `.emacs' (see section `Init File' in Руководство по GNU Emacs).
Начиная с версии 20, GNU Emacs предоставляет дружественный интерфейс, называемый Customize, для изменения значений переменных, задаваемых пользователем. See section `Easy Customization Interface' in Руководство по GNU Emacs, для подробностей об этом пакете. Переменные Texinfo можно найти в группе `Development/Docs/Texinfo', когда вы вызвали команду M-x customize.
Еще один способ применить команду форматирования с TeX к
Texinfo-файлу -- поместить эту команду в список локальных
переменных в конце этого Texinfo-файла. Вы можете задать команду
tex или texi2dvi в качестве переменной
compile-command и велеть Emacs запустить ее, напечатав M-x
compile. Это создаст специальную оболочку, называемую буфером
`*compilation*', в которой Emacs запускает команду компиляции.
Например, в конце файла `gdb.texinfo', после @bye, вы могли
бы написать следующее:
Local Variables: compile-command: "texi2dvi gdb.texinfo" End:
Этот метод чаще всего применяется программистами, которые также компилируют таким образом программы; смотрите section `Compilation' in Руководство по GNU Emacs.
Каждый Texinfo-файл, предназначенный для обработки TeX, должен
начинаться командой \input и содержать команду
@setfilename:
\input texinfo @setfilename arg-not-used-by-TeX
Первая команда указывает TeX загрузить макросы, которые нужны ему для обработки Texinfo-файла, а вторая команда открывает вспомогательные файлы.
Каждый Texinfo-файл должен заканчиваться строкой, прекращающей работу TeX и выводящей незавершенные страницы:
@bye
Строго говоря, эти строки -- все, что нужно, чтобы Texinfo-файл был успешно обработан TeX.
Однако, обычно начало включает команду @settitle для определения
названия печатного руководства, команду @setchapternewpage,
титульный лист, страницу с информацией об авторских правах и разрешения
на копирование. Кроме @bye, конец файла обычно включает именные
указатели и содержание. (И конечно, большинство руководств также
содержат тело текста.)
Для дальнейшей информации смотрите:
@settitle,
@setchapternewpage,
TeX должен знать, где найти файл `texinfo.tex', который вы велели ему включить командой `\input texinfo' в начале первой строки. Файл `texinfo.tex' говорит TeX, как обращаться с @-командами; он включается во все стандартные дистрибутивы GNU.
Обычно файл `texinfo.tex' помещается в каталог по умолчанию, который содержит макросы TeX, когда устанавливается GNU Emacs или другое программное обеспечение GNU. (По умолчанию это `/usr/local/share/texmf/tex/texinfo/texinfo.tex'.) В этом случае TeX сможет найти файл, и вам не понадобится делать ничего особенного. Или вы можете поместить `texinfo.tex' в текущий каталог при запуске TeX, и TeX найдет его там.
Также, вам нужно установить `epsf.tex' в то же место, что и
`texinfo.tex', если он не был уже установлен из другого
дистрибутива. Этот файл нужен для поддержки команды @image
(see section Вставка рисунков).
При желании вы можете создать дополнительный файл `texinfo.cnf' и
установить и его. TeX читает этот файл во время исполнения команды
@setfilename (see section @setfilename). Вы
можете поместить в нем любые команды по вашему желанию, в соответствии с
локальными общесистемными соглашениями. Они будут читаться TeX при
обработке любого документа Texinfo. Например, если `texinfo.cnf'
содержит строку `@afourpaper' (see section Печать на формате A4), то все
документы Texinfo будут обрабатываться с таким размером страницы. Если
вам нечего написать в `texinfo.cnf', вам не обязательно его
создавать.
Если ни одно из указанных выше положений этих системных файлов для вас
не достаточно, вы можете задать каталоги явно. Для `texinfo.tex',
вы можете сделать это, написав полный путь к файлу после команды
\input. Другой способ, работающий и для `texinfo.tex', и
для `texinfo.cnf' (и любого другого файла, которой мог бы читать
TeX), -- установить переменную среды TEXINPUTS в вашем файле
`.cshrc' или `.profile'.
Какой из `.cshrc' или `.profile' вам нужен, зависит от того,
используете ли вы совместимый с Bourne shell (sh, bash,
ksh, ...) или совместимый с C shell (csh, tcsh)
командный интерпретатор. Последний читает для инициализации файл
`.cshrc', а первый читает `.profile'.
В файле `.cshrc', вы можете использовать следующую
последовательность команд csh:
setenv TEXINPUTS .:/home/me/mylib:/usr/lib/tex/macros
В файле `.profile', вы можете использовать следующую
последовательность команд sh:
TEXINPUTS=.:/home/me/mylib:/usr/lib/tex/macros export TEXINPUTS
В MS-DOS/MS-Windows, вы могли бы сказать это таким образом (11):
set TEXINPUTS=.;d:/home/me/mylib;c:/usr/lib/tex/macros
Обычно пользователи DOS/Windows помещают такие команды в файл `autoexec.bat' или Реестр Windows.
Эти установки заставили бы TeX искать файл для `\input' сначала в текущем каталоге, обозначаемом `.', затем в каталоге гипотетического пользователя `me/mylib' и, наконец, в системном каталоге `/usr/lib/tex/macros'.
Наконец, вы можете захотеть сделать дамп форматного файла (@xref{Memory dumps,,, @external{web2c}, Web2c}), чтобы TeX мог загружать Texinfo быстрее. (Недостаток этого в том, что при обновлении `texinfo.tex' потребуется повторный дамп.) Вы можете сделать это, запустив такую команду, в предположении, что TeX находит `epsf.tex':
initex texinfo @dump
(@dump -- это примитив TeX.) Затем вам нужно перенести
`texinfo.fmt' в то место, где находятся ваши .fmt-файлы;
обычно это подкаталог `web2c' вашего TeX, например,
`/usr/local/share/tex/web2c'.
Иногда TeX не может набрать строку, не расширяя ее за правый край. Это может случиться, когда TeX встречает что-то, что он интерпретирует как длинное слово, которое он не может перенести, такое как адрес электронной почты или очень длинный заголовок. Когда такое случается, TeX печатает сообщение об ошибке вроде этого:
Overfull @hbox (20.76302pt too wide)
(В TeX, строки являются "горизонтальными боксами", отсюда термин "hbox". `@hbox' -- это примитив TeX, не нужный в языке Texinfo.)
TeX также выдает номер строки в исходном Texinfo-файле и текст плохой строки, который помечен во всех местах, которые TeX счел точками возможного переноса. See section Поиск ошибок при форматировании с TeX, для большей информации об ошибках при наборе.
Если в Texinfo-файле есть переполненный горизонтальный бокс, вы можете переписать предложение так, чтобы бокс не переполнялся, или вы можете решить оставить его. Небольшое вторжение на правое поле часто не играет роли и даже может быть незаметно.
Если у вас есть много переполненных боксов и/или антипатия к переписыванию, вы можете увеличить допустимый междусловный пропуск, избегнув таким образом (если повезет) много неудачных разрывов строк; это делается так:
@tex \global\emergencystretch = .9\hsize @end tex
(Вы можете подобрать дробь по необходимости.) Такое огромное значение
для \emergencystretch не может приниматься по умолчанию, потому
что тогда набранный вывод был бы в основном заметно ниже качеством.
Значение по умолчанию равно `.15\hsize'. \hsize -- это
размерность в TeX, содержащая текущую ширину строки.
Однако, для существующих переполненных боксов TeX будет печатать большой уродливый черный прямоугольник после строки, содержащей переполненный горизонтальный бокс, если не сказано иного. Это делается, чтобы вы заметили место, где возникла проблема, если вы корректируете черновик.
Для предотвращения таких ужасов в вашей окончательной распечатке,
напишите следующее в начале Texinfo-файла на отдельной строке, перед
командой @titlepage:
@finalout
По умолчанию, TeX набирает страницы для печати в формате 8.5 на 11 дюймов. Однако, вы можете указать TeX набирать документ в формате 7 на 9.25 дюймов, который подходит для переплетенных книг, вставив следующую команду на отдельной строке в начале Texinfo-файла, перед титульным листом:
@smallbook
(Так как многие книги имеют размер примерно 7 на 9.25 дюймов, эту
команду лучше было бы назвать @regularbooksize, но она стала
называться командой @smallbook в сравнении с форматом 8.5 на 11
дюймов.)
Если вы пишите команду @smallbook между строк start-of-header и
end-of-header, то в режиме Texinfo команда форматирования области с
помощью TeX, texinfo-tex-region, будет форматировать область с
размером "маленькой" книги (see section Начало заголовка).
See section Команды блоков @small..., для информации о командах, облегчающих создание примеров
для меньших руководств.
See section Форматирование с помощью texi2dvi, и section Подготовка к применению TeX, другие способы отформатировать в
формате @smallbook, не требующие изменения исходного файла.
Вы можете сказать TeX форматировать документ для печати на бумаге
европейского формата A4 с помощью команды @afourpaper. Пишите
эту команду на отдельной строке недалеко от начала Texinfo-файла, до
титульного листа. Например, так вы могли бы написать заголовок для
данного руководства:
\input texinfo @c -*-texinfo-*- @c %**start of header @setfilename texinfo @settitle Texinfo @afourpaper @c %**end of header
See section Форматирование с помощью texi2dvi, section Подготовка к применению TeX, другие способы отформатировать в
формате @afourpaper, не требующие изменения исходного файла.
Вы можете предпочесть или не предпочесть форматирование, получающееся с
помощью команды @afourlatex. Есть также команда
@afourwide для бумаги A4 в широком формате.
@pagesizes [ширина][, высота]: Произвольный размер страниц
Вы можете явно задать высоту и (возможно) ширину области основного
текста на странице с помощью команды @pagesizes. Пишите ее на
отдельной строке недалеко от начала Texinfo-файла, до титульного листа.
Сначала пишется высота, потом, если нужно, ширина, разделенные запятыми.
Примеры:
@pagesizes 200mm,150mm
и
@pagesizes 11.5in
Это может быть полезно при печати на формате B5. Подчеркнем, эта команда задает размер области текста, а не размер бумаги (который равен 250mm на 177mm для B5, 14in на 8.5in для legal).
Чтобы сделать более изощренные изменения, например изменение полей страницы, вы должны определить новую команду в `texinfo.tex' (или `texinfo.cnf', see section Подготовка к применению TeX).
See section Форматирование с помощью texi2dvi, and section Подготовка к применению TeX, другие способы задать команду
@pagesizes, не требующие изменения исходного файла.
@pagesizes игнорируется makeinfo.
С помощью команды @cropmarks вы можете (попытаться) заставить
TeX печатать метки обреза листа в углах страниц. Пишите эту команду
на отдельной строке между @iftex и @end iftex недалеко
от начала Texinfo-файла, до титульного листа, как показано здесь:
@iftex @cropmarks @end iftex
Это команда преимущественно для принтеров, которые набирают несколько
страниц на одном листе или одной пленке; но вы можете попытаться
применить ее для пометки углов книги с размером 7 на 9.25 дюймов,
установленным командой @smallbook. (Принтеры могут не
напечатать обрезные метки для вывода обычного размера, напечатанного на
обычного размера бумаге.) Так как различные печатающие устройства
работают по-разному, вам придется с духом приключения поисследовать
использование этой команды. Вам, возможно, понадобится переопределить
эту команду в файле `texinfo.tex'.
Вы можете попытаться указать TeX печатать страницы большими или
меньшими, чем обычно, с помощью команды TeX \mag. Весь набор
масштабируется пропорционально больше или пропорционально меньше.
(\mag обозначает "magnification", то есть "увеличение".) Это
не @-команда Texinfo, а команда plain TeX, перед которой
ставится обратная косая черта. Вы должны писать эту команду между
@tex и @end tex (see section Непосредственный вызов команд программы форматирования).
После команды \mag пишите `=' и затем число, равное
желаемому увеличению, умноженному на 1000. Например, чтобы напечатать
страницы размером в 1.2 от нормального, напишите следующее недалеко от
начала Texinfo-файла, до титульного листа:
@tex \mag=1200 @end tex
В некоторых технологиях печати вы можете напечатать копии нормального размера, выглядящие лучше, чем обычно, передав в типографию увеличенный оригинал-макет. Они производят уменьшение, улучшая в действительности разрешение.
В зависимости от вашей системы, DVI-файлы, подготовленные с помощью
нестандартной \mag, могут не печататься или печататься только при
определенных увеличениях. Будьте готовы к экспериментам.
Вы можете сгенерировать из исходного Texinfo-файла выходной PDF-файл, используя для обработки вашего файла программу @command{pdftex}, а не простой @command{tex}. Просто запустите `pdftex foo.texi' вместо `tex foo.texi' или задайте для @command{texi2dvi} ключ @option{--pdf} .
PDF означает Portable Document Format@transnote{Переносимый формат документов.}, он был изобретен фирмой Adobe Systems. Определение формата файлов доступно свободно, также доступен свободная программа просмотра для системы X Windows. Поскольку PDF -- это двоичный формат, команды `@ifpdf' или `@pdf', по аналогии с другими выходными форматами, не существует.
Несмотря на слово `переносимый' в названии, PDF-файлы близко не подходят по переносимости к форматам простого ASCII (Info, HTML), которые также поддерживаются Texinfo (о переносимости относительно DVI можно поспорить). Они также бывают намного больше, и в ни нет хорошей поддержки растровых шрифтов, используемых в TeX (по умолчанию). Тем не менее, PDF-файл показывает на экране действительный печатный документ как можно более правдиво, в отличие, скажем, от HTML, так что оба нужны.
Поддержа PDF в Texinfo довольно рудиментарна.
Эта глава рассказывает, как создать и установить Info-файлы. See section Info-файлы, для получения общих сведений о самом формате этих файлов.
makeinfo -- это программа, преобразующая Texinfo-файл в
Info-файл, файл на HTML, или простой текст.
texinfo-format-region и texinfo-format-buffer -- это
функции GNU Emacs, преобразующие Texinfo в Info.
Информацию об установке Info-файла в систему Info смотрите в see section Установка Info-файла.
makeinfo
Утилита makeinfo создает Info-файл из исходного Texinfo-файла
быстрее любой форматирующей команды Emacs и предоставляет лучшие
сообщения об ошибках. Мы рекомендуем применять ее. makeinfo ---
это программа на Си, независимая от Emacs. Вы не должны запускать
Emacs, чтобы использовать makeinfo, что означает, что вы можете
использовать makeinfo на машинах, слишком маленьких, чтобы
запустить Emacs. Вы можете запустить makeinfo любым из трех
таких способов: из оболочки операционной системы, из оболочки внутри
Emacs или напечатав команды C-c C-m C-r или C-c C-m C-b в
режиме Texinfo в Emacs.
Команды texinfo-format-region и texinfo-format-buffer
полезны, если вы не можете запустить makeinfo. Кроме того, при
некоторых обстоятельствах они форматируют небольшие области или буферы
быстрее, чем makeinfo.
makeinfo из оболочки
Чтобы создать Texinfo-файл из Info-файла, напечатайте makeinfo и
имя Texinfo-файла. Таким образом, чтобы создать Info-файл для Bison,
напечатайте в оболочке следующее:
makeinfo bison.texinfo
(Вы можете запустить оболочку в Emacs, напечатав M-x shell.)
makeinfo
Команда makeinfo принимает несколько ключей. Чаще всего ключи
применяются для задания колонки заполнения и стиля сносок. Каждый ключ
командной строки -- это слово с предшествующими символами `--' или
буква с предшествующим `-'. Вы можете использовать сокращения для
длинных ключей, если они однозначны.
Например, вы можете использовать следующую команду для создания из файла `bison.texinfo' такого Info-файла, в котором каждая строка заполнена на 68 колонок:
makeinfo --fill-column=68 bison.texinfo
Вы можете последовательно написать два ключа или более, например так:
makeinfo --no-split --fill-column=70 ...
Это сохранит Info-файл целиком в виде, возможно, очень большого файла и установит колонку заполнения равной 70.
Воспринимаются такие ключи:
@set
переменная в Texinfo-файле (see section @set, @clear и @value).
makeinfo
перед выходом (в предположении, что продолжать бесполезно); по
умолчанию 100.
@footnotestyle (see section Сноски).
Когда стиль сносок установлен в значение `separate',
makeinfo создает новую ноду для сносок, находящихся в текущей
ноде. Когда стиль сносок установлен в значение `end',
makeinfo помещает сноски в конце текущей ноды. Игнорируется
`--html'.
@include. По умолчанию, makeinfo
производит поиск только в текущем каталоге. Если каталог не
задан, добавляется каталог `.', то есть текущий. Заметьте, что
каталог может на самом деле быть списком нескольких каталогов,
разделенных обычным символом-разделителем путей (`:' в Unix,
`;' в MS-DOS/MS-Windows).
makeinfo
и затем отбрасываются. Этот ключ используется программой
@command{texi2dvi}, если у вас установлена старая версия
`texinfo.tex', которая не поддерживет @macro.
makeinfo. По умолчанию,
большие выходные файлы (размером более 70 тысяч байт) разбиваются на
меньшие подфайлы. При выводе в формате Info, размер каждого примерно 50
тысяч байт. При выводе в формате HTML, каждый файл содержит одну ноду
(see section Создание HTML).
makeinfo. Это
можно сделать также командой @novalidate (see section Используйте TeX). Обычно после обработки Texinfo-файла
производятся некоторые проверки соответствия, чтобы убедиться, что
перекрестные ссылки разрешаются и прочее. See section Проверка указателей.
makeinfo
последовательно нумерует все сноски в одной ноде, сбрасывая номер сноски
на 1 в начале каждой ноды.
@setfilename в исходном Texinfo-файле
(see section @setfilename). Если файл равен `-', вывод идет в
стандартный вывод и подразумевается `--no-split'. При выводе в
формате HTML, файл -- это имя выходного файла для первой ноды
(see section Создание HTML).
@include. Если каталог не задан,
добавляется каталог `.', то есть текущий. Смотрите `-I' для
получения деталей.
@paragraphindent (see section Отступ в начале абзаца). Значение
отступа интерпретируется следующим образом:
makeinfo будет
делать, не выдавая предупреждения. Если нода содержит больше ссылок,
чем это число, makeinfo создаст эти ссылки, но также выдаст
предупреждение. Значение по умолчанию равно 1000.
@clear
переменная в Texinfo-файле (see section @set, @clear и @value).
makeinfo выводить сообщения о том, что она делает.
Обычно makeinfo выводит сообщения, только если есть ошибки или
предупреждения.
Если вы не подавили проверку указателей с помощью ключа
`--no-validate' или команды @novalidate в исходном файле
(see section Используйте TeX), makeinfo сделает
проверку конечного Info-файла. Как правило это означает проверку того,
что все ноды, на которые вы ссылались, на самом деле существуют. Вот
полный список проверок:
Некоторые документы Texinfo могут не пройти фазу проверки, потому что в
них команды вроде @value и @definfoenclose
использовались в определениях нод и в перекрестных ссылках
непоследовательно. Рассмотрим следующий пример:
@set nodename Node 1
@node @value{nodename}, Node 2, Top, Top
Это нода 1.
@node Node 2, , Node 1, Top
Это нода 2.
Эдесь на ноду "Node 1" ссылаются как по точному имени, так и через
@value.
По умолчанию @command{makeinfo} терпит в таких случаях неуспех,
поскольку имена нод не раскрываются полностью, пока не будут записаны в
выходной файл. Вы должны всегда стараться ссылаться на ноды
последовательно; скажем, в примере выше во второй строка @node
следует также использовать @value. Если однако, по какой-либо
причине вы должны ссылаться на имена нод непоследовательно, и
@command{makeinfo} не подтверждает правильность этого файла, вы можете
использовать ключ @option{--commands-in-node-names}, чтобы принудить
@command{makeinfo} производить ресурсоемкое раскрытие всех имен нод,
которые она находит в документе. Это, однако, может заметно замедлить
работу программы; для больших файлов, таких как the Jargon file, было
зафиксировано двукратное увеличение времени преобразования.
Поддержка @-команд в директивах @node не обладает
достаточной общностью, чтобы ей можно было свободно пользоваться.
Например, если приведенный выше пример переопределит бы где-то в
документе nodename, то makeinfo не сможет преобразовать
ее, даже если вызвать с ключом @option{--commands-in-node-names}.
@option{--commands-in-node-names} не имеет действия, если задан ключ @option{--no-validate}.
makeinfo из Emacs
Вы можете запустить makeinfo из режима Texinfo в GNU Emacs,
используя команду makeinfo-region или makeinfo-buffer. В
режиме Texinfo, эти команды по умолчанию привязаны к C-c C-m C-r и
C-c C-m C-b.
Когда вы вызываете makeinfo-region или makeinfo-buffer,
Emacs запрашивает имя файла, предлагая по умолчанию имя текущего файла.
Вы можете, если хотите, отредактировать в минибуфере имя файла по
умолчанию, перед нажатием RET и началом процесса
makeinfo.
Команды Emacs makeinfo-region и makeinfo-buffer запускают
программу makeinfo во временном буфере оболочки. Если
makeinfo находит ошибки, Emacs отображает сообщения об ошибках в
этом временном буфере.
Вы можете произвести грамматический разбор сообщений об ошибках,
напечатав C-x ` (next-error). Это заставляет Emacs
перевести курсор на ту строку в исходном Texinfo-файле, которая, по
мнению makeinfo вызывает ошибку. See section `Running make or Compilers Generally' in Руководство по GNU Emacs,
для подробной информации об использовании команды next-error.
Помимо этого, вы можете уничтожить оболочку, в которой запущена команда
makeinfo, или сделать так, чтобы буфер оболочки показывал самые
последние строки вывода.
makeinfo, созданный
makeinfo-region или makeinfo-buffer.
makeinfo самые последние строки
вывода.(Обратите внимание, аналогичные команды для уничтожения и центрирования процесса TeX -- это C-c C-t C-k и C-c C-t C-l. See section Форматирование и печать в режиме Texinfo.)
Вы можете задать ключи для makeinfo, установив переменную
makeinfo-options с помощью команд M-x edit-options или
M-x set-variable, или установив эту переменную в вашем файле
инициализации `.emacs'.
Например, вы можете написать в вашем файле `.emacs' следующее:
(setq makeinfo-options
"--paragraph-indent=0 --no-split
--fill-column=70 --verbose")
Дальнейшую информацию смотрите в section Ключи для makeinfo, а также "Editing Variable Values," "Examining and
Setting Variables," и "Init File" в Руководстве по GNU Emacs.
texinfo-format...
В режиме Texinfo GNU Emacs вы можете отформатировать Texinfo-файл или
его часть с помощью команды texinfo-format-region. Она
форматирует текущую область и выводит форматированный текст во временный
буфер, называемый `*Info Region*'.
Аналогично, вы можете отформатировать буфер с помощью команды
texinfo-format-buffer. Она делает новый буфер и выводит в него
Info-файл. Вызов C-x C-s сохранит этот Info-файл под именем,
заданным строкой @setfilename, которая должна быть недалеко от
начала Texinfo-файла.
texinfo-format-region
texinfo-format-buffer
Команды texinfo-format-region и texinfo-format-buffer
обеспечивают некоторую проверку ошибок, а другие функции могут
предоставить вам дальнейшую помощь в нахождении ошибок форматирования.
Эти процедуры описаны в приложении; смотрите section Ошибки форматирования.
Однако программа makeinfo часто работает быстрее и предоставляет
лучшую проверку ошибок (see section Запуск makeinfo из Emacs).
Вы можете отформатировать Texinfo-файлы для Info, используя
batch-texinfo-format и пакетный режим Emacs. Вы можете запустить
Emacs в пакетном режиме из оболочки, в том числе из оболочки внутри
Emacs. (See section `Command Line Switches and Arguments' in Руководство по GNU Emacs.)
Вот команда оболочки для форматирования всех файлов в текущем каталоге, оканчивающихся на `.texinfo':
emacs --batch --funcall batch-texinfo-format *.texinfo
Emacs обрабатывает все файлы, перечисленные в командной строке, даже если во время форматирования некоторых возникли ошибки.
Запускайте batch-texinfo-format только в пакетном режиме Emacs,
как показано; эта команда не интерактивна. Она уничтожает Emacs после
завершения.
batch-texinfo-format удобна, если у вас нет makeinfo, и вы
хотите отформатировать несколько Texinfo-файлов одновременно. Когда вы
используете пакетный режим, вы создаете новый процесс Emacs. Это
высвобождает ваш текущий Emacs, так что вы можете продолжать в нем
работать. (Когда вы запускаете texinfo-format-region или
texinfo-format-buffer, вы не можете использовать Emacs ни для
чего больше, пока команда не закончит работу.)
Если Texinfo-файл содержит более 30000 байт,
texinfo-format-buffer автоматически создает таблицу тегов для его
Info-файла; makeinfo всегда создает таблицу тегов. С
таблицей тегов Info может переходить к другим нодам быстрее, чем
без нее.
Кроме того, если Texinfo-файл содержит более примерно 70000 байт,
texinfo-format-buffer и makeinfo разбивают большой
Info-файл на меньшие косвенные подфайлы примерно по 50000 байт в
каждом. Большие файлы разбиваются на меньшие, чтобы Emacs не должен был
делать большие буферы для хранения большого Info-файла целиком; вместо
этого Emacs выделяет памяти чтобы как раз хватило для маленького,
отсоединенного файла, нужного в данный момент. Таким способом Emacs
избегает ненужной траты памяти, когда вы запускаете Info. (До того, как
было реализовано разбиение, Info-файлы всегда делались короткими, а для
создания единого, большого печатного руководства из меньших Info-файлов
были разработаны включаемые файлы. See section Включаемые файлы, для
подробной информации. Включаемые файлы до сих пор используются для
очень больших документов, таких как The Emacs Lisp Reference
Manual, в котором каждая глава -- это отдельный файл.)
Когда файл разбит, сама Info использует укороченную версию первоначального файла, содержащую только таблицу тегов и ссылки на отсоединенные файлы. Отсоединенные файлы называются косвенными файлами.
Отсоединенные файлы имеют имена, образованные добавлением `-1',
`-2', `-3' и так далее к имени файла, заданного
командой @setfilename. Укороченная версия первоначального файла
так же имеет имя, заданное @setfilename.
На одной стадии написания оригинала этого документа, к примеру, Info-файл был сохранен как `test-texinfo', и этот файл выглядел следующим образом:
Info file: test-texinfo, -*-Text-*- produced by texinfo-format-buffer from file: new-texinfo-manual.texinfo ^_ Indirect: test-texinfo-1: 102 test-texinfo-2: 50422 test-texinfo-3: 101300 ^_^L Tag table: (Indirect) Node: overview^?104 Node: info file^?1271 Node: printed manual^?4853 Node: conventions^?6855 ...
(Но в `test-texinfo' было гораздо больше нод, чем показано здесь.) Каждый из отсоединенных, косвенных файлов, `test-texinfo-1', `test-texinfo-2' и `test-texinfo-3', перечислен в этом файле после строки, в которой написано `Indirect:'. Таблица тегов помещена после строки `Tag table:'.
В перечне косвенных файлов, число, следующее после имени файла, хранит накопленное количество байт в предыдущих косвенных файлах, не считая сам перечень файлов, таблицу тегов или текст разрешения на копирование в каждом файле. В таблице тегов, число, следующее после имени ноды, хранит позицию начала этой ноды, в байтах от начала (разбиваемого) файла.
Если вы используете для создания Info-файлов
texinfo-format-buffer, вы, возможно, захотите запустить команду
Info-validate. (Команда makeinfo сама по себе делает
хорошие проверки, вам не нужно применять Info-validate.) Однако,
вы не можете запустить команду проверки нод M-x Info-validate в
косвенных файлах. Для получения информации о том, как предотвратить
разбиение файла и как проверить структуру нод, смотрите
section Запуск Info-validate.
Как альтернативу обычному выводу в формате Info, вы можете использовать
ключ `--html' для создания вывода в формате HTML для установки на
Web-сайте (к примеру). В данном выпуске makeinfo производит
монолитный HTML-файл; разбиение по главам или нодам не поддерживается.
Мы надеемся в скором времени реализовать эту возможность.
Выходному HTML-файлу дается имя в соответствии с @setfilename,
но расширение `.info' заменяется на `.html'.
Входной текст Texinfo, помеченный командой @ifhtml, будет давать
вывод, только если задан ключ `--html'. Входной текст, помеченный
@html, передается на выход буквально (с подавлением обычного
преобразования входных символов `<', `>' и `&', имеющих
особое значение в HTML).
Ключ `--footnote-style' на данный момент игнорируется при выводе HTML; для сносок делаются гиперсвязи на конец выходного файла.
Создаваемый HTML главным образом соответствует стандарту (то есть HTML
2.0, RFC1866). Исключение в том, что из команды @multitable
создаются таблицы HTML 3.2, но так, чтобы они как можно лучше
отображались броузерами без поддержки таблиц. Пожалуйста, сообщайте о
выводе, полученном от makeinfo без сообщений об ошибок, но
нарушающем HTML 3.2 DTD как об ошибке программы.
В начало нод, как при выводе в Info, вставляются панели навигации. Это
можно предотвратить, используя ключ @option{--no-headers} вместе с
@option{--no-split}. Элементы заголовка <link> могут
поддерживать перемещение, как в Info, с броузерами, реализующими эту
возможность HTML 1.0, такими как Lynx и Emacs W3. Все же вы
обычно теряете возможность поиска регулярных выражений и вхождений
именного указателя во многих файлах, предоставляемую программами чтения
Info. Вместо этого, когда возможно, из команд Texinfo создаются
гиперсвязи. Команды `@xref', ссылающиеся на другие документы,
создаются в предположении, что они также доступны в форме HTML, и к
имени Info-файла в `@xref' добавляется `.html'.
Предположительно, часто это не будет работать.
Info-файлы обычно хранятся в каталоге `info'. Вы можете читать Info-файлы с помощью отдельной программы Info или программой чтения, встроенной в Emacs. (See Info file `info', node `Top', введение в Info.)
Чтобы Info могла работать, в каталоге `info' должен быть файл, служащий каталогом верхнего уровня системы Info. По соглашению, этот файл называется `dir'. (Вы можете узнать местоположение этого файла, нажав в Emacs C-h i, чтобы войти в Info, и затем C-x C-f, чтобы увидеть полный путь к каталогу `info'.)
Файл `dir' сам по себе является Info-файлом. В нем содержится меню верхнего уровня для всех Info-файлов в системе. Это меню выглядит следующим образом:
* Menu:
* Info: (info). Система просмотра документации.
* Emacs: (emacs). Расширяемый, самодокументированный
текстовый редактор.
* Texinfo: (texinfo). Создание печатного руководства с
помощью TeX или Info-файла из
одного исходного файла.
...
Каждый из этих пунктов меню указывает на первую (`Top') ноду Info-файла, чье имя написано в круглых скобках. (В пункте меню не обязательно задавать ноду `Top', так как если нода не задана, Info сама переходит к ноде `Top'. See section Ссылки на другие Info-файлы.)
Таким образом, пункт `Info' указывает на первую ноду файла `info', а пункт `Emacs' -- на первую ноду файла `emacs'.
В каждом Info-файле, указатель `Вверх' (`Up') первой ноды ссылается на
файл dir. Например, строка первой ноды руководства по Emacs
выглядит в Info так:
File: emacs Node: Top, Up: (DIR), Next: Distrib
В данном случае имя файла dir написано заглавными буквами -- оно
может быть написано как заглавными, так и строчными. В общем случае это
не так, но для `dir' делается исключение.
Чтобы включить новый Info-файл в систему, вы должны написать пункт меню и добавить его в файл `dir' в каталоге `info'. Например, если вы добавляете документацию для GDB, вам следует написать такой новый пункт:
* GDB: (gdb). Отладчик C на уровне исходного кода.
Первая часть пункта меню -- это название этого пункта, за которым следует двоеточие. Во второй части записано имя Info-файла в круглых скобках, и за ним точка. Третья часть представляет собой описание.
Имя Info-файла обычно имеет расширение `.info'. Значит, Info-файл для GDB мог бы называться `gdb' или `gdb.info'. Программы чтения Info автоматически пробуют имена файлов и с расширением `.info'(12), и без него; поэтому лучше избегать написания лишнего текста и не писать в пункте меню `.info' явно. Например, в пункте меню GDB в качестве имени файла нужно использовать `gdb', а не `gdb.info'.
Если Info-файл не находится в каталоге `info', есть три способа указать его местоположение:
Info-directory-list в вашем собственном или локальном для вашей
машины файле инициализации.
Эта переменная сообщает Emacs где искать файлы `dir' (эти файлы
должны обязательно называться `dir'). Emacs объединяет файлы с
именем `dir' из каждого из перечисленных каталогов. (В Emacs
версии 18, вы можете записать в переменную Info-directory имя
только одного каталога.)
Например, чтобы достичь тестового файла в каталоге `/home/bob/info/', вы можете добавить подобный пункт в меню стандартного файла `dir':
* Тест: (/home/bob/info/info-test). Тестовый файл Боба.
В данном случае абсолютное имя файла `info-test' написано в качестве второй части пункта меню.
Или вы можете написать такую команду в вашем файле `.emacs':
(require 'info)
(setq Info-directory-list
(cons (expand-file-name "/home/bob/info") Info-directory-list))
Она велит Emacs объединить файл `dir' из каталога
`/home/bob/info' с системным файлом `dir'. Info перечислит
файл `/home/bob/info/info-test' как пункт меню файла
`/home/bob/info/dir'. Emacs производит объединение, только когда
M-x info запущена первый раз, так что если вы хотите установить
Info-directory-list в сессии Emacs, где вы уже запускали
info, вы должны выполнить (setq Info-dir-contents nil),
чтобы принудить Emacs заново составить файл `dir'.
И наконец, вы можете сообщить Info путь поиска, установив переменную
среды @env{INFOPATH} в файле инициализации вашей оболочки, таком как
`.cshrc', `.profile' или `autoexec.bat'. Если вы
пользуетесь оболочкой, совместимой с Bourne shell, такой как sh
или bash, вам нужно установить переменную среды @env{INFOPATH} в
файле инициализации `.profile'; но если вы пользуетесь csh
или tcsh, вы должны установить эту переменную в файле
`.cshrc'. В системах MS-DOS/MS-Windows, вы должны установить
@env{INFOPATH} в вашем файле `autoexec.bat' или в Реестре. Каждый
тип командного интерпретатора используют различный синтаксис.
setenv INFOPATH .:~/info:/usr/local/emacs/info
INFOPATH=.:$HOME/info:/usr/local/emacs/info export INFOPATH
set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info
Как обычно, `.' обозначает текущий каталог. Emacs использует
переменную среды @env{INFOPATH} для инициализации значения переменной
Emacs Info-directory-list. Самостоятельная программа чтения Info
сливает все файлы, называемые `dir', во всех каталогах,
перечисленных в переменной среды @env{INFOPATH}, в одно меню,
представляемое вам в ноде, называемой `(dir)Top'.
Какое бы значение вы не установили для @env{INFOPATH}, если его
последним символом является двоеточие(14), оно
замещается путем по умолчанию (задаваемым при компиляции). Это дает вам
возможность дополнять путь по умолчанию, избавляя вас от необходимости
перечислять все стандартные каталоги. Например (с использованием
синтаксиса sh):
INFOPATH=/local/info: export INFOPATH
приводит к поиску сначала в `/local/info', а потом в стандартных каталогах. Двойные двоеточия или двоеточия в начале не рассматриваются особо.
Когда вы создаете свой собственный файл `dir' для использования с
Info-directory-list или @env{INFOPATH}, проще всего начать с
копирования существующего файла `dir' и замены всего текста после
`* Menu:' вашими желаемыми пунктами. При таком способе сохранится
пунктуация и специальные символы CTRL-_, которые необходимы для Info.
При установке в вашу систему Info-файла, вы можете использовать
программу install-info для обновления файла-каталога Info
`dir'. Обычно install-info запускается make-файлом пакета
сразу после копирования Info-файла в подходящее для установки место.
Чтобы Info-файл мог работать с install-info, вы должны
использовать команды @dircategory и @direntry в исходном
Texinfo-файле. Используйте @direntry...@end
direntry для задания пунктов меню, добавляемых в файл-каталог Info, и
@dircategory для задания той части каталога Info, в который их
следует поместить. Вот как эти команды используются в данном
руководстве:
@dircategory Система документации Texinfo @direntry * Texinfo: (texinfo). Формат документации GNU. * install-info: (texinfo)Вызов install-info. ... ... @end direntry
Это дает в Info-файле следующее:
INFO-DIR-SECTION Система документации Texinfo START-INFO-DIR-ENTRY * Texinfo: (texinfo). Формат документации GNU. * install-info: (texinfo)Вызов install-info. ... ... END-INFO-DIR-ENTRY
Программа install-info видит эти строки в Info-файле и так
узнает, что нужно делать.
Всегда пишите команды @direntry и @dircategory
недалеко от начала Texinfo-файла, до первой команды @node.
Если вы напишете их после, install-info не заметит их.
Если вы используете @dircategory в исходном Texinfo-файле более
одного раза, каждое применение задает `текущую' категорию; все
последующие команды @direntry будут добавлять новый пункт к этой
категории.
Вот несколько рекомендуемых категорий @dircategory: `GNU
packages', `GNU programming tools', `GNU programming documentation',
`GNU Emacs Lisp', `GNU libraries', `Linux', `TeX', `Individual
utilities'. Идея состоит в том, чтобы включать ноду `вызов' для каждой
устанавливаемой пакетом программы в категории `Individual utilities', а
вхождение для руководства целиком -- в другой подходящей категории.
Программа install-info вставляет вхождения меню из Info-файла в
файл `dir', каталог верхнего уровня системы Info (объяснения, как
работает файл `dir', смотрите в предыдущих разделах). Чаще всего
она запускается в процессе установки программного обеспечения или при
составлении каталога всех руководств в системе. Обзор использования:
install-info [ключ]... [info-файл [dir-файл]]
Если не заданы info-файл или dir-файл, то должны быть заданы
ключи (описанные ниже), определяющие их. Для них нет значений по
умолчанию, определяемых на стадии компиляции, и стандартный ввод не
используется. install-info за один запуск может считать только
один info-файл и записать один dir-файл.
Если dir-файл (будучи задан) не существует, install-info
создает его, если возможно (без вхождений).
Если какой-нибудь входной файл сжат с помощью gzip
(see section `Invoking gzip' in Gzip), install-info автоматически
распаковывает его для чтения. А если сжат dir-файл,
install-info также автоматически оставляет его сжатым после
записи всех изменений. Если не существует сам dir-файл,
install-info пытается открыть `dir-file.gz'.
Ключи:
--delete
--dir-file=имя
-d имя
--entry=текст
-e текст
--help
-h
--info-file=файл
-i файл
--info-dir=кат
-D кат
--item=текст
--quiet
--remove
-r
--section=разд
-s разд
--version
-V
Здесь приведен алфавитный список @-команд Texinfo. Квадратные скобки, [ ], обозначают необязательные аргументы; многоточие, `...', обозначает повторяемый текст.
@пробельный символ
@, за которым следует пробел, табуляция или новая строка,
дают нормальный растяжимый междусловный пробел. See section Несколько пробелов.
@!
@"
@'
@*
@* командой @refill. See section @*: Разрыв строки.
@,{c}
@-
@- и @hyphenation: Переносы.
@.
@:
@=
@?
@@
@^
@`
@{
@}
@~
@AA{}
@aa{}
@acronym{аббревиатура}
@acronym{аббревиатура}.
@AE{}
@ae{}
@afourpaper
@afourpaper
@afourwide
@alias новая=существующая
@anchor{имя}
@anchor: Определение произвольных назначений для ссылок.
@appendix название
@unnumbered и @appendix.
@appendixsec название
@appendixsection название
@appendixsection -- это более
длинная форма записи команды @appendixsec. See section @unnumberedsec, @appendixsec, @heading.
@appendixsubsec название
@subsection.
@appendixsubsubsec название
@asis
@table, @ftable и @vtable для
печати первой колонки таблицы без выделения ("как есть").
See section Создание таблиц из двух колонок.
@author автор
@title, @subtitle и @author.
@b{текст}
@bullet{}
@bullet{} (*).
@bye
@bye. See section Завершение Texinfo-файла.
@c комментарий
@comment.
See section Комментарии.
@cartouche
@end cartouche. Не влияет на Info.
See section Рисование рамок вокруг примеров.)
@center строка-текста
@titlefont, @center и @sp.
@centerchap строка-текста
@chapter, но центрирует заголовок главы. See section @chapter.
@chapheading название
@majorheading, @chapheading.
@chapter название
@chapter.
@cindex вхождение
@cite{ссылка}
@cite{ссылка}.
@clear флаг
@ifset
флаг и @end ifset и предотвращая раскрытие
@value{флаг} в значение, в которое установлен
флаг. See section @set, @clear и @value.
@code{образец-кода}
@code{пример-кода}.
@command{имя-команды}
@comment комментарий
@c.
See section Комментарии.
@contents
@copyright{}
@copyright{} ((C)).
@defcodeindex имя-именного-указателя
@code. See section Определение новых именных указателей.
@defcv категория класс имя
@defcvx категория класс имя
@deffn категория имя аргументы...
@deffnx категория имя аргументы...
@deffn принимает в
качестве аргументов категорию определяемого объекта, имя объекта и его
аргументы, если таковые имеются. See section Команды для определений.
@defindex имя-именного-указателя
@definfoenclose новая-команда, перед, после,
@defivar класс имя-переменной-экземпляра
@defivarx класс имя-переменной-экземпляра
@defmac имя-макроса аргументы...
@defmacx имя-макроса аргументы...
@defmethod класс имя-метода аргументы...
@defmethodx класс имя-метода аргументы...
@defop категория класс имя аргументы...
@defopx категория класс имя аргументы...
@defop принимает в качестве аргументов общее
название категории операции, имя класса этой операции, ее имя и
аргументы, если таковые имеются. See section Команды для определений, а также
section Объектно-ориентированное программирование.
@defopt имя-пользовательского-параметра
@defoptx имя-пользовательского-параметра
@defspec имя-специальной-формы аргументы...
@defspecx имя-специальной-формы аргументы...
@deftp категория имя-типа атрибуты...
@deftpx категория имя-типа атрибуты...
@deftp принимает в качестве
аргументов категорию, имя типа (слово вроде `int' или `float')
и затем имена атрибутов объектов этого типа. See section Команды для определений, а
также section Типы данных.
@deftypefn классификация тип-данных имя аргументы...
@deftypefnx классификация тип-данных имя аргументы...
@deftypefn принимает в качестве
аргументов классификацию определяемого объекта, его тип, имя и
аргументы, если таковые имеются. See section Команды для определений, а также
section Две или более "первых" строк.
@deftypefun тип-данных имя-функции аргументы...
@deftypefunx тип-данных имя-функции аргументы...
@deftypeivar класс тип-данных имя-переменной
@deftypeivarx класс тип-данных имя-переменной
@deftypemethod класс тип-данных имя-метода аргументы...
@deftypemethodx класс тип-данных имя-метода аргументы...
@deftypeop категория класс тип-данных имя аргументы...
@deftypeopx категория класс тип-данных имя аргументы...
@deftypevar тип-данных имя-переменной
@deftypevarx тип-данных имя-переменной
@deftypevr классификация тип-данных имя
@deftypevrx классификация тип-данных имя
@defun имя-функции аргументы...
@defunx имя-функции аргументы...
@defvar имя-переменной
@defvarx имя-переменной
@defvr категория имя
@defvrx категория имя
@defvr принимает в
качестве аргументов категорию объекта и его имя. See section Команды для определений, а
также section Две или более "первых" строк.
@detailmenu
makeinfo от остановки на детальном списке нод в главном
меню. See section Части главного меню.
@dfn{термин}
@dfn{термин}.
@dircategory часть-dir
@direntry
@end direntry. See section Установка файлов-каталогов Info.
@display
@example (делает в
тексте отступ, не заполняет), но не выбирает новый шрифт. Парная с
@end display. See section @display и @smalldisplay.
@dmn{размер}
@dmn{размер}: Форматирование размеров.
@documentencoding кодировка
@documentencoding enc: Задание входной кодировки.
@documentlanguage CC
@documentlanguage cc: Задание языка документа.
@dotaccent{c}
@dots{}
@dots{} (...) и @enddots{} (@enddots{}).
@email{адрес[, отображаемый-текст]}
@email{адрес[, отображаемый-текст]}.
@emph{текст}
@end среда
@env{переменная-среды}
@enddots{}
@dots{} (...) и @enddots{} (@enddots{}).
@enumerate [число-или-буква]
@item. Возможно, начинает перечень с числа-или-буквы.
Парная с @end enumerate. See section @enumerate: создание нумерованных перечней.
@equiv{}
@equiv{} (==): Обозначение эквивалентности.
@error{}
@error{} (error-->): Обозначение сообщения об ошибке.
@evenfooting [левая] @| [средняя] @| [правая]
@evenheading [левая] @| [средняя] @| [правая]
@iftex. See section Как создать свои заголовки.
@everyfooting [левая] @| [средняя] @| [правая]
@everyheading [левая] @| [средняя] @| [правая]
@example
@end example. See section @example.
@exampleindent отступ
@exampleindent: отступы в блоках.
@exclamdown{}
@exdent строка-текста
@exdent: Отмена отступа в строке.
@expansion{}
@expansion{} (==>): Обозначение раскрытия.
@file{имя-файла}
@file{имя-файла}.
@finalout
@findex вхождение
@flushleft
@flushright
@end flushleft. @flushright
аналогична. See section @flushleft и @flushright.
@footnote{текст-сноски}
@footnotestyle стиль
@format
@example, но не
сужает поля. Парная с @end format. See section @example.
@ftable команда-форматирования
@item. Автоматически вносит каждый элемент первой колонки в
указатель функций. Парная с @end ftable. Аналогична
@table, за исключением автоматического заполнения указателя
функций. See section @ftable и @vtable.
@group
@end group. Не относится к Info.
See section @group: Предотвращение разрывов страниц.
@H{c}
@heading название
@unnumberedsec, @appendixsec, @heading.
@headings on-off-single-double
@headings.
@html
@end html. See section Непосредственный вызов команд программы форматирования.
@hyphenation{пе-ре-не-сен-ное слово}
@- и @hyphenation: Переносы.
@i{текст}
@ifclear флаг
@ifclear флаг и следующей командой @end
ifclear. See section @set, @clear и @value.
@ifhtml
@ifinfo
@end ifhtml и, соотв., с
@end ifinfo. See section Условно видимый текст.
@ifnothtml
@ifnotinfo
@ifnottex
@end
ifnothtml, @end ifnotinfo или @end ifnotinfo,
соответственно. See section Условно видимый текст.
@ifset флаг
@ifset флаг и следующей командой @end
ifset. See section @set, @clear и @value.
@iftex
@end iftex.
See section Условно видимый текст.
@ignore
@end ignore.
See section Комментарии.
@image{файл, [ширина], [высота]}
@include файл
@inforef{имя-ноды, [имя-ссылки], имя-info-файла}
@inforef.
\input файл-определений-макросов
\input используется
вместо @, потому что TeX не распознает @, пока не
прочитает файл с определениями. See section Заголовок Texinfo-файла.
@item
@itemize и
@enumerate; обозначает начало текста первой колонки для
@table, @ftable и @vtable. See section Перечни и таблицы.
@itemize символ-или-команда-создающая-значок
@end itemize.
See section @itemize: создание простых перечней.
@itemx
@item, но не создает дополнительный вертикальный пропуск над
текстом вхождения. See section @itemx.
@kbd{символы-клавиатуры}
@kbd{символы-клавиатуры}.
@kbdinputstyle стиль
@kbd использовать шрифт, отличный от шрифта
@code. See section @kbd{символы-клавиатуры}.
@key{название-клавиши}
@key{название-клавиши}.
@kindex вхождение
@L{}
@l{}
@lisp
@end lisp. See section @lisp.
@lowersections
@raisesections и @lowersections.
@macro имя-макро {параметры}
@имя-макро{параметры}. Поддерживается только
makeinfo и texi2dvi. See section Определение макросов.
@majorheading название
@chapheading. В Info этот заголовок подчеркивается
строкой звездочек. See section @majorheading, @chapheading.
@math{математическое-выражение}
@math: Вставка математических выражений.
@menu
@end menu. See section Меню.
@minus{}
@minus{} (-): Вставка знака минус.
@multitable описание-ширины-колонок
@end multitable.
See section Ширина колонок многоколоночных таблиц.
@need n
@need mils: Предотвращение разрывов страниц.
@node имя, следующая, предыдущая, вверх
@node.
@noindent
@noindent.
@novalidate
@setfilename.
See section Проверка указателей.
@O{}
@o{}
@oddfooting [левая] @| [средняя] @| [правая]
@oddheading [левая] @| [средняя] @| [правая]
@OE{}
@oe{}
@option{имя-ключа}
@page
@page: Переход на новую страницу.
@pagesizes [ширина][, высота]
@pagesizes [ширина][, высота]: Произвольный размер страниц.
@paragraphindent отступ
asis.
See section Отступ в начале абзаца.
@pindex вхождение
@point{}
@point{} (-!-): Обозначение точки в буфере.
@pounds{}
@pounds{} (@pounds{}): Фунты стерлингов.
@print{}
@print{} (-|): Обозначение печатаемого вывода.
@printindex имя-именного-указателя
@pxref{имя-ноды, [вхождение], [тема-или-название], [info-файл], [руководство]}
@pxref.
@questiondown{}
@quotation
@end quotation. See section @quotation.
@r{текст}
@raisesections
@raisesections и @lowersections.
@ref{имя-ноды, [вхождение], [тема-или-название], [info-файл], [руководство]}
@ref.
@refill
@result{}
@result{} (=>): Обозначение вычисления.
@ringaccent{c}
@samp{текст}
@samp{текст}.
@sc{текст}
@sc{текст}: Шрифт маленьких заглавных букв.
@section название
@section.
@set флаг [строка]
@ifset
флаг и @end ifset. Возможно, устанавливает значение
флага равным строке. See section @set, @clear и @value.
@setchapternewpage on-off-odd
@setchapternewpage.
@setcontentsaftertitlepage
@contents находится в другом месте. See section Создание содержания.
@setfilename имя-info-файла
@setfilename.
@setshortcontentsaftertitlepage
@shortcontents находится в другом месте.
See section Создание содержания.
@settitle название
@settitle.
@shortcontents
@summarycontents.
See section Создание содержания.
@shorttitlepage название
@titlepage.
@smallbook
@small....
@smalldisplay
@smallexample (делает в
тексте отступы, не заполняет), но не переключается на равноширинный
шрифт. В формате @smallbook, печатает текст меньшим шрифтом,
чем @display. Парная с @end smalldisplay.
See section Команды блоков @small....
@smallexample
@smallbook,
печатает текст меньшим шрифтом, чем @example. Парная с
@end smallexample. See section Команды блоков @small....
@smallformat
@smalldisplay, но не сужает
поля и не переключается на равноширинный шрифт. В формате
@smallbook, печатает текст меньшим шрифтом, чем @format.
Парная с @end smallformat. See section Команды блоков @small....
@smalllisp
@smallbook,
печатает текст меньшим шрифтом. Парная с @end smalllisp.
See section Команды блоков @small....
@sp n
@sp n: Вставка пустых строк.
@ss{}
@strong {текст}
@emph{текст} и @strong{текст}.
@subheading название
@subsection.
@subsection название
@subsection.
@subsubheading название
@subsubsection название
@subtitle название
@title, @subtitle и @author.
@summarycontents
@shortcontents.
See section Создание содержания.
@syncodeindex источник назначение
@code. See section Объединение именных указателей.
@synindex источник назначение
@t{текст}
@tab
@table форматирующая-команда
@item. Пишите каждое вхождение первой колонки на той же строке,
что и @item. Вхождения первой колонки печатаются шрифтом,
определяемым форматирующей-командой. Парная с @end table.
See section Создание таблиц из двух колонок. Также
смотрите section @ftable и @vtable,
section @itemx.
@TeX{}
@tex
@end tex.
See section Непосредственный вызов команд программы форматирования.
@thischapter
@thischaptername
@thisfile
@thispage
@thistitle
@tieaccent{cc}
@tindex вхождение
@title название
@title, @subtitle и @author.
@titlefont{текст}
@titlefont, @center и @sp.
@titlepage
@end titlepage. Текст между
@titlepage и @end titlepage не появляется в Info.
See section @titlepage.
@today{}
@top название
makeinfo,
указывает самую первую строку @node в файле, которая должна быть
написана непосредственно перед командой @top. Используется для
способности makeinfo вставлять указатели. Этот заголовок
подчеркивается строкой звездочек. И строка @node, и строка
@top обычно должны быть окружены @ifinfo и @end
ifinfo. В TeX и texinfo-format-buffer, команда @top
просто синоним для @unnumbered. See section Создание указателей с помощью @command{makeinfo}.
@u{c}
@ubaraccent{c}
@udotaccent{c}
@unnumbered название
@unnumbered и @appendix.
@unnumberedsec название
@unnumberedsec, @appendixsec, @heading.
@unnumberedsubsec название
@subsection.
@unnumberedsubsubsec название
@uref{url[, отображаемый-текст][замещение]}
@uref{url[, отображаемый-текст]}.
@url{url}
@url{унифицированный-указатель-ресурса}.
@v{c}
@value{флаг}
@set флаг. See section @set, @clear и @value.
@var{метасинтаксическая-переменная}
@var{метасинтаксическая-переменная}.
@vindex вхождение
@vskip количество
@vskip
может быть использована только в контексте, игнорируемом Info.
See section Страница с информацией об авторских правах и разрешения.
@vtable форматирующая-команда
@item. Автоматически вносит каждый элемент первой колонки в
указатель переменных. Парная с @end vtable. Аналогична
@table, за исключением автоматического заполнения указателя
переменных. See section @ftable и @vtable.
@w{текст}
@w командой @refill. See section @w{текст}: Предотвращение разрывов строк.
@xref{имя-ноды, [вхождение], [тема-или-название], [info-файл], [руководство]}
@xref.
Вот несколько советов по написанию документации в Texinfo:
Пишите много вхождений в именные указатели, различными способами. Читателям нравятся именные указатели; они полезны и удобны.
Хотя проще писать вхождения именных указателей в процессе написания тела текста, некоторые предпочитают писать их после. В любом случае, пишите вхождения перед абзацем, к которому они относятся. Тогда вхождение будет указывать на первую страницу абзаца, который разделен между страницами.
Вот еще несколько советов, которые мы сочли полезными:
@section Чай и булки @cindex Завтрак @cindex Чаепитие @cindex Булки, французские, к чаю @cindex Французские булки, к чаю @cindex Чай, с булками Съешь ещё этих мягких французских булок да выпей чаю.(Заметьте, что этот пример показывает вхождения для одного понятия, записанные разными способами -- `Булки, французские' и `Французские булки' -- так что читатели могут найти их в именном указателе по-разному.)
@table и после
команды @end table; но никогда не вставляйте после команды
@table или перед @end table.
Например,
Разновидности булок: @table @samp @item Мягкие Хороши к чаю. @item Французские Тоже хороши к чаю. @end table @noindent С другой стороны, ...Вставляете пустые строки до и после
@itemize ... @end
itemize и @enumerate ... @end enumerate таким же
образом.
Завершенные фразы легче читать, чем ...
Пишите дату и номера редакции и версии в трех местах в каждом руководстве:
@ifinfo, для читающих Texinfo-файл.
@titlepage, для читающих печатное руководство.
Также полезно написать заметку перед первым разделом @ifinfo для
объяснения, что вы делаете.
Например:
@c ===> ВНИМАНИЕ! <==
@c Укажите дату и номера редакции и версии
@c в *трех* местах:
@c 1. Первый раздел ifinfo 2. титульный лист 3. первая нода
@c Чтобы найти эти места, ищите !!установить
@ifinfo
@c !!установить редакцию, дату, версию
Редакция 4.03, @cite{Руководство по GDB} для GDB версии 4.3,
январь 1992 г.
...
--- или используйте @set и @value (see section Пример применения @value).
Команды для определений, а это @deffn, @defun,
@defmac и им подобные, позволяют вам делать описания в едином
формате.
@table
... @end table, а не @deffn или другие команды для
определений.
@TeX{}. Обратите внимание на
заглавные `T' и `X'. Эта команда заставляет программы
форматирования набирать это название в соответствии с пожеланиями
Дональда Кнута, автора TeX.
Не используйте для форматирования Texinfo-файла пробелы, за исключением
текста внутри @example ... @end example и похожих
блоков.
Например, TeX заполняет следующее:
@kbd{C-x v}
@kbd{M-x vc-next-action}
Производит следующую логическую операцию
над файлом с контролем версий,
соответствующим текущему буферу.
таким образом, что оно выглядит так:
C-x v M-x vc-next-action Производит следующую логическую операцию над файлом с контролем версий, соответствующим текущему буферу.
В этом случае, текст нужно форматировать с помощью @table,
@item и @itemx, для создания таблицы.
@code вокруг символов Лисп, включая имена команд.
Например,
Главная функция --- это @code{vc-next-action}, ...
@var вокруг мета-переменных. Не окружайте их
угловыми скобками.
Помещайте точки и другие знаки препинания вне кавычек, если только эти знаки препинания не относятся к словам, заключенным в кавычки. Эта практика противоречит издательским соглашениям, принятым в Соединенных Штатах@transnote{Но соответствует правилам пунктуации русского языка.}, но позволяет читателю различать содержимое кавычек и целого отрывка.
Например, вы должны написать точку в следующем предложении вне кавычек:
Очевидно, `au' является сокращением от ``author''.
так как `au' не служит сокращением от `author.' (с точкой после слова).
The major function assists you in checking in a file to your version control system and registering successive sets of changes to it as deltas.
@dfn вокруг вводимого слова, чтобы
обозначить, что у читателя не предполагается знание его смысла, и что он
может сможет узнать его значение из данного отрывка.
Абсолютно никогда не используйте @pxref, кроме как в особом
контексте, для которого она была разработана: внутри круглых скобок,
когда закрывающая круглая скобка идет сразу после закрывающей фигурной.
Одна форматирующая программа автоматически вставляет закрывающие знаки
препинания, а вторая -- нет. Это означает, что вывод выглядит
правильно и на печати, и в Info-файле, но только если эта команда
применена внутри круглых скобок.
Вы можете вызвать такие программы, как Emacs, GCC и gawk из
оболочки. Документация для любой программы должна содержать раздел,
описывающий это. К сожалению, если имена нод и названия этих разделов
всегда различны, читатели считают, что найти этот раздел трудно.
Называйте такие разделы фразой, начинающейся словом `Вызов ...', например `Вызов Emacs'; тогда пользователи смогут легко найти этот раздел.
Когда вы используете @example для описания соглашений о вызове
функции Си, используйте синтаксис ANSI C, как здесь:
void dld_init (char *@var{path});
И в последующем обсуждении ссылайтесь на значения аргументов по тем же
именам аргументов, снова выделяя их с помощью @var.
Избегайте использования устаревшего синтаксиса, выглядящего так:
#include <dld.h> dld_init (path) char *path;
Также, лучше избегать написания #include над объявлением лишь для
того, чтобы показать, что эта функция объявлена в заголовочном файле.
Это может произвести неправильное впечатление, что #include
относится к объявлению функции. Либо скажите явно, какой заголовочный
файл содержит объявление, либо, что еще лучше, напишите имя
заголовочного файла, используемого для группы функций, в начале раздела,
описывающего эти функции.
Вот несколько примеров плохого стиля, которого нужно избегать:
В этом примере скажите " ... you must @dfn{check
in} the new version." Это более гладко читается.
When you are done editing the file, you must perform a
@dfn{check in}.
В следующем примере скажите "... makes a unified interface such as VC mode possible."
SCCS, RCS and other version-control systems all perform similar functions in broadly similar ways (it is this resemblance which makes a unified control mode like this possible).
И в этом примере, вам нужно указать, к чему относится `it':
If you are working with other people, it assists in coordinating everyone's changes so they do not step on each other.
@bye.
Ни одна из программ форматирования не обрабатывает текст после
@bye; это так же, как если бы текст был между @ignore
... @end ignore.
Это пример законченного короткого Texinfo-файла, без каких-либо комментариев. Вы можете найти этот пример с комментариями в первой главе. See section Короткий пример Texinfo-файла.
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename sample.info
@settitle Пример документа
@c %**end of header
@setchapternewpage odd
@ifinfo
Это короткий пример законченного Texinfo-файла.
Copyright @copyright{} 1999 Free Software Foundation, Inc.
@end ifinfo
@titlepage
@sp 10
@comment Заголовок печатается крупным шрифтом
@center @titlefont{Пример заголовка}
@c Две следующие команды начинают страницу с
@c информацией об авторских правах
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1999 Free Software Foundation, Inc.
@end titlepage
@node Top, Первая глава, , (dir)
@comment имя-ноды, следующая, предыдущая, вверх
@menu
* Первая глава:: Первая и единственная глава в
этом примере.
* Указатель понятий:: В этом указателе есть два элемента.
@end menu
@node Первая глава , Указатель понятий, Top , Top
@comment имя-ноды, следующая, предыдущая, вверх
@chapter Первая глава
@cindex Пример вхождения именного указателя
Это содержимое первой главы.
@cindex Другой пример вхождения именного указателя.
Это нумерованный перечень.
@enumerate
@item
Это первый пункт.
@item
Это второй пункт.
@end enumerate
Команды @code{makeinfo} и @code{texinfo-format-buffer}
преобразуют Texinfo-файлы, такие как этот, в Info-файлы,
а @TeX{} форматирует печатное руководство.
@node Указатель понятий, , Первая глава, Top
@comment имя-ноды , следующая, предыдущая , вверх
@unnumbered Указатель понятий
@printindex cp
@contents
@bye
Texinfo-файлы должны содержать разделы, сообщающие читателям, что они имеют право копировать и распространять Texinfo-файл, Info-файл и печатное руководство. Также, если вы пишите руководство по программному обеспечению, вы должны объяснить, что это программное обеспечение свободно и либо включить Универсальную Общественную Лицензию GNU (GPL), либо предоставить ссылку на нее. See section `Distribution' in Руководство по GNU Emacs, -- это пример текста, который можно использовать в разделах документа "Распространение", "Универсальная Общественная Лицензия" и "ГАРАНТИЙ НЕТ". See section Условия копирования Texinfo, для получения примера краткого объяснения, как условия копирования наделяют вас правами.
В Texinfo-файле, первый раздел @ifinfo обычно начинается со
строки, говорящей, что документирует этот файл. Это то, что первым
увидит человек, читающий необработанный Texinfo-файл или использующий
продвинутую команду Info g *. See Info file `info', node `Expert', для дальнейшей информации. (Читатель, использующий
обычные команды Info, как правило начинает читать с первой ноды и
пропускает этот первый раздел, не входящий ни в одну ноду.)
В разделе @ifinfo после обзорного предложения следует
уведомление об авторских правах, а за ним уведомление о разрешении на
копирование. Один из абзацев разрешений на копирование окружается
командами @ignore и @end ignore. Этот абзац говорит,
что Texinfo-файл разрешается обрабатывать с помощью TeX и печатать,
если печатное руководство содержит соответствующее уведомление об
авторских правах. Этот абзац не вносится в Info-файл, так как он не
относится к Info-файлу; но он является обязательной частью
Texinfo-файла, так как разрешает людям обрабатывать этот Texinfo-файл в
TeX и печатать результаты.
В печатном руководстве уведомление о предоставляемом Фондом Свободного
Программного Обеспечения разрешении на копирование следует после
уведомления об авторских правах и издательских сведений и располагается
в области, очерченной командами @titlepage и @end
titlepage. Уведомление о разрешении на копирование точно то же, что и
уведомление в разделе @ifinfo, за исключением того, что абзац,
заключенный между @ignore и @end ignore не является
частью этого уведомления.
Чтобы проще было вставить уведомления о разрешениях в каждый раздел Texinfo-файла, образец уведомлений для каждого раздела приведены ниже полностью.
Вам может понадобиться указать правильное название раздела, упомянутого в уведомлении о разрешениях. Например, в Руководстве по GDB, раздел, ссылающийся на Универсальную Общественную Лицензию называется "Универсальная Общественная Лицензия GDB", но в примере, показанном ниже, на этот раздел ссылаются как обычно, "Универсальная Общественная Лицензия GNU". Если Texinfo-файл не содержит копию Универсальной Общественной Лицензии, исключите ссылку на нее, но оставьте конец предложения.
В разделе @ifinfo Texinfo-файла, стандартное для Фонда
Свободного Программного Обеспечения уведомление об авторских правах
выглядит следующим образом:
Этот файл описывает ... Copyright 1998 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. @ignore Permission is granted to process this file through TeX and print the results, provided the printed document carries a copying permission notice identical to this one except for the removal of this paragraph (this paragraph not being relevant to the printed manual). @end ignore Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the sections entitled ``Copying'' and ``GNU General Public License'' are included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.
В разделе Texinfo-файла @titlepage после уведомления об
авторских правах и издательских сведений следует стандартное для Фонда
Свободного Программного Обеспечения уведомление о разрешении на
копирование. Стандартная формулировка выглядит так:
Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the sections entitled ``Copying'' and ``GNU General Public License'' are included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.
Когда TeX или команда форматирования Info встречают в Texinfo-файле
команду @include, они обрабатывают содержимое указанного
командой файла и включают его в создаваемый DVI- или Info-файл.
Вхождения именных указателей из включаемых файлов вносятся в именные
указатели выходного файла.
Включаемые файлы позволяют вам держать большой документ в виде удобных небольших частей.
Чтобы включить в Texinfo-файл другой файл, напишите команду
@include в начале строки, и за ней имя включаемого файла на той
же строке. Например:
@include buffers.texi
Включаемый файл должен быть просто сегментом текста, который вы
предполагаете вставить как есть в общий или внешний Texinfo-файл;
он не должен содержать стандартные начальную и завершающую части
Texinfo-файла. В особенности, вы не должны начинать включаемый файл
строкой `\input texinfo'; если вы сделаете так, эта фраза вставится
во внешний файл буквально. Аналогично, вы не должны завершать
включаемый файл командой @bye; текст после @bye не
форматируется.
Раньше в начале каждого включаемого файла нужно было обязательно писать
строку @setfilename, но теперь не нужно. Теперь не имеет
значения, написали ли вы такую строку или нет. Если строка
@setfilename существует во включаемом файле, она игнорируется.
По соглашению, включаемый файл начинается строкой @node, за
которой следует строка @chapter. Каждый включаемый файл -- это
одна глава. Это облегчает использование обычных команд создания и
обновления нод и меню внутри включаемого файла. Однако, простые команды
Emacs для создания и обновления нод и меню не работают со множественными
Texinfo-файлами. То есть вы не можете использовать эти команды для
заполнения указателей `Next', `Previous' и `Up' в строке @node,
которая начинает включаемый файл. Также вы не можете использовать
обычные команды для создания главного меню полного файла. Вы либо
должны заполнить меню и указатели `Next', `Previous' и `Up' вручную,
либо использовать команду режима Texinfo для GNU Emacs,
texinfo-multiple-files-update, разработанную для
@include-файлов.
texinfo-multiple-files-update
Режим Texinfo в GNU Emacs предоставляет команду
texinfo-multiple-files-update. Эта команда создает или обновляет
во включаемом файле указатели `Next', `Previous' и `Up', а также во
внешнем или общем Texinfo-файле; и создает или обновляет главное меню во
внешнем файле. В зависимости от того, вызвали ли вы ее с
необязательными аргументами, эта команда обновляет либо только указатели
в первой строке @node включаемого файла, либо все указатели:
@node в каждом файле, включенном во внешний или общий
Texinfo-файл.
@node в каждом
включаемом файле.
texinfo-master-menu с аргументом, когда вы работаете только с
одним файлом.
Обратите внимание на применение префиксного аргумента при интерактивном
использовании: с обычным префиксным аргументом, просто C-u,
команда texinfo-multiple-files-update вставляет главное меню; с
числовым префиксным аргументом, таким как C-u 8, эта команда
обновляет все указатели и меню во всех файлах и затем
вставляет главное меню.
Если вы планируете использовать команду
texinfo-multiple-files-update, то внешний Texinfo-файл,
перечисляющий включаемые файлы, не должен содержать ничего, кроме
начальной и завершающей частей Texinfo-файла и нескольких команд
@include для включаемых файлов. Он не должен включать даже
именных указателей, которые должны быть перечислены в отдельном
включаемом файле.
Кроме того, каждый включаемый файл должен содержать ровно одну ноду
верхнего уровня (обычно это @chapter или эквивалент), и эта ноды
должна быть первой нодой во включаемом файле. Более того, все эти нод
верхнего уровня из каждого включаемого файла должны быть на одном
иерархическом уровне в общей структуре. Обычно все они являются нодами
@chapter, @appendix или @unnumbered. Таким
образом, каждый включаемый файл содержит одну и только одну ноду с
главой или эквивалентного уровня.
Внешний файл должен содержать только одну ноду, ноду `Top'. Он
не должен содержать никаких нод кроме одной ноды `Top'. Команда
texinfo-multiple-files-update не будет их обрабатывать.
@include
Вот пример законченного внешнего Texinfo-файла с
@include-файлами внутри, до запуска
texinfo-multiple-files-update, которая вставила бы главное меню:
\input texinfo @c -*-texinfo-*-
@setfilename include-example.info
@settitle Include Example
@setchapternewpage odd
@titlepage
@sp 12
@center @titlefont{Include Example}
@sp 2
@center by Whom Ever
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1998 Free Software Foundation, Inc.
@end titlepage
@ifinfo
@node Top, First, , (dir)
@top Master Menu
@end ifinfo
@include foo.texinfo
@include bar.texinfo
@include concept-index.texinfo
@summarycontents
@contents
@bye
Включаемый файл, например `foo.texinfo', может выглядеть так:
@node First, Second, , Top @chapter First Chapter Contents of first chapter ...
Полное содержание `concept-index.texinfo' может выглядеть так:
@node Concept Index @unnumbered Concept Index @printindex cp
Внешний исходный Texinfo-файл для The GNU Emacs Lisp Reference Manual называется `elisp.texi'. Этот внешний файл содержит главное меню из 417 пунктов и список из 41 включаемого файла.
Когда Info была первоначально создана, было принято делать много небольших Info-файлов на одну тему. Каждый Info-файл форматировался из отдельного исходного Texinfo-файла. Этот обычай был предназначен для того, чтобы в Emacs не нужно было создавать большой буфер для хранения большого Info-файла целиком, когда кто-то хотел получить информацию; вместо этого Emacs выделял ровно столько памяти, сколько нужно для маленького Info-файла, содержащего нужную информацию. Таким образом Emacs избегал лишнего расхода памяти.
Ссылки из одного файла в другой делались путем указания и имени файла, и
имени ноды. (See section Ссылки на другие Info-файлы.
Также смотрите section @xref с четырьмя и пятью аргументами.)
Включение файлов было разработано преимущественно как способ создания
единого, большого печатного руководства из нескольких меньших
Info-файлов. В печатном руководстве все ссылки были внутри одного
документа, так что TeX мог автоматически определить для них номера
страниц. Команды форматирования Info использовали включаемые файлы лишь
для создания объединенных именных указателей; каждый отдельный
Texinfo-файл нужно было форматировать для Info индивидуально. (Каждый
из них, следовательно, должен был содержать свою строку
@setfilename.)
Однако, так как большие Info-файлы теперь автоматически разбиваются, больше нет необходимости сохранять их маленькими.
Теперь множественные Texinfo-файлы используются преимущественно для больших документов, таких как The GNU Emacs Lisp Reference Manual и для проектов, в которых несколько человек одновременно пишут разные разделы документа.
Кроме того, команды форматирования для Info были расширены для работы с
командой @include так, чтобы создавать единый большой Info-файл,
который разбивается при необходимости на меньшие файлы. Это означает,
что вы можете писать меню и перекрестные ссылки не обращаясь к различным
Texinfo-файлам.
Большинство печатных руководств содержат заголовки вверху каждой страницы, исключая титульный лист и страницу с информацией об авторских правах. Некоторые руководства также содержат нижние заголовки. (Верхние и нижние заголовки не имеют значения для Info, в которой нет страниц.)
Texinfo предоставляет стандартные заголовки страниц для руководств, печатаемых на одной стороне каждого листа и для руководств, печатаемых на обоих сторонах листа. Как правило, вы будете использовать один из этих форматов, но вы также можете определить свой формат, если хотите.
Кроме того, вы можете указать, должны ли главы начинаться на новой странице или просто продолжать ту же страницу, где была предыдущая глава; и, если главы начинаются на новых страницах, вы можете указать, должны ли эти страницы быть нечетными.
По соглашению, книги печатаются на обоих сторонах каждого листа. Когда вы открываете книгу, правая страница имеет нечетный номер, и главы начинаются на правых страницах -- предыдущая левая страница оставляется пустой, если необходимо. Отчеты, однако, часто печатаются только на одной стороне листа, и главы начинаются на новой странице, следующей сразу после конца предыдущей главы. В коротких или неофициальных отчетах главы часто вообще не начинаются на новой странице, а отделяются от предшествующего текста небольшим пропуском.
Команда @setchapternewpage контролирует, начинаются ли главы на
новой странице, и какой из стандартных форматов заголовков используется.
Помимо этого, в Texinfo есть несколько команд для верхних и нижних
заголовков, которые вы можете использовать для создания ваших
собственных форматов заголовков.
В Texinfo верхние и нижние заголовки -- это одна строка в начале и одна в конце страницы; вы не можете создать многострочные заголовки. Каждый верхний или нижний заголовок разделен на три части: левую, среднюю и правую. Любая часть или вся строка может быть оставлена пустой. Текст левой части заголовка прижимается влево, текст средней части центрируется, а текст правой части прижимается вправо.
Texinfo предоставляет два стандартных формата заголовков: один для руководств, печатаемых на одной стороне листа, и второй для руководств, печатаемых на обоих сторонах листа.
По умолчанию нижний заголовок не задается, поэтому нижняя строка остается пустой.
Стандартный формат для печати на одной стороне листа состоит из строки заголовка, в которой левая часть содержит название главы, средняя часть пуста, а правая часть содержит номер страницы.
При печати на одной стороне листа страница выглядит так:
__________________________ | | | глава номер страницы | | | | Начало текста ... | | ... | | |
Стандартный формат для печати на двух сторонах зависит от того, четная это страница или нечетная. По соглашению, четные страницы находятся слева, а нечетные справа. (TeX сам настроит ширину правых и левых полей. Обычно поля получаются правильной ширины, но при двусторонней печати стоит проверить, что страницы соединятся верно -- иногда принтер производит вывод, в котором четные страницу имеют более широкое правое поле, чем нечетные страницы.)
В стандартном формате для двусторонней печати левая часть левых (четных)
страниц содержит номер страницы, средняя часть пуста, а правая часть
содержит название книги (заданное командой @settitle). Левая
часть правых (нечетных) страниц содержит название главы, средняя часть
пуста, а правая часть содержит номер страницы.
Две последовательные страницы, как в раскрытой книге, выглядят так:
__________________________ __________________________ | | | | | номер страницы название | | глава номер страницы | | | | | | Начало текста ... | | Продолжение текста ... | | ... | | ... | | | | |
Перед названием главы печатается слово "Глава", номер главы и двоеточие. Это помогает проследить, в каком месте руководства вы находитесь.
TeX не начинает создавать заголовки страниц для стандартного
Texinfo-файла, пока не достигнет команды @end titlepage. Таким
образом, титульный лист и страница с информацией об авторских правах не
нумеруются. Команда @end titlepage заставляет TeX начать
создавать заголовки страниц в соответствии со стандартным форматом,
заданным командой @setchapternewpage, идущей перед разделом
@titlepage.
Возможны четыре варианта:
@setchapternewpage нет
@setchapternewpage on.
@setchapternewpage on
@setchapternewpage off
@headings double; смотрите
section Команда @headings.)
@setchapternewpage odd
В Texinfo нет команды @setchapternewpage even.
Вы можете использовать стандартные заголовки, предоставляемые Texinfo, или определить свои. По умолчанию, в Texinfo нет нижних заголовков, так что если вы определите их, доступный размер страницы для основного текста несколько уменьшится.
Texinfo предоставляет шесть команд для задания верхних и нижних заголовков:
@everyheading и @everyfooting создают заголовки,
одинаковые для четных и нечетных страниц.
@evenheading и @evenfooting создают заголовки для четных
(левых) страниц.
@oddheading и @oddfooting для нечетных (правых) страниц.
Записывайте настройки заголовков в Texinfo-файле сразу после команды
@end titlepage. Заключайте ваше описание между команд
@iftex и @end iftex, так как команда
texinfo-format-buffer может не распознать их. Также вы должны
отменить предопределенные команды для заголовков командой
@headings off до определения ваших собственных описаний.
Ниже показано, как сказать TeX помещать слева название главы, номер страницы посредине и дату справа в каждом заголовке как для четных, так и нечетных страниц:
@iftex
@headings off
@everyheading @thischapter @| @thispage @| @today{}
@end iftex
Вы должны отделять левую часть от средней и среднюю от правой, вставляя между частей `@|'. Иначе команда задания формата не сможет определить, где кончается текст одной части и начинается текст другой.
Каждая часть может содержать текст или @-команды. Текст печатается как если бы эта часть была обычным абзацем в теле страницы. @-команды заменяются на номер страницы, дату, название главы или что-либо еще.
Вот шесть команд для верхних и нижних заголовков:
@everyheading левая @| средняя @| правая
@everyfooting левая @| средняя @| правая
@evenheading левая @| средняя @| правая
@oddheading левая @| средняя @| правая
@evenfooting левая @| средняя @| правая
@oddfooting левая @| средняя @| правая
Используйте группу @-команд `@this...' для получения названий
глав и разделов и номеров страниц. Вы можете использовать команды
`@this...' в левой, средней или правой части и любом месте
Texinfo-файла, если они заключены между команд @iftex и
@end iftex.
Вот все команды `@this...':
@thispage
@thischaptername
@thischapter
@thistitle
@settitle.
@thisfile
Вы также можете использовать команду @today{}, которая
раскрывается в текущую дату, в формате `14 августа 1997г.'.
Другие @-команды и текст печатаются в заголовке точно так же, как бы они выводились в теле страницы. Удобно включать такой текст, особенно если вы пишете наброски:
@iftex
@headings off
@everyheading @emph{Набросок!} @| @thispage @| @thischapter
@everyfooting @| @| Версия: 0.27: @today{}
@end iftex
Будьте осторожны со слишком длинными названиями: они могут перекрыть другую часть заголовка и испортить его.
Помимо ошибок в содержимом документации, вы можете допустить в Texinfo еще два вида ошибок: ошибки в @-командах и ошибки в структуре нод и глав.
В Emacs есть два способа для нахождения ошибок в @-командах и два для ошибок в структуре.
Для нахождения ошибок в @-командах вы можете запустить TeX или команду форматирования области в той области, где возникла проблема; на самом деле вы можете запускать эти команды для каждой области по мере написания.
Для нахождения ошибок в структуре нод или глав, вы можете использовать
команду C-c C-s (texinfo-show-structure) и другие команды
пакета occur, а также команду M-x Info-validate.
Программа makeinfo проделывает отличную работу по нахождению
ошибок и сообщению о них -- намного лучшую, чем команда
texinfo-format-region или texinfo-format-buffer. Кроме
того, различные функции для автоматического создания и обновления
указателей на ноды устраняют многие возможные ошибки человека.
Если есть возможность, применяйте команды обновления для создания и
вставки указателей и меню. Они предотвращают появление многих ошибок.
Потом используйте makeinfo (или ее проявления в режиме Texinfo,
makeinfo-region и makeinfo-buffer) для форматирования
вашего файла и проверки наличия других ошибок. Это наилучший способ
работы с Texinfo. Однако, если вы не можете использовать
makeinfo, или ваши ошибки слишком загадочны, вы можете применить
инструменты, описанные в данном приложении.
После написания части Texinfo-файла, вы можете использовать команду
texinfo-format-region или makeinfo-region, чтобы
проверить, отформатируется ли область должным образом.
Но вероятнее всего вы читаете этот раздел, потому что по какой-либо
причине не можете использовать команду makeinfo-region; поэтому в
дальнейшем полагается, что вы пользуетесь командой
texinfo-format-region.
Если вы допустили ошибку в @-команде, texinfo-format-region
останавливается на этом месте или после него и выводит сообщение об
ошибке. Чтобы увидеть, в каком месте буфера допущена ошибка,
переключитесь в буфер `*Info Region*'; курсор будет находиться в
позиции после места ошибки. Кроме того, текст после того места, где
допущена (или, точнее, была обнаружена) ошибка, не будет
отформатирован.
Например, если вы случайно завершите меню командой @end menus с
`s' в конце, вместо @end menu, вы увидите сообщение об ошибке,
говорящее:
@end menus is not handled by texinfo
Курсор остановится в той точке буфера, где допущена ошибка или немного после. Буфер будет выглядеть так:
---------- Buffer: *Info Region* ----------
* Menu:
* Using texinfo-show-structure:: How to use
`texinfo-show-structure'
to catch mistakes.
* Running Info-Validate:: How to check for
unreferenced nodes.
@end menus
-!-
---------- Buffer: *Info Region* ----------
Команда texinfo-format-region иногда выдает немного странные
сообщения об ошибках. Например, следующая перекрестная ссылка не может
быть отформатирована:
(@xref{Поиск ошибок, для подробной информации.)
В этом случае texinfo-format-region находит, что пропущена
закрывающая фигурная скобка, но выводит сообщение, сообщающее о
несбалансированных круглых, а не фигурных скобках. Это происходит,
потому что форматирующая команда ищет непарные фигурные скобки, как если
бы они были круглыми.
Иногда texinfo-format-region не может обнаружить ошибку.
Например, во фрагменте ниже, закрывающая фигурная скобка поменялась
местами с закрывающей круглой скобкой:
(@xref{Поиск ошибок), для подробной информации.}
Форматирование дает:
(*Note для подробной информации.: Поиск ошибок)
Единственный способ заметить эту ошибку -- понять, что ссылка должна выглядеть так:
(*Note Поиск ошибок::, для подробной информации.)
Кстати, если вы читаете эту ноду в Info и введете f RET
(Info-follow-reference), то получите такое сообщение об ошибке:
Невозможно найти ноду: "Поиск ошибок) Единственный ...
Это происходит, потому что Info воспринимает пример с ошибкой как первую
перекрестную ссылку в этой ноде, и, если вы нажмете RET сразу
после ввода команды Info f, попытается перейти к указанной ноде.
Если вы введете f catch TAB RET, Info завершит имя
ноды правильно написанного примера и перенесет вас к ноде `Поиск
ошибок'. (Если вы попробуете так сделать, вы сможете вернуться из ноды
`Поиск ошибок', нажав l (Info-last).)
Вы также можете найти ошибки при форматировании с помощью TeX.
Как правило, вам стоит сделать это после того, как вы прогнали
texinfo-format-buffer (или лучше makeinfo-buffer) на том
же файле, потому что иногда texinfo-format-buffer выводит более
полезные сообщения об ошибках, чем TeX. (See section Поиск ошибок при форматировании для Info,
для подробной информации.)
Например, TeX был запущен для Texinfo-файла, часть которого приведена здесь:
---------- Buffer: texinfo.texi ----------
name of the Texinfo file as an extension. The
@samp{??} are `wildcards' that cause the shell to
substitute all the raw index files. (@xref{sorting
indices, for more information about sorting
indices.)@refill
---------- Buffer: texinfo.texi ----------
(В перекрестной ссылке нет закрывающей фигурной скобки.) TeX выдает следующий вывод и останавливается:
---------- Buffer: *tex-shell* ----------
Runaway argument?
{sorting indices, for more information about sorting
indices.) @refill @ETC.
! Paragraph ended before @xref was complete.
<to be read again>
@par
l.27
?
---------- Buffer: *tex-shell* ----------
В данном случае TeX выдает точное и понятное сообщение об ошибке:
Абзац закончился до завершения @xref.
`@par' -- это внутренняя команда TeX, не относящаяся к Texinfo. `l.27' означает, что TeX обнаружил ошибку в строке 27 Texinfo-файла. `?' служит приглашением для ввода, которое TeX использует в таких случаях.
К сожалению, сообщения TeX не всегда настолько полезны, и вам нужно быть по-настоящему Шерлоком Холмсом, чтобы понять, что за неприятность произошла.
В любом случае, если вы столкнулись с подобной проблемой, вы можете сделать одну из трех следующих вещей.
Если вы запускаете TeX из Emacs, вы должны переключиться в буфер оболочки и перейти к строке, в которой TeX печатает `?' в качестве приглашения для ввода.
Иногда TeX может отформатировать файл, не выдавая сообщений об
ошибках, даже если ошибки есть. Обычно это случается, если команда не
была завершена, но TeX смог продолжить обработку. Например, если вы
не завершите простой перечень командой @end itemize, TeX
запишет DVI-файл, который вы сможете распечатать. Единственным
сообщением об ошибке, которое выведет TeX, будет несколько загадочный
комментарий
(@end occurred inside a group at level 1) (команда @end встречена внутри группы на уровне 1)
Однако, если вы распечатаете DVI-файл, то обнаружите, что во всем тексте
файла после перечня сделан отступ, как будто этот текст является частью
последнего пункта перечня. Этим сообщением об ошибке TeX хотел
сказать, что ожидал найти команду @end где-нибудь в файле; но он
не может определить, где она действительно была нужна.
Другой источник пресловутых труднонаходимых ошибок -- это пропущенная
команда @end group. Если вы когда-нибудь окажетесь
поставленными в тупик непонятными ошибками, поищите первым делом
пропущенные команды @end group.
Если в Texinfo-файле пропущены строки заголовка, TeX может остановиться в начале работы и вывести что-то похожее на приведенное ниже. Символ `*' означает, что TeX ждет ввода.
This is TeX, Version 3.14159 (Web2c 7.0) (test.texinfo [1]) *
В таком случае просто напечатайте \end RET после звездочки. Потом напишите в Texinfo-файле строки заголовка и запустите TeX снова. (Обратите внимание, вы должны использовать обратную косую черту, `\'. TeX использует `\' вместо `@'; а при этих обстоятельствах вы работаете непосредственно с TeX, а не с Texinfo.)
texinfo-show-structureНе всегда легко уследить за нодами, главами, разделами и подразделами Texinfo-файла. В особенности это справедливо, если вы пересматриваете или дополняете Texinfo-файл, написанный кем-то другим.
В GNU Emacs в режиме Texinfo, команда texinfo-show-structure
перечисляет все строки, начинающиеся @-командами, определяющими
структуру: @chapter, @section, @appendix и так
далее. Если задан аргумент (C-u в качестве числового
аргумента, при интерактивном вызове), эта команда показывает также
строки @node. В режиме Texinfo команда
texinfo-show-structure по умолчанию привязана к ключу C-c
C-s.
Строки выводятся в буфер, называемый буфером `*Occur*', с отступами
по уровню иерархии. Например, вот часть полученного при запуске
texinfo-show-structure в данном руководстве:
13 lines matching "^@\\(chapter \\|sect\\|subs\\|subh\\|
unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
in buffer texinfo-06.texi.
3:@chapter Ноды
26: @heading Два способа
59: @section Иллюстрация нод и меню
167: @section Команда @code{@@node}
222: @subheading Выбор имен нод и указателей
245: @subsection Как писать строку @code{@@node}
294: @subsection Советы по написанию строки @code{@@node}
...
Здесь написано, что строки 59, 222 и 245 файла `texinfo-06.texi'
начинаются командами @section, @subheading и
@subsection, соответственно. Если вы переместите курсор в окно
`*Occur*', вы можете поместить курсор на одной из этих строк и
перейти к соответствующему месту Texinfo-файла с помощью команды
C-c C-c (occur-mode-goto-occurrence). See section `Using Occur' in Руководство по GNU Emacs, для
получения подробной информации о команде
occur-mode-goto-occurrence.
Первая строка в окне `*Occur*' описывает регулярное
выражение, заданное в переменной texinfo-heading-pattern. Это
регулярное выражение -- тот образец, по которому производит поиск
команда texinfo-show-structure. See section `Using Regular Expressions' in Руководство по GNU Emacs, для получения подробной
информации.
Когда вы вызываете команду texinfo-show-structure, Emacs
отобразит структуру всего буфера. Если вы хотите посмотреть структуру
только части буфера, например одной главы, используйте команду C-x
n n (narrow-to-region) для пометки области. (See section `Narrowing' in Руководство по GNU Emacs.) Так был получен пример
выше@transnote{При переводе руководство было разбито на несколько файлов
по главам, поэтому не было необходимости использовать этот метод.}.
(Чтобы снова увидеть весь буфер, используйте C-x n w
(widen).)
Если вы вызовете texinfo-show-structure с числовым аргументом,
напечатав C-u C-c C-s, будут перечислены строки, начинающиеся
с @node, а так же строки, начинающиеся @-командами
@chapter, @section и подобными.
Вы можете вспомнить структуру Texinfo-файла, взглянув на список в окне `*Occur*'; и если вы неправильно назвали ноду или пропустили раздел, то сможете исправить ошибку.
occur
Иногда команда texinfo-show-structure выдает слишком много
информации. Вероятно, вы хотите вспомнить общую структуру
Texinfo-файла, и вам не нужен слишком детальный список, выдаваемый
командой texinfo-show-structure. в таком случае вы можете
непосредственно использовать команду occur. Для этого
напечатайте
M-x occur
и затем в ответ на приглашение напечатайте регулярное выражение,
образец для поиска. (See section `Regular Expressions' in Руководство по GNU Emacs.) Команда occur начинает работу от
текущей позиции курсора до конца буфера. Если вы хотите запустить
occur для буфера целиком, поместите курсор в начале
буфера.
Например, чтобы увидеть все строки, содержащие слово `@chapter', просто напечатайте `@chapter'. Вы получите список всех глав. Также будут перечислены все предложения со словом `@chapter' в середине строки.
Если вы хотите увидеть только строки, начинающиеся словом
`@chapter', напечатайте на запрос occur `^@chapter'.
Если вы хотите увидеть все строки, заканчивающиеся определенным словом
или фразой, завершите последнее слово символом `$', например
`поиск ошибок$'. Это может быть полезно, если вы хотите увидеть
все ноды, являющиеся частью одной и той же главы или раздела, и,
следовательно, имеющие один и тот же указатель `Up'.
See section `Using Occur' in Руководство по GNU Emacs, для большей информации.
Вы можете использовать команду Info-validate для проверки,
ссылаются ли `Next', `Previous', `Up' или другие указатели на ноды. Эта
команда проверяет, что каждый указатель ссылается на существующую ноду.
Команда Info-validate работает только с Info-файлами, но не с
Texinfo-файлами.
Программа makeinfo проверяет указатели автоматически, так что вам
не придется применять команду Info-validate, если вы используете
makeinfo. Вам понадобится применять Info-validate, если
вы не можете запустить makeinfo и вместо этого должны создавать
Info-файл, используя texinfo-format-region или
texinfo-format-buffer, или если вы пишите Info-файл с
нуля.
Info-validate
Чтобы использовать Info-validate, обратитесь к Info-файлу,
который вы хотите проверить и напечатайте:
M-x Info-validate
Обратите внимание, в команде Info-validate должна стоять
заглавная буква `I'. Вы также должны создать таблицу тегов перед
запуском Info-validate. See section Создание тегов в файле.
Если файл написан правильно, вы получите сообщение "File appears valid". Однако, если есть указатель, ссылающийся на несуществующую ноду, в буфер `*problems in info file*' будет выведено сообщение об ошибке.
Например, Info-validate была запущена в тестовом файле,
содержащем только первую ноду данного руководства. Одно из сообщений
говорит:
In node "Обзор", invalid Next: Режим Texinfo
Это значит, что нода, называемая `Обзор', содержит указатель `Next', который ни на что не ссылается (что верно в данном случае, так как в этом тестовом файле есть только одна нода).
Теперь предположим, что мы добавили ноду, называемую `Режим Texinfo', к нашему тестовому файлу, но не задали для нее указатель `Previous'. Тогда мы получим следующее сообщение об ошибке:
In node "Режим Texinfo", should have Previous: Обзор
Это происходит, потому что каждому указателю `Next' должен соответствовать указатель `Previous' (в ноде, на которую указывает `Next'), ссылающийся назад.
Info-validate также проверяет, все ли пункты меню и перекрестные
ссылки ссылаются на действительные ноды.
Info-validate требует наличия таблицы тегов и не работает с
разбитыми файлами. (Команда texinfo-format-buffer автоматически
разбивает большие файлы.) Чтобы использовать Info-validate с
большим файлом, вы должны запустить texinfo-format-buffer с
аргументом, чтобы она не разбивала Info-файл; и вы должны создать для
этого неразбитого файла таблицу тегов.
Вы можете запустить Info-validate только для одного Info-файла,
имеющего таблицу тегов. Эта команда не работает с косвенными
подфайлами, созданными при разбиении главного файла. Если у вас есть
большой файл (длиннее 70000 байт или около этого), вам нужно запускать
команды texinfo-format-buffer или makeinfo-buffer таким
образом, чтобы они не создавали косвенных подфайлов. Вам также нужно
будет создать для Info-файла таблицу тегов. После того, как вы это
сделали, вы можете запускать Info-validate и искать неправильные
ссылки на ноды.
Первый шаг -- создание неразбитого Info-файла. Чтобы запретить
texinfo-format-buffer разбивать Texinfo-файл на меньшие
Info-файлы, задайте команде M-x texinfo-format-buffer
аргумент:
C-u M-x texinfo-format-buffer
или, иначе
C-u C-c C-e C-b
Если вы сделаете так, Texinfo не будет разбивать файл и создавать для него таблицу тегов.
После создания неразбитого Info-файла вы должны создать для него таблицу тегов. Обратитесь к Info-файлу, в котором вы хотите сделать таблицу тегов и напечатайте:
M-x Info-tagify
(Обратите внимание на заглавную букву `I' в Info-tagify.)
Это создаст Info-файл с таблицей тегов, который вы сможете
проверить.
Третий шаг -- проверить Info-файл:
M-x Info-validate
(Обратите внимание на заглавную букву `I' в Info-validate.)
Кратко, шаги таковы:
C-u M-x texinfo-format-buffer M-x Info-tagify M-x Info-validate
После проверки структуры нод вы можете перезапустить
texinfo-format-buffer обычным способом, так что она автоматически
сделает таблицу тегов и разобьет файл, или вы можете создать таблицу
тегов и разбить файл вручную.
Вам стоит разбивать большие файлы или предоставлять командам
texinfo-format-buffer или makeinfo-buffer делать это для
вас автоматически. (Обычно вы будете предоставлять эту работу одной из
команд форматирования. See section Создание Info-файла.)
Файлы, получаемые в результате разбиения, называются косвенными подфайлами.
Info-файлы разбиваются для экономии памяти. Работая с меньшими файлами, Emacs не должен создавать большие буферы для хранения информации.
Если в Info-файле более 30 нод, вам стоит также создать для него таблицу
тегов. See section Запуск Info-validate, для получения информации о
методе создания таблицы тегов. (Опять же, таблицы тегов обычно
создаются автоматически командой форматирования; вам нужно создавать
таблицу тегов самим, только если вы пишите файл вручную. Скорее всего,
вам придется это делать для большого неразбитого файла, в котором вы
хотите запустить Info-validate.)
Обратитесь к Info-файлу, который вы хотите разбить и снабдить таблицей тегов, и напечатайте две команды:
M-x Info-tagify M-x Info-split
(Обратите внимание, буква `I' в `Info' -- заглавная.)
Когда вы примените команду Info-split, буфер сменится на
(маленький) Info-файл, в котором перечислены косвенные подфайлы. Этот
файл должен быть записан вместо файла, к которому вы первоначально
обратились. Косвенные подфайлы записываются в тот же каталог, где
находился первоначальный файл, а их имена генерируются добавлением к
имени первоначального файла символа `-' и числа.
Главный файл продолжает работать в качестве Info-файла, но содержит лишь таблицу тегов и каталог подфайлов.
Команда @refill заполняет абзац и, возможно, делает отступ в его
первой строке.(15) Команда @refill уже не
важна, но мы описываем ее, так как она была нужна раньше. Вы увидите ее
во многих старых Texinfo-файлах.
Без перезаполнения, абзацы, содержащие длинные @-конструкции могли
выглядеть после форматирования плохо, потому что программа
форматирования удаляет @-команды и укорачивает некоторые строки больше
других. Раньше ни команда texinfo-format-region, ни
texinfo-format-buffer не перезаполняли абзацы автоматически.
Нужно было писать команду @refill в конце каждого абзаца, чтобы
эти форматирующие команды заполняли их. (И TeX и makeinfo
всегда перезаполняли абзацы автоматически.) Теперь все программы,
форматирующие для Info, автоматически заполняют и делают отступы в
абзацах, которые этого требуют.
Команда @refill заставляет texinfo-format-region и
texinfo-format-buffer перезаполнять абзац в Info-файле
после того, как завершена вся другая обработка. По этой причине
вы не можете использовать @refill в абзаце, содержащем
@* или @w{ ... }, так как перезаполнение перекроет
эти команды.
Команды texinfo-format-region и texinfo-format-buffer
теперь автоматически добавляют @refill в конец каждого абзаца,
который должен быть заполнен. Они не добавляют @refill в конец
абзацев, которые содержат @* или @w{ ...}, и,
следовательно, не перезаполняют их и не делают в них отступы.
Символ `@' используется для начала специальных команд Texinfo. (Он имеет то же значение, что и `\' в plain TeX.) В Texinfo есть четыре вида @-команд:
@.,
@:, @*, @SPACE, @TAB,
@NL, @@, @{ и @}.
@dots{} =>
`...', @equiv{} => `==',
@TeX{} => `TeX' и @bullet{} =>
`*'.
@dfn обозначает вводимый
или определяемый термин; она используется следующим образом: `В
Texinfo, @@-команды -- это команды @dfn{разметки}.'
@center или @cindex.
Если не требуется аргумент, после слова пишется символ конца строки.
Если нужен аргумент, он отделяется от имени команды пробелом. Фигурные
скобки не используются.
Таким образом, алфавитные команды разделяются на классы с разными синтаксисами аргументов. Нельзя сказать, к какому классу принадлежит команда по виду ее имени, но можно определить это по ее значению: если команда обозначает графический знак, то она относится к классу 2 и не требует аргументов; если важно использовать команду вместе с другим текстом в абзаце, то она относится к классу 3, и за ней должен следовать аргумент в фигурных скобках; иначе она относится к классу 4 и использует остаток строки в качестве аргумента.
Команды классов 3 и 4 имеют разный синтаксис, чтобы было легче читать
Texinfo-файлы, а так же чтобы помочь правильной работе команд GNU Emacs
для заполнения и работы с абзацами. Есть только одно исключение из
этого правила: команда @refill, которая всегда используется в
конце абзаца, сразу после завершающей точки или другого знака
препинания. @refill не принимает аргументов и не требует
фигурных скобок. @refill никогда не смущает команды Emacs для
абзацев, потому что никогда не появляется в начале строки.
TeX распространяется свободно. Вы можете получить TeX для Unix-систем по анонимному ftp или на физическом носителе. Основной материал состоит из пакета Web2c TeX (http://tug.org/web2c).
Инструкции по загрузке по анонимному ftp и сведения о других доступных дистрибутивах:
ftp://tug.org/tex/unixtex.ftp http://tug.org/unixtex.ftp
Фонд свободного программного обеспечения предоставляет основной дистрибутив, достаточный для печати руководств на Texinfo, на Source Code CD-ROM. Вы можете заказать его по этому адресу:
Free Software Foundation, Inc.
59 Temple Place Suite 330
Boston, MA 02111-1307
USA
Телефон: +1-617-542-5942
Факс: (включая Японию) +1-617-542-2652
Бесплатный факс (в Японии):
0031-13-2473 (KDD)
0066-3382-0158 (IDC)
Электронная почта: gnu@gnu.org
Существует много других дистрибутивов TeX; смотрите http://tug.org/.
@anchor{Command and Variable Index} Это алфавитный список всех @-команд, а также функций Emacs Lisp и некоторых переменных. Чтобы списком было удобнее пользоваться, команды перечислены без начального символа `@'.
Jump to: ! - " - ' - ( - * - , - - - . - : - = - ? - @ - \ - ^ - ` - a - b - c - d - e - f - g - h - i - k - l - m - n - o - p - q - r - s - t - u - v - w - x - { - } - ~
@titlepage
@anchor{Concept Index} Jump to: ( - . - : - < - @ - \ - a - b - c - d - e - f - g - h - i - j - l - m - n - p - r - s - t - u - А - Б - В - Г - Д - Е - З - И - К - Л - М - Н - О - П - Р - С - Т - У - Ф - Х - Ц - Ч - Ш - Э - Я
@include, пример файла
@menu, составные части
@node, написание строки
@w, для пустых элементов
install-info
href, создание в HTML
makeinfo внутри Emacs
makeinfo, ключи
TEXINPUTS, переменная среды
@occur
@deffn
Info-validate
makeinfo из Emacs
@setfilename
makeinfo
@kbd
@node
makeinfo
@inforef
@pxref
@ref
@xref
@include
makeinfo
@code
@inforef
@pxref
@ref
@xref
@node, требования
tex и texindex
This document was generated on 2 April 2002 using texi2html 1.56k.