LDP Author Guide
Prev	Chapter 4. DocBook タグの使い方	Next

4.10. ツールとヒント

出力結果を見たり索引を作ったりする処理は、文書作成中に何度も繰り返されますし、エラーが出ることも多いはずです。こうした処理を楽に行うために、いくつかのスクリプトを用意しました。よろしければカスタマイズして使ってください。

4.10.1. ソースのコンパイル

compiles-sgml スクリプトは、一連のコマンドをグループ化したものです。パラメータとして、SGML の文書名と出力したいフォーマット名を渡す必要があります。

下記のバージョンのスクリプトでは、 XML, HTML, TeX, RTF, PS, DVI および写像 PS (mirrored PS) フォーマットをサポートしているので、フォトリトグラフを生成する場合には理想的です。

索引の生成は、collateindex.pl[1] スクリプトが自動的に行うので、左記スクリプトをあらかじめシステムにインストールしておいてください。

様々なフォーマットで出力を生成する下記のコマンドとは別に、他にも直接変換を行うツールが Cygnus™ から提供されています。そのツールは、ここから入手することができます。

以下のスクリプトは、ここから手に入れることもできます。

上記の場所には、 collateindex.pl もあります。

Example 4-8. compiles-sgml スクリプト

#!/bin/bash
#
# Compile DocBook documents into several output formats.
#
# Godoy.
# 19991230 - Initial release.
# 20000117 - Placed the options using "case" and parameters passed 
#	     via command line. The pages on the Zope are already updated.
#	      --- Removed to public version (/home/ldp). 
# 20000120 - Placed the call to use the books.dtd.
# 20000126 - Placed the commands for the index generation.
# 

# If the jade is already installed, disconsider the line bellow.
 JADE=/usr/bin/jade

# If the jade package is already installed, disconsider the line bellow.
# JADE=/usr/bin/openjade

DOCUMENT=$1
shift 1
TYPE=$1

. ~/.bash_profile
. ~/.bashrc

case $TYPE in
    html)
       rm -f *.htm
       rm -f *.html
       perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o index.sgml 
       jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl $DOCUMENT.sgml
       perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o index.sgml HTML.index
       $JADE -t sgml -i html -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl -d /home/ldp/SGML/conectiva/livros.dsl#html $DOCUMENT.sgml
    ;;
    rtf)
       rm -f $DOCUMENT.rtf
       perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o index.sgml 
       jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl $DOCUMENT.sgml
       perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sgml HTML.index
       $JADE -t rtf -V rtf-backend -d /home/ldp/SGML/style/dsssl/docbook/print/docbook.dsl -d /home/ldp/SGML/conectiva/books.dsl#print $DOCUMENT.sgml
    ;;
    xml)
       rm -f $DOCUMENT.xml
       perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o index.sgml 
       jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl $DOCUMENT.sgml
       perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sgml HTML.index
       $JADE -t sgml -i xml -d /home/ldp/SGML/style/xsl/docbook/html/docbook.xsl $DOCUMENT.sgml
    ;;
    tex)
       rm -f $DOCUMENT.tex
       perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o indice.sgml 
       jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl $DOCUMENT.sgml
       perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sgml HTML.index
       $JADE -t tex -V tex-backend -d /home/ldp/SGML/style/dsssl/docbook/print/docbook.dsl -d /home/ldp/SGML/conectiva/livros.dsl#print $DOCUMENT.sgml
    ;;
    dvi)
       rm -f $DOCUMENT.tex
       rm -f $DOCUMENT.dvi
       perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o indice.sgml 
       jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl $DOCUMENT.sgml
       perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sgml HTML.index
       $JADE -t tex -V tex-backend -d /home/ldp/SGML/style/dsssl/docbook/print/docbook.dsl -d /home/ldp/SGML/conectiva/livros.dsl#print $DOCUMENT.sgml
       jadetex $DOCUMENT.tex
    ;;
    mirror)
       rm -f $DOCUMENT.tex
       rm -f $DOCUMENT.dvi
       rm -f $DOCUMENT.mirror.ps
       perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o indice.sgml 
       jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl $DOCUMENT.sgml
       perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sgml HTML.index
       $JADE -t tex -V tex-backend -d /home/ldp/SGML/style/dsssl/docbook/print/docbook.dsl -d /home/ldp/SGML/conectiva/livros.dsl#print $DOCUMENT.sgml
       jadetex $DOCUMENT.tex
       dvips -h /home/ldp/estilos/skel/mirr.hd -O 1.5cm,3cm -f $DOCUMENT.dvi -o $DOCUMENT.mirror.ps
    ;;
    ps)
       rm -f $DOCUMENT.tex
       rm -f $DOCUMENT.dvi
       rm -f $DOCUMENT.ps
       perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o indice.sgml 
       jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl $DOCUMENT.sgml
       perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sgml HTML.index
       $JADE -t tex -V tex-backend -d /home/ldp/SGML/style/dsssl/docbook/print/docbook.dsl -d /home/ldp/SGML/conectiva/livros.dsl#print $DOCUMENT.sgml
       jadetex $DOCUMENT.tex
       dvips -The 1.5cm,3cm -f $DOCUMENT.dvi -o $DOCUMENT.ps
    ;;
    *)
       echo "How to use: $0 file {html|tex|rtf|xml|ps|dvi|mirror}"
       exit 1
       esac

exit 0

こうしたスクリプトは、Makefile を作って、関数のいくつかを最適化することで、修正できるのがお分かりになると思います。

4.10.2. article の最初のページに要旨を挿入する

article の最初のページに要旨を表示できる機能が欲しいと思う場合があるかもしれません。ただ、DocBook の article は、標準では、この機能を持っていません。 (訳注: DocBook の book を使う場合は、問題ありません。)

これを有効にするには、利用しているスタイルシートに修正を加える必要があります。

以下の例は、その場合の処理について述べています。使い方は、 Example 4-8 をご覧ください。

Example 4-9. article で、自動的に要旨を挿入するための stylesheet の設定

<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!entity html-docbook PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA DSSSL>
<!entity print-docbook PUBLIC "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN" CDATA DSSSL>
]>

<style-sheet>
<style-specification use="html">
<style-specification-body>

; Includes a summary at the beginning of an item. 
(define %generate-article-toc% #t)

</style-specification-body>
</style-specification>
<style-specification use="print">
<style-specification-body>

; Includes a summary at the beginning of an item.    
(define %generate-article-toc% #t)

</style-specification-body>
</style-specification>
<external-specification id="html" document="html-docbook">
<external-specification id="print" document="print-docbook">
</style-sheet>

4.10.3. 索引を自動的に挿入する

DocBook には索引付けをするためのマークアップがありますが、それらは自動的には生成されません。しかし、collateindex.pl ツールを使えば、索引生成は自動化できます。

次にこのスクリプトの使い方を説明します。実際の例は、この文書で先ほどご覧になったと思います。(Example 4-8参照)

HTML スタイルシートと、オプション -V html-index を使って、jade で文書を処理します。
$ jade -t sgml -d html/docbook.dsl -V html-index document.sgml
collateindex.pl を使って、index.sgml 文書を生成します。
$ perl collateindex.pl -o index.sgml HTML.index

上記の例が機能するには、外部エンティティ(external entity) を定義して index.sgml ファイルを取り込む必要があります。

Example 4-10. 索引を付けるために外部エンティティを設定する

<!doctype article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [

<!-- Insertion of the index -->
<!entity index SYSTEM "index.sgml">
]>

文中に必要な情報を取り込む方法については、Section 4.5 もご覧ください。

Note: PS か PDF での出力の際に目次や索引を取り込もうとしている場合は、 jadetex か pdfjadetex を最低 3 回は実行する必要があることに注意してください。これは、TeX が必要とする処理であり、DocBook もしくはそれに関連したアプリケーションの問題ではありません。

4.10.4. 文書の中の下書き部分を隠す

面白い機能として、文書の作成中に、その作成部分を最終稿として公開するかどうかを簡単なチェックだけで決めることができる機能があります。既存の文書を更新しようとしている場合などには特に、文書内に草稿として位置づけられている部分がいくつも存在する場合がよくあります。

DocBook では、パラメータ・エンティティ(parameter entity)を使って、文書内に散らばった特定部分の文章を、状況に応じて隠したり表示したりすることができます。文書を更新している場合には、文書がどう見えるのかを確認したり、新しい章や編のおおまかな出来具合を確認したりする必要がありますが、その草稿部分を最終稿には表示したくないということがよくあります。

パラメータ・エンティティを使うと、文書の冒頭の一行を変更するだけで、そうした草稿部分を文書内に含めたり、文書から削除したりすることができます。

Example 4-11. パラメータ・エンティティを使う

<!entity % review "INCLUDE">
...
<![%review;[
<para>この段落は、上記エンティティ "review" の値が "INCLUDE" と
定義されたときに、文書中の一部となります。</para>
]]>

上記エンティティ review は、文書内のいろいろな箇所に書き込むことができます。その部分への変更が終了したら、上記の例ならば、 3 行目と 6 行目を削除するだけです。

草稿のままで保持して、最終稿には含めないようにするには、エンティティの値を INCLUDE から IGNORE に書き換えるだけで済みます。

4.10.5. 頻繁に利用する文書を外部から取り込む

外部エンティティ(external entity)の重要な特性は、よく使われるメモや文書を取り扱う際に発揮されます。

この特性を活かして、(例えば、ライセンスや社則などの)頻繁に利用される文章をファイルにして、そうしたファイルを文書の適切な位置に取り込むことができます。

この特性を応用した例に、先ほどの Example 4-10 があります。また、この HOWTO 文書自体の SGML コードもその一例です。

Prev	Home	Next
翻訳者やコード変換者の氏名を表示する	Up	文書のサンプル