docdiff 0.6.2 → 0.6.4

data/README_ja.md

@@ -0,0 +1,351 @@
+# DocDiff
+
+* [English](README.md) | Japanese
+
+(C) 2000 Hisashi MORITA
+
+## 簡単な説明
+
+2つのテキストファイルを単語ごと、文字ごと、あるいは行ごとに比較する
+
+## スクリーンショット
+
+<div style="display: grid; grid-template-columns: 1fr 1fr;">
+
+<p>HTML出力<br />
+<img src="doc/img/screenshot-format-html-firefox.png" alt="HTML output"/></p>
+
+<p>HTML出力（ダイジェスト）<br />
+<img src="doc/img/screenshot-format-html-digest-firefox.png" alt="HTML output (digest)" /></p>
+
+<p>tty出力<br />
+<img src="doc/img/screenshot-format-tty-rxvtunicode-en.png" alt="tty output" /></p>
+
+<p>tty出力（日本語のテキストを比較）<br />
+<img src="doc/img/screenshot-format-tty-rxvtunicode-ja.png" alt="tty output (comparing Japanese text)" /></p>
+
+<p>tty出力<br />
+<img src="doc/img/screenshot-format-tty-xterm-en.png" alt="tty output" /></p>
+
+<p>tty出力（日本語のテキストを比較）<br />
+<img src="doc/img/screenshot-format-tty-xterm-ja.png" alt="tty output (comparing Japanese text)" /></p>
+
+</div>
+
+<p>英語のテキスト（コードページ437）を比較（Windows上のCygwin環境）<br />
+<img src="doc/img/screenshot-format-tty-cmdexe-en.png" alt="Comparing English text (codepage 437) on Windows (Cygwin)" /></p>
+
+<p>日本語のテキスト（コードページ937）を比較（Windows上のCygwin環境）<br />
+<img src="doc/img/screenshot-format-tty-cmdexe-ja.png" alt="Comparing Japanese text (codepage 932) on Windows (Cygwin)" /></p>
+
+<p>行ごと、単語ごと、文字ごとの比較が可能（フォーマットはtty）<br/>
+<img src="doc/img/screenshot-resolution-linewordchar-xterm.png" alt="You can compare text files by line, word, or character (format: tty)" /></p>
+
+（バージョン0.3.2時点のスクリーンショットです。）
+
+## 概要
+
+DocDiffは2つのテキストファイルを比較してその違いを表示します。単語ごと、文字ごと、そして行ごとにファイルを比較できます。結果を出力する形式は、HTML、tty（文字端末向けのエスケープシーケンス）、Manued（真鵺道という校正用のマークアップ形式）などが用意されており、ユーザ定義のタグを使うこともできます。
+
+次のエンコーディング（文字コード）と行末コード（改行文字）をサポートしています: ASCII（およびISO-8859-*などのシングルバイトエンコーディング）、UTF-8、EUC-JP、Shift_JIS（Windows-31J）、そしてCR、LF、CRLF。
+
+## 使い方
+
+### 概要
+
+```
+$ docdiff [options] oldfile newfile
+```
+
+e.g.
+
+```
+$ docdiff old.txt new.txt > diff.html
+```
+
+詳しくはヘルプメッセージを参照してください（`docdiff --help`）。
+
+### 例
+
+<pre>
+$ cat 01_ja_eucjp_lf.txt
+こんにちは、私の名前はわたなべです。
+私はJust Another Ruby Porterです。
+$ cat 02_ja_eucjp_lf.txt
+こんばんは、私の名前はまつもとです。
+Rubyを作ったのは私です。私はRuby Hackerです。
+$ docdiff --tty 01_ja_eucjp_lf.txt 02_ja_eucjp_lf.txt
+<span class="before-change" style="background: yellow; border: thin inset;"><del>こんにちは</del></span><span class="after-change" style="background: lime; font-weight: bolder; border: thin outset;"><ins>こんばんは</ins></span>、私の<span class="before-change" style="background: yellow; border: thin inset;"><del>名前はわたなべです</del></span><span class="after-change" style="background: lime; font-weight: bolder; border: thin outset;"><ins>名前はまつもとです</ins></span>。
+<span class="add" style="background: deepskyblue; font-weight: bolder; border: thin outset;"><ins>Rubyを作ったのは私です。</ins></span>私は<span class="del" style="background: hotpink; border: thin inset;"><del>Just Another </del></span>Ruby <span class="before-change" style="background: yellow; border: thin inset;"><del>Porter</del></span><span class="after-change" style="background: lime; font-weight: bolder; border: thin outset;"><ins>Hacker</ins></span>です。
+$
+</pre>
+
+## 必要なソフトウェア
+
+* 実行時に必要なソフトウェア:
+  - [Ruby](https://www.ruby-lang.org/) (>= 3.0)
+* 開発時に必要なソフトウェア:
+  - Make ([GNU Make](https://www.gnu.org/software/make/))
+  - [Git](https://git-scm.com/)
+  - [md2html](https://github.com/mity/md4c)（ドキュメント生成用）
+  - [Rake](https://ruby.github.io/rake/)（オプショナル）
+  - sed, gzip, tar, etc.
+
+## インストール方法
+
+いくつかのOSでは、DocDiffがパッケージとして提供されていることがあります。そのような場合は、それらのパッケージを使ってインストールするのが早道でしょう。
+
+### Debianパッケージ
+
+サイト単位でのインストール:
+
+```
+$ sudo apt update
+$ sudo apt install docdiff
+```
+
+### Gemパッケージ
+
+Rubyに詳しいならば、gemパッケージとしてDocDiffをインストールしたいと思うかもしれません。
+
+ユーザ単位でのインストール（[RubyGems.org](https://rubygems.org/)から）:
+
+```
+$ gem install docdiff
+```
+
+ユーザ単位でのインストール（手元でのビルドから）:
+
+```
+$ rake build
+$ gem install pkg/docdiff-X.Y.Z.gem
+```
+
+（注意：Gemとしてインストールしたアプリケーションを起動するには、`PATH`環境変数を適切に設定する必要があります。[rbenv](https://github.com/rbenv/rbenv)などのRuby環境管理ツールを使うと便利かもしれません。）
+
+### Makeを使ってソースからインストールする
+
+やむをえずMakeを使ってソースからDocDiffをインストールするときは、事前によくテストしてください。
+
+`tmp`ディレクトリへのテストインストール:
+
+```
+$ mkdir tmp
+$ make install DESTDIR=tmp PREFIX=/local
+$ tree tmp || la -lR tmp
+```
+
+ユーザ単位でのインストールの例（ファイルを上書きしたりディレクトリ構造を汚くしたりしかねないので、おすすめしませんが）:
+
+```
+$ make install DESTDIR=~ PREFIX=/local
+```
+
+## 設定
+
+設定ファイルは次の場所に配置すると有効になります:
+
+* `/etc/docdiff/docdiff.conf`（サイト全体の設定）
+
+* `~/.config/docdiff/docdiff.conf`（ユーザごとの設定）（[`$XDG_CONFIG_HOME`](https://specifications.freedesktop.org/basedir/0.8/)参照）
+
+  （警告：`~/etc/docdiff/docdiff.conf`や`~/.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"]`)
+
+* 比較した結果:
+  <pre>
+  <del>foo </del><ins>foo</ins><ins>
+  </ins>bar
+  </pre>
+  (`"<del>foo </del><ins>foo</ins><ins>\n</ins>bar"`)
+
+Fooは（必要もないのに）削除されると同時に挿入されています。
+
+作者はこの問題をいつか解決したいと思っていますが、簡単ではなさそうです。もし空白を1つの要素として分割したなら（i.e. `["foo", " ", "bar"]`）、比較した結果出力される単語の並びが今よりも不自然になってしまいます。良い案があったら教えてください。
+
+### DocDiffをバージョン管理システムと組み合わせて使う
+
+DocDiffをVCSの外部diffプログラムとして使いたければ、次のようにするとよいでしょう。
+
+* Git:
+  ```
+  $ GIT_EXTERNAL_DIFF=~/bin/gitdocdiff.sh git diff
+  ```
+  `~/bin/gitdocdiff.sh`:
+  ```
+  #!/bin/sh
+  docdiff --ascii --lf --tty --digest $2 $5
+  ```
+
+* Subversion:
+  ```
+  $ svn diff --diff-cmd=docdiff --extensions "--ascii --lf --tty --digest"
+  ```
+
+（場合によっては`git diff --word-diff-regex="\w"`で十分なこともありますが。）
+
+zshを使えば、いろいろな場所にある文書をDocDiffや他のユーティリティで自由に比較できます。次の例ではリポジトリ内の特定のリビジョンのfoo.htmlとウェブサイト上のfoo.htmlとを比較しています。
+
+* Git:
+  ```
+  $ docdiff =(git show abc1234:foo.html) =(curl --silent http://www.example.org/foo.html)
+  ```
+
+* Subversion:
+  ```
+  $ docdiff =(svn cat -r3 http://svn.example.org/repos/foo.html) =(curl --silent http://www.example.org/foo.html)
+  ```
+
+### プレーンテキストではない文書ファイルを比較する
+
+適切な変換ツールを使えば、プレーンテキスト以外のファイルも比較できる場合があります。
+
+* PDF文書中のテキストを比較する:
+  ```
+  $ docdiff =(pdftotext foo.pdf -) =(pdftotext bar.pdf -)
+  ```
+
+* HTML文書中のテキスト（タグを除く）を比較する:
+  ```
+  $ docdiff =(w3m -dump -cols 10000 foo.html) =(w3m -dump -cols 10000 http://www.example.org/foo.html)
+  ```
+
+* Microsoft Word文書中のテキストを比較する:
+  ```
+  $ docdiff =(wvWare foo.doc | w3m -T text/html -dump -cols 10000) =(wvWare bar.doc | w3m -T text/html -dump -cols 10000)
+  ```
+
+### Latin-* (ISO-8859-*) のための回避策: ASCIIを指定する
+
+文字コードがLatin-* (ISO-8859-*) のテキストを扱うときは、文字コードに`ASCII`を指定してみてください。`ASCII`が指定されると、DocDiffは対象をシングルバイト文字のテキストとして扱います。
+
+* Latin-1テキストを比較する:
+  ```
+  $ docdiff --encoding=ASCII latin-1-old.txt latin-1-new.txt
+  ```
+
+## ライセンス
+
+このソフトウェアはいわゆる修正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ライブラリ（`lib/docdiff/diff.rb`および`lib/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 (author)
+
+## 謝辞
+
+* Akira TANAKA (diff library author)
+* Shin'ichiro HARA (initial idea and algorithm suggestion)
+* Masatoshi SEKI (patch)
+* Akira YAMADA (patch, Debian package)
+* Kenshi MUTO (testing, bug report, Debian package)
+* Kazuhiro NISHIYAMA (bug report)
+* Hiroshi OHKUBO (bug report)
+* Shugo MAEDA (bug report)
+* Kazuhiko (patch)
+* Shintaro Kakutani (patches)
+* Masayoshi Takahashi (patches)
+* Masakazu Takahashi (patch)
+* Hibariya (bug report)
+* Hiroshi SHIBATA (patch)
+* Tamotsu Takahashi (patches)
+* MIKAMI Yoshiyuki (patch)
+
+このリストが全く不完全で、いろいろな形で貢献してくださった多くの方々へ謝意を表しそこねていることをお詫びします。本当にありがとうございます。
+
+## 情報源
+
+### フォーマット
+
+* [HTML/XHTML](https://www.w3.org/)
+* tty (Graphic rendition using VT100 / ANSI escape sequences)
+  - [VT100](https://vt100.net/docs/tp83/appendixb.html)
+  - [ANSI](https://tldp.org/HOWTO/Bash-Prompt-HOWTO/x329.html)
+* [Manued](https://sundayresearch.eu/hitoshi/otherprojects/manued/) ([in Japanese](https://sundayresearch.eu/hitoshi/otherprojects/manued/index-j.html)) (Manuscript Editing Language: a proofreading method for text)
+
+### 同様の機能を備えたソフトウェア
+
+テキストを単語単位や文字単位で比較することができるソフトウェアは、数多く存在します。
+
+* CLI:
+  - [wdiff](https://www.gnu.org/software/wdiff/) (requires spaces between words)
+  - cdif / [sdif-tools](https://github.com/kaz-utashiro/sdif-tools)
+* GUI:
+  - [WinMerge](https://winmerge.org/) (Windows)
+* Editor extensions:
+  - [ediff](https://www.gnu.org/software/emacs/manual/html_mono/ediff.html) (Emacs)
+  - [diff-detail](http://ohkubo.s53.xrea.com/xyzzy/index.html#diff-detail) ([xyzzy](https://github.com/xyzzy-022/xyzzy))

data/Rakefile

@@ -2,51 +2,11 @@ require 'rake/clean'
 require 'rake/testtask'
 require 'bundler/gem_tasks'
 
-RUBY    = ENV['RUBY'] ||= 'ruby'
-DOCS   = FileList['ChangeLog', 'readme.en.html', 'readme.ja.html',
-                  'index.en.html', 'index.ja.html']
-DOCSRC = FileList['readme.html', 'index.html', 'img', 'sample']
-TESTS  = FileList['test/*_test.rb']
-TESTLOGS = Dir.glob('test/*_test.rb').map{|f|
-  File.basename(f).ext('log')
-}
-
-WWWUSER     = ENV['WWWUSER']     ||= 'hisashim,docdiff'
-WWWSITE     = ENV['WWWSITE']     ||= 'web.sourceforge.net'
-WWWSITEPATH = ENV['WWWSITEPATH'] ||= 'htdocs/'
-WWWDRYRUN   = ENV['WWWDRYRUN']   ||= '--dry-run'
+ENV['SOURCE_DATE_EPOCH'] ||= `git show --quiet --format=%ct HEAD`
 
 Rake::TestTask.new do |t|
-  t.test_files = TESTS
+  t.test_files = FileList['test/*_test.rb']
   t.verbose = true
 end
 
 task :default => :test
-
-desc "generate documents"
-task :docs => DOCS
-
-file 'ChangeLog' do |t|
-  sh "devutil/changelog.sh > #{t.name}"
-end
-
-rule(/.*\.(?:en|ja)\.html/ => proc{|tn| tn.gsub(/\.(?:en|ja)/, '')}) do |t|
-  sh "#{RUBY} -E UTF-8 langfilter.rb" +
-    " --#{t.name.gsub(/.*?\.(en|ja)\.html/){$1}}" +
-    " #{t.prerequisites.first} > #{t.name}"
-end
-
-desc "force to rsync web contents"
-task :wwwupload do |t|
-  sh "rake www WWWDRYRUN="
-end
-
-desc "rsync web contents"
-task :www => DOCSRC + DOCS do |t|
-  sh "rsync #{WWWDRYRUN} -auv -e ssh --delete" +
-    " --exclude='.svn' --exclude='.git'" +
-    t.prerequisites.join(' ') +
-    " #{WWWUSER}@#{WWWSITE}:#{WWWSITEPATH}"
-end
-
-CLEAN.include(DOCS, TESTLOGS)

data/bin/docdiff

@@ -14,6 +14,7 @@ default_config = {
   :format        => "html",
   :cache         => true,
   :digest        => false,
+  :pager         => nil,
   :verbose       => false
 }
 
@@ -28,73 +29,78 @@ end
 
 ARGV.options {|o|
   o.def_option('--resolution=RESOLUTION',
-    possible_resolutions = ['line', 'word', 'char'],
+    resolutions = ['line', 'word', 'char'],
     'specify resolution (granularity)',
-    possible_resolutions.join('|') + ' (default is word)'
+    "#{resolutions.join('|')} (default: word)"
     ){|s| clo[:resolution] = (s || "word")}
-  o.def_option('--line', 'set resolution to line'){clo[:resolution] = "line"}
-  o.def_option('--word', 'set resolution to word'){clo[:resolution] = "word"}
-  o.def_option('--char', 'set resolution to char'){clo[:resolution] = "char"}
+  o.def_option('--line', 'same as --resolution=line'){clo[:resolution] = "line"}
+  o.def_option('--word', 'same as --resolution=word'){clo[:resolution] = "word"}
+  o.def_option('--char', 'same as --resolution=char'){clo[:resolution] = "char"}
 
   o.def_option('--encoding=ENCODING',
-    possible_encodings = ['ASCII','EUC-JP','Shift_JIS','CP932','UTF-8','auto'],
-    'specify character encoding',
-    possible_encodings.join('|'), "(default is auto. try ASCII for single byte encodings such as ISO-8859-X)"
+    encodings = ['ASCII', 'EUC-JP', 'Shift_JIS', 'CP932', 'UTF-8', 'auto'],
+    "specify character encoding",
+    "#{encodings.join('|')} (default: auto)",
+    "(try ASCII for single byte encodings such as ISO-8859)"
     ){|s| clo[:encoding] = (s || "auto")}
   o.def_option('--ascii', 'same as --encoding=ASCII'){clo[:encoding] = "ASCII"}
-  o.def_option('--iso8859x', 'same as --encoding=ASCII'){clo[:encoding] = "ASCII"}
+  o.def_option('--iso8859', 'same as --encoding=ASCII'){clo[:encoding] = "ASCII"}
+  o.def_option('--iso8859x', 'same as --encoding=ASCII (deprecated)'){clo[:encoding] = "ASCII"}
   o.def_option('--eucjp', 'same as --encoding=EUC-JP'){clo[:encoding] = "EUC-JP"}
   o.def_option('--sjis', 'same as --encoding=Shift_JIS'){clo[:encoding] = "Shift_JIS"}
   o.def_option('--cp932', 'same as --encoding=CP932'){clo[:encoding] = "CP932"}
   o.def_option('--utf8', 'same as --encoding=UTF-8'){clo[:encoding] = "UTF-8"}
 
   o.def_option('--eol=EOL',
-    possible_eols = ['CR','LF','CRLF','auto'],
+    eols = ['CR','LF','CRLF','auto'],
     'specify end-of-line character',
-    possible_eols.join('|') + ' (default is auto)'
+    "#{eols.join('|')} (default: auto)",
     ){|s| clo[:eol] = (s || "auto")}
   o.def_option('--cr', 'same as --eol=CR'){clo[:eol] = "CR"}
   o.def_option('--lf', 'same as --eol=LF'){clo[:eol] = "LF"}
   o.def_option('--crlf', 'same as --eol=CRLF'){clo[:eol] = "CRLF"}
 
   o.def_option('--format=FORMAT',
-    possible_formats = ['tty','manued','html','wdiff','stat','user'],
+    formats = ['tty', 'manued', 'html', 'wdiff', 'stat', 'user'],
     'specify output format',
-    possible_formats.join('|'),
-    "(default is html)",
+    "#{formats.join('|')} (default: html) (stat is deprecated)",
     '(user tags can be defined in config file)'
     ){|s| clo[:format] = (s || "manued")}
   o.def_option('--tty', 'same as --format=tty'){clo[:format] = "tty"}
   o.def_option('--manued', 'same as --format=manued'){clo[:format] = "manued"}
   o.def_option('--html', 'same as --format=html'){clo[:format] = "html"}
   o.def_option('--wdiff', 'same as --format=wdiff'){clo[:format] = "wdiff"}
-  o.def_option('--stat', 'same as --format=stat (not supported yet)'){clo[:format] = "stat"}
+  o.def_option('--stat', 'same as --format=stat (not implemented) (deprecated)'){clo[:format] = "stat"}
 
   o.def_option('--label LABEL', '-L LABEL',
-    'Use label instead of filename (not supported yet)'
+    'use label instead of file name (not implemented; exists for compatibility with diff)'
     ){|s1, s2| clo[:label1], clo[:label2] = s1, s2}
 
   o.def_option('--digest', 'digest output, do not show all'){clo[:digest] = true}
   o.def_option('--summary', 'same as --digest'){clo[:digest] = true}
   o.def_option('--display=DISPLAY',
-    possible_types = ['inline', 'multi'],
+    display_types = ['inline', 'block', 'multi'],
     'specify presentation type (effective only with digest; experimental feature)',
-    possible_types.join('|'),
-    '(default is inline)'){|s| clo[:display] ||= s.downcase}
-  o.def_option('--cache', 'use file cache (not supported yet)'){clo[:cache] = true}
+    "#{display_types.join('|')} (default: inline) (multi is deprecated)",
+    ){|s| clo[:display] ||= s.downcase}
+  o.def_option('--cache', 'use file cache (not implemented) (deprecated)'){clo[:cache] = true}
+  o.def_option('--pager=PAGER', String,
+    'specify pager (if available, $DOCDIFF_PAGER is used by default)'
+    ){|s| clo[:pager] = s}
+  o.def_option('--no-pager', 'do not use pager'){clo[:pager] = false}
+  o.def_option('--config-file=FILE', String,
+    'specify config file to read'){|s| clo[:config_file] = s}
   o.def_option('--no-config-file',
     'do not read config files'){clo[:no_config_file] = true}
-  o.def_option('--config-file=FILE',
-    'specify config file to read'){|s| clo[:config_file] = s}
-  o.def_option('--verbose', 'run verbosely (not supported yet)'){clo[:verbose] = true}
+  o.def_option('--verbose', 'run verbosely (not well-supported) (deprecated)'){clo[:verbose] = true}
 
   o.def_option('--help', 'show this message'){puts o; exit(0)}
   o.def_option('--version', 'show version'){puts DocDiff::AppVersion; exit(0)}
-  o.def_option('--license', 'show license'){puts DocDiff::License; exit(0)}
-  o.def_option('--author', 'show author(s)'){puts DocDiff::Author; exit(0)}
+  o.def_option('--license', 'show license (deprecated)'){puts DocDiff::License; exit(0)}
+  o.def_option('--author', 'show author(s) (deprecated)'){puts DocDiff::Author; exit(0)}
 
   o.on_tail("When invoked as worddiff or chardiff, resolution will be set accordingly.",
-    "Config files: /etc/docdiff/docdiff.conf, ~/etc/docdiff/docdiff.conf")
+    "Config files: /etc/docdiff/docdiff.conf, ~/.config/docdiff/docdiff.conf (or ~/etc/docdiff/docdiff.conf (deprecated))")
 
   o.parse!
 } or exit(1)
@@ -108,12 +114,20 @@ unless clo[:no_config_file] == true # process_commandline_option
   end
   #    message = docdiff.process_config_file(DocDiff::UserConfigFileName)
   case
-  when File.exist?(DocDiff::UserConfigFileName) && File.exist?(DocDiff::AltUserConfigFileName)
-    raise "#{DocDiff::UserConfigFileName} and #{DocDiff::AltUserConfigFileName} cannot be used at the same time.  Remove or rename either one."
+  when [File.exist?(DocDiff::UserConfigFileName),
+        File.exist?(DocDiff::AltUserConfigFileName),
+        File.exist?(DocDiff::XDGUserConfigFileName)].count(true) >= 2
+    raise <<~EOS
+      #{DocDiff::UserConfigFileName}, #{DocDiff::AltUserConfigFileName}, and \
+      #{DocDiff::XDGUserConfigFileName} cannot be used at the same time. \
+      Keep one and remove or rename the others.
+    EOS
   when File.exist?(DocDiff::UserConfigFileName)
     message = docdiff.process_config_file(DocDiff::UserConfigFileName)
   when File.exist?(DocDiff::AltUserConfigFileName)
     message = docdiff.process_config_file(DocDiff::AltUserConfigFileName)
+  when File.exist?(DocDiff::XDGUserConfigFileName)
+    message = docdiff.process_config_file(DocDiff::XDGUserConfigFileName)
   end
   if clo[:verbose] == true || docdiff.config[:verbose] == true
     STDERR.print message
@@ -126,11 +140,20 @@ unless clo[:config_file].nil?
     raise "#{clo[:config_file]} does not exist."
   end
   if clo[:verbose] == true || docdiff.config[:verbose] == true
-    STDERR.pring message
+    STDERR.print message
   end
 end
 docdiff.config.update(clo)
 
+docdiff.config[:pager] =
+  if (pager = docdiff.config[:pager]).is_a?(String) && !pager.empty?
+    pager
+  elsif (pager = docdiff.config[:pager]) == false
+    pager
+  elsif (pager = ENV['DOCDIFF_PAGER']) && !pager.empty?
+    pager
+  end
+
 # config stuff done
 
 # process the documents
@@ -188,4 +211,4 @@ output = docdiff.run(doc1, doc2,
     :format     => docdiff.config[:format],
     :digest     => docdiff.config[:digest],
     :display    => docdiff.config[:display]})
-print output
+docdiff.print_or_write_to_pager(output, docdiff.config[:pager])

data/{docdiff.conf.example → doc/example/docdiff.conf.example}

@@ -6,10 +6,11 @@
 # eol = LF
 # format = html
 # digest = off
-# cache = off   # not implemented yet
-# verbose = no  # not implemented yet
+# cache = off   # (not implemented) (deprecated)
+# pager = less --raw-control-chars
+# verbose = no  # (not well-supported) (deprecated)
 #
-## user-defined tags (not well-supported yet)
+## user-defined tags (not well-supported)
 # tag_common_start        = '<=>'
 # tag_common_end          = '</=>'
 # tag_del_start           = '<->'