Скачать
Архив
Ссылки

© 2001-2003
Алексей Алишевских
alexeya at gmail-dot-com

Last Modified:
01/24/2006 14:01:16

Russian FOP HOWTO:

Установка и конфигурация

Этот документ описывает методику установки и конфигурации Apache FOP (Formatting Objects Processor) для работы с пользовательскими шрифтами. Данная методика опробована при конфигурировании FOP версий 0.19.x и до 0.20.5 включительно.

1 Приборы и материалы

Что нам понадобится:

  • Дистрибутив FOP версий 0.19.x или 0.20.x. Обратите внимание, что сейчас FOP не требует перекомпиляции при изменении конфигурации, поэтому можно взять сразу бинарный дистрибутив с готовым билдом fop.jar. А можно взять исходники и собрать FOP самостоятельно.
  • Некоторое количество ваших любимых TrueType шрифтов, поддерживающих кириллицу в Unicode. Если затрудняетесь, зайдите в каталог windows/fonts свежеустановленной Windows - там должно быть около десятка шрифтов, входящей в ее поставку (Arial, Courier New, Times New Roman и т.д.) Для других ОС шрифтовые файлы могут быть перенесены из Windows. Перечень шрифтов, протестированных с FOP можно найти здесь. Копировать шрифтовые файлы из исходного места никуда не нужно, просто запомните пути к тому месту, где они лежат. Также не требуется инсталляция этих шрифтов в системе.
  • Понадобится предустановленная JDK версии 1.2 и выше.

2 Установка и запуск FOP

Установка FOP проста и обычно, не вызывает особых проблем.

Просто распакуйте дистрибутив (файл fop-0.x.x.tar.gz) куда-нибудь по своему усмотрению. Проверьте, включен ли каталог с исполняемыми файлами java-машины в системный PATH (наберите "java -version" в командной строке). На UNIX можно вместо PATH определить переменную окружения JAVA_HOME, содержащую путь к каталогу установки java.

Каталог установки FOP также рекомендуется включить в системный PATH. В этом случае, скрипт запуска FOP (fop.bat или fop.sh) будет доступен из любого текущего каталога системы.

С этой же целью на Windows рекомендуется отредактировать fop.bat, указав абсолютные пути для библиотек вместо относительных. Для fop.sh (UNIX) можно задать переменную окружения FOP_HOME. Править скрипт для удобного запуска FOP можно множеством способов. Я например, использую переменную окружения FOP_HOME и под Windows. Делайте, как вам удобнее.

Теперь можно попробовать запустить FOP для преобразования вашего тестового XSL-FO файла в PDF:

fop -fo foo.fo -pdf foo.pdf
или просто:
fop foo.fo foo.pdf

Для преобразования XML+XSLT в PDF вызовите:

fop -xml foo.xml -xsl foo.xsl -pdf foo.pdf

Полный список всех доступных опций запуска FOP можно увидеть, запустив fop.bat/fop.sh без параметров.


По умолчанию FOP скомпилирован с 14 шрифтами (Times, Helvetica и Courier в разных вариациях начертания, Symbol и ZapfDingbats. К сожалению, эти шрифты не включают кириллицу, поэтому русского текста в PDF не получится. Для этого нужно подключить пользовательские Unicode-шрифты, чем мы с вами, собственно, и занимаемся.

3 Генерация метрик шрифтов

Для того, чтобы подключить пользовательские шрифты, для каждого шрифта необходимо создать файл метрик -- XML-файл с параметрами глифов. Для этого в состав FOP входит утилита TTFReader (org.apache.fop.fonts.apps.TTFReader). Для Type1-шрифтов существует аналогичная утилита PFMReader, но для нас это не актуально.

Для генерации метрик TTF-шрифта вызовите TTFReader:

java -cp build/fop.jar;lib/avalon-framework.jar;lib/xml-apis.jar;
         lib/xercesImpl.jar;lib/xalan.jar 
      org.apache.fop.fonts.apps.TTFReader fontfile.ttf fontmetrics.xml

Пути для библиотек в этом примере заданы относительно каталога установки FOP. Само собой, можно написать скрипт для удобного запуска TTFReader.

4 Регистрация новых шрифтов

После того, как для шрифтов сгенерированы метрики, нужно указать эти шрифты и метрики в конфигурационном файле FOP -- userconfig.xml, находящемся в подкаталоге conf каталога FOP.

Откройте этот файл и найдите в нем секцию /configuration/fonts. В комментарии к этой секции вы должны увидеть примеры XML-элементов font, определяющих параметры каждого шрифта:

<font metrics-file="arial.xml" kerning="yes" embed-file="arial.ttf">
    <font-triplet name="Arial" style="normal" weight="normal"/>
    <font-triplet name="ArialMT" style="normal" weight="normal"/>
 </font>
 <font metrics-file="arialb.xml" kerning="yes" embed-file="arialb.ttf">
    <font-triplet name="Arial" style="normal" weight="bold"/>
    <font-triplet name="ArialMT" style="normal" weight="bold"/>
 </font>
 <font metrics-file="ariali.xml" kerning="yes" embed-file="ariali.ttf">
    <font-triplet name="Arial" style="italic" weight="normal"/>
    <font-triplet name="ArialMT" style="italic" weight="normal"/>
 </font>
 <font metrics-file="arialbi.xml" kerning="yes" embed-file="arialbi.ttf">
    <font-triplet name="Arial" style="italic" weight="bold"/>
    <font-triplet name="ArialMT" style="italic" weight="bold"/>
 </font>

Каждый элемент font содержит один или более элементов font-triplet, с помощью которых определяется множество синонимов-алиасов имени данного шрифта (в данном примере шрифту присваиваются имена-синонимы Arial и ArialMT, ссылающиеся на один и тот же шрифтовый файл). Эти имена будут использоваться для адресации шрифтовой гарнитуры в атрибуте XSL "font-family". Полезно сразу же присвоить стандартные алиасы serif, sans-serif и monospace шрифтам, которые вы хотите использовать как дефолтные "шрифт с засечками", "шрифт без засечек" и "моноширинный". Заметьте, что sans-serif -- это шрифт FOP по умолчанию, то есть тот, который используется при отсутствии атрибута font-family.

Атрибуты style и weight определяют начертание шрифта, то есть значения атрибутов XSL "font-style" и "font-weight", которые вместе адресуют данное начертание. Так, в приведенном примере определяются четыре начертания шрифта Arial - нормальное(style="normal", weight="normal"), полужирное (style="normal", weight="bold"), курсивное (style="italic", weight="normal") и полужирное курсивное (style="italic", weight="bold").

Таким образом, нам необходимо создать для каждого начертания шрифта по одному элементу font, ссылающегося на шрифтовый файл и файл метрик:

<font metrics-file="file:///C:/java/fop-0.20.5/font-metrics/cour.xml"
 kerning="yes" embed-file="C:/WINNT/Fonts/cour.ttf">
    <font-triplet name="Courier" style="normal" weight="normal"/>
    <font-triplet name="Courier New" style="normal" weight="normal"/>
    <font-triplet name="monospace" style="normal" weight="normal"/>
</font>

Обратите внимание, что для файла метрик нужно указывать путь в формате URI (с префиксом протокола "file:"), в то время как путь к шрифтовому файлу указывается в обычном формате ОС.

5 Запуск с пользовательской конфигурацией


После того как шрифты зарегистрированы в userconfig.xml, необходимо добавить параметр "-с PATH_TO_USERCONFIG" в опции запуска FOP (в скриптах fop.bat/fop.sh):

org.apache.fop.apps.Fop -c C:/java/fop-0.20.5/conf/userconfig.xml ...

Это все. Теперь можете попробовать указать имена ваших шрифтов в атрибутах FO "font-family", снова обработать ваш тестовый FO-файл и посмотреть на результат.

6 Запуск встроенного FOP с пользовательской конфигурацией

Выше был рассмотрен случай запуска FOP из командной строки (с помощью класса org.apache.fop.apps.Fop). Но в ряде случаев требуется запуск FOP из другого java-приложения (в частности, сервлета) -- с помощью класса org.apache.fop.apps.Driver. Для того, чтобы FOP нашел и использовал наш конфигурационный файл, нужно инстанцировать класс org.apache.fop.apps.Options с этим файлом до вызова Driver.run(). Все это, в общем случае, выглядит следующим образом:

Driver driver = new Driver(new InputSource(input),
                             new FileOutputStream(output));
driver.setRenderer(Driver.RENDER_PDF);
Options options = new Options(new File("path/to/userconfig.xml"));
driver.run();

Комментарии, замечания и пожелания по поводу данного текста приветствуются.