Руководство хакера
TEItools довольно плохо документированы. Ниже идет
минимальная информация и советы. Надеюсь, этот раздел
когда-нибудь станет пользовательской документацией по
TEItools. Есть добровольцы?
Запуск
Пользовательский интерфейс к TEItools -- один скрипт,
sgml2any. Он, однако, должен запускаться под
каким-либо другим именем, например, linuxdoc2tei или
tei2tex, что достигается символьным линком или просто
копированием. Синтаксис следующий:
скрипт входной_файл [стилевые опции]
входной_файл -- имя исходного файла SGML для
обработки.
Каждая стилевая_опция выглядит как -style
имя или как -style
имя=значение. Порядок опций -style имеет
значение. Один ключ -style может иметь несколько
стилей, перечисленных через запятую. Подробнее о
стилях -- ниже.
Возможно, вы будете создавать свои собственные расширения
к TEItools. Они могут включать:
- локальные DTD;
- локальные стили;
- локальные скрипты и библиотеки.
Для помощи в такой локальной разработке домашний каталог
TEItools может иметь подкаталог site, который можно
сделать символьным линком вовне иерархии $SGML_HOME
для облегчения апгрейдов. Он должен иметь ту же структуру,
что и основное дерево каталогов TEItools. Файлы ищутся
вначале в дереве site, потом -- в основном дереве.
Вход и выход
sgml2any определяет входной и выходной форматы
просто по своему имени: если он запущен под именем
tei2rtf, то входной формат будет tei, а
выходной -- rtf.
Каждый входной формат соответствует каталогу под
$SGML_HOME. Каждому выходному, в свою
очередь, -- каталог под каталогом входного. Он уже
содержат спецификацию CoST по имени script,
необходимые дополнительные файлы и каталог
styles. Файлы в последней и являются стилями.
Каждая спецификация обрабатывает документы независимо от
других, что отличает TEItools от систем, основанных
на DSSSL. (И, пожалуйста, не говорите мне что мой путь менее
правильный. Вы даже в первую десятку указавших на это не
попадете ;-)) Я старался сделать спецификации максимально
близкими по виду выходных файлов, так что все различия в
виде выходных форматов следует считать ошибками.
Стилевые файлы используются просто путем приписывания их
к концу спецификации, так что они могут переименовывать
существующие процедуры Tcl и подставлять вместо них свои
замены. Стили для преобразования, например, из tei в
rtf ищутся в каталоге
$SGML_HOME/tei/rtf/styles.
Если стиль имеет вид имя=значение, то глобальная
переменная TEItools_имя_value
устанавливается равной значение. Ее значение может
затем использоваться коде спецификации или стилей.
Чтобы разобраться в спецификациях, вам нужно понимать Tcl,
CoST,
и, для случая выходного формата RTF, RATFINK.
Локализация
TEItools должны легко адаптироваться к новому
языку. Они хорошо работают с русским, поскольку я их
использую именно так. В поставку включены файлы локализации
для русского, английского, французского и финского языков.
Делая поддержку нового языка, берите один из них в качестве примера.
Все, что зависит от локализации, находится в файлах
$SGML_HOME/lib/locale.ЯЗЫК.tcl. ЯЗЫК
определяется в таком порядке:
- Если корневой элемент <tei.2> имеет атрибут
lang, используется его значение. Иначе
- Если определена переменная окружения
SGML_LANG, используется ее значение. Иначе
- Если определена переменная окружения
LANG, используется ее значение. Иначе
- используется значение en.
Заметьте, что для формирования имени файла локализации
LANG приводится к нижнему регистру.
Файлы локализации определяют следующее.
Во-первых, нужно определить substitution[2] localize,
которая определяет вставляемые в документы слова на данном
языке. Во-вторых, там же определяются зависящие от
локализации функции. Сейчас их список таков:
- openLang { lang } (LaTeX)
- Соответствующая команда
\selectlanguage{}. Если ваш TeX не использует
пакет babel, возвращает пустую строчку. Пример:
\selectlanguage{english}.
- closeLang{} (LaTeX)
- Закрывающий \selectlanguage{}.
- tabTitle { number } (RTF)
- Заголовок таблицы с номером
number. Пример: "Таблица ${number}."
- figTitle { number } (RTF)
- Заголовок иллюстрации с номером
number.
- appendixPrefix { number } (RTF)
- Генератор букв для нумерации
приложений. Например, если вы хотите, чтобы приложения
назывались "А", "Б", и так далее, то
[appendixPrefix 0] должна возвращать "А" и
т.д.
Существующие стили
Заметьте, что каждый стиль относится только к одному
выходному формату.
HTML
- number_heads
- Добавляет нумерацию
к заголовкам разделов.
- split
- Разрезает вывод на файлы
по разделам первого уровня.
- toc_ref
- К концу каждого раздела
первого уровня добавляется ссылка на
содержание.
- toc_depth=NN
- Устанавливает глубину содержания равной NN. По
умолчанию 3.
- forced_toc
- Добавляет
сгенерированное содержание.
- framed_toc
- Содержание
генерируется в отдельном фрейме.
- frames=X:Y
- При
использовании framed_toc задает отношение ширины
левого фрейма (содержания) к ширине правого
(текста). По умолчанию -- 1:4.
- indent_para
- Начинает абзацы с
красной строки.
- CSS=URL
- Использует
каскадный стиль, указываемый URL.
- no_signature
- Не включает в конце
каждого файла строку Сгенерировано TEItools.
TeX
- 11pt,12pt
- Изменяет размер
шрифта с 10pt по умолчанию на 11 или 12pt.
- scale=NN
- Устанавливает
коэффициент увеличения равным NN.
- page_headers
- Меняет стиль
страницы. Появляется верхний колонтитул с названием
главы и номером страницы, отделенный линейкой. По
умолчанию номер страницы ставится внизу страницы.
- running_title
- Вместо обычной
титульной страницы ставит заголовок в начало первой
страницы документа.
- linuxdoc_title
- Делает заголовок
в стиле linuxdoc-sgml. Требует стиля
running_title.
- no_title
- Запрещает генерацию
титульной страницы.
- no_front_matter
- Запрещает
нумерацию вводной части текста римскими
цифрами.
- ps_fonts
- Использует Type1 шрифты
вместо стандартных шрифтов METAFONT.
- pdf
- Результирующий .tex
файл предназначается для обработки pdflatex,
чтобы получить PDF. Требует стиля ps_fonts.
- skip=NN
- NN здесь
является коэффициентом увеличения интервала между
строчками. Разумные значения -- 1.5 и 2.
- parskip
- Добавляет между абзацами
вертикальный интервал размером 1ex.
- numdepth=N
- Здесь N
задает максимальный уровень вложенности <div?>, на
котором еще нумеруются заголовки разделов. По
умолчанию равно 3.
- openpage=gi
- Здесь gi
должно быть одним из div1, div2 и
т.д. Каждый элемент gi будет начинаться с новой
страницы.
- firstpage=N
- Здесь
N задает номер первой страницы текста.
- landscape
- Переключается в режим
горизонтального листа. Вам понадобится запускать
dvips с опцией -t landscape чтобы
получить корректную ориентацию результирующего
PostScript'а.
- float_pages
- Выносит плавающие
объекты (иллюстрации) на выделенные страницы.
- twocolumn
- Текст верстается в две
колонки .
- two_side
- Текст верстается для
двусторонней печати.
- small_tables
- Уменьшает шрифт,
используемый в таблицах.
- fancyvrb
- Заключает примеры
(элементы <eg>) в рамку.
- raggedright
- Текст верстается
отжатым влево.
RTF
- linuxdoc_title
- См. выше.
- dont_number_heads
- Делает заголовки
элементов <div?> ненумерованными.
- external_figs
- Использует отдельные
файлы .bmp вместо вставки графики в текст
RTF. StarOffice, кажется, требует
первого, MS
Word, кажется, требует второго,
ApplixWords, кажется, ни так, ни эдак
моей графики не видит. :-(
Стили в RTF
Возможно использовать задаваемые пользователем стили в
генерируемом RTF. Пример задания стилей смотрите в
$SGML_HOME/site/tei/rtf/styles/userstyle.