В формате Texinfo поддерживается несколько типов перекрестных ссылок: с дополнительным текстом и без него, ссылки в пределах одного и того же файла, на определенные места в других файлах Texinfo и, наконец, ссылки, указывающие куда-то "во внешний мир".
Узлы [Nodes] -- самые частые "мишени", на которые "нацеливаются" ссылки.
Команда @anchor{
имя-метки}
создает в
документе дополнительную метку [anchor], на которую можно ссылаться из другого
места. Сама по себе команда @anchor
в оттранслированном документе
не видна. Имена меток не должны конфликтовать с именами узлов.
Вставляет "декорированную" перекрестную ссылку. Команда @xref создает оформление для ссылки в начале предложения.
Пример:
... является основой для нескольких многоточечных
методов. @xref{Multi-point Methods}. Мы
изучаем одноточечные методы ...
@pxref ведет себя подобно @xref, но предназначен для использования внутри скобок.
Пример:
Алгоритм терпит неудачу в случае корней
более высокого порядка (@pxref{Higher Order Root}) и
корней первого порядка, заданных неверными условиями.
Вставляет простую (не "декорированную") перекрестную ссылку. В остальном ведет себя подобно @xref.
До сих пор мы использовали команды создания перекрестных ссылок с одним аргументом. Команды эти, однако, могут принимать до пяти параметров. Ниже представлены примеры того, как, в зависимости от числа аргументов, изменяется внешний вид оттранслированного текста. Я привожу примеры "гибкого" использования команды @xref
@xref{
имя-метки}
дает на выходе
*Note
имя-метки::
при трансляции в Info и
Смотри раздел
имя-раздела
[
имя-метки],
страница
номер-страницы
при трансляции для печати, здесь имя-радела и номер-страницы -- соответственно название раздела и номер страницы, где в версии для печати располагается метка "имя-метки".
@xref{
имя-метки,
имя-перекрестной-ссылки}
после трансляции даст:
*Note
имя-перекрестной-ссылки:
имя-метки
и
Смотри раздел
имя-раздела
[
имя-метки],
страница
номер-страницы
@xref{
имя-метки,
имя-перекрестной-ссылки,
заголовок-темы}
дает:
*Note
имя-перекрестной-ссылки:
имя-метки
и
Смотри раздел
имя-раздела
[
заголовок-темы],
страница
номер-страницы
@xref{
имя-метки,
имя-перекрестной-ссылки,
заголовок-темы,
имя-файла-info,
заголовок-печатного-руководства}
в результате трансляции получаем:
*Note
имя-перекрестной-ссылки:
(
имя-файла-info)
имя-метки
и
Смотри раздел
"
заголовок-темы"
в
заголовок-печатного-руководства
Texinfo определяет обширный набор команд прямого или "физического" форматирования, помечающих части текста, как код, пользовательский ввод, имя файла и т.д.
@emph{
набранный-курсивом-текст}
Отображает набранный-курсивом-текст (сюрприз:) курсивом. В Info курсивное начертание "приближенно" изображается с помощью символов подчеркивания, как скобки охватывающих _набранный-курсивом-текст_.
Пример:
Для обработки файлов Texinfo
пользуйтесь tex(1) @emph{а не}latex(1).
@strong{
текст-набранный-жирным}
Отображает текст-набранный-жирным шрифтом жирного начертания. В Info этому "примерно" соответствует символы "звездочка", охватывающие *текст-набранный-жирным*.
Пример:
Файлы Info @strong{не могут} содержать
графику высокого разрешения.
@file{
имя_файла}
Выделяет имя_файла, окружая его одиночными кавычками, например так
filename'
. При подготовке версии для печати имя_файла
печатается шрифтом пишущей машинки.
Пример:
Убедитесь, что в вашей Linux-системе
установлена самая свежая версия @file{texinfo.tex}.
@url{
универсальный-локатор-ресурса}
Таким образом в тексте выделяется универсальный локатор ресурса (URL). В экранной версии универсальный-локатор-ресурса будет помещен в угловые скобки. При выводе на печать угловые скобки не добавляются, но универсальный-локатор-ресурса набирается моноширинным шрифтом "пишущей машинки".
Пример:
Дополнительная информация по Texinfo
можно найти на @url{http://texinfo.org/}.
@code{
код-программы}
Служит для выделения коротких участков программного кода.
Предпочтительной является форма @code{bless}
с двумя аргументами, поэтому всегда пишите
@code{bless $objref, $class}.
@samp{
текст, набираемый "как есть",
буквально}
Помечает символы, непосредственно набираемый текст, имена символов и т.д.
Угловые скобки (@samp{<}, @samp{>}) являются
основным разделителем в HTML.
@var{
текст, подлежащий замене}
Помечает мета-синтаксические [meta-syntactic] переменные, знаменитые
foo
и bar
.
Команды Perl @code{bless} лучше всего вызывать
с двумя аргументами, например так @code{bless
@var{object_reference}, @var{classname}}.
@kbd{
названия клавиш}
Помечает отдельные клавиши или серии клавиш.
В emacs, нажмите @kbd{C-h i} для вызова
встроенного браузера Info, или наберите @kbd{M-x
info}.
@command{
имя-команды}
Помечает имя команды.
Двумя наиболее важными командами шелла являются
@command{ls} и @command{cd}.
@option{
имя-опции}
Метит имя опции командной строки @option
вот так:
Опция @option{--html} заставляет
@command{makeinfo} создавать на выходе файл HTML
вместо файла Info.
@option
не подходит для форматирования синопсиса команды. Для
того, чтобы оформить краткое описание использования команды лучше
воспользоваться окружением @example
. Скажем так:
@example
makeinfo --html --output=@var{output-filename} @var{input-filename}
@end example
а в блоке текста к опциям обращаться, как @option{--html}
и
@option{--output}
, а к аргументам команд как
@var{output-filename}
и
@var{input-filename}
.
makeinfo преобразует файлы Texinfo (.texi) в
Файлы Info
По умолчанию, makeinfo создает файл Info с именем, указанным параметром
@setfilename
. Опция --no-split
не разрешает
makeinfo дробить выходной файл на отдельные файлы [chunks] приблизительно по
50KB каждый.
Помимо всего прочего, обработка файла Texinfo программой makeinfo тщательно проверяет его синтаксическую структуру.
Текстовой файл ASCII
Опция --no-headers
требует от makeinfo создать простой
текстовой ASCII-файл. Формат текстового файла полезен при вычитке экранной
версии и удобен для проверки правописания с помощью, например,
diction(1).
По названию команды вы, наверное, уже догадались, что texi2html преобразует
файлы Texinfo в HTML. С помощью опции -monolithic
вывод
осуществляется в виде одного файла. Другая опция, -split
указывает создать отдельный файл для каждого узла.
По умолчанию texi2html транслирует секции @iftex
и не
использует разделы @ifinfo
. С помощью опции
-expandinfo
можно получить противоположный результат.
Обратите внимание на то, что опции texi2html начинаются с одного дефиса.
Создает из исходного файла Texinfo файл в независимом от устройства формате
.dvi. Применение dvips(1)
к файлу .dvi
позволяет получить на выходе код Postscript. Я нахожу полезными опции
--clean
и --quiet
. Первая удаляет промежуточные
файлы, оставляя только файл .dvi. А вторая отключает вывод
необязательных сообщений (тут автор использует "непереводимую игру слов":
No gnews is good gnews!'', т.е. "Отсутствие гнуовостей -- хорошая гнуовость"
-- прим. перев.).
texi2pdf за "один присест" создает из исходного файла Texinfo файл в
формате Переносимого Документа [Portable Document File] (.pdf). Можно
использовать те же опции, что и в случае texi2dvi. Я, однако, заметил, что
texi2pdf определенно требуется опция --pdf
, иначе он
останавливается, громко требуя файл .dvi, даже когда этот файл точно
существует. Гр-р! Так что я обычно выполняю следующее:
texi2pdf --quiet --clean --pdf foobar.texi
От других рассмотренных нами систем подготовки документации Texinfo отличается тем, что для целей экранного просмотра документы Texinfo могут быть транслированы в отличный от HTML формат, а именно -- в формат Info. Естественно, что для формата экранного просмотра требуется браузер!
info
, прародитель всех браузеров Info, это простой, но, тем не
менее, эффективный браузер просмотра
файлов Info в консоли.
Для того, чтобы просмотреть страницы Info по теме Тема используйте вызов
info Тема
Для просмотра файла Info файл-info к вызову info добавьте параметр
--file=
файл-info, где файл-info содержит полный
путь к нужному файлу Info.
Если вы желаете начать просмотр с конкретного узла имя-node,
добавьте параметр --node=
имя-node.
Моя любимая ошибка -- смешивание темы с -- -- файлом-info, т.е. набор команды
info ./cache-profiler.info
вместо подразумеваемого
info --file=./cache-profiler.info
Это основанный на curses(3)
браузер с навигацией в стиле
lynx(1)
. pinfo очень красиво раскрашивает страницы Info
Скриншот доказывает улучшение возможностей просмотра фалов Info в emacs 21.x.
Я знаю, что это лишь Emacs Info, но оно мне сильно-сильно нравится! Я его даже люблю!
Можно просмотреть установленную документацию в формате Info (C-h
i
', info
). Или же можно загрузить
файл Info и командой Info-on-current-buffer
превратить буфер в
браузер Info (обратите внимание на заглавную букву "I"). Если нет желания
переключаться между рабочими буферами и режимом просмотра Info, то можно
открыть файл в режиме просмотра (C-x 5 f
',
find-file-other-frame
). Для того, чтобы открыть новый фрейм с
браузером Info, переключитесь в буфер *info*
в текущем окне emacs
и выполните команду view-buffer-other-frame
.
Чтобы получить от "браузенья" дополнительное удовольствие, попробуйте
команду Info-speedbar-browser
.
xinfo -- древнейшая программа для просмотра Info-файлов в среде X11. Цветовой разметки текста нет. Более всего меня в нем раздражает -- до такой степени, что я его никогда не использую -- то, что навигация и отображение полностью разделены. Я имею в виду, что для перехода по ссылке в одной панели, приходиться "кликать" мышью по панели верхнего уровня. Щелчки мыши по самому меню ни к чему не приводят.
Скриншот можно посмотреть здесь.
Ну, это мой любимый браузер Info для X! В нем есть все "приятности"
info(1)
: он быстро стартует, а его окно удобно устроено.
Если вы используете Gnome, то, наверное, знакомы
сgnome-help-browser(1x)
. В нем можно просматривать и страницы Info.
То же самое относится и к пользователям KDE... Вы, вероятно, знакомы с
kdehelp(1x)
. Среди других форматов в нем поддерживается и страницы Info.
kdehelp легко убедить показать конкретный Info-файл:
kdehelp ./cache-profiler.info
Просто на большой?!
konqueror
тоже показывает файлы info (по крайней мере
konqueror 2.2.2): просто надо напечатать "info:" в строке адреса.
Приложение | Поддержка других форматов | требует X11 | Навигация в стиле info |
---|---|---|---|
info |
нет | нет | да |
pinfo |
нет | нет | нет |
emacs |
нет | нет | да |
xinfo |
нет | да | да |
tkinfo |
нет | да | да |
gnome-help-browser |
да | да | нет |
kdehelp |
да | да | нет |
Формат исходного текста документов Texinfo:
Домашняя страница Texinfo, на которой можно найти много справочной информации http://texinfo.org/
Существующие конвертеры Texinfo перечислены здесь: http://www.fido.de/kama/texinfo/texinfo-en.html
Крис руководит расположенной в Верхней Баварии (Германия) компанией, консультирующей по вопросам Open Source Software. Не смотря на то, что по образованию он физик (он получил ученую степень Доктора Философии в Мюнхенском Технологическом Университете), его главные интересы вращаются вокруг численных методов, гетерогенных сред программирования и разработки программного обеспечения. Связаться с ним можно по адресу [email protected].