Tworzenie dokumentacji z DocBook i Maven - wtyczka Docbkx Maven Plugin

Już nie pierwszy raz zastanawiałem się w czym tworzyć dokumentację. Jakkolwiek TeX jest dobry i korzystając z niego można tworzyć profesjonalną dokumentację, to jednak znacznie prostszy i przez to z pewnością popularniejszy wydaje się DocBook. Nie znam DocBooka, ale gdziekolwiek nie spojrzę na darmową dokumentację formatu innego niż Confluence Wiki, czy generowaną przez to narzędzie, wygląd książek tworzonych z pomocą DocBook przykuł nie raz moją uwagę. I nie raz obiecywałem sobie rozpoznać w jaki sposób możnaby tworzyć dokumenty PDF i HTML z jego pomocą.

Dzisiaj podczas uaktualniania źródeł wtyczki Geronimo Eclipse Plugin zobaczyłem, wiele z nierozpoznanych przez svn plików. Powiedzmy, że było ich około 30-40 plików wszystkie oznaczone jako nieznane - uruchomienie svn status pokazuje je z ?. Postanowiłem je usunąć. Cygwin i shell są w takiej sytuacji nieocenione. Skończyło się ostatecznie na poleceniu:

  svn status | cut -d ' ' -f7 | xargs rm -rf

Wszystkie nieznane svn pliki wycięte. Zanim jednak je skonstruowałem potrzebowałem poznać format wyniku svn status. Rzut oka na książkę Version Control with Subversion i miałem odpowiedź. Coś mnie tknęło, aby zajrzeć do źródeł książki, a tam DocBook (!) A co mi tam - pomyślałem - zobaczę jak się tworzy dokumentację PDF z pomocą DocBooka. Nie miałem zamiaru tracić czasu, więc od razu zacząłem poszukiwania wtyczki DocBook dla Maven. Znalazłem docbook-maven-plugin, czyli coś czego w ogóle nie powinienem dotykać. Szkoda czasu. Nawet nie zamierzam wskazywać na jej stronę domową. Stworzyłem projekt mavenowy, a w nim zgodnie z wymaganiami wtyczki katalog src/docbook i umieściłem w nim dwa pliki - ksiazka.xml (zgodnie z dokumentacją Creating DocBook Documents i źródłami książki o Subversion):

 <?xml version='1.0'?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
                "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
 [
 <!ENTITY ch1 SYSTEM "ch1.xml">
 ]>
 
 <book id="ksiazka">
   <title>Moja pierwsza ksiazka w DocBook</title>
 
   <bookinfo>
 
     <subtitle>Podtytul</subtitle>
 
     <edition>First</edition>
     <isbn>?-?????-???-?</isbn>
     <authorgroup>
 
       <author>
         <firstname>Jacek</firstname>
         <surname>Laskowski</surname>
       </author>
 
     </authorgroup>
 
     <pagenums>350 pages (est.)</pagenums>
     <pubdate>(TBA)</pubdate>
 
     <copyright>
       <year>2008</year>
       <holder>Jacek Laskowski</holder>
     </copyright>
 
     <legalnotice><para>Legalnotice</para></legalnotice>
 
   </bookinfo>
 
   &ch1;
 
 </book>

oraz ch1.xml:

 <chapter id="ksiazka.rozdzial1">
   <title>Wprowadzenie</title>
 
   <para>Teraz dopiero sobie popiszemy</para>
 
   <sect1 id="ksiazka.rozdzial1.pomocy">
     <title>Gdzie szukac pomocy?</title>
 
     <para>Chcialbym pomoc, ale sam wiesz - zarobiony jestem!</para>
 
     <screen>
 jlaskowski@dev ~
 $ uname -a
 CYGWIN_NT-5.1 dev 1.5.25(0.156/4/2) 2007-12-14 19:21 i686 Cygwin
 </screen>
   </sect1>
 </chapter>

Uruchomienie wtyczki bez modyfikacji pom.xml projektu to trochę sztuczek mavenowych.

 jlaskowski@dev /cygdrive/c/projs/sandbox/docbook-ksiazka
 $ mvn org.apache.maven.plugins:maven-help-plugin:2.0.2:describe -Dmedium=true \
        -Dplugin=org.codehaus.mojo:docbook-maven-plugin:1.0.0-alpha-1
 [INFO] Scanning for projects...
 [INFO] ----------------------------------------------------------------------------
 [INFO] Building docbook-ksiazka Maven Webapp
 [INFO]    task-segment: [org.apache.maven.plugins:maven-help-plugin:2.0.2:describe]
 (aggregator-style)
 [INFO] ----------------------------------------------------------------------------
 [INFO] [help:describe]
 [INFO] Plugin: 'org.codehaus.mojo:docbook-maven-plugin:1.0.0-alpha-1'
 -----------------------------------------------
 Group Id:  org.codehaus.mojo
 Artifact Id: docbook-maven-plugin
 Version:     1.0.0-alpha-1
 Goal Prefix: docbook
 Description:
 
 This plugin adds support for Docbook transformations to Maven.
 
 Mojos:
 
 Goal: 'transform'
 Description:
 Transforms a set of Docbook files into XHTML output. Currently there is only support for
 XHTML output, though is planned to add all kind of outputs available in the standard
 stylesheets.
 
 [INFO] ------------------------------------------------------------------------
 [INFO] BUILD SUCCESSFUL
 [INFO] ------------------------------------------------------------------------
 [INFO] Total time: < 1 second
 [INFO] Finished at: Wed Feb 27 21:22:27 PST 2008
 [INFO] Final Memory: 3M/254M
 [INFO] ------------------------------------------------------------------------

Długie nazwy przy wtyczkach to po prostu sposób na ich uruchomienie bez konieczności ich instalacji w lokalnym repozytorium czy wspomnianej modyfikacji pliku projektu pom.xml.

Okazuje się, że ja albo wtyczka nie mogliśmy poradzić sobie z najprostszym przykładem, który wykańczał wtyczkę docbook-maven-plugin z komunikatem FNFE:

 jlaskowski@dev /cygdrive/c/projs/sandbox/docbook-ksiazka
 $ mvn clean docbook:transform
 [INFO] Scanning for projects...
 [INFO] Searching repository for plugin with prefix: 'docbook'.
 [INFO] ----------------------------------------------------------------------------
 [INFO] Building docbook-ksiazka Maven Webapp
 [INFO]    task-segment: [clean, docbook:transform]
 [INFO] ----------------------------------------------------------------------------
 [INFO] [clean:clean]
 [INFO] Deleting directory c:\projs\sandbox\docbook-ksiazka\target
 [INFO] [docbook:transform]
 [INFO] Loading olink database generation stylesheet
 [INFO] Creating olink database for 2 Docbook stale file(s)
 ...
 [INFO] Creating master olink database file
 [INFO] Transforming 2 Docbook stale file(s)
 [INFO] ------------------------------------------------------------------------
 [ERROR] BUILD FAILURE
 [INFO] ------------------------------------------------------------------------
 [INFO] java.io.FileNotFoundException:  
c:\projs\sandbox\docbook-ksiazka\target\site\docbook\ch1.html 
(The system cannot find the path specified)
 [INFO] ------------------------------------------------------------------------
 [INFO] For more information, run Maven with the -e switch
 [INFO] ------------------------------------------------------------------------
 [INFO] Total time: 2 minutes 47 seconds
 [INFO] Finished at: Wed Feb 27 22:08:29 PST 2008
 [INFO] Final Memory: 35M/254M
 [INFO] ------------------------------------------------------------------------

Z jakiś nieznanych mi powodów podczas uruchomienia w trybie śledzenia (opcja -X polecenia mvn) wtyczka nie znajdowała pliku ch1.xml. Już wiedziałem, że za długo się z nią zmagam.

Nie było łatwo znaleźć wtyczki DocBook do Mavena i już nawet zdecydowałem się na uruchomienie zadania Ant z poziomu Maven, gdy przypadkiem natrafiłem na wpis Docbkx Maven Plugin 2.0.8 released. Świeża wersja sprzed kilku dni i jej wysoki numer dawały nadzieję, że nie wszystko stracone.

 jlaskowski@dev /cygdrive/c/projs/sandbox/docbook-ksiazka
 $ mvn org.apache.maven.plugins:maven-help-plugin:2.0.2:describe -Dmedium=true \
    -Dplugin=com.agilejava.docbkx:docbkx-maven-plugin:2.0.8
 [INFO] Scanning for projects...
 [INFO] ----------------------------------------------------------------------------
 [INFO] Building docbook-ksiazka Maven Webapp
 [INFO]    task-segment: [org.apache.maven.plugins:maven-help-plugin:2.0.2:describe] 
 (aggregator-style)
 [INFO] ----------------------------------------------------------------------------
 [INFO] [help:describe]
 ...
 [INFO] Plugin: 'com.agilejava.docbkx:docbkx-maven-plugin:2.0.8'
 -----------------------------------------------
 Group Id:  com.agilejava.docbkx
 Artifact Id: docbkx-maven-plugin
 Version:     2.0.8
 Goal Prefix: docbkx
 Description:
 
 A Maven plugin for generating HTML from DocBook.
 
 Mojos:
 
 Goal: 'generate-pdf'
 Description:
 A Maven plugin for generating fo output from DocBook documents, using version
 1.73.2 of the DocBook XSL stylesheets.
 
 Goal: 'generate-eclipse'
 Description:
 A Maven plugin for generating eclipse output from DocBook documents, using version
 1.73.2 of the DocBook XSL stylesheets.
 
 Goal: 'generate-manpages'
 Description:
 A Maven plugin for generating manpages output from DocBook documents, using version
 1.73.2 of the DocBook XSL stylesheets.
 
 Goal: 'generate-html'
 Description:
 A Maven plugin for generating html output from DocBook documents, using version
 1.73.2 of the DocBook XSL stylesheets.
 
 [INFO] ------------------------------------------------------------------------
 [INFO] BUILD SUCCESSFUL
 [INFO] ------------------------------------------------------------------------

Zapowiadało się wspaniale!

 jlaskowski@dev /cygdrive/c/projs/sandbox/docbook-ksiazka
 $ mvn clean docbkx:generate-pdf
 [INFO] Scanning for projects...
 [INFO] Searching repository for plugin with prefix: 'docbkx'.
 [INFO] artifact org.apache.maven.plugins:maven-docbkx-plugin: 
 checking for updates from central
 [INFO] ------------------------------------------------------------------------
 [ERROR] BUILD ERROR
 [INFO] ------------------------------------------------------------------------
 [INFO] The plugin 'org.apache.maven.plugins:maven-docbkx-plugin' 
 does not exist or no valid version could be found
 [INFO] ------------------------------------------------------------------------
 [INFO] For more information, run Maven with the -e switch
 [INFO] ------------------------------------------------------------------------
 [INFO] Total time: < 1 second
 [INFO] Finished at: Wed Feb 27 22:14:48 PST 2008
 [INFO] Final Memory: 1M/254M
 [INFO] ------------------------------------------------------------------------

No tak! Przecież nie mam jej w repozytorium lokalnym, więc wywołuję ją w formacie rozszerzonym.

 jlaskowski@dev /cygdrive/c/projs/sandbox/docbook-ksiazka
 $ mvn clean com.agilejava.docbkx:docbkx-maven-plugin:2.0.8:generate-pdf
 [INFO] Scanning for projects...
 [INFO] ----------------------------------------------------------------------------
 [INFO] Building docbook-ksiazka Maven Webapp
 [INFO]    task-segment: [clean, com.agilejava.docbkx:docbkx-maven-plugin:2.0.8:generate-pdf]
 [INFO] ----------------------------------------------------------------------------
 [INFO] [clean:clean]
 [INFO] Deleting directory c:\projs\sandbox\docbook-ksiazka\target
 ...
 [INFO] [docbkx:generate-pdf]
 [INFO] ------------------------------------------------------------------------
 [INFO] BUILD SUCCESSFUL
 [INFO] ------------------------------------------------------------------------

Jeju! Działa i to za pierwszym strzałem. Pora sprawdzić dokumentację. Żadnego katalogu target? Pora zajrzeć do dokumentacji, bo widzę, że bez niej ani rusz. Kilka chwil na User Guide i już wiadomo, że katalog z moją książką powinien być src/docbkx. Przenoszę pliki i ponownie wykonuję wtyczkę docbkx-maven-plugin.

 jlaskowski@dev /cygdrive/c/projs/sandbox/docbook-ksiazka
 $ mvn clean com.agilejava.docbkx:docbkx-maven-plugin:2.0.8:generate-pdf
 [INFO] Scanning for projects...
 [INFO] ----------------------------------------------------------------------------
 [INFO] Building docbook-ksiazka Maven Webapp
 [INFO]    task-segment: [clean, com.agilejava.docbkx:docbkx-maven-plugin:2.0.8:generate-pdf]
 [INFO] ----------------------------------------------------------------------------
 [INFO] [clean:clean]
 [INFO] Deleting directory c:\projs\sandbox\docbook-ksiazka\target
 [INFO] [docbkx:generate-pdf]
 [WARNING] Failed to find catalog files.
 [INFO] Processing ksiazka.xml
 Feb 27, 2008 10:22:30 PM org.apache.fop.hyphenation.Hyphenator getHyphenationTree
 SEVERE: Couldn't find hyphenation pattern en
 [INFO] Processing ch1.xml
 [INFO] ------------------------------------------------------------------------
 [INFO] BUILD SUCCESSFUL
 [INFO] ------------------------------------------------------------------------
 [INFO] Total time: 27 seconds
 [INFO] Finished at: Wed Feb 27 22:22:31 PST 2008
 [INFO] Final Memory: 21M/254M
 [INFO] ------------------------------------------------------------------------

Jest! BUILD SUCCESSFUL i widać, że coś tam wtyczka przetwarzała.

 jlaskowski@dev /cygdrive/c/projs/sandbox/docbook-ksiazka
 $ ls -l target/docbkx/pdf
 total 120
 -rwx------+ 1 jlaskowski None 40792 Feb 27 22:22 ch1.fo
 -rwx------+ 1 jlaskowski None  6567 Feb 27 22:22 ch1.pdf
 -rwx------+ 1 jlaskowski None 58902 Feb 27 22:22 ksiazka.fo
 -rwx------+ 1 jlaskowski None  9745 Feb 27 22:22 ksiazka.pdf

Jest i książka w formacie PDF! Tego mi było trzeba. Wystarczy teraz zgłębić tajniki DocBook i można publikować PDFy.