タグ別アーカイブ: DITA

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


来週に迫る「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ウェビナーへ直接お申込みいただく場合: ウェビナー登録ページ

MDITAをDITAに変換する

さて、前回の記事ではMarkdown DITAとMDITAの違いについて確認しました。
Markdown DITAはMDITAと比べDITA形式へ変換するためのライティング形式の向きが強いという感想を書きましたが、MDITAをDITAへ変換することもそう難しいことではありません。

DITAパブリッシングエンジンDITA-OT[1]には、標準的な出力形式として「Normalized DITA」があります。
Normalized DITAについてはDITA-OTの出力形式についてのページ[2]や弊社の「DITA入門 パブリッシング」のページ[3]でも軽く紹介をしています。外部プロジェクトなどで使用できるように、内部パスの依存関係などを処理した状態のDITAを出力するものです。DITA-OTを使ってMarkdownファイルをDITAのXML形式にするには、この出力を用いるのが便利そうです[4]。XMLオーサリングソフト[5]などではより簡便な方法が用意されているかもしれません。

今回処理するMDITAファイルは次のsample.mdとします。DITA-OTのバージョンは3.4.1を使用しました。

---
id: sampleofmd
keyword:
- markdown
indexterm:
- md
---

# Markdownサンプル {.task}

これはMarkdownのサンプルです。

この文書は`dita --format dita`でDITA形式に変換されます。

## MDITAでセクション

これはMDITAでのセクション例。IDは自動で振られています。

後からの比較のために、MDITAでは記法として有効でないものを含んでいます。

通常のDITAファイルであればDITA-OTは単体ファイルでも変換が可能ですが、
このsample.mdを直接処理しようとすると、エラーを吐きます。

dita -i \topics\sample.md --format=dita -o .
Error: Failed to run pipeline: [DOTJ012F][FATAL] Failed to parse the input file 'file:/d:topics/sample.md'.: file:/d:topics/sample.md Line 1:Content is not allowed in prolog.

とりあえず今回はマップ経由で変換を行うことにします。

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map id="index">
<title>map title</title>
<topicref href="topics/sample.md" format="mdita" />
</map>

結果を見ると、指定した場所にマップファイルとフォルダ構造を保った
トピックファイルがあります。フォルダへ移動すると、sample.mdファイルがありますね。
……? md? と思いながらファイルをエディタで開いてみると、拡張子はともかく
DITAのTopic情報タイプになっています。


<?xml version="1.0" encoding="UTF-8"?><?path2rootmap-uri ../?>
<!DOCTYPE topic
  PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="sampleofmd"><title>Markdownサンプル {.task}</title><shortdesc>これはMarkdownのサンプルです。</shortdesc><prolog><metadata><keywords><keyword>markdown</keyword></keywords></metadata><data name="indexterm" value="md"/></prolog><body><p>この文書は<codeph>dita --format dita</codeph>でDITA形式に変換されます。</p><section id="mditaでセクション-secid"><title>MDITAでセクション {#secid}</title><p>これはMDITAでのセクション例。IDは自動で振られています。</p></section></body></topic>

topic のidはYAML Frontmatterで指定した通りになっています。
{」「}」囲みで要素の追加マークアップを行う記法は処理されず、
そのままタイトルに残っていますね。

本文の最初の段落はshortdescに格納されています。

YAML Frontmatterと変換後のPrologを見ると、
keywordskeywordは想定通り処理されています。
一方でindextermは汎用のdata要素
namevalueとして格納されてしまいました。
YAML FrontmatterのKeyValueはLwDITAの対応範囲内で処理されていることが分かります。

セクションを切った箇所では、Markdown記法の見出しが、
sectionidの値として自動で振られています。ここも記法が対応していないので、
{」「}」で囲われたマークアップは処理されていません。id内では記載できる文字の関係か、
微妙に表記が変わっています。

本文段落、
`」「`」で囲われた箇所が<codeph>に変換されているのが確認できます。
もし<pre>になることを意図していた場合はExtended Profileでタグを直接書きます。

それでは、md.ditamapのtopicrefformatを書き換え、
これをMarkdown DITAと認識させてDITAに変換してみましょう。

<topicref href="topics/sample.md" format="markdown" />

先程と同様にマップをDITA-OTの入力に指定します。

<?xml version="1.0" encoding="UTF-8"?><?path2rootmap-uri ../?>
<!DOCTYPE task
PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<task id="markdownサンプル"><title>Markdownサンプル </title>
<prolog><metadata><keywords><keyword>markdown</keyword></keywords></metadata>
<data name="id" value="sampleofmd"/>
<data name="indexterm" value="md"/></prolog>
<taskbody><context>
<p>これはMarkdownのサンプルです。</p>
<p>この文書は<codeph>dita --format dita</codeph>でDITA形式に変換されます。</p>
</context>
</taskbody>
<task id="secid"><title>MDITAでセクション </title>
<taskbody>
<context><p>これはMDITAでのセクション例。IDは自動で振られています。</p></context>
</taskbody></task></task>

トピックタイトル行で設定したtaskが反映されています。一方で、YAML Frontmatterに記述したidは先程のindextermのように扱われ、topicのidにはなってくれていません。さらに、構造が色々壊れたものが出力されていますね。変換のコード実装を読まないとなんとも言えませんが、Strict Taskを想定しているのであればsectionは出現しませんから、Markdown DITAを書く場合には、より取り得る要素に注意しながら記述する必要があるということでしょうか。

MDITAをDITAに変換しました。Markdown DITAとの違いに注意する必要はありますが、
ドキュメントの段階的なDITAへのステップとして、
あまりピーキーではない制約のMarkdown文書をDITAの形式へ変換できることは
確かに悪くないと感じました。

DITAやDITA以外のXMLをMarkdownに変換する方向の試みも存在します。
次週はこのアプローチについて述べる予定です。

  1. [1] DITA-OT
  2. [2] Normalized DITA – DITA-OT
  3. [3] DITA-OTの対応する出力形式
  4. [4] Markdown content – DITA-OT
  5. [5] XML/DITA関連製品 – アンテナハウス

DITA/XML - Antenna House

関連記事
XMLエディタで始めるリッチなMarkdown入門?
MDITA(LwDITA uses Markdown)の書き方
DITAとしてのMDITA
Markdown DITAとMDITA
XMLをMarkdownに変換することについて

「自動組版エンジン【AH Formatter V7】セミナー 」を3/6に開催します【2/27追記:中止のお知らせ】

2/27追記:3/6日に開催を予定しておりました「自動組版エンジン【AH Formatter V7】セミナー 」は新型コロナウイルス感染症に関わる状況の急激な変化を鑑み、開催を中止いたします。

概要

大容量・多言語データに最適な自動組版ソフト【AH Formatter】が、8年振りのメジャーバージョンアップを行いました。その新機能の説明と最新の海外動向、事例紹介、及びDITAに関する簡単なセミナーを行います。

【AH Formatter】は、独自開発した PDF出力エンジンで、
アクセシブルなタグ付きPDF や印刷用の PDF/X、長期保存用の PDF/A などさまざまな PDF形式の出力ができます。

 セミナー内容

AH Formatter 20年の歩み
アンテナハウス 小林 徳滋

AH Formatter V7.0 新機能紹介
 アンテナハウス 額賀 正彦
PDFもDTPデータもハイブリッドで提供可能 自動組版クラウドサービス「DOT3」でのFormatter利用事例
株式会社 ニューキャスト 川原 正隆 様
求人・クーポン・住宅などの情報誌からメーカーや商社発行のカタログなど様々な商業印刷物をクラウド上のFormatter(ASPライセンス)でPDF生成しています。
また、同じデータをInDesignで編集可能なIDMLにも変換してハイブリッドな提供を実現している事例をご紹介します。

AH Formatter 海外動向
アンテナハウス 平出 桂子
Tangeloは企業用レポートを作成するためのソリューションを西ヨーロッパ、北米、アジア太平洋地域のクライアントに提供しているアンテナハウスのパートナーです。TangeloがAH Formatter を使ってどのようなサービスを提供しているかをお伝えします。
DITAの「コンテンツ再利用」について
 アンテナハウス 小林 具典
DITAの大きな目標のひとつである「コンテンツ再利用」の仕組みを説明します。
またこの仕組みを上手に利用することにどういうメリットがあるのかにも触れます。

タイムテーブル

 開始  終了
13:15 13:30 受付開始
13:30 13:35 ご挨
13:35 14:05 AH Formatter 20年の歩み
14:05 14:35 AH Formatter V7.0 新機能紹介
14:35 15:15 事例紹介 ニューキャスト様
15:25 15:55 AH Formatter 海外動向
15:55 16:25 DITAの「コンテンツ再利用」について
16:25 16:45 質疑応答

会場

日時 2020年3月6日(金)13:15~16:45
 会場  関東ITソフトウェア健康保険組合 1FA
 住所 東京都新宿区百人町2丁目27-6

参加登録は次のページで受け付けております。

「こくちーず」で参加登録

AH Formatterのページはこちら


DITA Festa 2020 京都

まだ DCJ(DITA コンソーシアムジャパン)から公式な発表はありませんが、どうやら3月の中ごろに「DITA Festa 2020 京都」の開催を計画しているようです。おそらくですが、昨年11月に開催された「DITA Festa 2019 東京」の中から特に評判の良かったセッションをそのまま京都まで持って行くと思われます。
近日中にDCJから公式発表があると思いますので、関西方面でDITAに興味ある方はぜひご参加を。

DCJの公式サイトはこちら(https://dita-jp.org/)です。


oXygen 21.1 がリリースされています

oXygen のカレントバージョンは21.1です。古いバージョンをお使いの方はバージョンアップをご検討ください。

主な機能強化点は次のとおりです。

■ DITA 関連

  • 生成される WebHelp(日本語)の検索処理の改善
  • DITA マップやトピックから参照されるリソースの階層/依存関係の表示
  • 関連リンクとして追加できるトピックを素早く見つけられるように
  • 画像の挿入前にプレビュー確認

■ HTML 関連

  • 現在の編集場所で有効な要素、属性、および値の提案、多くの提案の注釈、およびHTML5仕様へのリンク

■ JSON 関連

  • JSON インスタンスを生成するためのさまざまなオプションを設定できるダイアログボックスを新設

その他多数の強化が行われています。詳しくは ここ をご参照ください。


「DITA Festa 2019 Tokyo」開催です

恒例の DITA Festa がやって来ます。
2019年11月27日(水)、28日(木)の二日間、場所は市ヶ谷駅のすぐ目の前です。

今回は、オムロン殿、日本電気殿、ローランド ディー.ジー.殿から DITA の導入事例発表があります。すでに受講受付が始まっていますので、興味のある方はお早めに。参加費は無料です。

詳しくは こちら をご参照ください。


XMetaL Author Enterprise 14.0(英語版)

昨日 に引き続き XML エディターの紹介です。
かつて、DITA を入力するにはこれしかない、とまで言われた XMetaL です。もちろん現在でも多くのお客様がお使いです。

今日時点での最新バージョンは 14.0 で、残念ながらまだ日本語版はありません。
14.0 では次のような機能拡張が行われています。

  • 「Workbench」機能搭載
    XMetaL Author の複数のソースから文書を素早く簡単に表示および編集する機能です。
  • Lightweight DITA XML トピックおよびマップの編集をサポート
  • 検索/フィルタボックス追加
    XMetaL をカスタマイザして、このダイアログに独自の設定パネルを追加することができます。
  •  [検索と置換] ダイアログ機能強化
  • 変更履歴表示機能
    変更履歴が DITA 再利用コンテンツに表示されるようになりました。
  • DITA Open Toolkit Release 3.2.1、2.4.4、および 2.0 搭載

下記から評価版をダウンロードできますので、ぜひお試しを。
https://xmetal.com/content-xmetal-author/

ちなみに「XMetaL」の表記ですが、大文字だけ抜き出すと「XML」なんですね。

xmetal-cap


oXygen XML Editor 21.0

自動車の取説、プラント制御システムの取説、航空機の取説等、マニュアル制作の現場では DITA を使って原稿執筆をするケースが増えています。このとき執筆ツール(XMLエディタ)として oXygen が注目されています。

今日時点での最新バージョンは 21.0 で、次のような機能拡張が行われています。

  • DITA 関連
    ・DITA 再利用可能コンポーネントビューの改善
    ・パスの大文字・小文字の間違いをすばやく訂正
    ・ルートマップから keys 定義を収集・検証
    ・画像の挿入前にプレビュー確認
  • WebHelp 関連
    ・検索結果にパンくずリストを表示
    ・DITA-OT 3.xに互換性のある WebHelp
  • XSLT
    ・XSLT 3.0のサポートが改善
    ・属性および要素関数の内容を補完
  • その他
    ・文書を自動的に回復(ドキュメントを自動的にバックアップ)
    ・属性ビューで ID を自動的に生成
    ・置換ボタンで1箇所のみを置換

下記から評価版をダウンロードできますので、ぜひお試しを。
https://www.oxygenxml.com/xml_editor/download_oxygenxml_editor.html

oxygen-cap


海外出展情報 その2

DITA North America (続き)

<< DITA North America(前回)
セッションの合間には、展示室で出席者と出展者が集まる休憩がありました。 この会議の出展者の大部分はアンテナハウスのパートナーでしたので、彼らと再会し、今後のソフトウェア機能を確認し、パートナーシップを強化するための様々な機会について議論する絶好の機会でした。 既存のお客様はもとより初めての訪問者も、当社の製品に対する要望、問題を解決する方法についての質問、当社が提供するより多くの他の製品を知ることに興味を持っていました。 全体として、今年のカンファレンスでの参加率、ブースでの関心の高さ、そしてパートナーやクライアントとの興味深いディスカッションを通じて、満足のできる結果であったと思います。

さて4月は展示会がとても多い月です。ちょうど今ネバダ州のラスベガスで Xplor International に出展している最中です。また4月29日にはアラバマ州ハンツビルで開催の AIA Product Support に参加する予定です。いずれもお客様、パートナーとの情報共有の大変良い機会となり、アンテナハウスが健全で成長し続けている企業であることを示す良い機会となることでしょう。

今朝ほど丁度 営業担当から、Xplor International の報告が届きましたので、合わせてご紹介いたします。

Xplor International

アンテナハウスが CCM およびデジタルドキュメントの専門家のための Xplor19 に参加するのは今年で3年目です。 Xplor19 は今年から大きくイベントの変更がありました。 過去10年間、フロリダ州オーランドで開催された単独のイベントだったのですが、今年 Xplor は、ISA International Sign Expo との提携を発表し、カンファレンスをネバダ州ラスベガスに移しました。 今後、カンファレンスの開催は、オーランドとラスベガスで交互で行われます。 2つのカンファレンスは独立したイベントとして運営し続けますが、出席者は両方のイベントの特典を体験、享受できるよう、特別なオファーや招待状を受け取ることができます。 今年は開催のスタイルにも変更がありました。イベントは夕方に始まり、一般的なセッションのトラックは出展者と同じホールで行われました。一方ビジネステクノロジー、デリバリーテクノロジー、マーケティングテクノロジーは他のホールで行われました。

アンテナハウス(海外サイト)
http://www.antennahouse.com/

http://rainbowpdf.com/


Pages: 1 2 3 Next