1. TakashiI Avatar TakashiI
  2. Untitled project
  3. conf2dita

Wiki

Clone wiki

conf2dita / Home

View History

About

This Confluence plugin is able to authoring DITA on Confluence.

But I am not nearly know that of DITA and has never made a writing in DITA, nor that it has the output. I created this plugin as I think if there is an output format XML format DITA to the Confluence whether not spread the use range of Confluence.

Confluence Version what I checked.

  • 5.3.1
  • 5.7.3
  • 5.8.9

DITA Version.

1.2

Requirement other plugin

Since this plugin treats DITA elements as Confluence Macro, so we need Confluence macros corresponding to DITA elements. So, I make this DITA Macros Confluence plugin.
Please install this Macro plugin.

Writing DITA

  • Using Confluence DITA Macros, you can write Confluence pages as DITA.
  • You need not input body/conbody/taskbody Macro. It will be automatically added at the time of conversion.

Define topic type

Topic type is determined by the Confluence label. Topic type will be determined at the time of conversion to DITA by putting a prefix of "dita-" to the label name.

ex) A Confluence page labeled "dita-concept" is treated as concept topic type.

Setting DITA properties

  • Properties about DITA topic can be set from panel positioned Confluence editor left bottom.
    Clipboard03.jpg now only dita topic id that you can be set.
  • Confluence Macro property is treated as DITA property.
  • Without using Confluence DITA macro elements (that can be written directly from the Confluence editor) can not propeties be set. For example, character decorative elements such as bold, italic, underline, list elements, and list elements UL / OL property can not be set.

About Table

Clipboard02.jpg

  • For tables, you have to wrap HTML-table in DITA table Macro, such as {dita-table}, {dita-simpletable} or {dita-choicetable}.
  • To Setting properties to tables, rows and cells
    1. Properties of table itself are set by Confluence Table Macros' property.
    2. Rows properties are set by click "set dita table row property" icon in Confluence Editor Table Toolbar.
    3. Cells properties are set by click "set dita table cell property" icon in Confluence Editor Table Toolbar.
  • You cannot set rows and cells properties when a new page production. Please set from once saved.
  • Temporarily, setting properties to table function is removed at version 1.0.3.

Export Confluence as DITA

Select "Export DITA" in Confluence Page tool menu.

export_dita.png

There is options such as whether you export with child pages.

export_dita_options.png

Import DITA to Confluence page

Please be in ZIP file when performing the import. When only a of DITA file, please import in the ZIP.

Open a Confluence page where you want to import under there, and Select "DITA Import" from page tool menu.

import_dita.png

When you import, you can choose three of import option below

  1. Arranged in a flat under this page.
  2. Reflects the folder structure of the ZIP.
  3. Use dita map file.

import_dita_options.png

Sample Import DITA file

You can download sample dita import files.

Limitation

Supported topic types

  • topic
  • task
  • concept

Import or export size limitaiton

It dependss on Tomcat HTTP timeout length. There is a possibility that caused the HTTP timeout within that does not fit to the process is finished trying to process a large DITA and the number of large amounts of page too. We feel the future it is necessary to change the task processing.

Unsupported matters

I can not write too there...

Ask!

Please support me. such as...

  • About Authoring DITA.
  • Test code.
  • Translation. (Special thanks Google translation!!)

-------------------------------------

概要

このプログラムは、ConfluenceでDITAを記述するためのプラグインです。 作者はDITAのことをほとんど知りません。実際にDITAで執筆をしたことも無ければ、出力をしたこともありません。Confluenceの出力形式にDITAというXML形式があるとConfluenceの使用範囲が広がるのではないかと思いこのプラグインを作成しました。

動作確認しているConfluenceのバージョン

  • 5.3.1
  • 5.7.3
  • 5.8.9

ベースとなっているDITAのバージョン

1.2

追加インストールが必要なもの

DITAのタグに相当するConfluenceのマクロが必要です。 こちらのConfluenceプラグインをインストールすることで、本プラグインで使用できるDITAのConfluenceマクロを追加できます。

DITAの執筆

  • DITAのタグを入力する要領でConfluenceのマクロを入力していきます。マクロのプロパティはそのままDITAのプロパティとして扱われます。
  • body/conbody/taskbody系のタグは使用する必要がありません。変換時に自動的に付加されます。

トピックタイプの指定

トピックタイプは、Confluenceラベルにより決定されます。
ラベル名に「dita-」のプレフィクスを付けることでDITAに変換時にトピックタイプが決定されます。

プロパティの設定について

  • DITA自体へのプロパティは、Confluenceエディタ左下の
    Clipboard03.jpg から<d>アイコンをクリックしてください。現在はIDの設定しかありません。
  • DITAタグへのプロパティは、Confluenceのマクロプロパティを使用します。
  • DITAマクロを使わずに、Confluenceエディタから直接執筆できる要素はプロパティが設定できません。太字・イタリック・下線などの文字装飾要素や、UL/OLなどのリスト要素はプロパティが設定できません。

表組みについて

Clipboard02.jpg

  • 表組みは、表自体を{dita-table}や{dita-simpletable}、{dita-choicetable}で囲ってください。
  • 表組みのプロパティ設定は、下記の通りです。
    1. 表自体のプロパティは囲っている表マクロで設定してください。
    2. 行のプロパティは、エディターの「set dita table row property」のボタンから設定してください。
    3. セルのプロパティは、エディターの「set dita table cell property」のボタンから設定してください。
  • 表組みのプロパティは新規ページ制作時には設定できません。一旦保存してから設定してください。
  • version 1.0.3で表組みへのプロパティ設定機能を一旦削除しました。

ConfluenceのDITAファイルをエクスポートする

DITAとしてエクスポートしたいページのツールメニューから選択してください。
export_dita.png

エクスポート時には、子ページを含んでエクスポートするかなどのオプションがあります。 export_dita_options.png

既存のDITAファイルをインポートする

インポートを行う際はZIPファイルにしてください。1つのDITAファイルでもZIPにしてインポートしてください。

配下にインポートしたいページに移動し、ツールメニューから選択してください。
import_dita.png

インポートする際には、下記の3つのインポートオプションが選択できます。

  1. ZIPの構造に関係なくフラットに展開
  2. ZIPの構造そのままをConfluenceのページとして展開
  3. DITAMAPに沿った展開

import_dita_options.png

インポートのサンプルファイル

インポート用のサンプルDITAファイル がありますので、ダウンロードしてインポートしてみてください。

制限事項

対応しているトピックタイプ

現在、下記のトピックタイプに対応しています。

  • topic
  • task
  • concept

インポート・エクスポートのページ数

TomcatのHTTPタイムアウトに依存します。 あまり大きなDITAや多量のページ数を処理しようとすると処理が終了しきらないうちにHTTPタイムアウトを起こしてしまう可能性があります。将来的にタスク処理に変更する必要があると感じています。

未対応事項

有り過ぎて書ききれません。。。

ご協力ください

以下の内容について、ご協力いただけると改善につながります。

  • DITAのノウハウ。現場での使用パターンなど。
  • Confluenceプラグインのテストコードの書き方、テスト実行方法について。
  • 翻訳精度

Updated