Wikiで書籍を執筆するためのプラグインを作ってみた

FSWiki

共著の場合はWordやOpenOfficeだと同じファイルをいじったときにコンフリクトするのが問題なのでWikiで書籍を執筆できないかなぁ…ということで、FSWikiで書籍の執筆に必要そうなプラグインを作ってみました。まだソースは手元にしかありませんが、概ね以下のような感じです。

章、見出しの作成

1ページで1章分の原稿を執筆することを想定しています。各ページにはchapterプラグインで章の情報を記述します。また、見出しは普通のWikiの見出しの記法で記述するのですが、title1、title2、title3プラグインで見出し番号を表示できるようにしました。title1、title2、title3プラグインは見出しへの相互参照にも使用しますが、相互参照の方法については後述します。

{{chapter 1,章のタイトル}}
!!!{{title1}}見出し1
...
!!{{title2}}見出し2
...
!{{title3}}見出し3
...

ソースコード

FSWikiにはpreタグで囲んで出力するための記法やプラグインがあるのでそれを使ってもいいのですが、Web上で参照するときはシンタックスハイライトされていたほうが見やすいよね、ということでgoogle-code-prettifyを使用して強調表示を行うためのプラグインを用意しています。

{{list
public class HelloWorld {
  public static void main(String[] args){
    System.out.println("Hello World!");
  }
}
}}

図表番号

captionプラグインを使用すると図表番号を付与することができます。第一引数に種別（表、図、リストなど）、第二引数にキャプションに表示する文字列を指定します。

{{caption 表,StringUtilsのメソッド一覧}}
,メソッド名,説明
,boolean isEmpty(String str),文字列がnullまたは空文字列かどうかを判定
,boolean isNotEmpty(String str),文字列がnullまたは空文字列でないかを判定
...

見出し同様、図表にも相互参照をはることができますが、相互参照の方法については後述します。

アウトラインの表示

FSWikiではoutlineプラグインでページの見出しのアウトラインを表示することができますが、新たにtocプラグインというプラグインを追加しています。tocプラグインを使用すると見出し番号付きのアウトラインを表示することができます。

{{toc}}

また、tocプラグインはデフォルトでは現在表示しているページのアウトラインを表示しますが、引数にページ名を指定することで指定したページのアウトラインを表示することができます。このため以下のようなページを作成しておくことで書籍全体の目次を作成することができます。

!!!目次
!!第一章
{{toc Chapter1}}
!!第二章
{{toc Chapter2}}
...

outlineプラグインはページの先頭に入れて使うことが多いですが、tocプラグインをサイドメニューに入れておくことでWordの見出しマップのような感じで使うことができるはずです。

相互参照

linkプラグインを使用するとtitle1〜title3プラグインで定義した見出し、およびcaptionプラグインで定義した図表番号へのリンクを出力することができます。
見出しへのリンクを作成する場合、title1〜title3プラグインの引数でリンク用のラベルを定義しておき、linkプラグインではそのラベルを参照するようにします。linkプラグインを記述した位置に見出しの文字列が見出し番号付きでリンクが出力されます。

!!!{{title1 installation}}インストール
...
詳細については{{link installation}}を参照のこと。

図表の場合はcaptionプラグインの第三引数に同じくリンク用のラベルを定義し、linkプラグインではそのラベルを参照します。linkプラグインを記述した位置に図表番号付きでリンクが出力されます。

{{caption 表,StringUtilsのメソッド一覧,StringUtils_method_list}}
...
{{link StringUtils_method_list}}

なお、linkプラグインは第二引数にページ名を指定することで、他のページの見出しやリストにジャンプするリンクを出力することも可能です。

インストール方法については{{link installation,Chatper1}}を参照のこと。

コメントの記述

memoプラグインを使用すると執筆中にTODOコメントを入れたり、レビュー時のコメントを記述することができます。ページ内の任意の箇所に以下のように記述しておくと、表示時にはコメント部分（以下の例の場合は「TODO：あとで書く」の部分）が強調して表示されます。

{{memo TODO：あとで書く}}

memolistプラグインを使用すると現在のページ内のmemoコメントが一覧表示され、リンクをクリックするとそのコメントにジャンプすることができます。

!!!コメント一覧
{{memolist}}

執筆中はmemolistプラグインをサイドメニューに入れておくと便利っぽいです。

ワードカウント

原稿の執筆時は文字数、ページ数を意識する必要がある場合があります。wordcountプラグインで現在表示しているページの文字数、pagecountプラグインでページ数（1ページ2000文字で計算）を表示することができます。

*文字数：{{wordcount}}
*ページ数：{{pagecount}}

これも執筆中はサイドメニューに入れておくとよいでしょう。

コラム等の記述

本文の内容とは少し外れる内容だったり、特に注意が必要な点などをコラムとして記述したい場合があります。このような場合、columnプラグインを使用します。

{{column コラムのタイトル
ここにコラム等の内容をWiki形式で記述すします。
ブロックプラグインなので複数行の記述が可能です。
}}

TODO

とりあえずこれで必要最低限のことはできるかなと思うのですが、実際にこれで書籍を執筆することを考えると以下のような問題もありそうです。

  • 1章=1ページという前提でプラグインを作成しているが、1つの章の分量が多いようなケースでは章を複数のページに分割したいというケースもあるかも。
  • 図を入れるのがめんどくさい（画像ファイルをアップロードしたあとref_imageプラグインを記述する必要がある）
  • FSWikiの記法ではセルのマージなどが必要な複雑な表は書くことができない
  • memoプラグインでは短いコメントしか書けない（レビュー時など長いコメントを書きたかったり、コメントのやり取りを行いたい場合がある）
  • 編集がコンフリクトした場合に今のFSWikiでは差分がわからない（これは執筆用途に限らずFSWiki本体の問題ですね）
  • 履歴を保存する設定にしておくことで各リビジョンや任意のリビジョン間での差分を文字単位に参照することができるが、1ページの文字数が多くなると文字単位の差分表示がかなり重くなる

まとめ

書籍の執筆だけでなく、Web上で公開するドキュメントの執筆にも使えそうな気がします（執筆中は非公開設定で運用し、完成したら公開するような感じ）。
とりあえず必要最低限の機能は実装できたと思うので、過去の書籍の原稿をピックアップして移し変えてみて、実際に使えそうかどうかを試してみようと思います。