code up

スポンサーサイト

上記の広告は1ヶ月以上更新のないブログに表示されています。
新しい記事を書く事で広告が消せます。

PDF, HTMLをひとつのソースファイルから生成する - Single Source Publishing

とあるサイトのヘルプページを作成する。ついでにPDFドキュメントとして配布、ダウンロードもできるようにしたい。HTMLとPDF(*.doc)をそれぞれ編集するのは超面倒。

ということで登場するのがSingle source publishing (aka Single sourcing)。ひとつの元ファイルから複数の形式で出力するツールを探してみました。

以下ではひとつのオリジナルファイルからPDF, HTMLを出力する方法にのみ絞っています。ただ、ツールによってはEPUBとかWindowsヘルプの出力に対応しているものもあります。

ツール一覧

Wikipediaに紹介されてるものの抜粋 + αを独自に紹介。

Sphinx
reStructuredTextで記述したファイルを複数の形式に出力するツール。
Microsoft Word
Office 2007あたり(リボンが登場したあたり?)から標準でPDF出力ができるようになっている。HTMLは昔からできていたような。ただHTMLに出力すると余計なコードが混ざるのが気になります。
Google Docs (Google Docs)
ブラウザで編集してPDF, HTMLどちらにも出力できる。
XML + XSLT + XSL-FO(Apache FOP等)
ずいぶん昔から使われていた方法。ApacheのWebサイトの一部はXMLからXSLTでHTMLに変換して生成していた気がする。最近はApache Forrestがメインのようだけど。
Apache Forrest + Eclipse + XML + Apache Forrest Plugin
ApacheのWebサイト用のHTML作成には最近よく使われている感じがする。プラグインは簡単にはインストールできなそうだし、もうずいぶん放置されてるっぽい
Vex(Eclipse Plugin; マーケットプレイスからインストール可) + DocBook + Eclipse
日本語で紹介しているサイトが少ない気がするけど、マーケットプレイスで見ると評価の高いEclipseプラットフォーム上のXML(DocBook/xhtml)エディタ。
Wiki (Eclipse + Mylyn WikiText等)
少し目的とはずれるかもしれないけど、Wikiエンジン使って文書を書いてPDFで印刷という方法もアリかと。
oXygen XML Editor - WYSIWYG DocBook Editor
有料。$488。高い・・・・!
Markdown + Pandoc + Tex Live(LuaTex) + Eclipse(Markdown Editor plugin for Eclipse) または ReText
Githubなんかでも最近よく見かける.mdという拡張子。マークアップ言語としては比較的最近できた言語。Eclipse PluginがMarketplaceからインストールできない。
ReTextは、UTF-8の読み書きができないっぽい。BOM有のUTF-8ファイルを試したところ正しく読み込んだが保存するとShift_JISになる・・・。Git版だと読み込んだ後、文字コードを切り替えられるが毎回行わねばならず面倒、しかも保存するとやっぱりShift_JISになってしまう。
Eclipseを使わない人用のMarkdownエディタを探しているのだが、今のところいいのは見つからない・・・。ポイントとしてはフリーでtable出力のプレビューができるものを探しているのだけど。
最終的にはSublime Text 2(Markdown)で書いて、PandocでHTML, PDFをAnt経由で生成するという方法に落ち着いた。
  • WindowsストアのMarkdown Editortable記法未対応。Windows7じゃ使えないんですよね、おそらく。
  • MarkDown#EditorMarkdownなのかなーと思いつつ、、、table記法には未対応。
  • MarkPadWritemonkeytable未対応。
  • MarkdownPad 2tableへの対応は有料版になるっぽい。
  • どこかでこれしかないと推していたResophNotes。クラウドに保存したデータのWindowsクライアントという位置づけなのか、そもそもローカルファイルが開けなかった。
  • DownMakerとてもシンプルなエディタ。tableは作ってくれないみたい。

reStructuredTextとかMarkdownとか

HTMLを完結に書くことを目的としているのだけれどもちょっと物足りない。どちらも下線(underline)に対応していないのだ。下記に述べるように日本語の斜体も表現できないため、強調したい時は「太字」か「括弧つき」しか方法がない。色も付けられないので、いわゆる文字書式で凡例を分けるようなマニュアル作成には向かない。

斜体(イタリック)による強調は、Pandoc(Tex)でPDFを出力した際消えてしまう。日本語のフォントにはイタリックフォントが含まれていないからなのだそうだが、いわゆるPDF Writerとかでは斜体(Slant)を実現しているのでいずれできるようになるのかもしれない。LuaTex-jaの最新版ではできそうな説明があるのだが、最新版(Tex Live 2013)ではプロセスがクラッシュしてしまいうまくできなかった。

Vex

ユーザーガイドを参考に。インストールはEclipseのマーケットプレイスから「Vex (Latest Milestone)」を選択しました。

  1. File→New→Other...からXML Authoring→Document
  2. 今回はDocBook 5.0で作成するのでDocument Typeから「DocBook v5.0」を選ぶのだが、v5.0は4つある。DTDはDTDをローカルの(プラグインのjarにあるDTDを)参照。残りの3つのXSDから「DocBook v5.0 (http://docbook.org/ns/docbook)」を選択した。残りの2つのXSD(http://www.oasis-open.org/docbook/xml/5.0/xsd/docbook.xsd, http://docbook.org/xml/5.0/xsd/docbook.xsd)はEclipse上のXML Validationでエラー(Referenced file contains errors ...)となるため。尚DTDを指定してXSLTを走らせると「java.io.FileNotFoundException: http://www.oasis-open.org/docbook/xml/5.0/docbook.dtd」で怒られる。その場合は下記のようにDTDの指定を変えれば大丈夫っぽい
    <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML 5.0//EN" "http://www.oasis-open.org/docbook/xml/5.0b5/dtd/docbook.dtd">
  3. 簡単な文書を作成してみるのでRoot Elementからはbookを選択
  4. ファイル名は拡張子を.dbkにしておくと関連付けが自動的にVisual XML Editorに
  5. XMLのパスをステータスバーで確認しながらカーソルを動かして要素やテキストを追加していく
  6. 属性値はEclipseのPropertiesビューで編集

Vexを使ってみた感想

  • ソース(XML)を見る方法がない
  • 要素によって(恐らくarticle以下)だと思うが、Ctrl+Deleteで要素が増殖したり要素が消せない時がある
  • book要素の下に(間違えて)titleabbrevを挿入したら編集できなくなった・・・
  • 日本語がインラインで入力できない。Eclipse外で入力中の文字を処理して確定すると埋め込まれる
  • どこが入力する場所なのか視覚上判断しづらい。「_」「 ̄」「|」がカーソル位置で、下部のステータスバーにXMLのパスがあるので、それらを組み合わせながら、ということらしい
  • あくまでエディタなので出力までは行ってくれない

DocBook

Unable to strip the namespace from DB5 document

Saxon-HE 9.5.0.2を使うと発生。stackoverflowによるとSaxon-HEはXSLT 2.0なので、exsl:node-set()が不要になったからXSLT 1.0のプロセッサを使えよ、とのことらしい。

出力 - HTML

build.xmlはこんな感じ。事前にXalan2とdocbook-xslをMaven Repositoryからダウンロード。下記project_classpathには、左記ダウンロードしたファイルが含まれています。

<taskdef name="fop"
         classname="org.apache.fop.tools.anttasks.Fop"
         classpathref="project_classpath" />

<target name="docbook">
    <mkdir dir="out/docbook" />
    <xslt basedir="doc"
          destdir="out/docbook"
          extension=".html"
          classpathref="project_classpath"
          force="on">
        <!-- 
        XSLT 2.0 Processorを使うとエラーになる。使用する場合は6.5.5(XSLT 1)を使う
        <factory name="net.sf.saxon.TransformerFactoryImpl" />
        
        <factory name="org.apache.xalan.processor.TransformerFactoryImpl" />
        <factory name="org.apache.xalan.xsltc.trax.TransformerFactoryImpl" />
        -->
        <factory name="org.apache.xalan.processor.TransformerFactoryImpl" />
        <style>
            <javaresource name="docbook/html/docbook.xsl" classpathref="project_classpath" />
        </style>
        <outputproperty name="encoding" value="UTF-8"/>
    </xslt>
    <xslt basedir="doc"
          destdir="out/docbook"
          extension=".fo"
          classpathref="project_classpath"
          force="on">
        <factory name="org.apache.xalan.processor.TransformerFactoryImpl" />
        <style>
            <javaresource name="docbook/fo/docbook.xsl" classpathref="project_classpath" />
        </style>
        <param name="l10n.gentext.default.language" expression="ja"/>
        <param name="ulink.show" expression="0"/>
        <param name="paper.type" expression="A4"/>
        <param name="hyphenate" expression="false"/>
        <param name="title.font.family" expression="MS PGothic"/>
        <param name="body.font.family" expression="Meiryo UI"/>
        <param name="monospace.font.family" expression="MS Mincho"/>
    </xslt>
    <fop format="application/pdf"
         outdir="out/docbook"
         force="on"
         userconfig="fop-config.xml">
        <fileset dir="out/docbook">
            <include name="*.fo"/>
        </fileset>
    </fop>
</target>

build.xmlから参照しているfop-config.xml(userconfig.xml)。最初はorg.apache.fop.fonts.apps.TTFReader使ってメトリックス(metrics)ファイルを作成したんだけど、どうやら最近のでは作らなくていいみたい。Windows/Fontsフォルダ指定して、auto-detect指定すれば自動的にフォント名を見つけてくれました。Apache FOP 1.1のドキュメント

<?xml version="1.0" encoding="UTF-8"?>
<fop version="1.0">

	<renderers>
		<renderer mime="application/pdf">
			<encryption-params>
				<encryption-length>128</encryption-length>
				<owner-password>foobar</owner-password>
				<nocopy />
				<noedit />
				<nofillinforms />
				<noassembledoc />
			</encryption-params>		
	
			<fonts>
				<directory>C:/Windows/Fonts</directory>
				<auto-detect/>
			</fonts>
		</renderer>
	</renderers>
</fop>

Vexで作ってみたDocBook

作業中の図

出来上がったXML

尚linkタグのhrefはEclipse上ではシンタックスエラーになってしまう。その場合、xmlns:xlink="http://www.w3.org/1999/xlink"のネームスペースを加えてxlink:hrefというように(XMLを直接いじって)直すとEclipse上の警告が消える。

<?xml version='1.0' encoding='utf-8'?>
<book xmlns="http://docbook.org/ns/docbook">
	<title>タイトル</title>
	<chapter>
		<title>チャプタータイトル</title>
		<para>パラグラフ</para>
		<para>段落。そして<emphasis>強調</emphasis>。</para>
	</chapter>
	<chapter>
		<title>タイトル2</title>
		<para>
		<link href="http://upload.wikimedia.org/wikipedia/commons/3/30/googlelogo.png">
		<inlinemediaobject><imageobject>
		<imagedata fileref="http://upload.wikimedia.org/wikipedia/commons/3/30/googlelogo.png"/>
		</imageobject></inlinemediaobject></link></para>
	</chapter>
</book>

手作業で直した後

<?xml version='1.0' encoding='UTF-8'?>
<book xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink">
	<title>タイトル</title>
	<chapter>
		<title>チャプタータイトル</title>
		<para>パラグラフ</para>
		<para>段落。そして<emphasis>強調</emphasis>。</para>
	</chapter>
	<chapter>
		<title>タイトル2</title>
		<para>
		<link xl:href="http://upload.wikimedia.org/wikipedia/commons/3/30/Googlelogo.png">
		<inlinemediaobject><imageobject>
		<imagedata fileref="http://upload.wikimedia.org/wikipedia/commons/3/30/Googlelogo.png"/>
		</imageobject></inlinemediaobject></link></para>
	</chapter>
</book>

HTMLで出力

PDFで出力

DocBookを使ってみた感想

  • セットアップまでが長い!調べながらなので丸一日かかった。次からは数時間で済むだろうが、手間がかかる・・・
  • 参照するライブラリが多すぎる、特にFOP。というかbatik

Ivyで追加したライブラリ達。commons-io, commons-logging等既に取り込んであるものは省略。

  • DocBook XSLは1.78.0
  • Xalanは2.7.1
  • Apache FOPは1.1
  • XML Graphics Commonsは1.5
  • Avalonは4.3.1
  • batikは1.7
<dependency org="net.sf.docbook" name="docbook-xsl" rev="${net.sf.docbook.docbook-xsl}" transitive="false">
	<artifact name="docbook-xsl" type="zip" m:classifier="resources" />
</dependency>

<dependency org="xalan" name="xalan" rev="${xalan.xalan}" transitive="false" />
<dependency org="xalan" name="serializer" rev="${xalan.xalan}" transitive="false" />

<dependency org="org.apache.xmlgraphics" name="fop" rev="${org.apache.xmlgraphics.fop}" transitive="false" />
<dependency org="org.apache.xmlgraphics" name="xmlgraphics-commons" rev="${org.apache.xmlgraphics.xmlgraphics-commons}" transitive="false" />

<dependency org="org.apache.avalon.framework" name="avalon-framework-api" rev="${org.apache.avalon.framework}" transitive="false" />
<dependency org="org.apache.avalon.framework" name="avalon-framework-impl" rev="${org.apache.avalon.framework}" transitive="false" />

<dependency org="org.apache.xmlgraphics" name="batik-svg-dom" rev="${org.apache.xmlgraphics.batik}" transitive="false" />
<dependency org="org.apache.xmlgraphics" name="batik-bridge" rev="${org.apache.xmlgraphics.batik}" transitive="false" />
<dependency org="org.apache.xmlgraphics" name="batik-awt-util" rev="${org.apache.xmlgraphics.batik}" transitive="false" />
<dependency org="org.apache.xmlgraphics" name="batik-gvt" rev="${org.apache.xmlgraphics.batik}" transitive="false" />
<dependency org="org.apache.xmlgraphics" name="batik-transcoder" rev="${org.apache.xmlgraphics.batik}" transitive="false" />
<dependency org="org.apache.xmlgraphics" name="batik-extension" rev="${org.apache.xmlgraphics.batik}" transitive="false" />
<dependency org="org.apache.xmlgraphics" name="batik-ext" rev="${org.apache.xmlgraphics.batik}" transitive="false" />

<dependency org="org.apache.xmlgraphics" name="batik-anim" rev="${org.apache.xmlgraphics.batik}" transitive="false" />
<dependency org="org.apache.xmlgraphics" name="batik-css" rev="${org.apache.xmlgraphics.batik}" transitive="false" />
<dependency org="org.apache.xmlgraphics" name="batik-dom" rev="${org.apache.xmlgraphics.batik}" transitive="false" />
<dependency org="org.apache.xmlgraphics" name="batik-parser" rev="${org.apache.xmlgraphics.batik}" transitive="false" />
<dependency org="org.apache.xmlgraphics" name="batik-util" rev="${org.apache.xmlgraphics.batik}" transitive="false" />
<dependency org="org.apache.xmlgraphics" name="batik-xml" rev="${org.apache.xmlgraphics.batik}" transitive="false" />
<dependency org="org.apache.xmlgraphics" name="batik-script" rev="${org.apache.xmlgraphics.batik}" transitive="false" />
<dependency org="org.apache.xmlgraphics" name="batik-svggen" rev="${org.apache.xmlgraphics.batik}" transitive="false" />
<dependency org="org.apache.xmlgraphics" name="batik-js" rev="${org.apache.xmlgraphics.batik}" transitive="false" />
関連記事
上記広告は1ヶ月以上更新のないブログに表示されています。新しい記事を書くことで広告を消せます。