TidyLib って何なの？

TidyLibは、見てわかるとおりDave Raggettによる有名なHTML Tidyのライブラリ版です。実際、呼び出せるライブラリとしてHTML Tidyを再構成することが、 Source Forgeプロジェクトを始める大きな動機のひとつでした。コマンドラインツールはすばらしいのですが、ほかのソフトウエアに統合するのが難しく非能率です。

要求仕様

私たちには、ライブラリのための非公式な要件がいくつかありました:

ここから理解できます

おそらく、最も重要な要件は、ライブラリの組み込みが容易なことです。ほぼ一般的にCリンケージが採用されているため、 Cインターフェースは多くのプログラミング言語から呼び出せるはずです。さらにコードがすでにCだったという事実、そしてチームがすでにCにとても満足していたことから、ライブラリの公開インターフェースはCに保たれるべきだという結論に至りました。

ほかの主な仕様決定は、公開インターフェースであいまいな型を使うことでした。これで、アプリケーションは周りに整数を引き渡すだけで済むようになります。そして異なった言語でデータ型を変える必要は最小になります。

この方針は、すでに成功しています。 C++ 、 Pascal 、 COM / ATL 用の非常に薄いライブラリラッパーを書くのは簡単でした。同様に、SWIGを使ったPerlラッパーはすばやく生成できました。 Python 、 Ruby のための SWIG ラッパー、 Java と他のものは同様に可能性があるでしょう。

何も壊さない

もちろん、TidyはTidyのままであるべきです。バグを入れたり機能を失うことは好ましくありませんでした。結局、進めていくうちにテストドキュメントのボディがとても貴重であることがわかりました。

スレッドセーフ / 再入可能

HTML Tidyは内容妥当性検査やXHTML変換で多くの採用実績があるので、クライアントサイド同様に、サーバアプリケーション領域で合理的に動く TidyLib を作ることは重要でした。

この要件は、ライブラリがマルチスレッドアプリケーションで使われるように完全に再入可能であることを意味します。

柔軟な I/O

より大きな統合方針の一部として、すべての入出力を完全に抽象化することを決めました。これは、文字符号化方式の処理とバイト処理の（比較的）クリーンな分離を意味します。内部でライブラリは、「ソース」から読み込んで「シンク」に書き込みます。この抽象概念は、マークアップと設定両方の「ファイル」で使われます。具体的な実装をファイルとメモリ I/O に提供します。しかし、新しいソースとシンクが公開インタフェースを通して用意されるかもしれません。

私たちは同様に続くべきいくつかの既存技術を持っていました。もっとも著しいのは、Marc-Andre Lemburgの mxTidyです。 Tidy 用の Python ラッパーを書く過程で、 Marc-Andre はこれらの原則を応用して C ライブラリを構築しました。 TidyLib は Mark の仕事の完成と考えることができます。

はじめる

ソースを手に入れる

ライブラリソースを手に入れる最良の方法はCVSディレクトリです。もし、CVSをインストール済み（推奨！）なら以下のコマンドを実行してください。

C:\src> mkdir tidylib
C:\src> cd tidylib
C:\src\tidylib> set TIDYCVSROOT=:pserver:anonymous@cvs.sourceforge.net:/cvsroot/tidy
C:\src\tidylib> cvs -d %TIDYCVSROOT% login
C:\src\tidylib> cvs -d %TIDYCVSROOT% export -d C:\src\tidylib -r HEAD _
 build console htmldoc include src test

CVSがパスワードを求めてきたら、ただENTERを押してください。ライン継続の意味でアンダースコア（_）を使わないでください。単に長いコマンドラインを使ってください。手順はUNIX風です。あなたのファイルシステムのための適切なパス区切り文字に解釈してください。そして、 -d <dir> オプションを使わないでください。スクリプトあるいはバッチファイルに上記をコピーアンドペーストしてください。

本当に怠け者のために Tidy プロジェクトページから gzip されたソース tar ボールを引き出すことができます。

構築する

build/readme.txtで、ビルドオプションの概要を見てください。そこには、全体的なレイアウトとサポートされるビルドシステム上のさらに多くの情報が書かれています。

Unix / GNU

For GNU gcc, just use the gmake build/gmake/Makefile. The usual target is all. If you want a debug build, use the debug target. For other Unix compilers, you may have to set the CC macro to point to your compiler, usually just cc. The same, large number of Unix systems are supported "out of the box" as Tidy Classic. Tidy usually does a good job of automatically identifying the current platform. If not, tweak platform.h as needed and send us a patch!

もし GCC/MinGW を使っているなら、同様に gmake を使うべきです。

In addition, there are targets for clean and install. Be sure to look at the Makefile before using install to make sure the binaries, headers and library go where you want. By default, /usr/bin, /usr/include, and /usr/lib, respectively. There are macros in the Makefile to customize your installation.

make all

Windows / Visual C++

VC++用に、コマンドラインでmsvc/Makefile.vc6、あるいは、IDEでbuild/msvc/tidy.dswが使えます。名前が示すように、これらは Visual C++ version 6.0 で動作します。 Service Pack 3 が大いに推奨されます。 Makefile.vc6 は、同じターゲットをサポートし、 all、 debug、 clean、 install すべてが使用できます。

nmake /f Makefile.vc6 all

GNU AutoConf/AutoMake

The input files to drive the GNU AutoConf tool set have been added. See build/gnuauto/readme.txt for instructions on how to use GNU build tools with Tidy.

例

多分、それを使った単純なプログラムを見ることが、 Tidyを呼び出す方法を理解する近道です。整数を返す関数が次の値を返すということが、 APIについて知るべき基本事項です。

0 == 成功: Good to go.
1 == ワーニング有、エラー無し: エラーバッファをチェックするか、詳細についてはエラーメッセージを追跡してください。
2 == エラーとワーニング有: 規定値では、Tidyは出力を作成しません。 TidyForceOutput オプションで強制的に出力させることができます。警告と同様、エラーバッファをチェックするか、詳細についてはエラーメッセージを追跡してください。
<0 == 深刻なエラー: たいてい、値は -errno と同じです。 errno.h を見てください。

デフォルトで、警告とエラーメッセージが stderr に送られます。 tidySetErrorFile() あるいは tidySetErrorBuffer() を使って診断出力をリダイレクト出来ます。 tidy.h で詳細を見てください。

#include <tidy.h>
#include <buffio.h>
#include <stdio.h>
#include <errno.h>


int main(int argc, char **argv )
{
  const char* input = "<title>Foo</title><p>Foo!";
  TidyBuffer output = {0};
  TidyBuffer errbuf = {0};
  int rc = -1;
  Bool ok;

  TidyDoc tdoc = tidyCreate();                     // 「ドキュメント」初期化
  printf( "Tidying:\t%s\n", input );

  ok = tidyOptSetBool( tdoc, TidyXhtmlOut, yes );  // XHTMLへ変換
  if ( ok )
    rc = tidySetErrorBuffer( tdoc, &errbuf );      // 診断キャプチャ
  if ( rc >= 0 )
    rc = tidyParseString( tdoc, input );           // 入力を解析
  if ( rc >= 0 )
    rc = tidyCleanAndRepair( tdoc );               // お掃除
  if ( rc >= 0 )
    rc = tidyRunDiagnostics( tdoc );               // いつも不平を言う
  if ( rc > 1 )                                    // エラーでも強制出力
    rc = ( tidyOptSetBool(tdoc, TidyForceOutput, yes) ? rc : -1 );
  if ( rc >= 0 )
    rc = tidySaveBuffer( tdoc, &output );          // 簡易表示

  if ( rc >= 0 )
  {
    if ( rc > 0 )
      printf( "\nDiagnostics:\n\n%s", errbuf.bp );
    printf( "\nAnd here is the result:\n\n%s", output.bp );
  }
  else
    printf( "A severe error (%d) occurred.\n", rc );

  tidyBufFree( &output );
  tidyBufFree( &errbuf );
  tidyRelease( tdoc );
  return rc;
}

ママ！テンポラリファイルが無いよ！

アプリケーションメモ

もちろん、マークアップと設定の両方のファイルを解析して保存する機能があります。冒険好きが新しい入力ソースと出力シンクを作る可能性もあります。たとえば、URLソースが所定のURLからマークアップを引き出すことが考えられます。

アプリケーションがいくらでも ドキュメントとバッファオブジェクトのインスタンスを作ることが出来ることは覚えておく価値があります。それらの作成と破棄にそれほどコストはかかりません。（単に、メモリーを確保して0で埋めるだけです。）それらは必要であれば、ローカルに作成･破棄される可能性があります。状態を維持するために長時間周りのオブジェクトを引き止める問題がありません。たとえば、サーバーアプリケーションは大域ドキュメントを主設定として保持するかもしれません。ドキュメントが解析される時、マスターインスタンスから設定データをコピーすることが出来ます。 tidyOptCopyConfig()を見てください。原本がスタートアップで初期化される場合、同期化は必要ありません。

API ドキュメント

API ドキュメントの初稿がTidyヘッダーファイルに追加され、 Doxygen を使って生成されました。

Nightly Build

Source Forge コンパイルファーム上のビルドプロシージャは、ライブラリソースに基づいてコマンドラインドライバを作成するために更新されました。 Tidy バイナリを見てください。

将来のアプローチ

The ink isn't dry yet on TidyLib and already folks want more! Well, waddaya expect? Several ideas have been discussed on the dev mailing list.

文字符号化方式

Currently, all character encoding support is hard wired into the library. This means we do a poor job of supporting many popular encodings such as GB2312, euc-kr, eastern European languages, cyrillic, etc. Any of these languages must first be transcoded into ISO-10646/Unicode before Tidy can work with it.

Two basic approaches have been proposed: just use iconv or adapt Clark Coopers's XML::Encoding as a callable library. On the face of it, iconv is preferable. Because it is GPL'ed, however, the license may be incompatible. Also, there are transcription issues related to Big5 and other code sets that may or may not be addressed by iconv. XML::Encoding, otoh, uses the Perl Artistic License and explicitly supports all alternate transcriptions for Big5 and others. For more info, see CPAN and Tidy Issues.

エラー処理

エラーの分類
メッセージ地域化の改善
解析と診断の分離を改善

コンテントモデル

Per-element-and-version 属性サポート
DTD 内部サブセットのサポート
モジュール式 XHTML のサポート (XHTML 1.1)

Page last updated on 26 November, 2002 by C. Reitzel