2009年11月8日日曜日

JBossのテンプレートでDocBook - (1/8) -

はじめに

DocBookスタイルシートと使うと同じドキュメントソースからPDF,HTMLなど
いろいろな形式のドキュメントファイルが作れてなかなか便利なのだけれども
そこそこ見栄えの良いものにしょうとすると結構大変なのです。
cssファイルであったり、イメージファイルを自前で用意しなくてはいけないから…
そこでJBossのドキュメント作成に使われ入るテンプレートなどを拝借して
見栄えの良いドキュメントを作ろう！というのが今回のテーマです。

投稿者 fummy 時刻: 20:06
ラベル: ,

JBossのテンプレートでDocBook - (2/8) -

準備する

ライブラリーとスタイルシートをダウンロードします。

DocBookテンプレートはJBossのMavenリピジトリからダウンロードします。

DocBookスタイルシート docbook-xsl-1.75.2.zip
DocBookテンプレート jbossorg-docbook-xslt-1.1.0.jar
jbossorg-jdocbook-style-1.1.0.jdocbook-style
フォント jbossorg-fonts-1.0.0.jdocbook-style
(さざなみフォント)
XSLTプロセッサ saxon6-5-5.zip
ライブラリー Xerces-J-bin.2.9.1.zip
fop-0.95-bin.zip
highlight-1.0.0.jar
jhighlight-1.0.jar
ビルドツール Ant 1.7
※antコマンドが実行できるように設定しておいてください。
XalanとSaxon
JBoosのDocBookテンプレートを使ってDocBookを作成する場合、 XSLTプロセッサはSaxonを選択する方が無難かも？
highlightライブラリーを使って拡張変換処理をしているみたいで、この処理の実行時にXalanではエラーになってしまう。
xslファイルのネームスペースを利用して拡張変換処理クラスの処理を有効にするのだけれど
ネームスペースの指定方法がSaxonとXalanでは違っていてXalanので設定の仕方がよく分からなかった。
適当な場所に作業フォルダー(C:\mybook)を作り、ダウンロードしたファイルを配置します。
  • C:\mybook
    • doc
      • inc
        • HelloWorld.java
      • book.xml
      • chapter.xml
    • html
    • lib
      • fop-0.95
        • fop.bat
      • saxon6-5-5
        • saxon-jdom.jar
        • saxon-xml-apis.jar
        • saxon.jar
      • xerces-2_9_1
        • xercesImpl.jar
      • highlight-1.0.0.jar
      • jhighlight-1.0.jar
    • pdf
    • resources
      • docbook-xsl-1.75.2
        • fo
        • xhtml
      • j-docbook-fonts
        • fonts
      • j-docbook-style
        • images
          • images
            • community
            • my-image.png
      • j-docbook-xslt
        • xslt
    • build.xml
    • fop.xconf
jbossorg-fonts-1.0.0.jdocbook-style は拡張子を *.zip に変更して解凍します。
フォルダ名をj-docbook-fontsに変更して配置します。
jbossorg-jdocbook-style-1.1.0.jdocbook-style は拡張子を *.zip に変更して解凍します。
フォルダ名をj-docbook-styleに変更して配置します。
jbossorg-docbook-xslt-1.1.0.jar は拡張子を *.zip に変更して解凍します。
フォルダ名をj-docbook-xsltに変更して配置します。
fop.xconfはlib/fop/conf フォルダにあるファイルをコピーします。
docフォルダにソースドキュメントを作成します。
resources/j-docbook-style/images/imagesフォルダに ドキュメント作成に使うイメージファイルを配置します。
ビルド後、htmlフォルダにhtmlファイルが出力されます。
ビルド後、pdfフォルダにpdfファイルが出力されます。

投稿者 fummy 時刻: 19:09
ラベル: ,

JBossのテンプレートでDocBook - (3/8) -

ソースドキュメントを作成する

book.xml, chapter.xml, HelloWorld.java をファイルを作成します。

ファイルの文字コードはUTF-8(BOMなし)にします。

book.xml
<?xml version="1.0" encoding="UTF-8"?>
<book
  xmlns="http://docbook.org/ns/docbook"
  xmlns:xi="http://www.w3.org/2001/XInclude"
  xml:id="mybook">
  <title>Myブック</title>
  <chapter xml:id="mybook.chapter-1">
    <title>メインのファイル</title>
    <section>
      <title>テーブルを表示</title>
      <table>
        <title>成果物とPackaging</title>
        <tgroup cols="4">
          <colspec colnum="1" colwidth="100" />
          <colspec colnum="2" colwidth="200" />
          <colspec colnum="3" colwidth="50" colname="jar" 
            align="center"/>
          <colspec colnum="4" colwidth="50" colname="war" 
            align="center"/>
          <thead valign="top">
            <row>
              <entry morerows='1'>Phase</entry>
              <entry morerows='1'>Plugin:Goal</entry>
              <entry namest="jar" nameend="war">
                packaging
              </entry>
            </row>
            <row>
              <entry>jar</entry>
              <entry>war</entry>
            </row>
          </thead>
          <tbody valign="top">
            <row>
              <entry>compile</entry>
              <entry>compiler:compile</entry>
              <entry>○</entry>
              <entry>○</entry>
            </row>
            <row>
              <entry morerows='1'>package</entry>
              <entry>jar:jar</entry>
              <entry>○</entry>
              <entry>―</entry>
            </row>
            <row>
              <entry>war:war</entry>
              <entry>―</entry>
              <entry>○</entry>
            </row>
          </tbody>
        </tgroup>
      </table>
    </section>
  </chapter>
  <xi:include href="chapter.xml" parse="xml"/>
</book>

chapter.xml
<?xml version="1.0" encoding="UTF-8"?>
<chapter
  xmlns="http://docbook.org/ns/docbook"
  xmlns:xi="http://www.w3.org/2001/XInclude"
  xml:id="mybook.chapter-2">
  <title>インポートされたファイル</title>
  <section>
    <title>DocBookで遊ぼう</title>
    <caution>
      <title>注意書！</title>
      <para>ペンキ塗りたて</para>
    </caution>
    <example>
      <title>HelloWorld.java</title>
      <programlisting role="java"><xi:include 
        href="inc/HelloWorld.java" parse="text" 
        encoding="UTF-8" /></programlisting>
        <screenco>
          <areaspec />
            <screen>javac HelloWorld.java<co 
              xml:id="mybook.chapter-2.javac"/></screen>
            <calloutlist>
              <callout arearefs="mybook.chapter-2.javac">
                <para>コンパイルをします。</para>
              </callout>
            </calloutlist>
        </screenco>
    </example>
    <figure>
      <title>my-image.png表示</title>
      <imageobject>
        <imagedata format="PNG" 
          fileref="images/my-image.png" />
      </imageobject>
    </figure>
  </section>
</chapter>

HelloWorld.java
public class HelloWorld
{
  public static void main(String[] args)
  {
    System.out.println("HelloWorld");
  }
}
textdataタグについて
DocBookのtextdataタグを使っても外部ファイルを取込むことができるが
相対パスでファイルを指定した場合Saxonではうまく読込めない。
(相対パスから絶対パスの組立てでファイルパスがずれてしまう)
Xalanでは問題なく処理できる。
外部ファイルの取込みは<xi:include>タグを使う方が無難なようだ。
またインクルードするファイルは文字コードをUTF-8(BOMなし)で改行コードをLFとしておく方がよい。

投稿者 fummy 時刻: 19:00
ラベル: ,

JBossのテンプレートでDocBook - (4/8) -

DocBook HTMLテンプレートを編集する

ページヘッダーに表示されるイメージとリンクを変更します。

『resources/j-docbook-xslt/xslt/org/jboss』フォルダーにある『xhtml.xsl』ファイルと『xhtml-common.xsl』ファイルを編集します。

xhtml.xsl
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
  ...
  <!--<xsl:import href="http://docbook.sourceforge.net/release/xsl/1.72.0/xhtml/chunk.xsl"/>-->
  <xsl:import href="file:///C:/mybook/resources/docbook-xsl-1.75.2/xhtml/chunk.xsl"/>
  ...
DocBookスタイルシートのパスをローカルファイルに変更します。

xhtml-common.xsl
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" ...
  ...
  <!--<xsl:param name="siteHref" select="'http://www.jboss.org'"/>-->
  <!--<xsl:param name="docHref" select="'http://docs.jboss.org/'"/>-->
  <!--<xsl:param name="siteLinkText" select="'JBoss.org'"/>-->
  <!--<xsl:param name="docLinkText" select="'Community Documentation'"/>-->
  <xsl:param name="siteHref" select="'#'"/>
  <xsl:param name="docHref" select="'#'"/>
  <xsl:param name="siteLinkText" select="'MyHost'"/>
  <xsl:param name="docLinkText" select="'MyHost Documentation'"/>
  ...
  <!-- Set chunk.section.depth to 0 to just chunk chapters. -->
  <!--<xsl:param name="chunk.section.depth" select="0"/>-->
  <xsl:param name="chunk.section.depth" select="5"/>
  ...
ヘッダーリンクを変更します。
パラメータを変更してセクションごとにファイルを分割します。（５階層まで）



『resources/j-docbook-style/css/css』フォルダーにある 『documentation.css』ファイルを編集します。

documentation.css
...
#title a.site_href {
  display:block;
  height:89px;
  width:310px;
  float:left;
  /* background:url(../images/community/jbossorglogo.png) top left no-repeat; */
}

#title a.doc_href {
  display:block;
  height:89px;
  /* background:transparent url(../images/community/community_doc.png) top right no-repeat; */
}
...
ヘッダーイメージを削除します。または、差し替える場合はファイルパスを変更します。

投稿者 fummy 時刻: 18:51
ラベル: ,

JBossのテンプレートでDocBook - (5/8) -

DocBook PDFテンプレートを編集する

日本語フォントとイメージファイルの設定します。

『resources/j-docbook-xsl/xslt/org/jboss』フォルダーにある『common.xsl』ファイルと『pdf.xsl』ファイルを編集します。

common.xsl
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
  ...
  <!-- <xsl:param name="l10n.gentext.default.language" select="'en'"/> -->
  <xsl:param name="l10n.gentext.default.language" select="'ja'"/>
  <xsl:param name="l10n.gentext.language" select="'ja-JP'"/>
  ...
言語設定を日本語に変更します。

pdf.xsl
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" ...
  ...
  <!--<xsl:import href="http://docbook.sourceforge.net/release/xsl/1.72.0/fo/docbook.xsl"/>-->
  <xsl:import href="file:///C:/mybook/resources/docbook-xsl-1.75.2/fo/docbook.xsl"/>
  ...
  <!--<xsl:param name="fop.extensions" select="1"/>-->
  <!--<xsl:param name="fop1.extensions" select="0"/>-->
  <!--<xsl:param name="img.src.path"/>-->
  <xsl:param name="fop.extensions" select="0"/>
  <xsl:param name="fop1.extensions" select="1"/>
  <xsl:param
    name="img.src.path">file:///C:/mybook/resources/j-docbook-style/images/</xsl:param>
  <xsl:param name="keep.relative.image.uris" select="1"/>
  <xsl:param name="ignore.image.scaling" select="1"/>
  ...
  <xsl:template name="pickfont-sans">
    <xsl:variable name="font">
      <xsl:choose>
        <xsl:when test="$l10n.gentext.language = 'ja-JP'">
          <!--<xsl:text>KochiMincho,</xsl:text>-->
          <xsl:text>Sazanami-Gothic-Regular,</xsl:text>
          ...
  <xsl:template name="pickfont-serif">
    <xsl:variable name="font">
      <xsl:choose>
        <xsl:when test="$l10n.gentext.language = 'ja-JP'">
          <!--<xsl:text>KochiMincho,</xsl:text>-->
          <xsl:text>Sazanami-Gothic-Regular,</xsl:text>
          ...
  <xsl:template name="pickfont-mono">
    <xsl:variable name="font">
      <xsl:choose>
        <xsl:when test="$l10n.gentext.language = 'ja-JP'">
          <!--<xsl:text>KochiMincho,</xsl:text>-->
          <xsl:text>Sazanami-Gothic-Regular,</xsl:text>
          ...
DocBookスタイルシートのパスをローカルファイルに変更します。
prefix(file://)を付けて絶対パスで指定します。
fop.extensions,fop1.extensions,ignore.image.scalingのパラメータを変更、追加します。
イメージファイルを配置したフォルダのパスを設定します。
prefix(file://)を付けて絶対パスで指定します。
改行を入れずに一行で記述します。改行を入れるとエラーになります。
日本語フォントをKochiMinchoからSazanami-Gothic-Regularに変更します。

投稿者 fummy 時刻: 18:25
ラベル: ,

JBossのテンプレートでDocBook - (6/8) -

フォント設定ファイルを編集する

『fop.xconf』ファイルを編集します。

fop.xconf
<?xml version="1.0"?>
<fop version="1.0">
  ...
  <renderers>
    <renderer mime="application/pdf">
      ...
      <fonts>
        ...
        <directory recursive="true">
          file:///C:/mybook/resources/j-docbook-fonts/fonts
        </directory>
        <auto-detect />
        ...
フォントファイルを配置したフォルダのパスを設定します。
prefix(file://)を付けて絶対パスで指定します。

投稿者 fummy 時刻: 17:20
ラベル: ,

JBossのテンプレートでDocBook - (7/8) -

ビルドする

『build.xml』ファイルを作成します。

build.xml
<?xml version="1.0" encoding="UTF-8"?>
<project name="docbook" default="build-pdf">
  <property name="root.dir" location="."/>
  <property name="doc.dir" location="${root.dir}/doc"/>
  <property name="html.dir" location="${root.dir}/html"/>
  <property name="pdf.dir" location="${root.dir}/pdf"/>
  <property name="lib.dir" location="${root.dir}/lib"/>
  <property name="res.dir" location="${root.dir}/resources"/>
  <property name="style.dir" 
    location="${res.dir}/j-docbook-style"/>
  <property name="document" value="document"/>
  <property name="book.xml" location="${doc.dir}/book.xml"/>
  <property name="fop.xconf" location="${root.dir}/fop.xconf"/>
  <property 
    name="docbook.dir" 
    location="${res.dir}/docbook-xsl-1.75.2"/>
  <property 
    name="xhtml.stylesheet" 
    location="${res.dir}/j-docbook-xslt/xslt/org/jboss/xhtml.xsl"/>
  <property 
    name="pdf.stylesheet" 
    location="${res.dir}/j-docbook-xslt/xslt/org/jboss/pdf.xsl"/>
  <property 
    name="conf.key" 
    value="-Dorg.apache.xerces.xni.parser.XMLParserConfiguration"/>
  <property 
    name="conf.val" 
    value="org.apache.xerces.parsers.XIncludeParserConfiguration"/>
  <property 
    name="xinclude.parser.conf" 
    value="${conf.key}=${conf.val}"/>
  <property 
    name="builder.key" 
    value="-Djavax.xml.parsers.DocumentBuilderFactor"/>
  <property 
    name="builder.val" 
    value="org.apache.xerces.jaxp.DocumentBuilderFactoryImpl"/>
  <property 
    name="document.builder.factory" 
    value="${builder.key}=${builder.val}"/>
  <property 
    name="parser.key" 
    value="-Djavax.xml.parsers.SAXParserFactory"/>
  <property 
    name="parser.val" 
    value="org.apache.xerces.jaxp.SAXParserFactoryImpl"/>
  <property 
    name="sax.parser.factory" 
    value="${parser.key}=${parser.val}"/>
  <property 
    name="xerces.dir" 
    location="${lib.dir}/xerces-2_9_1"/>
  <property 
    name="saxon.dir" 
    location="${lib.dir}/saxon6-5-5"/>
  <property name="fop.dir" location="${lib.dir}/fop-0.95"/>
  <taskdef name="fop" 
    classname="org.apache.fop.tools.anttasks.Fop">
  <classpath>
    <fileset dir="${fop.dir}/lib">
      <include name="*.jar" />
    </fileset>
    <fileset dir="${fop.dir}/build">
      <include name="fop.jar" />
      <include name="fop-hyph.jar" />
    </fileset>
  </classpath>
  </taskdef>
  <path id="saxon.classpath">
    <fileset dir="${saxon.dir}" id="saxon.fileset">
      <include name="saxon.jar" />
      <include name="saxon-jdom.jar" />
      <include name="saxon-xml-apis.jar" />
    </fileset>
    <fileset dir="${docbook.dir}/extensions" 
      id="saxon.fileset.ext">
      <include name="saxon65.jar" />
    </fileset>
    <fileset dir="${xerces.dir}" id="xerces.fileset">
      <include name="xercesImpl.jar" />
    </fileset>
    <fileset dir="${lib.dir}" id="jboss.fileset">
      <include name="highlight-1.0.0.jar" />
      <include name="jhighlight-1.0.jar" />
    </fileset>
  </path>
  <target name="build-html">
    <delete dir="${html.dir}" />
    <mkdir dir="${html.dir}" />
    <java classname="com.icl.saxon.StyleSheet" 
      classpathref="saxon.classpath" fork="true">
      <jvmarg value="${xinclude.parser.conf}" />
      <jvmarg value="${document.builder.factory}" />
      <jvmarg value="${sax.parser.factory}" />
      <arg line=
        "-o ${html.dir}/${document}.html ${book.xml} ${xhtml.stylesheet} base.dir=${html.dir}/"/>
    </java>
    <copy todir="${html.dir}">
      <fileset dir="${style.dir}/css">
        <include name="css/*" />
      </fileset>
      <fileset dir="${style.dir}/images/">
        <include name="images/**/*" />
      </fileset>
    </copy>
  </target>
  <target name="build-pdf">
    <delete dir="${pdf.dir}" />
    <mkdir dir="${pdf.dir}" />
    <java classname="com.icl.saxon.StyleSheet" 
      classpathref="saxon.classpath" fork="true">
      <jvmarg value="${xinclude.parser.conf}" />
      <jvmarg value="${document.builder.factory}" />
      <jvmarg value="${sax.parser.factory}" />
      <arg line="-o ${pdf.dir}/${document}.fo ${book.xml} ${pdf.stylesheet}"/>
    </java>
    <fop format="application/pdf" outdir="${pdf.dir}" 
      userconfig="${fop.xconf}" messagelevel="debug">
      <fileset dir="${pdf.dir}">
        <include name="*.fo" />
      </fileset>
    </fop>
  </target>
</project>

コマンドフロンプトを開き作業フォルダーに移動します。
cd C:\mybook

ANTを実行してHTMLファイルを作成します。
ant build-html
ビルド後、htmlフォルダにhtmlファイルが出力されます。

ANTを実行してPDFファイルを作成します。
ant build-pdf
ビルド後、pdfフォルダにpdfファイルが出力されます。


投稿者 fummy 時刻: 12:05
ラベル: ,

JBossのテンプレートでDocBook - (8/8) -

おわりに

Webベースでドキュメントを作ろうと思ったときの選択肢としてはWiki、CMSなんかもあります。(もちろんBlogもありますし直接HTMLで作るのも当然ありです。)
ドキュメントの管理を考えるとDocBookがいいのかなと思っています。
ただ手軽さには難があるかなというのが正直なところです。
あとドキュメントの内容に比べてファイルが長くなるかなとも…
それで管理と手軽さでいくと結局、Wikiが無難なのかも？

今回はANTを使ってビルドしましたがMavenとmaven-jdocbook-pluginを使う方法もあります。(こちらの方法が正攻法だと思います。)
今回の方法はmaven-jdocbook-pluginの処理をantで書き直したような感じになると思います。
またの機会にmaven-jdocbook-pluginについてもまとめてみたいと思います。
参考
http://www.exacteye.com/docbook.html
http://www.docbook.org/tdg5/en/html/docbook.html
http://docbook.sourceforge.net/release/xsl/current/doc/index.html
http://www.sagehill.net/docbookxsl/index.html
http://xmlgraphics.apache.org/fop/0.95/fonts.html
投稿者 fummy 時刻: 11:51
ラベル: ,
登録: 投稿 ( Atom )