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

XSL-FO 試行錯誤 SVG 2.0 inline-sizeのTips

2023年01月19日に『Antenna House Formatter V7.3』がリリースされました!
関連して、2023年01月31日(火)16:00-17:00 にZoomウェビナーとして『Antenna House Formatter V7.3 リリース!  新機能と利用シーン紹介』を開催します。


https://us06web.zoom.us/webinar/register/4716717860524/WN_ElB-ZrzFQzShzKGqWZMHqg

新機能紹介ということで、XSL-FOやCSSページ組版の基礎知識があることを前提としています。しかし、特に知識の無い方でも「自動組版でこんな細かいレイアウト調整が効くのか」と楽しめることを目指していますので、お時間が合いましたら是非参加登録いただければ幸いです。

ウェビナースライドはFormatter V7.3で組版しています。スライドはCSSで組んでいるのですが、話題がSVGについてなので、暫くぶりとなる「XSL-FO 試行錯誤」シリーズを題に含めました。
(前回のXSL-FO試行錯誤のカレンダー作成の続きについてはまた時間があるときにさせていただければ……)

さて、本記事ではウェビナーで割愛する部分について、先行して補足します。
ということで、見た目が地味なのであまり深く掘り下げない予定のinline-sizeによるテキストの折り返しについてです。

発表スライドの見出し部分にはSVG 2.0を使っています。

テキストを配置するとき、SVG 1.xでは折り返しを扱えませんでした。
よって、複数行のテキストを配置するときは次の手順(これ以外にもなくはないですが)です。

右揃えで3行でテキストを描画するとします。座標は適当です。

  1. 改行位置でテキストを分割し、別のtspanに分ける
  2. それぞれのtspanにx,yの座標を指定する。2行目であれば1行目から1文字分以上離れた位置にyを設定する
<!-- SVG 1.x -->
<text x="0" y="0">
<tspan text-anchor="end" x="250" y="0">Formatter V7.3</tspan>
<tpsan text-anchor="end"  x="250" y="10">リリース!</tspan>
<tspan text-anchor="end"  x="250" y="20">新機能と利用シーン</tspan>
<text>

text-anchor=”end”によって、xの位置がテキストの終端になっています。

x,yはSVG内の座標系なので、font-size:18ptのように絶対単位で指定されていると対応する高さを調整するのはちょっと手間ですね。
他にも拡大縮小の際などにこれを忘れずに変更しなければなりません。

メリット、といえるかは分かりませんが、あらかじめ分割しているので、意図しない行分割が発生するということはないでしょう。

SVG 2.0のテキスト折り返し機能を使えば、折り返しを自動化可能です。Formatter V7.3ではinline-sizeによる折り返しをサポートしています。
Scalable Vector Graphics (SVG) 2 11.4.1. The ‘inline-size’ property



<text x="0" y="0" inline-size="1000">Formatter V7.3リリース! 新機能と利用シーン</text>

inline-sizeにはテキストの行長を指定します。

  • 両端揃えができない
  • 日本語は行頭・行末禁則以外では基本的に改行可能と判断される

また、見出しのような箇所で使う場合、次のことを意識しておくとよいでしょう。

今まで手動でやっていた行分割を自動処理にする都合上、特に、本文でない箇所での行分割規則は意識しておかなければなりません。
言語処理が日本語になっていれば(xml:lang=”ja”が適用されるような箇所であれば)
意図してそうしない限り「ー」は先頭に来ませんが、「リ」はそうではないので、

Formatter V7.3 リ
リース!

となるかもしれません。

特定単語の行分割を防ぐため、その箇所のマークアップをtspanにして、分割禁止のプロパティを付けることにします。
「tspanを使うなら結局SVG 1.xとあまり変わらない?」と思われるかもしれませんが、座標の明示がなくなるので処理はかなり単純化します。
「この単語で行分割されるのは困るが、ここ以外であれば別に構わない」というケースが多いとみているのですが、どうでしょうか。

<!-- <heading>Formatter V7.3<keep>リリース!</keep><keep>新機能</keep>と<keep>利用シーン</keep></heading> -->
...
<xsl:template match="heading">
  <svg:svg viewBox="0 0 1920 1080" >
  ...
    <svg:style>
      svg|tspan.keep {
        word-break: keep-all;
      }
    </svg:style>

    <svg:text x="1800" y="100" text-anchor="end"><xsl:apply-templates mode="#current"/></svg:text>
  </svg:svg>
</xsl:template>
...

<xsl:template match="keep">
  <svg:tspan class="keep"><xsl:apply-templates mode="#current"/></svg:tspan>
</xsl:template>

上記は実際に使用したコードではないため、参考程度にお考えください。
inline-sizeが対応するalign調整はtext-anchorによるものになるため、両端揃えの自動配置はできません。

その他、SVGのテキストを使う場合の注意点として、FOのブロックやHTMLのテキストと異なり、
「viewBoxは伸長しないため、想定よりテキストが長くなると表示が見切れる」という点があります。
つまり、「ページ単位で表示領域を確保できる」など、特に高さ・テキスト長があらかじめ想定できる
範囲で使うようにするとよいでしょう。

そして、Formatter V7.3で対応したSVGフィルタ・マスク機能と組み合わせることで文字列に効果を付加できます!

SVGテキストとマスク

画像に対し、テキストをマスクとして被せたものになります。このSVGではtext-anchor=”middle”です。
実のところ、SVGマスク以外の方法もあります、ただ、SVGマスクやフィルタは汎用的ですし、追加の独自仕様無しでXSL-FOでも使えるというメリットがあります。


【動画公開】XSLT超入門3, CSS組版スライドと補足

ちょっと一息アンテナハウスウェビナー「XSLT超入門 3 XPathについて」を終えました。ご視聴いただいた方、ありがとうございます。お時間の合わなかった方、動画が公開されたので、ぜひご覧ください。


Zoomの注釈機能

発表直前に気付いたのですが、Zoomの「画面の共有」ボタンの横に、いつの間にやら「注釈」というボタンが増えていたので早速使ってみました。いかがでしたでしょうか。

PowerPointスライドと違い(おそらくほとんどの)PDFビューアにはレーザポインタ機能がないので、助かりますね。(他機能として、テキストも表示できます。スライド表示中に「これ補足した方がいいかな」といった思いつきでテキストを追加したりはPDF注釈でも実現できますが、操作の切り換えの手間があるため、Zoomにあるに越したことはない、くらいの感想です。)

CSS組版スライド

担当したここ数回のウェビナーではPowerPointでスライドを作成していました。今回も途中まではそうだったのですが、内容の大幅な修正を行うついでにAH FormatterでHTML+CSS組版によるPDFスライドに移行しました。

以前XSL-FOでスライドを組版したことを紹介しました。スライド発表程度の長さであれば単一HTMLでもあまりテキスト分量はかさみません。今回、HTMLが650行弱、CSSは240行程度でした。実作業としてはSCSSで記述して変換していたので……240行程度でした。まあ、セレクタ部分は簡潔になりますが、改行・インデントとしてはあまり変わらないんですね。CSSについてはAH CSS Formatterの既定のCSSを読み込んだ上でなので、0から組むのであればもう少し嵩むでしょう。

VS CodeでSCSSを編集 with AH CSS Extension

SCSSの編集はVS Codeで行いました。VS CodeでのCSSの補完・サジェストについては、@media printなども最初からある程度対応しています。
加えて先日、AH CSS Formatterの豊富な拡張仕様を入力補助してくれるAH CSS Formatter Extensionが公開されたので早速使っています。SCSSファイル編集でも有効なようです。

https://github.com/AntennaHouse/ahformatter-vscode-css-ja

「HTMLソースでスライドを作成する」というと、気になるのは「発表スライドとWebページを同時作成できるか?」という点ではないでしょうか。結論としては「内容次第」ということに落ち着いてしまうのですが、「ある程度まで同一ソースで作成する」ことを目標とすると、方針として押さえるべき点は次のことでしょう。

  • HTMLソースはWebページ向けが主、スライドは従
    • スライド組版時はdisplay:noneにする情報を決めておく
    • スライド向けCSSを先行する場合、とくに注意するのはfloat配置とheightの100%

もちろん、広告を目的とするWebページなどで一度に入る情報量を絞ることなどはよくあります。ここではある程度技術的内容のプレゼンとそのWebページ化を前提としています。

スマホ向けとPC・タブレット向けのページを同じソースで作成する場合にスマホ向けをメインにレイアウトすることを「モバイル・ファースト」といったりしますが、Webページとプレゼンテーションの関係はもう一捻りあります。
モバイルとそれ以外で異なるのは、主に画面サイズです(より正しくは前提とする通信環境によるリソースの出し分けなどもあります)。
一方、Webページとプレゼンにおいて、Webページはそれのみですが、プレゼンは(通常)「スライド+発表者+発表」で構成されます。この違いは「読者側が受動的か能動的か」「発表者による注意対象・情報量のコントロール」といった差異を生みます。

HTMLソースの話に戻ると、ある変換を行うとき、情報量は落とす方が楽で、足すのはかなり困難です。
つまり「より情報量を必要とする方を主とし、そうでないものを従とする」ということになります。
プレゼンは発表という追加情報を前提とするため、スライドにWebページと同じ情報量を与えると情報量が過多になりがちです。

CSSでは手軽に表示を隠蔽する方法としてdisplay:noneがあります。これは、プレゼンでは口頭で与える情報を、Webページではテキストで表示する、という目的にも使えます。

@media print {
.web-page-only {
  display:none;
  }
}

前提として、「スライド上隠蔽されても前後の話は分かるようにする」というライティングが必要です。なので、パラグラフライティングの基本や、DITAにおけるshortdescのように、「これは最低限最初に伝える」という文章から書いていくよいでしょう。

ページ向け媒体ではフロートはページの上端、下端を前提に書けます。これはpositionについても同様です。

XSLT超入門3の補足

さて、発表の補足です。

何度か述べましたが、XPathの特長は、簡単には「ある文書で、目的の箇所を簡便な記法で指定できる」「取り出した値の加工が行える」ことにあります。ただ「hoge/fuga/…」と書きつらねるだけでなく、軸や述部といった機能・概念を使うことで、他の言語、というかDOMインターフェイスでは難しいこともスマートに行える、ということをXSLT超入門3ではフューチャーしたのですが、いかがでしたでしょうか。
「ここが分からないのでここをじっくりやってほしい」などの要望を、メール・SNS・動画へのコメントなどでいただけると幸いです。

さて、発表について、事前の予定から大きく削った箇所としては2箇所です。データモデルと、XPath 1.0のコードを3.1でリライトするという内容です。

データモデルについては、XPath 2.0でいかに整理されたか、3.0(3.1)で何が拡充されたか、の詳細を削りました。このあたりについてはW3CのXDMのページに図示があるので内部処理モデルに興味のある方はご参照ください。

XPath 3.1でのリライトについては、題材として丁度良いバランスのものを見つけるのはかなり難しかったため、構成から削除しました。「XPath 1.0でまともに処理できるように記述した上で、XPath 3.1で明らかに改善されるように書き直す」ということの難しさは、「そもそも1.0で書けなかった処理を拡充したものがほとんど」「1.0では(XSLT上では)独自functionの定義もできないので、XSLTも多分に含むことになる」といった点にあると感じます。XSLT 1.0のコードでの超絶技巧についてはfunctXライブラリが有名でしょうか。

超絶技巧はおいておいて、もう少し簡単なものはあります。

XPath 1.0(XSLT 1.0)
<xsl:template match="*[contains(@class, ' topic/ph ')]"> 
  ...
</xsl:template>
XPath 3.0(3.1) (XSLT 3.0)
<xsl:template match="*[contains-token(@class, 'topic/ph')]"> 
  ...
</xsl:template>

行っているのはDITAの@class処理で、スペース区切りで続く文字列の部分一致判定です。contains()では含まれてさえいれば真を返してしまうので、topic/ph前後にスペースは必須です。ないと「mytopic/ph」なども一致してしまいます。
contains-token()は、なんだったら名指しで「HTMLやDITAのclass処理に使えるよ」と書かれているのでさもありなん。

コア関数についてはかなり駆け足で紹介しました。コード例をバーッと載せていましたが、コードをしっかり読んでもらうことは意図していません。
これは構成上割と悩みどころで、関数名と処理内容を淡々と流すのであれば、ウェビナーよりもWebサイトや本などを参照するように誘導しても良いと考えています。あるいは数時間~数日のワークショップであれば、サンプル、基本、応用、基本、……といった進め方をしたと思います。

とくにXPath 1.0では、関数型言語らしい「関数を組み合わせて使う」ことはなかなか難しいため、その有用性のアピールを分かりやすく行うのは難しくなっています。

発表中、contains()が(2.0)となっていましたがこれは記述ミスで、XPath 1.0からあります。


速習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まですべてやる」というのはかなり体力が必要です。自動組版を検討するにあたって「文書作成から組版までのどの過程を自分たちで行い、どの過程を自分たちではやらないようにするか」を判断する一材料としてもお役に立てるかもしれません。

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



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