Написание документации, часть IV: Texinfo
В формате Texinfo поддерживается несколько типов перекрестных ссылок: с
дополнительным текстом и без него, ссылки в пределах одного и того же файла, на
определенные места в других файлах Texinfo и, наконец, ссылки, указывающие
куда-то "во внешний мир".
Узлы [Nodes] -- самые частые "мишени", на которые "нацеливаются" ссылки.
Команда @anchor{имя-метки} создает в
документе дополнительную метку [anchor], на которую можно ссылаться из другого
места. Сама по себе команда @anchor в оттранслированном документе
не видна. Имена меток не должны конфликтовать с именами узлов.
- @xref
-
Вставляет "декорированную" перекрестную ссылку. Команда @xref создает
оформление для ссылки в начале предложения.
Пример:
... является основой для нескольких многоточечных
методов. @xref{Multi-point Methods}. Мы
изучаем одноточечные методы ...
- @pxref
-
@pxref ведет себя подобно @xref, но предназначен для использования внутри
скобок.
Пример:
Алгоритм терпит неудачу в случае корней
более высокого порядка (@pxref{Higher Order Root}) и
корней первого порядка, заданных неверными условиями.
- @ref
-
Вставляет простую (не "декорированную") перекрестную ссылку. В остальном
ведет себя подобно @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
-
makeinfo преобразует файлы Texinfo (.texi) в
-
Файлы Info
По умолчанию, makeinfo создает файл Info с именем, указанным параметром
@setfilename. Опция --no-split не разрешает
makeinfo дробить выходной файл на отдельные файлы [chunks] приблизительно по
50KB каждый.
Помимо всего прочего, обработка файла Texinfo программой makeinfo
тщательно проверяет его синтаксическую структуру.
-
Текстовой файл ASCII
Опция --no-headers требует от makeinfo создать простой
текстовой ASCII-файл. Формат текстового файла полезен при вычитке экранной
версии и удобен для проверки правописания с помощью, например,
diction(1).
- texi2html
-
По названию команды вы, наверное, уже догадались, что texi2html преобразует
файлы Texinfo в HTML. С помощью опции -monolithic вывод
осуществляется в виде одного файла. Другая опция, -split
указывает создать отдельный файл для каждого узла.
По умолчанию texi2html транслирует секции @iftex и не
использует разделы @ifinfo. С помощью опции
-expandinfo можно получить противоположный результат.
Обратите внимание на то, что опции texi2html начинаются с одного
дефиса.
- texi2dvi
-
Создает из исходного файла Texinfo файл в независимом от устройства формате
.dvi. Применение dvips(1) к файлу .dvi
позволяет получить на выходе код Postscript. Я нахожу полезными опции
--clean и --quiet. Первая удаляет промежуточные
файлы, оставляя только файл .dvi. А вторая отключает вывод
необязательных сообщений (тут автор использует "непереводимую игру слов":
No gnews is good gnews!'', т.е. "Отсутствие гнуовостей -- хорошая гнуовость"
-- прим. перев.).
- texi2pdf
-
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 к вызову info добавьте параметр
--file=файл-info, где файл-info содержит полный
путь к нужному файлу Info.
Если вы желаете начать просмотр с конкретного узла имя-node,
добавьте параметр --node=имя-node.
Моя любимая ошибка -- смешивание темы с -- --
файлом-info, т.е. набор команды
info ./cache-profiler.info
вместо подразумеваемого
info --file=./cache-profiler.info
- pinfo
-
Это основанный на curses(3) браузер с навигацией в стиле
lynx(1). pinfo очень красиво раскрашивает страницы Info
- emacs
-
Скриншот доказывает улучшение
возможностей просмотра фалов 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
-
xinfo -- древнейшая программа для просмотра Info-файлов в среде X11.
Цветовой разметки текста нет. Более всего меня в нем раздражает -- до такой
степени, что я его никогда не использую -- то, что навигация и отображение
полностью разделены. Я имею в виду, что для перехода по ссылке в одной панели,
приходиться "кликать" мышью по панели верхнего уровня. Щелчки мыши по самому
меню ни к чему не приводят.
Скриншот можно посмотреть
здесь.
- tkinfo
-
Ну, это мой любимый браузер Info для X! В нем есть все "приятности"
info(1): он быстро стартует, а его окно удобно устроено.
- gnome-help-browser
-
Если вы используете Gnome, то, наверное, знакомы
сgnome-help-browser(1x). В нем можно просматривать и страницы Info.
- kdehelp
-
То же самое относится и к пользователям KDE... Вы, вероятно, знакомы с
kdehelp(1x). Среди других форматов в нем поддерживается и страницы Info.
kdehelp легко убедить показать конкретный Info-файл:
kdehelp ./cache-profiler.info
Просто на большой?!
konqueror тоже показывает файлы info (по крайней мере
konqueror 2.2.2): просто надо напечатать "info:" в строке адреса.
Обзор распространенных программ просмотра Info
Обзор распространенных Info-браузеров. "Поддержка других
форматов" означает умение показывать документы в других форматах. "требует
X11" означает, что программа работает только в среде X Window. "Навигация в
стиле info" означает, что в программе дублируется команды
навигации info(1).
| Приложение |
Поддержка других форматов |
требует X11 |
Навигация в стиле info |
info |
нет |
нет |
да |
pinfo |
нет |
нет |
нет |
emacs |
нет |
нет |
да |
xinfo |
нет |
да |
да |
tkinfo |
нет |
да |
да |
gnome-help-browser |
да |
да |
нет |
kdehelp |
да |
да |
нет |
- За
-
- Формат Texinfo: определяемые пользователем макросы (в этой статье не
обсуждались)
- Вывод в формате TeX: совершенство верстки, фантастическое качество
печатной версии
- Формат Info: альтернатива вездесущему HTML
- Программы просмотра Info: стандартизированная, быстрая и удобная
навигация
- Против
-
Домашняя страница Texinfo, на которой можно найти много справочной информации
http://texinfo.org/
Существующие конвертеры Texinfo перечислены здесь: http://www.fido.de/kama/texinfo/texinfo-en.html
Кристоф Шпиль [Christoph Spiel]
Крис руководит расположенной в Верхней Баварии (Германия) компанией,
консультирующей по вопросам Open Source Software. Не смотря на то, что по
образованию он физик (он получил ученую степень Доктора Философии в Мюнхенском
Технологическом Университете), его главные интересы вращаются вокруг численных
методов, гетерогенных сред программирования и разработки программного
обеспечения. Связаться с ним можно по адресу [email protected].
