カテゴリー別アーカイブ: 構造化文書

DX総合EXPO秋 ご来場者様に『簡単!Markdown+CSSによる冊子本作り ー理論と実践ー』を特別プレゼント

10月1日~10月3日迄、東京ビッグサイトで開催のDX総合EXPO秋のアンテナハウスブースへのご来場者様に、『簡単!Markdown+CSSによる冊子本作り ー理論と実践ー』をプレゼントします。

アンテナハウスブース:東京ビッグサイト南館1F A01-12

ご希望の方に、無料で贈呈致しますが、冊子本の在庫数に限りがございますのでなくなってしまったらご容赦ください。

本書は、Markdownで執筆した原稿を、HTMLに変換した上で、AH CSS Formatterで組版、POD印刷して、製本した冊子本です。Common Markの解説書としてもご参照いただくことができます。

本書の概要

本書の目標は、Markdownで執筆した原稿から冊子本印刷のためのPDF作成までを一気通貫で行う仕組みを設計し、本書自身を素材にして、実践することです。

本書は次のステップで制作されました。本書の内容にはその過程を詳しく報告しております。また、本書の冊子版自体が実践の成果物です。

1. Markdownの仕様について調査してまとめます。
2. 原稿にどのようにマークアップするかのマークアップ仕様を検討・作成します。
3. 原稿のMarkdownファイルを執筆します。
4. 冊子本のパート構成を整理し、本書のパート構成を決めます。
5. 原稿のMarkdownファイルをHTMLファイルに変換するプログラムを作成します。
6. 目次と索引を作成するプログラムを作ります。プログラムでHTMLファイルの内容に目次と索引を付け加えます。これにより本書の本体を自動組版するためのHTMLファイルができ上ります。
7. 本の判型や、ページの基本版面、見出し、段落のレイアウト、本文テキストの修飾などのレイアウト仕様を設計します。レイアウト設計に基づいて、Cascading Style Sheets (CSS)を作成します。
8. HTMLとCSSをAH Formatterに入力し、POD版入稿のためのPDFを作成します。

下記ブログ記事に目次等の情報が記載されています。
https://blog.antenna.co.jp/ILSoft2/archives/10189




瞬簡PDF 統合版 2024
アンテナハウスPDFソフトの統合製品!


HTML on Word
WebページをWordで作る!

『HTML on Word』は聖杯か?

本日(9月9日)『HTML on Word』のWebページに次のようなお客様の声が掲載されました。

海外のお客様なので、原文は英語です。

日本語にしてしまうとあまり面白くありませんが、英語はロマンテックな文章です。原文は次のとおりです。

“I have been chasing the holy grail of word to html for many years now and I must say your software is the most proficient. “

最初に読んだ時、『HTML on Word』が聖杯レベル! と読んで舞い上がってしまったのですが、よく読むとそうじゃないようです。

つまり、長い間WordをHTMLに変換する聖杯を探していたけど、いままで見た中で『HTML on Word』が一番良いという意味なのでした。賛辞には間違いないのですが、聖杯レベルではありませんね。

それにしても、WordからHTMLへの変換ソフトウェアを聖杯に擬えるのって、ずいぶん素敵な表現をするものですね。

WordからHTMLへの完全な変換ソフトを作るのは超難しい。もしそれがあるとすると、それは、聖杯に匹敵するほど伝説的な存在になる(なので、完全な製品は存在しないのだ)と言ってしまうと言いすぎになるのでしょうか。




瞬簡PDF 統合版 2024
アンテナハウスPDFソフトの統合製品!


アウトライナー
PDFを解析して しおり・目次を自動生成

[XSL-FO試行錯誤]索引のページ番号表示で一部を太字にする

索引語に続くページ番号表示。「3,6,11-15,100,…」のように並んでいても、「どこがその語を説明している箇所なのか」は分かりません。そのようなときに、索引表現ではとくに重要・説明的である箇所のページ番号についてスタイルを変えて表現することがあります。これを実現するFOについて考えてみましょう。


「ある箇所について特別な処理をしたい」というとき、必要なのは次の情報です。

  • 「ある箇所」と他を区別するルール
  • 特別な処理を実現するFO

今回の場合、「通常の索引と、重要な1箇所の索引が区別できること」については元のXMLとXSLT処理の書き方によって
大きく異なると思われますので、それらを最終的に落とし込むFOについて検討します。

索引用FOの機能

索引用のFOの基本は、@index-keyによって指定されるキーと、そのキーを表示するための<fo:index-citation-reference>です。

索引 XSL-FOの基礎 第2版

これらのFOでは、該当するキーを含むページ番号について、FOプロセッサが列挙し表示を調整するという処理を行います。
つまり、FOプロセッサというユーザの手を離れた段階で処理されるので、「索引用のFOで一部のページ番号だけを太字にしたい」という要求を実現するには、このFOでは上手くいかなさそうだということを意味します。


索引用FOでは「2ページだけを太字にする」処理は難しい

索引にリンクを付けたい場合はfo:index-citation-list/@page-number-treatment="link"で表示されたページ番号にリンクが付与されます。

汎用のページ番号参照

あるページの参照だけであれば、fo:page-number-citaionに該当箇所のidを指定すれば実現できます。これを利用することにします。
制限として、数ページにわたるページ番号参照には対応できません。

汎用的なリンク用のFOであるfo:basic-linkでは、internal-destinationにidを指定することで内部リンクを付与できます。

よって、id情報があれば、該当の番号のページへジャンプするリンクが付与されたページ番号参照が実現できます。

最終的な方針とFO

重要な箇所の索引をspとします。通常の索引のときは、fo:wrapper/@index-keyを挿入する通常の索引用の属性を、spの索引のときはfo:wrapper/@idを本文に挿入します。このとき、spの前後でindex-keyの値は変えておきます。

本文のFOを通常の索引とspとで切り換える
<fo:block><fo:wrapper index-key="あんてなはうす1"/>アンテナハウスは、Data Usability Companyです。</fo:block>
<!-- spの索引語 -->
<fo:block ...><fo:wrapper id="antenna"/>アンテナハウスは、日本のソフトウェア企業で、XML自動組版ソフトウェアAntenna House Formatterや、PDFに関連した製品を開発・販売しています。</fo:block>
<fo:block ...><fo:wrapper index-key="あんてなはうす2"/></fo:block>
<fo:block ...><fo:wrapper index-key="あんてなはうす2"/></fo:block>

索引ページのFO
<fo:block ... space-after="2rem" font-size="72pt">索引</fo:block>
  <fo:block background-color="black" color="white">あ</fo:block>
  <fo:block text-align-last="justify" text-align="justify">アンテナハウス<fo:leader leader-pattern="dots" leader-alignment="center"/><!--
--><fo:index-page-citation-list merge-sequential-page-numbers="merge"
	merge-pages-across-index-key-references="merge" 
	merge-ranges-across-index-key-references="merge">
	<fo:index-page-citation-list-separator>,</fo:index-page-citation-list-separator>
	<fo:index-page-citation-range-separator>-</fo:index-page-citation-range-separator>
	<fo:index-key-reference ref-index-key="あんてなはうす1" page-number-treatment="link" />
</fo:index-page-citation-list><!--spの索引--><fo:inline>,<fo:inline font-weight="bolder"><fo:basic-link
 internal-destination="antenna"><fo:page-number-citation ref-id="antenna"/></fo:basic-link></fo:inline>,</fo:inline><fo:index-page-citation-list
  merge-sequential-page-numbers="merge"
  merge-pages-across-index-key-references="merge" 
  merge-ranges-across-index-key-references="merge">
	<fo:index-page-citation-list-separator>,
	<fo:index-page-citation-range-separator>-
	<fo:index-key-reference ref-index-key="あんてなはうす2"  page-number-treatment="link"/>
</fo:index-page-citation-list>
</fo:block>

fo:index-page-citation-listは複数のfo:index-page-referenceを持てますが、今回は特別扱いするfo:inlineを挟みたいため、一旦終了して特別処理の箇所の後に別のfo:index-page-citation-listを開始しています。

これをFormatterで組版し、冒頭に上げた画像の索引が作成できました。

補足

実作業で厄介なのはXSLTでの処理時に@index-keyを持たないspを、索引リスト作成時にどのようにして取得するかでしょうか。また、spである索引が登場する場合としない場合、sp前後に同じ語の索引が登場しない場合の「,」表示の分岐など、索引FOが吸収していた面倒な分岐も自前で用意する必要があるでしょう。

索引ウェビナーの宣伝

索引について、もう少し全般的な紹介をするウェビナーを2023年9月19,26日(火)16時に行います。今回の記事は応用実装よりでニッチ度が高いものでしたが、まだまだ話題がありますので、どうぞご検討ください。




HTML on Word
WebページをWordで作る!


アウトライナー
PDFを解析して しおり・目次を自動生成

[CSS組版]ページ番号のリセット

今回紹介するのは「表紙を同一のHTMLから生成するとき、
表紙のページ番号はカウントしたくない」という要望の実現についてです。誤りがあれば、ご指摘いただければ幸いです。

組版にはAntenna House CSS Formatter V7.3MR1を利用しています。スクリーンショット画像の、ページ番号以外の本文内容について画像によって差異がありますが、記事を作りながら都度組版をしていたためで、本題には支障ありません。

CSSページ組版でページ番号を参照するには、content: counter(page)と指定します。

リセット未指定でのページ番号カウントを見てみましょう。

@page {
    size: JIS-B5 portrait;
    margin: 2cm;
    @bottom-center {
        content: counter(page);
        font-size: 24pt;
        font-variant: oldstyle-nums;
    }
}

@pageルールで全体のページレイアウトを設定しています。@bottom-centerでページ番号を表示するように指定していますね。

1枚目のページに「1」、2枚目のページに「2」が振られています。

pageカウンタをリセット

1枚目を表紙ページとして、2枚目のページに「1」が振られるようにしてみましょう。

ところでCSSのカウンタはページ組版に限らない汎用的な仕組みです。pageはページ組版のとき、定義済みのカウンタ名として存在している状態です。
つまり、カウンタリセットの仕組みを使うことで、ページ番号についてもリセットが可能です。

... {
      counter-reset: page 1;
     }

できることが分かったところで、次の問題、すなわち「どのセレクタ(要素・ルール)にリセットを記述するか」に移ります。

今回は「表紙ページ」と「それ以外のページ」という分け方ができます。「表紙用のページレイアウト」、
「本文用のページレイアウト」が用意できると嬉しいわけです。@pageルールでは、そういう処理が書けます。

@page {...}
@page mainmatter {
  counter-reset: page 1;     
}
#cover {
    break-after: always;  
}
div#mainmatter {
    page: mainmatter;
}
<div id="cover">
    <h1>[CSS組版]ページ番号のリセット</h1>
    <p>今回紹介するのは...</p>
</div>
<div id="mainmatter">
    <p>CSSページ組版でページ番号を参照するには、...</p>
</div>

上手くいった……と油断するのはまだ早いです。このままでは、@page mainmatterの対象ページが切り換わる度にpageは1にリセットされるのです。

リセット対象のページを追加で条件付けすることで解決できます。@page mainmatter:firstを追加することで、「mainamtterページレイアウトが使用される最初のページでpageを1にリセットする」という処理になります。

 @page mainmatter:first {
    counter-reset: page 1;     
}

期待する出力になりました。

表紙のページレイアウトからページ番号を削除する

ついでに、表紙ページからはページ番号表示を外しておきます。

@page cover {
    @bottom-center {
        /*bottom-centerのコンテンツを上書き*/
        content:"";
    }
}
#cover {
    /*coverページレイアウトを適用*/
    page: cover;
    break-after:always;
}

参考




瞬簡PDF 統合版 2024
アンテナハウスPDFソフトの統合製品!


HTML on Word
WebページをWordで作る!

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でも使えるというメリットがあります。




瞬簡PDF 編集 2024
かんたん操作でPDFを自由自在に編集


HTML on Word
WebページをWordで作る!

【動画公開】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からあります。




アウトライナー
PDFを解析して しおり・目次を自動生成


瞬簡PDF 統合版 2024
アンテナハウスPDFソフトの統合製品!

速習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回からの流れを受けて、基本的なコードリーディングによる学習ができる段階まで持っていけるようにすることを目標にしています。ご参加をお待ちしています。




瞬簡PDF 変換 2024
PDFをOffice文書へ高精度変換


瞬簡PDF 書けまっせ 2024
PDFに文字が書ける! 入力欄を自動認識

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




アウトライナー
PDFを解析して しおり・目次を自動生成


瞬簡PDF 変換 2024
PDFをOffice文書へ高精度変換

『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を使えたり、文字列結合に「||」を使えるといった枝葉の変更点を使用しています。

参考資料




瞬簡PDF 作成 2024
ドラッグ&ドロップでPDF作成


瞬簡PDF 書けまっせ 2024
PDFに文字が書ける! 入力欄を自動認識

書籍の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版(、そして販売準備中のプリントオンデマンド版も)の完成まで少しだけお待ちください。

参考資料




HTML on Word
WebページをWordで作る!


アウトライナー
PDFを解析して しおり・目次を自動生成
Pages: 1 2 3 4 5 6 7 8 9 10 ... 49 50 51 Next