28 lutego 2008

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.