カテゴリー別アーカイブ: XML-DITA

速習XSLT超入門1(明日に迫るXSLT超入門2ウェビナー )

ゴールデンウィークも明け、XSLT超入門2のウェビナーが明日に迫りました。

セミナーのようなイベントでは、ナンバリングによって「初回参加してないからどうしよう」と尻込みされてしまう方がいるかもしれません。ということで、第1回をおさらいする記事を用意しました。
「これだけ見ておけば大丈夫」というよりは、書籍におけるあらすじと目次のようなものと考えてください。

導入として「XSLTを活用する自動組版の流れとして、XSLTがどの部分の役割を果たすか」を紹介しています。元の文書にあるコンテンツから目次を生成したりできます。
このウェビナー内では大きく触れていませんが(PDF自動生成超入門の内容なので)、「生成時まで内容が決定できないこと」をオブジェクトとしてレイアウトできるのがXSL-FOとなります。弊社製品Antenna House XSL Formatterによる拡張要素・プロパティも、この視点で眺めてみるとスタイルシート設計に役立つのではないでしょうか。

書籍の完成状態を例にして、抽象的な「構造」について紹介し、それをXMLで表現することについて触れています。

XMLを変換するにあたって、「どの部分を変換するか」という指定が必要になります。XSLTでは、そのためにXPathを使うよ、ということを紹介しています。XPathはXSLTから独立するほど多様な機能がありますが、「XML上の特定位置を指定する」ことは基本といって良いでしょう。そのために「ノード」という形でXML文書を解釈し、ノード間の関係としてXML上の位置を指定できるようにしています。関係の方向性として「軸」があり、不足する指定を補う「述部」がある、という紹介をしています。

より実際的な説明として、弊社の過去記事を紹介しておきます。
XSLTを学ぶ (1) XMLのツリーモデルとXPath/XSLTのツリーモデルではルートの意味が違う

明日のウェビナーが「基本文法編」ということで、では「XSLTの基本」は何を紹介しているんだ、疑問があるでしょう。ここでは初学者にとって概念的にあまり馴染みがないであろう、XSLTを構築する基本であるxsl:template@matchとxsl:apply-templatesについてを図を用いて紹介しています。文法は比較的資料があるため、図示に注力した形です。後半のデモでトラブルがあった関係でウェビナーと動画で違いが生じてしまっていますが、このmatchとapplyの関係はコインソータに似ている、ということを覚えておくと良いでしょう。

ウェビナーではトラブルのあったデモについては動画を撮り直しています。
デモを通し、xsl:template@matchとxsl:apply-templatesでXML文書を処理していく様子を紹介しています。

全体を通して、「学習開始で環境構築に悩むよりプレイグラウンドなどを利用するのも良い」「業務利用としてXMLエディタは十分ペイする」「変換元のXML文書としてCommonMark文書が難易度として丁度良いのではないか」といった話をしており、「初学者が取り組みやすい形を提示する」をサブテーマとしていました。

明日のウェビナーではこの第1回からの流れを受けて、基本的なコードリーディングによる学習ができる段階まで持っていけるようにすることを目標にしています。ご参加をお待ちしています。


DITA-OTでソースコードを書くならcoderefが便利

DITAでソースコードを書くときはcodeblock要素を使います。

(HTML5では引用ブロックやcodeblock(pre/code)もfigureの子孫として記述する方法がよく見られます。個人的な感覚として、英語だとキャプションに「figure 1」のようにしてソースコードが記載されていても違和感はないのですが、日本語で「図1」となっているところにソースコードが記載されていると違和感があります。)

さて、codeblockの中をどう書くかについて、方針はおおむね次の2つです。

  • 直接書く。XMLの<や>は
    • &lt;のようにして書く
    • xml-mentionドメインのタグを使って書く
  • coderefを使う

今回は記事タイトルにもあるように、coderefを使う方法が便利という話です。

DITA-OTではcodeblockでの処理について、仕様から拡張しています。記事タイトルが「DITAでcodeblockを書くときは~」ではないのはDITAの仕様ではないからです。なお、記事を作成する際に試行した環境はDITA-OT 3.7.1となります。

Extended codeblock processing DITA-OT

拡張内容は幾つかあるのですが、先に述べた通り、今回紹介するのはcoderefについてです。

codeblockにはテキストをそのまま記述することもできますが、XMLタグ、というか<などがきっちり処理されてしまうため、XMLやHTMLをソースコードとして例示するのは結構大変です。そこでcoderefです。

coderefは外部ソースコードを(主にテキストとして)参照し、結果を展開してほしい場合に使うタグです。@hrefで参照する先を指定します。XMLを参照する場合、@format=”xml”を付けましょう。

coderefの第一の利点は<をエスケープしなくて済む点です。これについてはDITA仕様のうちです。

coderefを使ったコードブロック
<codeblock xml:space="preserve"><coderef href="hoge.xml" /></codeblock>

ただ、実際のXMLファイルというのは結構行数が嵩みます。「coderefで参照する用にコード片を別ファイルに保存して……」というのはメインテナンス性からするとあまり歓迎できません。そこでDITA-OTの機能によって行数を制限します。

coderefの拡張記法は#から続くフラグメントによるものです。これに対応していない、DITA-OT以外のDITA処理系で使われても、ファイルの全行が出力されるだけで済みます。……結構大変なので、keyrefで切り出して切り換え可能にしておくのが良いかもしれませんね。

行数の記法はドキュメントにある通り、#line-range(<start>,<stop>)またはRFC 5147の記法で#line=<start><end>のようにして開始行、終了行を指定します。

このままで十分便利ですが、「元のソースコードを弄ったらトピックファイルで指定している行位置も変更しなくてはいけないのだろうか」と疑問を持たれたことでしょう。それはあまりメインテナンス性が良くありませんね。ということで、任意文字列を行位置の識別子にする方法が提供されています。
#token=<start-text>,<end-text>を指定すると、ソースコード中のstart-textがある行の次行からend-textがある行の前行までが範囲として取り出されます。想定としてはコメントアウトした行にstart-text、end-textを書いておく形のようなので、あまりトリッキーなことはしない方が良いでしょう。ほかにも幾つかの機能がDITA-OTのページで紹介されていますが、プラグインや処理系依存の機能もあるようなので都度確かめて使うと良いでしょう。

coderefのstart,end用文字列を追加したXML
<!-- example1start -->
<fo:block><fo:inline>Title</fo:inline></fo:block>
!-- example1end -->

ほか、coderefというcodeblockの中で更に別のタグを使うことのメリットは、@hrefで参照した箇所と、直接書く箇所をcodeblockの中で行える点です。

coderefを使ったコードブロック

<codeblock xml:space="preserve"><coderef href="hoge.xml#line-range(1,5)" />
... <!-- 直接書いた部分 -->
<coderef href="hoge.xml#line-range(10,15)" /></codeblock>

1-5行目、「…」を書いて10-15行目、なんて表示も可能になります。

そんなcoderef、DITA 2.0で若干の変更が入ることが現在のドラフトで言及されています。といってもエンドユーザがトピックを記述する上ではそう変化はなく、主に仕様上の立ち位置がより整理されるということのようです。


『Office Open XML Formats入門 第2版』を制作しました

2021年12月07日 16:00~17:00 に「ちょっと一息アンテナハウスウェビナー『Office Open XML Formats入門 第2版』制作報告」を発表しました。販売、公開よりも発表が先になってしまったため、内容が気になっていた方もいらっしゃるのではないでしょうか。

こちらが表紙画像です。

Amazon POD用表紙画像

2021年12月07日ウェビナーのバナー

組版をAH XSL Formatter V7.2で行ったため、『AH Formatter XML関連出版物の紹介』ページに掲載しています。

Amazonの販売ページへのリンクは次の通りです。

https://www.amazon.co.jp/gp/product/4900552836

また、本書のPDF版は弊社オンラインショップからご購入いただけます。印刷版とレイアウトの微調整を行いました。

https://web.antenna.co.jp/shop/html/products/detail.php?product_id=1301

HTML版はOffice Servers資料室のページからご覧いただけます。


ウェビナー概要や書籍紹介ページにある通り、アンテナハウス『Office Open XML Formats入門』の初版は2007年に出版社から刊行されました。
今年は2021年、つまり14年程前の書籍の改訂版ということになります。
内容的な修正は必要とはいえ、以前の版の原稿をベースに新たな版を制作するというとき、XML原稿はほとんど変更が必要ありません。以前の版の構造に不満がある場合はその限りではありませんが。

一方で大規模な修正の余地があるのがXSLTでした。そしてウェビナー(と書籍の後書き)では、XSLTについてはかなり省いて説明することになったため、本記事ともう一度どこかで補足することにしたいと思います。

2007年というのは、XSL的にもそこそこ大きな節目でした。XSLT 2.0のW3C勧告です。XSL 1.1の勧告は2006年でしたが、実利用として熟れていないという点では二者とも同様です。XSLT 2.0以降はミスの発見やスクリプトの見通しにおいてXSLT 1.0とは別言語に近い体験をもたらします。msxmlのXSLTが1.0であることや各ウェブブラウザほか処理系の多くが1.0までしか対応していないことも手伝って、使える状況が限られるのは悩ましいところです。

変更の概略

今回は自社事例でしたので、初版で1.0だったXSLTを3.0に書き換えました(完全に3.0向けに最適化したとはとても言えませんが)。

書籍初版の制作報告にもあったように、XSL 1.1での大きなポイントにbookmarkのとindex関係の語彙が入ったことが挙げられます。『Office Open XML Formats入門』初版では、bookmarkについてはXSL Formatterの拡張仕様、索引についてはbasic-linkとXSLTによる力技による解決が図られていました。

(AH )XSL Formatterの拡張仕様では実際のフローコンテンツ登場箇所と同一の箇所に記述するため、処理においてXML中の章構造に当たったときに同時に処理すれば良いことになります。よってXSLT記述としてはbookmark-tree用に処理を追加するよりも単純に書けます。XSLT 1.0で書く場合は複数回ドキュメントを走査することが難しいということも手伝っていたのかもしれません。

索引構造については、XSL 1.1のindexを導入することで、XSLTで行わなければならなかった処理が簡略化されます。索引語に当たったときの処理で、「既に同じ索引語が登場しているか」「同じ索引語が同ページに登場したときにページ数表示を合一する」といった判別がXSLのプロパティで変更可能になるため、分岐処理などが大幅に簡略化できました。

割とアドホックな書き換えを行っていたり、徹底できていなかったりするため、引き継ぎをするにはリファクタリングが必至ですが、大体このようなことを行いました。

  • テンプレート中に直接書き込まれたattributeをattribute-setへまとめる
  • 共通処理をまとめる。
  • apply-templatesを含まないような分岐は名前付きテンプレートへ追いだし、パラメータを渡すようにする
  • XPathによる値の取得はできるだけテンプレートの先頭でまとめ、利用箇所ではselect="$value"のように呼び出すだけにする

先に書いた通り徹底はできておらず、私自身も、テンプレート中で直接attributeを指定しているような箇所をかなり生み出してしまいました。とはいえ、ギリギリの時期に「ヘッダーの位置をもう少し下げて」といった指示に1行の変更だけで対応できるようにはできたので、無駄ではなかったと思います。

実は上に挙げたものはXSLT 1.0時点でも時間さえあれば行える変更で、3.0への変更には関係ありません。値のみを取得、操作したい箇所をfunction化したり、処理をreplace()関数に書き換えたりといった作業は2.0から行えます。3.0としては関数の括弧が入れ子ではなくarrowを使えたり、文字列結合に「||」を使えるといった枝葉の変更点を使用しています。

参考資料


書籍のHTML版の構造を考える(OOXML入門第2版)

12/07に「『Office Open XML Formats入門 第2版』制作報告」のウェビナーを行いました。ウェビナーで言及したように、『Office Open XML Formats入門 第2版』はHTML版も制作中です。

編集用XMLであるSimpleDoc(の改造版)はほぼHTMLの文法なので基本的にはそのままです。
とはいえ、そのままで出せるかというとそうでもなく、「表示媒体の違い」へ意識を向ける必要があります。本記事ではその辺りについて「こんなことを考えながら作っています」という話です。

形式

まず、HTMLとしてはHTML5、もといLiving Standardに合わせています。他社コンテンツを制作するような場合に比べれば更新の自由が利きますし、セマンティックな語彙が多い方が嬉しいですね。変換自体にはXSLT 3.0を利用しています。

スタイル設定

SCSSで大本を記述した後、CSSに変換したものをlinkの読み込み対象にしています。あるページ特有のスタイルというものは無かったため「_color.scss」「_header.scss」、「_footer.scss」これらを読み込む「common.scss」のようになっています。

ページ分割とナビゲーション

まずページ分割単位の決定。「最終的に1ページのHTMLファイルに収める」というのはそれなりの文量のある書籍では現実的ではありません(動的に内容を取得するのであればそういった方法もあるでしょう)。今回は「章単位でフォルダーを分け、節単位でファイルを分ける」ということにしました。
余談として、DITAではDITA-OT標準のHTML出力を行うとトピックごとにページが分けられます。書籍の形態を重視する場合はこのトピック単位というのは個人的にはやや扱いづらいものであったりします。

ナビゲーションの追加について。特に静的なページとして用意する場合、次の箇所へ遷移する方法の確保は重要です。HTML版用に新たに考えるべき項目としては「常に目次をページ内に配置する」「前後の箇所へのリンクを配置する」「検索用のページを用意する」といったことが挙げられます。

「常に目次をページ内に配置する」については「目次へのリンクを各ページに配置する」で濁してあります。ページごとに記述量が増えて若干デバッグがしづらくなるためです。全ページに目次を配置した場合も、ファイルサイズとしては誤差でしょう。「iframeタグで目次ページを表示させる」ことも可能ですが、今回はリンクを選択しました。

コンテンツの配置レイアウト

body/headerに章題と章トップページ・目次ページ・前後ページへのリンク、body/footerに前後ページへのリンク、body/main内にそのページのコンテンツを配置しました。
書籍と構成は変わるものの「常に(画面上という意味でなく)表示されて欲しい情報」とコンテンツとして欲しい情報といった整理を行うことに変わりはありません。

書籍版と見せ方を変えるもの

Webブラウザーでは紙の本ではできない操作が可能です。今回、次のような変更をしています。

  • コードブロックにoverflow:scrollを設定。
  • h3のsection内容をdetailsタグでアコーディオン表示設定。
  • 画像にwidth:100%を指定。

記事内容の主題といっても良い箇所だと思うんですが、3行で終わってしまいました。

相互参照、リンク

これは「できるならやった方が良い」という話です。HTML版用に新たに用意するにはコストが高く、やるのであればHTML版に関係なく取り組む価値があります。
書籍内の単語や索引、図参照などをハイパーリンクとして設定することについて、元原稿であまり積極的に設定していなかったためにほぼ見送りました。PDF用にリンク用の機構をしっかり準備、活用していれば流用できただけに惜しいです。

メタデータ

「メタデータ、head内をどこまで用意するか」といった話があります。「この場所(弊社Webサイト)にこのコンテンツがあることを知っている」方に対して公開する向きが強いため、ひとまず先送りにできるだろうということがあげられます。
JSON-LDによるメタ情報の追加やサーチエンジン巡回用のRobots.txt、といったものですね。

最低限の項目としてtitle、言語、エンコーディング、viewportの初期値といったものは設定しました。これらは文字化けやモバイル端末での表示性確保として最低限設定すべき箇所でしょう。

OGPについてはある程度用意した方がSNS上でのリンク表示が見栄えするのである程度は確保したいので悩ましいところです。

作業が完了していないこともあり今回はこの辺りで。HTML版(、そして販売準備中のプリントオンデマンド版も)の完成まで少しだけお待ちください。

参考資料


【動画公開】「DITAで本を書いてAH XSL Formatterで自動組版する」、FormatterClub2021ウェビナーのお知らせ

2021年8月10日に開催しました、ちょっと一息アンテナハウスウェビナー「DITAで本を書いてAH XSL Formatterで自動組版する」の録画を編集した動画が公開されています。

動画は1本10分程度の4本立てとなりました。

ご好評いただけましたようで、当日は予定時間をはみ出すくらいにご質問をいただきました。
「タグを気にせず書きたい」といった意見もございました。個人的には「タグを気にしながら書きたい」派でしたのでそういった方のための資料はあまり用意できていなかったのですが、そういった方面のアプローチも存在しますので、機会があればあらためてまとめたいと思います。

さて、この動画自体は少し前に公開されたのですが、何故今ブログ記事にしているかというと、次のイベントに関連するためです。

FormatterClub2021ウェビナー開催

日時
2021年9月17日(金)17:00~18:10
概要
今回のFormatterClubでは、キヤノンの吉田一様にFormatterでのマニュアル作成と自動組版の取り組みの発表の他、XSL拡張仕様のご説明、AH Formatterの今後をご紹介を致します。
内容紹介・お申込みページ
ウェビナー登録ページ【終了しました】

Formatter Club は、アンテナハウスの XML 自動組版ソフト『AH Formatter』を導入されているユーザーや関心を持っていただいている皆様と開発者とを繋ぎ、会員同士の交流、情報交換により『AH Formatter』の利用技術を向上させ、より皆様のお役に立てる製品としていくために役立てることを目的として発足いたしました。
『AH Formatter』とその関連技術(XSL、CSS、XML 多言語組版など)に関心のある方でしたらどなたも参加できます。参加費は無料です。
Formatter Club の活動には会員メーリングリストを情報交換のために利用し、会員専用の Web ページも提供いたします。また定例会を開催し、会員相互の親睦をはかります。定例会は、『AH Formatter』開発者から最新バージョンの紹介・デモ、活用事例紹介、組版技術の向上のための勉強会などを行います。

Formatter Club について | アンテナハウス株式会社

ということで、「XSL拡張仕様のご説明」として『使いこなしガイド』の紹介をさせていただく予定です。
今回のウェビナーはFormatter Club会員様以外でも参加が可能ですのでお気軽にご登録、ご視聴ください。

関連記事



来週に迫る「DITAで本を書いてAH XSL Formatterで自動組版する」ウェビナーと溢れ話

以前ブログ記事でも告知しました*1「DITAで本を書いてAH XSL Formatterで自動組版する」ウェビナーを来週8/10(火)に開催します。

以前の記事で触れましたように、このウェビナーは『AH XSL Formatter拡張仕様使いこなしガイド』の制作報告であるものの、プレゼンの性質と時間の都合上、省略することはどうしても出てきてしまいます。

本記事では、省略した中から「実際の制作はLightweight DITAから始めた」ことについて書きたいと思います。プレゼンから省略された一番の理由は「説明がややこしくなる」なので、一度内容を忘れてウェビナー終了後にまたご覧になっていただくのも良いかもしれません。

実際の制作はLightweight DITAから始めた

Lightweight DITA

Lightweight DITA(LwDITA)はDITAのサブセットであるXDITAと、XDITAと互換があるよう設計したHTML5で記述するHDITA、MarkdownとYAML Frontmatterで記述するMDITAを指します。DITA-OTの新しめのバージョンではformat="mdita"のようにして通常のDITAトピックと同様に処理可能です。
LwDITAについては以前に少し記事を書きました。併せてご覧ください。

原稿形式選定

原稿形式選定にあたってのライバルは、様々な弊社出版物の実績があるCAS-UB、『Office Open XML Format入門』で利用されたsimpleDocといったものがありました。それらからの選定にあたって「執筆協力予定メンバー全員がそれらの原稿形式に慣れているわけではない」ということがあり、「原稿をプレーンテキストまたはHTMLで受けとれるならオーサリング作業は何とかなるだろう」という考えがあり、とりあえずということでLightweight DITAを採用することにしました。

  • マークアップが不足して困ったとき別形式に移行しやすそう
  • MarkdownやHTMLなら何とか書けるだろう

「~だろう」というふわっとした状態で制作をスタートしてしまったことが大きな反省点です。内部調整的な話は「連絡・相談をしっかりしよう」ということに尽きるのですが、技術的な面でも問題がありました。技術的な面と書きましたが、初歩の話です。

反省点

  • DLとTableの使い分けははっきりさせておこう
  • LwDITAのマークアップは最低限しかないので、DITAへの移行時にどうするかを詰めておく
  • LwDITAでもkeyrefは使える

DLとTable、これは仕様の表についての話ですね。仕様についての書籍ですので、山のように登場します。
HTMLのセマンティクスでも、仕様や会社情報の列挙にtableを使うべきかDLを使うべきかというのは混乱しやすいですし、一概に片方のみを正解とも言えません。今回の仕様の表については「1箇所につき1仕様」「左にラベル、右に内容という構成」を考えると、DLを使用していればミスを減らせたのではないか、と後から思いました。また、MDITAの簡易マークアップによる表はsimpletableになりますが、(望ましい形への自動変換を自前で用意しない限り、)ページ数その他についてシビアになる制作物では使わない方が良いでしょう。なんならテーブルマークアップは手で書かずにデータ変換処理によって用意した方が良いです。

MDITAの簡易マークアップによる表

| Header |
|--------|
| Cell   |

LwDITAのマークアップは最低限であることについて。XMLタグの&lt;や&gt;を表示時に補ってくれるXMLドメインなどはLwDITAでは使えません。MDITAではattributeに変換時のためのclass(HTML)なども使えませんから、使い分けが想定されるのであればトピック数が数百ファイルになる前に何らかの対処が必要でした。

LwDITAでもkeyrefは使えます。主に図版のパスの問題ですね。実は執筆当初使い方が分からかったので後回しに(書き方が間違っており上手く処理されなかった)したところ、後半の作業で牙を剥きました。

LwDITAを諦めた最たる理由はindextermが使えなかったことですが、これについては以前の記事で触れていますので割愛します。

こういった反省点を基にLwDITAをもっと上手くライティング形式として活用できる展望はあるのですが、最近はXMLでの読み書きに抵抗が薄くなったため、その機会はそうそう無いかもしれません。

ということで、来週8月10日(火)16時から、ちょっと一息アンテナハウスウェビナー『DITAで本を書いてAH XSL Formatterで自動組版する』を開催しますので、ご参加いただければ幸いです。また、『AH XSL Formatter拡張仕様使いこなしガイド』*2もよろしくお願いします。

DITAで本を書いてAH XSL Formatterで自動組版する

日時
2021年8月10日(火)16:00~17:00
概要
2021年5月18日に公開/販売した『AH XSL Formatter 拡張仕様使いこなしガイド』の制作報告を通し、XML執筆からPDFを作る過程の知見をご紹介します。
DITAについてや、DITAでの書籍制作における実例の紹介や、DITAを扱うときの注意事項など、自動組版やXMLの使い方、DITAに興味がある方、Formatterユーザーさん、必見です!
内容紹介・お申込みページ
こくちーずプロからお申し込み:https://www.kokuchpro.com/event/20210810/
Zoomウェビナーへ直接お申込みいただく場合: ウェビナー登録ページ

XSL-FO試行錯誤 変換後を意識しながら独自XMLを考える

業務ではなくプライベートの話となるのですが、自分用のXML規格を考えたり、そのXMLを変換するXSLTを書いたりということをしています。

自分用のXMLはさらに自分用の軽量マークアップからの変換によって得ることを想定しているので、スキーマまで作りこもうと日々ジリジリと進めています。

XSLTは組版用でないXMLを組版用のXSL-FOに変換できるわけですが、「軽量マークアップとして書きやすく、XSL-FOやHTMLにもしやすい」XMLというのはなかなか難しいなと感じています。

脚注はDITAではfnタグでマークアップします。XSL-FOではfootnote、footnote-bodyに変換されるでしょう。CSS Paged mediaではspanにした後フロートさせることが多いようです。
Webページ、HTML5的には脚注文の位置はasideの中あたりが良いのでしょうか?ただ、HTMLページの一番下(フッタ)に置いてしまうとPDFや紙でのソレよりも遥か下に行ってしまい、後注、しかもappendix的な配置になってしまうかもしれません。
では脚注用のfootnoteタグを用意するのではなくnoteタグを用意してレイアウトは属性にしましょうか?

変換先がXSL-FOであれば出力は1ファイルが望ましいでしょう。
しかしたとえばDITAなら?元の独自XMLはマップやトピックをどのように扱っていると好ましいでしょうか?独自XML自体が外部ファイルをどう扱うかも重要です。XIncludeなどを援用する、しない。うーむ。

メインの構造をまたぐ構造、たとえば複数段落に対する注釈などについてはrange-startとrange-endのようなタグを作る方式である程度しのげますが、変換後に納得できる構造にできるかは悩ましいところ。

そんなことを考えていると休日が過ぎています。
XMLアプリケーションはそれぞれがそれぞれの用途のために専門化されているので、中間形式のための独自XML規格というのは実は難しいのかもしれません。

DITAで本を書いてAH XSL Formatterで自動組版する

日時
2021年8月10日(火)16:00~17:00
概要
2021年5月18日に公開/販売した『AH XSL Formatter 拡張仕様使いこなしガイド』の制作報告を通し、XML執筆からPDFを作る過程の知見をご紹介します。
DITAについてや、DITAでの書籍制作における実例の紹介や、DITAを扱うときの注意事項など、自動組版やXMLの使い方、DITAに興味がある方、Formatterユーザーさん、必見です!
内容紹介・お申込みページ
こくちーずプロからお申し込み:https://www.kokuchpro.com/event/20210810/終了しました
Zoomウェビナーへ直接お申込みいただく場合: ウェビナー登録ページ終了しました


【ちょっと一息アンテナハウスウェビナー】「DITAで本を書いてAH XSL Formatterで自動組版する」を開催します【8/10】

本ウェビナーは終了しました。

の「ちょっと一息アンテナハウスウェビナー」の告知ページが公開されましたので、当ウェビナー担当者から、ブログ記事でもお知らせします。


DITAで本を書いてAH XSL Formatterで自動組版する

日時
2021年8月10日(火)16:00~17:00
概要
2021年5月18日に公開/販売した『AH XSL Formatter 拡張仕様使いこなしガイド』の制作報告を通し、XML執筆からPDFを作る過程の知見をご紹介します。
DITAについてや、DITAでの書籍制作における実例の紹介や、DITAを扱うときの注意事項など、自動組版やXMLの使い方、DITAに興味がある方、Formatterユーザーさん、必見です!
内容紹介・お申込みページ
こくちーずプロからお申し込み:https://www.kokuchpro.com/event/20210810/終了しました
Zoomウェビナーへ直接お申込みいただく場合: ウェビナー登録ページ終了しました

元々制作報告については何らかの形で行っていく予定でしたが、この度ウェビナーの形で紹介することになりました。

さて、「ちょっと一息アンテナハウスウェビナー」は平日にお時間をいただくこともあり、時間的にはかなりコンパクトになっています。『AH XSL Formatter 拡張仕様使いこなしガイド』の制作にあたっては、トピックとしては「XMLのこと」「XSL-FOのこと」「XSLTのこと」「PDFのこと」「DITAのこと」「学習にあたって参考にした資料のこと」「入稿のこと」「Antenna House XSL Formatterのこと」「原稿、レビューなどの社内環境のこと」など色々とあり、小さくまとめるのはなかなか難しいのですが、今回のウェビナーでは「既存資産がDITA文書ではない状況で、DITAを原稿とした書籍制作の報告」を軸に行う予定です。

上のように書き出してみるとよく分かりますが、XML組版、そしてそれに関連する技術を使うためには押えておく事項が多く「1から10まですべてやる」というのはかなり体力が必要です。自動組版を検討するにあたって「文書作成から組版までのどの過程を自分たちで行い、どの過程を自分たちではやらないようにするか」を判断する一材料としてもお役に立てるかもしれません。

ウェビナー開催まで少し期間がありますので、ご満足いただけるよう鋭意準備を進めていきます。



『Antenna House XSL Formatter 拡張仕様使いこなしガイド』を公開・発売しました

に『Antenna House XSL Formatter 拡張仕様使いこなしガイド』を公開しました。


Antenna House XSL Formatter 拡張仕様使いこなしガイド | AH Formatter XML関連出版物の紹介

また、弊社Webページで公開しているPDF版のほか、AmazonのPrint On Demand(POD)により印刷版をお買い求めいただけます。

Antenna House XSL Formatter 拡張仕様使いこなしガイド | Amazon

書籍の概要や目次についての詳細は紹介ページに掲載されていますが、この記事では少し短くまとめて紹介します。

本書は、W3C勧告のExtensible Stylesheet Language(XSL)1.1のFormatting Object(FO)から、アンテナハウスが独自に拡張した機能について解説しています。本書は次の4章構成です。

  1. 『ショウケース』
  2. 『Antenna House XSL Formatter 拡張仕様と応用例』
  3. 『PDF出力』
  4. 『その他の拡張』

『ショウケース』はAntenna House XSL Formatterを利用してどのようなレイアウトが可能であるのか、サンプルをどんと出してから、どのようにXSL-FOを記述しているかを項目に分けて説明しています。



『AH XSL Formatter 拡張仕様と応用例』では拡張仕様によって可能になる文書構造、利用例を逆引きで掲載しています。「行いたい表現」から対応する仕様を探す際などにお役に立てていただくことを想定しています。

『PDF出力』『その他の拡張』も拡張仕様の逆引き項目を主内容としますが、PDFに特化した機能は多岐に渡り、セクションでまとめるには大変な量となってしまうため、章として独立しています。『その他の拡張』は印刷やオプション設定など、文書内部とは関連の薄い項目をまとめています。

それぞれのトピックは、ほかのトピックへの言及は極力避け、目次、または最後に配置した仕様一覧へと頻繁にアクセスすることを想定した構成になっています。

さて、本書自体もAntenna House XSL Formatter V7.1改訂2版を用いて制作されています。
LwDITAで下書きを行い、DITAに変換し調整、修正を行った後、DITA-OTとPDF5-MLを基に拡張したプラグインでFOに変換、Antenna House XSL FormatterでAmazon PODの要求する仕様に沿ったPDFを出力、という工程です。この詳細についてはまたブログなどでまとめられればと思います。

Antenna House Formatterでは試用版をご用意しています。XSL-FOによる組版、そして本書で紹介しているような拡張を試用してみたい方はぜひお申込みください。
AH Formatter 評価版のお申し込み



LwDITAで(途中まで)ドキュメントを書いてみました

これまでに数回Lightweight DITA(LwDITA)に言及したことがありました。LwDITAやDITAについては記事末尾の関連記事、参考資料をご覧ください。ざっくり書くと、リッチな文書フォーマットとその簡略化版です。

最近、社内でドキュメントにLwDITAを試用して執筆しています。これは少し正確ではなく、より正確にお伝えするなら「執筆していた」となります。現在DITA(ただし一部機能しか使用しない)に移行中となります。

そこそこ文量のあるドキュメントに使ってみての利点、欠点について記そうと思います。一部、実装と仕様どちらに対しての言及であるのか不明瞭である点がありますがご容赦ください。

LwDITAでできること

DITAとしての利点と、LwDITAとしての利点があります。DITAとしての利点はおおよそ次のようになります。

  • DITA文書の一部としてDITA-OTで処理可能
  • conref、keyrefが利用できる
  • トピック単位でファイルを分けて管理できる
  • メタデータに索引用のキーワードを集約できる

LwDITAはDITA文書の一部として、通常のDITAと混在して処理が可能です。管理の観点からすると必ずしも良くはありませんが、「最初LwDITAで書いてDITAへ移行していく」今回の私のユースケースや、「既存資産のDITAやXML形式を利用しつつ新規記述のコストを減らす」といったときに有用です。

conrefやkeyrefはDITAの機能で、簡単に言えばプログラム言語における変数をドキュメント中に使用できます。専門語の揺れを防いだり、URLの変更などに対応できます。長期的に同じドキュメントを使用したいときに便利です。

「トピック単位でファイルを分割して管理できる」、DITAがトピック指向の設計であるので、条件が合致するときは各ドキュメントの構成のシンプルさを保つことができます。後述する「索引の半自動化」に係わるところです。「メタデータに索引用のキーワードを集約できる」というのも大体同じメリットですが、メタデータを書く箇所がフォーマット側で各ファイル単位に用意されているものは実はあまり多くありません。

そして1行では書きにくいメリットとして、構造のどの位置で呼ばれたかによって、適用されるセクションレベルを変更できるという恩恵があります。簡単に例を挙げると、h2レベルの内容の途中で呼ばれた別ファイルの見出しトップレベルはh3と解釈されます。書いているうちにトピックを分割したくなったときなどに有用です。

LwDITAとしてDITAに対する利点は次があります。

  •  単純な最低限のマークアップ(em、strong、italic、リスト……)

メディアコンテンツ対応も地味に仕様としてはDITA1.3より進んでいるのですが、これは出た時期によるもので、実用的にはDITAでも対応されているはず。

さて、とくにMDITA(と一部拡張プロファイルとしてHDITA記法)を利用していたのですが、次の利点があります。

  • MDITAではYAMLフロントマターにkeyword、category、author、source、トピックIDを記述可能
  • DITAに限らず別形式へ変換可能という安心感

メタデータは単純なKeyValue、あるいは簡単な入れ子となるようなものが多いため、汎用エディタを使ってXML形式で記述するのは冗長に感じるときがあります。YAMLでとりあえずパパっと書けるのは楽でした。

最終形をPDFと考えたとき、DITAではやりづらくなる箇所もあるかもということで、別形式にしやすい意味ではMarkdownは安心感があります。その分表現力に制約がかかりますが。

「チームメンバーの記述可能なフォーマットの共通スキルがHTMLやMarkdown」といったケースもありうるかもしれません。

LwDITAでできないこと

  • 対応しているDITAメタデータ(prolog)が少ない
  • 対応しているプロパティ、要素が少ない(特にMDITA)
  • 独自拡張のDITAが対応できない

さもありなんといったところで、作業が進むと、簡易形式ゆえにオミットされた機能が使いたくなってきます。上に挙げた理由で、今はDITA化を進行中です。とはいえ、変換後もLwDITAと対応できない要素はあまり使っていません。

とくにMDITAの不満点として、<note> に対応する記法がありません。以前あった記法もなぜかdepricatedになったので、注やtipsなど、荒涼としたドキュメントにおけるポップでおしゃれなアクセントが書けないのです。

XDITAを飛び越えてフルウエイトのDITAに変換すると、<indexterm>、索引語の指定が使えるようになります。keywordとしてYAMLフロントマターに記述していた語へこのマークアップを行うと、トピックの開始位置に索引が自動でつくように設定できます。入れ子にもできるので索引のサブ項目もほとんど労力をかけずに可能です。

「特殊化したDITA」について軽く触れましたが、AH-DITAという拡張ではfo:propプロパティによってXSL-FO語彙によるスタイル付けをダイレクトに行うことができます。また、図表のフロート配置も<floatfig>で、より自由に行えるようになります。

その他細かいところや全体像などについても、そのうち記事にできればと思います。

参考資料・関連記事


Pages: 1 2 3 4 5 6 7 8 9 10 11 12 Next