Apache Velocity DocBook Framework

Wymieniony w tytule Apache Velocity DocBook Framework (AVDF) to sterowany antem zbiór narzędzi do zamiany dokumentów DocBook na HTML/PDF. Konkretnie tymi narzędziami są Fop (w wersji 0.20.5), Saxon i szablony XSL N. Walsha. Po ściągnięciu archiwum .zip lub .tgz ze strony projektu i rozpakowaniu, na dysku pojawi się następująca struktura katalogów:

<korzeń instalacji AVDF>
  |
  +---- build-docbook.xml
  +---- project.properties 
  +-- src
       +-- styles
  
  +-- docs
       +-- build.xml
       +-- project.properties
       +-- src
            +--css
            +--docbook
            |    +--<projekt>
            +-- images 
	    +-- target
  +-- lib

Katalog lib zawiera fopa i saxona plus niezbędne dodatkowe aplikacje. Katalog src/styles zawiera szablony ,,startowe'', uruchamiane przy zamianie plików XML na HTML i PDF. [Tu trzeba dłubnąć żeby dokonać polonizacji.] Wreszcie dokument ,,źródłowy'' ma być obowiązkowo umieszczony w katalogu docs/src/docbook/<projekt>. Pliki z rysunkami zaś muszą być umieszczone w docs/src/images. Wynik transformacji będzie się znajdował w docs/target/<projekt>. Dodatkowo w docs/src/css znajduje się szablon CSS wykorzystywany przez wygenerowane pliki HTML.

Polonizacja wymaga: 1) ściągnięcia następującego archiwum .zip i rozpakowania jego zawartości w tak sposób aby została dodana do oryginalnej dystrybucji AVDF (kilka plików zostanie nadpisanych); 2) wykonania polecenia ant -f build-docbook.xml dbf.init z poziomu korzenia instalacji AVDF. Tyle -- powinno działać. Reszta tego wpisu dotyczy szczegółów: co, jak i dlaczego. Można nie czytać...

Pliki build-docbook.xml zmieniłem tak, że dodałem do wywołania fopa argument -c plik.cnf, tj.:

<java classname="org.apache.fop.apps.Fop" fork="true" maxmemory="256m"
    dir="${basedir}" classpathref="dbf.classpath">
   <arg value="${pdf.target.file}.xml"/>
   <arg value="${target.dir}/${docbook.dir}/pdf/${docbook.file}.pdf"/>
<arg value="-c"/>
   <arg value="${dbf.basedir}/conf/userconfig.xml"/>
</java>

Parametr ${dbf.basedir} to katalog główny, w którym znajduje się cały framework. Dodany katalog conf/ zawiera plik konfiguracyjny fopa + pliki metryczne fontów. Same fonty (pliki .ttf) są w katalogu fonts/. Dodanie do AVDC fontów powoduje, że całość jest gotowa do użycia w każdym systemie. [Można oczywiście tak skonfigurować AVDF żeby używał fontów systemowych]. Z kilku zestawów rozpowszechnianych bezpłatnie fontów truetype (Core fonts for the Web (Nie najwyższej jakości i do tego ich rozpowszechnianie podlega pewnym ograniczeniom), TeX Gyre, Quasi, STIX (tylko jedna odmiana -- brak kroju bezszeryfowego i kroju typu monospace), DejaVue) zdecydowałem się na fonty Quasi. Wprawdzie są one już obsolete ale działają z fopem a fonty TeX Gyre, które są lepszą wersją Quasi -- nie bardzo. [Są problemy nawet po konwersji OTF->TTF.]

Położenie fontów w systemie jest określone w pliku conf/userconfig.conf. Ponieważ ścieżka do fontu nie może być zaszyta na zicher, plik conf/userconfig.conf rozpoczyna się od następującej deklaracji DOCTYPE:

<!DOCTYPE configuration SYSTEM "config.dtd" [
<!ENTITY fop.home  "@dbf.basedir@">
<!ENTITY ttf.dir   "@dbf.basedir@/fonts">

Napisy @dbf.basedir@ są zamieniane na to co trzeba po uruchomieniu ant -f build-docbook.xml dbf.init (trzeba to zrobić dokładnie raz). Cel (target) dbf.init wygląda zaś następująco:

 <target name='dbf.init' description='Adjust some system specific files'>

  <copy file="${basedir}/conf/userconfig.conf" tofile='${basedir}/conf/userconfig.xml'
     overwrite="true" failonerror="false" filtering="on" >
    <filterset>
      <filter token="dbf.basedir" value="${basedir}"/>
    </filterset>
  </copy>
  </target>

Jak widać plik conf/userconfig.conf jest kopiowany do conf/userconfig.xml a dodatkowo napisy @dbf.basedir@ są zamieniane na bieżącą wartość ${basedir}. To się nazywa token substitution (cf. Using Ant as a Text Substitution Preprocessor).

Ostatni etap polonizacji AVDF to poprawienie plików html.xsl, htmlsingle.xsl z katalogu src/styles. Dodałem do plików html.xsl oraz htmlsingle.xsl:

<xsl:output method="html" 
     encoding="utf-8"
     indent="no"
     saxon:character-representation="native;decimal" 
     xmlns:saxon="http://icl.com/saxon" />

<!-- zapisuje znaki `natywnie' a nie jako encje (domyślnie) -->
<xsl:param name="chunker.output.encoding" select="'utf-8'"/>
<xsl:param name="saxon.character.representation" select="'native;decimal'"/>

A do pliku pdf.xsl (z tego samego katalogu):

<!-- przełącza się na fonty Quasi, domyślnym fontem szeryfowym jest
 QuasiPalatinoTTF, zmień na QuasiTimesTTF jeżeli ma być Times New Roman -->
<xsl:param name="sans.font.family" select="'QuasiSwissTTF'"/>
<xsl:param name="title.font.family" select="'QuasiSwissTTF'"/>
<xsl:param name="body.font.family" select="'QuasiPalatinoTTF'"/>
<xsl:param name="monospace.font.family" select="'QuasiCourierTTF'"/>

Powyższe to minimum: polskie znaki są prawidłowo wyświetlane na ekranie oraz -- co ważne -- zapisywane w pliku jako sekwencje UTF a nie w postaci encji (tj. ó). Jeżeli układ graficzny dokumenty komuś nie odpowiada, no to musi jeszcze bardziej zmodyfikować pliki .xsl i/lub CSS (oczywiście szablony CSS dotyczą wyłącznie dokumentów HTML).