Go to the first, previous, next, last section, table of contents.


Обзор Texinfo

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, вы можете создавать печатный документ с обычными для книг свойствами, включая главы, разделы, перекрестные ссылки и именные указатели. Из этого же исходного 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-файлы

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):

Как правило, команды, встречающиеся внутри текста, нужно использовать с фигурными скобками, но команды, записываемые на отдельной строке, не нужно. Исключение составляют неалфавитные команды, такие как @:: они не требуют скобок.

По мере появления у вас опыта в использовании Texinfo, вы быстро научитесь, как писать разные команды: различные способы написания команд позволяют легче писать и читать Texinfo-файлы, чем если бы все команды следовали единому синтаксису. (Подробности о синтаксисе @-команд смотрите в section Синтаксис @-команд.)

Основные соглашения о синтаксисе

Этот раздел описывает общие соглашения, применяемые во всех документах Texinfo.

Внимание: Не используйте символы табуляции в 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-файлов заканчиваются расширением `.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-файла

Вообще говоря, Texinfo-файл содержит что-нибудь еще кроме минимально необходимых начала и конца -- обычно он состоит из шести частей:

1. Заголовок
Заголовок задает имя файла, сообщает TeX, какой форматный файл использовать, и выполняет другие служебные задачи.
2. Обзорное описание и авторские права
Сегмент Обзорное описание и авторские права описывает документ и содержит информацию об авторских правах и разрешениях на копирование для Info-файла. Этот сегмент должен быть заключен между командами @ifinfo и @end ifinfo, чтобы форматирующие программы помещали его только в Info-файл.
3. Название и авторские права
Сегмент Название и авторские права содержит название и информацию об авторских правах и разрешениях на копирование для печатного руководства. Этот сегмент должен быть заключен между командами @titlepage и @end titlepage. Название и страница с информацией об авторских правах появляется только в печатном руководстве.
4. Нода `Top' и главное меню
Главное меню содержит полное меню со всеми нодами Info-файла. Оно появляется только в Info-файле в первой ноде (ноде `Top').
5. Тело
Тело документа может быть структурировано подобно традиционной книге или энциклопедии или в свободной форме.
6. Конец
В Конце содержатся команды для печати именных указателей и составления содержания, а также команда @bye на отдельной строке.

Короткий пример Texinfo-файла

Вот завершенный, но очень короткий Texinfo-файл из шести частей. Первые три части файла, от `\input texinfo' до `@end titlepage', кажутся более запугивающими, чем они есть на самом деле. Большая часть материала -- это стандартный шаблон; когда вы пишите руководство, просто вставьте в этот сегмент названия для него. (See section Начало Texinfo-файла.)

Текст примера далее содержит отступ; комментарии не содержат. Полный файл, без комментариев, показан в section Пример Texinfo-файла.

Часть 1: Заголовок

Заголовок не появляется ни в Info-файле, ни в печатном документе. В нем устанавливаются различные параметры, включая имя Info-файла и название, используемое в заголовках печатной версии.

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename sample.info
@settitle Пример документа
@setchapternewpage odd
@c %**end of header

Часть 2: Обзорное описание и авторские права

Сегмент с обзорным описанием и авторскими правами не появляется в печатном документе.

@ifinfo
Это короткий пример законченного Texinfo-файла.

Copyright @copyright{} 1990 Free Software Foundation, Inc.
@end ifinfo

Часть 3: Титульный лист и авторские права

Сегмент с титульным листом и авторскими правами не появляется в Info-файле.

@titlepage
@sp 10
@comment Заголовок печатается крупным шрифтом
@center @titlefont{Пример заголовка}

@c Две следующие команды начинают страницу с информацией об
@c авторских правах
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1990 Free Software Foundation, Inc.
@end titlepage

Часть 4: Нода `Top' и главное меню

Нода `Top' содержит главное меню Info-файла. Так как в печатном руководстве вместо меню используется содержание, главное меню появляется только в Info-файле.

@node    Top,      First Chapter,          , (dir)
@comment имя-ноды, следующая,    предыдущая, вверх
@menu
* Первая глава::      Первая и единственная глава в
                        этом примере.
* Указатель понятий:: В этом указателе есть два элемента.
@end menu

Часть 5: Тело документа

Сегмент тела включает весь текст документа, кроме именных указателей и содержания. В этом примере показана нода и глава, содержащая нумерованный перечень.

@node    Первая глава, Указатель понятий, Top,     Top
@comment имя-ноды,      следующая,     предыдущая, вверх
@chapter Первая глава
@cindex Пример элемента именного указателя

Это содержимое первой главы.
@cindex Другой пример элемента именного указателя.

Это нумерованный перечень.

@enumerate
@item
Это первый пункт.

@item
Это второй пункт.
@end enumerate

Команды @code{makeinfo} и @code{texinfo-format-buffer}
преобразуют Texinfo-файлы, такие как этот, в Info-файлы;
а @TeX{} форматирует печатное руководство.

Часть 6: Конец документа

Последний сегмент включает команды для создания именного указателя в отдельной ноде и ненумерованной главе и для создания содержания; в нем, также, есть команда @bye, которая отмечает конец документа.

@node    Указатель понятий,         , Первая глава, Top
@unnumbered Указатель понятий

@printindex cp

@contents
@bye

Результаты

Так выглядит содержание первой главы примера:

Это содержание первой главы.

Это нумерованный перечень.

  1. Это первый пункт.
  2. Это второй пункт.

Команды 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, язык разметки для текста, предназначенный для чтения и интерактивно, и в напечатанной версии.


Go to the first, previous, next, last section, table of contents.