# DocDiff Readme

2000-12-09..2005-01-03, Hisashi MORITA

## 目次

- ニュース
- 予定
- 簡単な説明
- 概要
- 必要なもの
- インストール方法
- 使い方
- ライセンス
- クレジット
- 情報源

## ニュース

- 0.3.2 (2005-01-03)
  - Readme is multilingualized (added partial Japanese translation). Try switching CSS between en and ja. Monolingual files are also available (readme.en.html, readme.ja.html).
  - Outputs better error messages when it failed to auto-detect the encoding and/or eol, though the accuracy is the same.
  - Switched revision control system from CVS to Subversion.
- 0.3.1 (2004-08-29)
  - Added -L (--label) option place holder in order to be used as external diff program from Subversion.
- 0.3.0 (2004-05-29)
  - Re-designed and re-written from scratch.
  - Supports multiple encodings (ASCII, EUC-JP, Shift_JIS, UTF-8) and multiple eols (CR, LF, CRLF).
  - Supports more output formats (tty, HTML, Manued, wdiff-like, user-defined markup text).
  - Supports configuration files (/etc/docdiff/docdiff.conf, ~/etc/docdiff/docdiff.conf (or ~/.docdiff/docdiff.conf)).
  - Introduced digest (summary) mode.
  - Approximately 200% faster than older versions, thanks to akr's diff library.
  - Better documentation and help message.
  - License changed from Ruby's to modified BSD style.
  - Pure Ruby. Does not require external diff program such as GNU diff, or morphological analyzer such as ChaSen.
  - Runs on both Unix and Windows (tested on Debian GNU/Linux and Cygwin)
  - Unit tests introduced to decrease bugs and to encourage faster development.
  - Makefile introduced.
- 0.1.8 (2003-12-14)
  - Displays warning when --bymorpheme is specified but ChaSen is not available (patch by Akira YAMADA: Debian bug #192258).
  - Supports system-wide configuration file (if ~/.chasenrc.docdiff does not exist, reads /etc/docdiff/chasenrc) (patch by Akira YAMADA: Debian bug #192261).
- 0.1.7 (2003-11-21)
  - HTML output retains spaces (&nbsp; patch by Akira YAMADA).
  - Manued output is added. Use --manued command line option to get result in Manued-like format.
  - Fixed .chasenrc.docdiff to be compatible with the latest ChaSen, so that it does not cause error.
  - Alphabet words in the output may look ugly, since ChaSen does not keep spaces between alphabetical words recently.
  - Other minor bug fixes and code cleanup.
- 0.2.0b2 (2001-08-31)
  - Code cleanup.
- 0.2.0b1 (2001-08-31)
  - A bit faster than 0.1.x, using file cache.
  - A bit cleaner code.
- 0.1.6 (2001-05-16)
  - Increased diff option number from 100000 to 1000000 in order to support 900KB+ text files.
- 0.1.5 (2001-01-17)
  - Erased useless old code which were already commented out.
  - Added documentation. (Updated README, more comments)
  - First public release. Registered to RAA.
- 0.1.4 (2001-01-16)
  - Output is like <tag>ab</tag>, instead of ugly <tag>a</tag><tag>b</tag> (thanks again to Masatoshi Seki for suggestion).
  - Fixed hidden bug ('puts' was used to output result).
  - Some code clean-up, though still hairy enough.
- 0.1.3 (2001-01-09)
  - Tested with Ruby 1.6.2.
  - Fixed "meth(a,b,)" bug (thanks to Masatoshi Seki).
  - Switched development platform from Windows to Linux, but it should work fine on Windows too, except for ChaSen stuff.
- 0.1.2 (2000-12-28)
  - Mostly bug fix.
- 0.1.1 (2000-12-25)
  - Bug fix and some cleanup.
  - Quotes some of HTML special characters (<>&) when output in HTML.
  - Added support for tty output using escape sequence.
- 0.1.0 (2000-12-19)
  - ChaSen works fine now.
  - GetOptLong was introduced to support command line options.
- 0.1.0a1 (2000-12-16)
  - Added ChaSen support. Japanese word by word comparison requires ChaSen.
  - Converted scripts from Shift_JIS/CRLF to EUC-JP/LF.
- 0.0.2 (2000-12-10)
  - Rewritten to use class.
- 0.0.1 (2000-12-09)
  - First version. Proof-of-concept.
  - Supports ASCII, EUC-JP, LF only.
  - Supports HTML output only.
  - Requires GNU diff.
  - Distributed under the same license as Ruby's

See the ChangeLog for detail.

## 予定

- Fixing bugs.
- Incorporate user feedback.
- Better auto-recognition of encodings and eols.
- Make CSS and tty escape sequence customizable in config files.
- Adding a file upload CGI script, so that DocDiff can be used as a web application.
- Make stand-alone Windows application using Exerb, hopefully with fancy GUI.
- Multilingualization (M17N), when Ruby is multilingualized.
- Write "DocPatch".

## 簡単な説明

2つのファイルを単語ごとあるいは文字ごとに比較する

## 概要

DocDiffは2つのファイルを比較してその違いを表示します。単語ごと、文字ごと、そして行ごとにファイルを比較できます。結果を出力する形式は、HTML, tty（文字 端末向けのエスケープシーケンス）, Manued（真鵺道という校正用のマークアップ形式）などが用意されており、ユーザ定義のタグを使うこともできます。

次のエンコーディング（文字コード）と行末コード（改行文字）をサポートしています: ASCII, UTF-8, EUC-JP, Shift_JIS、そしてCR, LF, CRLF.

## 必要なもの

- Ruby
  （注意: あなたが使っているOS向けのRubyパッケージがiconvやuconvといったライブラリを含んでいない場合は、別途それらを手に入れる必要があるかもしれません。）

## インストール方法

注意: 正しくインストールするためには適切なファイルアクセス権限が必要です（管理者権限が必要な場合があります）。

1. `docdiff/`ディレクトリとその内容をrubyのライブラリを格納するディレクトリに配置して、Rubyインタプリタがdocdiffライブラリをロードできるようにする。
   (e.g.

   > `# `cp -r docdiff /usr/lib/ruby/1.8``

   )
2. `docdiff.rb`をコマンドを格納するディレクトリに配置する。
   (e.g.

   > `# `cp docdiff.rb /usr/bin/``

   )
   ここで必要に応じてファイル名を`docdiff`のように変更してもよい。
   (e.g.

   > `# `mv /usr/bin/docdiff.rb /usr/bin/docdiff``

   )
3. 適切なパーミッションを設定する。
   (e.g.

   > `# `chmod +x /usr/bin/docdiff.rb``

   )
4. (オプション) もしサイトの全ユーザに適用される設定ファイルが必要なら、`docdiff.conf.example`を`/etc/docdiff/docdiff.conf`として配置し、編集する。
   (e.g.

   > `# `cp docdiff.conf.example /etc/docdiff.conf`
   > # `$EDITOR /etc/docdiff.conf``

   )
5. (オプション) もしユーザごとの設定ファイルが必要なら、`docdiff.conf.example`を`~/etc/docdiff/docdiff.conf`として配置し、編集する。
   (e.g.

   > `% `cp docdiff.conf.example ~/etc/docdiff.conf`
   > % `$EDITOR ~/etc/docdiff.conf``

   )

## 使い方

### 概要

> `docdiff [options] oldfile newfile`
> e.g. `% `docdiff old.txt new.txt > diff.html``

詳しくはヘルプメッセージを参照してください（`docdiff --help`）。

### 例

> `% `cat sample/01.ja.eucjp.lf`
> こんにちは、私の名前はわたなべです。
> 私はJust Another Ruby Porterです。
> % `cat sample/02.ja.eucjp.lf`
> こんばんは、私の名前はまつもとです。
> Rubyを作ったのは私です。私はRuby Hackerです。
> % `docdiff sample/01.ja.eucjp.lf sample/02.ja.eucjp.lf`
> こんにちはこんばんは、私の名前はわたなべです名前はまつもとです。
> Rubyを作ったのは私です。私はJust Another Ruby PorterHackerです。
> %
> `

### 設定

設定ファイルは次の場所に配置すると有効になります:

- `/etc/docdiff/docdiff.conf`（サイト全体の設定）
- `~/etc/docdiff/docdiff.conf`（ユーザごとの設定）
  （標準の設定では、ホームディレクトリにドットファイルをまき散らかさないために、`~/etc/docdiff/docdiff.conf`が使われます。または、昔ながらのUnixの慣習に従って`~/.docdiff/docdiff.conf`を使ってももちろん構いません。ただし両方同時には使えません）

設定ファイルの記法は次のとおりです（`docdiff.conf.example`ファイルも参照してください。配布アーカイブに含まれているはずです）:

> `# comment
> key1 = value
> key2 = value
> ...`

値（value）は、数字として解釈できるもの以外は、すべて文字列として扱われます。数字は数値（たいていは整数）として扱われます。

### 問題解決とヒント

#### wrong argument type nil (expected Module) (TypeError)

DocDiffがたまにエンコーディングや行末文字の自動判定に失敗して、次のようなエラーを表示することがあります。

> `charstring.rb:47:in `extend': wrong argument type nil (expected Module) (TypeError)
> `

このような場合は、エンコーディングや行末文字を明示的に指定してやってみてください（e.g. `docdiff --utf8 --crlf`）。

#### 不適切な挿入と削除

スペースで区切られたテキスト（英文やプログラムのソースコードなど）を比較しているときに、行末にある単語が、特に必要もないのにいったん削除されてからまた挿入されることがあります。これはDocDiffの単語分割機能に制限があるせいで起きます。テキストは次のように単語に分割されます。

text 1:

> `foo bar
> ("foo bar" => ["foo ", "bar"])`

text 2:

> `foo
> bar
> ("foo\nbar" => ["foo", "\n", "bar"])`

comparison result:

> `foo foo
> bar
> ("<del>foo </del><ins>foo</ins><ins>\n</ins>bar")`

Fooは（必要もないのに）削除されると同時に挿入されています。

作者はこの問題をいつか解決したいと思っていますが、簡単ではなさそうです。もし空白を1つの要素として分割したなら（i.e. `["foo", " ", "bar"]`）、比較した結果出力される単語の並びが今よりも不自然になってしまいます。良い案があったら教えてください。

#### DocDiffをSubversionの外部diffとして利用する

DocDiffをSubversionなどの外部diffプログラムとして使いたければ、次のようにするとよいでしょう。

> `% `svn diff --diff-cmd=docdiff --extensions "--ascii --lf --tty --digest"``

## ライセンス

このソフトウェアはいわゆる修正BSDスタイルライセンス（http://www.opensource.org/licenses/bsd-license.php（広告条項なし））のもとで配布されています。このソフトウェアに貢献すると、あなたは貢献したものが同ライセンスのもとに取り込まれることに同意したとみなされます。

ソースコードの主となる部分の著作権と使用条件は次のとおりです:

>     Copyright (C) Hisashi MORITA.  All rights reserved.

>     Redistribution and use in source and binary forms, with or without
>     modification, are permitted provided that the following conditions
>     are met:
>     1. Redistributions of source code must retain the above copyright
>        notice, this list of conditions and the following disclaimer.
>     2. Redistributions in binary form must reproduce the above copyright
>        notice, this list of conditions and the following disclaimer in the
>        documentation and/or other materials provided with the distribution.
>     3. Neither the name of the University nor the names of its contributors
>        may be used to endorse or promote products derived from this software
>        without specific prior written permission.

>     THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
>     ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
>     IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
>     ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
>     FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
>     DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
>     OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
>     HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
>     LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
>     OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
>     SUCH DAMAGE.

diffライブラリ（`docdiff/diff.rb`および`docdiff/diff/*`）は、もともと田中哲さんによるRuby/CVSの一部分でした。Ruby/CVSは修正BSDスタイルライセンスのもとで配布されています。詳細は次を参照してください。

- http://raa.ruby-lang.org/list.rhtml?name=ruby-cvs
- http://cvs.m17n.org/~akr/ruby-cvs/

## クレジット

- Hisashi MORITA (primary author)
- Shin'ichiro HARA (initial idea and algorithm suggestion)
- Masatoshi SEKI (patch)
- Akira YAMADA (patch, Debian package)
- Kenshi Muto (testing, bug report)
- Akira TANAKA (diff library author)

## 情報源

### フォーマット

- HTML/XHTML
  http://www.w3.org
- tty (Graphic rendition using VT100 / ANSI escape sequence)
  VT100: http://vt100.net/docs/tp83/appendixb.html
  ANSI: http://www.tldp.org/HOWTO/Bash-Prompt-HOWTO/x329.html
- Manued (Manuscript Editing language: a proofreading method for text)
  http://www.archi.is.tohoku.ac.jp/~yamauchi/otherprojects/manued/

### 同様の目的を持ったソフトウェア

テキストを単語単位や文字単位で比較することができるソフトウェアは、ほかにもあります。

- GNU wdiff (Seems to support single byte characters only.)
  http://www.gnu.org/directory/GNU/wdiff.html
- cdif by Kazumasa UTASHIRO (Supports several Japanese encodings.)
  http://srekcah.org/~utashiro/perl/scripts/cdif
- ediff for Emacsen
  http://www.xemacs.org/Documentation/packages/html/ediff.html
- diff-detail for xyzzy, by Hiroshi OHKUBO
  http://ohkubo.s53.xrea.com/xyzzy/
- Manuediff (Outputs difference in Manued format.)
  http://hibiki.miyagi-ct.ac.jp/~suzuki/comp/export/manuediff.html