EPrints 2.3技術文書 - アーカイブ設定ファイル |
この章では、EPrintsシステムにおいて1アーカイブを設定するファイルをすべて説明します。
EPrintsアーカイブを作成すると、入力された情報は/opt/eprints2/archives/にあるarchiveid.xmlという名前のXMLファイルに保存されます。 このファイルについては後ほど説明します。
アーカイブ用の設定ファイル群が/opt/eprints2/defaultcfg/から、アーカイブ用設定ファイルディレクトリ(通常、/opt/eprints2/archives/archiveid/cfg/)にコピーされます。 このディレクトリには一般に、次のファイルおよびディレクトリが存在します。
この節では、XML形式のアーカイブ設定ファイルであるtemplate、phrases、ruler、citationsについて一般的な説明をします。metadata-types.xmlもXMLファイルですが、ここでの説明は当てはまりません。
このファイルはHTML要素(とその他の要素)を使用します。XHTMLはHTMLのまったく新しいバージョンであり、HTML4と後方互換性がありますが、SGMLではなくXMLを使って書かれています。 これは厳格ですが、あいまい性がなく、構文解析や変更が容易であることを意味しています。HTMLはご存知だと思いますが、主な相違点は以下のとおりです。
<br>
や <img src="foo">
のようにHTMLでは終了タグを持たないタグについても、たとえば、 <img src="foo"></img>
のように閉じる必要があります。
なお、これを <img src="foo" />
のようにさっぱりとした形に簡略化することができます。 <hr noshade>
要素などです。
XHTMLでは、これを <hr noshade="noshade" />
のように記述します。
以上をまとめると、HTMLでは
<img SRC=someurl> <hr NOSHADE WIDTH=2> <P>Foo bar</P>
と書くところを、XHTMLでは次のように書かなくてはいけません。
<img src="someurl" /> <hr noshade="noshade" width="2" /> <p>Foo bar</p>
より正確な情報はhttp://www.w3c.org/ を参照してください。
phrases、template、citationsの各ファイルは、サポートする言語毎に1つ用意します。 これらのファイルを使って、システムは複数の言語のページやメール文を作成することができます。 新しい言語をサポートするには、デフォルトで用意されている英語で書かれたすべての設定ファイルを翻訳する必要があります。 この作業を始める(大変な作業量です)前には、作業が重複しないようにEPrints開発者に連絡を取ってください。
すべてのXMLファイルは、外部エンティティを定義しているDTDを使用します。 エンティティは、&のように「&」で始まり、「;」で終わるXML(あるいはHTML)のアイテムです。 これらの追加エンティティは、generate_entitiesコマンドで作成されるエンティティDTDファイルに定義されています。 DTDは言語毎に1つ作成されます。ただし、今のところ違うのはアーカイブ名だけです。
é €
)を使うことができます。
これらのエンティティは、citationsファイルとrulerファイルでは利用できないことに注意してください。
これらのファイルではカスタムタグとXHTMLタグが混在しています。これらを区別するためにXMLファイルでは最初の要素で名前空間を定義しています。 実際上の要点は、EPrints独自タグはすべてプリフィックス「ep:」を持っていることです。EPrintsシステムの現行バージョンでは名前空間の情報を実際は無視しています。
以下は混合タグ(および、エンティティ)の例です。
<ep:phrase ref="lib/session:contact"><p>Feel free to contact <a href="mailto:&adminemail;">&archivename; administration</a> with details.</p></ep:phrase>
EPrintsの要素: phrase XHTMLの要素: p, a EPrintsのエンティティ: archiveemail, archivename
このXMLファイルはarchives/
ディレクトリ(通常、/opt/eprints2/archives/
)にあり、アーカイブについての最も基本的な情報を記述します。
このファイルは、configure_archiveコマンドにより生成(変更)され、一般に編集する必要はありません。
EPrintsは、Webサーバの立ち上げの際、このディレクトリにXMLファイルがないかを調べて、存在するすべてのXMLファイルのロードを試みます。
このファイルにはデータベース接続用のパスワードが書かれているので、所有者以外のユーザが読めないようにchmodする必要があります。
最上位の要素は「archive」で、アーカイブのidである「id」属性を持っています。 このidはファイル名と同じにするべきです。たとえば、このファイルがfoo.xmlの場合、idはfooとします。
<archive>
要素は、次の例のような、何らかのテキストを内容として持つ一連のXMLタグを持ちます。
<host>stoatprints.org</host>
以下のタグを順不同で指定します。
/
です。<archivename language="en">White Lemur</archivename> <archivename language="fr">La Archive d'Lemur Blanc</archivename>
(フランス人の皆さん、すいません。フランス語は苦手ですので)
このモジュールは他に5つのPerlモジュールをインポートします。 このモジュールを使って多くの点でシステムを調整できます。詳細については、すべてプログラムに記述されています。
不要な機能を隠したり、ブラウズや検索、購読誌機能をカスタマイズしたりするオプションがあります。
また、各タイプのユーザは何ができて、何ができないか、また、パスワードをどのように認証するかについて、カスタマイズすることができます。
この設定ファイルは、セッションの開始時と終了時に呼び出され、ログを出力したり、エンティティファイルのエンティティを生成したり、非公開ファイルのセキュリティを確保したりするPerlメソッドを含んでいます。
ブラウズビューは、「generate_views」コマンドで生成されます。このコマンドで何をするかは設定ファイルの「browse_views」アイテムで指定します。
このアイテムは、無名ハッシュ{}を要素とする無名配列[]へのリファレンスです。
ハッシュは3つの必須属性と多くのオプション属性を持ちます。
id=>"foo"
は、その名称をフレーズ「viewname_eprint_foo」から得ます。
一般にシステムは各引用形の周りにパラグラフタグを付けますが、カスタムcitationを使うとこのタグは付きません。
index.html
を/view/
に生成します。
nolinkに1を設定すると、この項目を隠します。
index.html
ファイルを/view/foo/
に生成しません。
最も一般的なビューは、サブジェクトによりブラウズするものです。
{ id=>"subject", allow_null=>0, fields=>"subjects", order=>"title/authors", hideempty=>1 }
もう少し複雑な次の設定では、著者IDと編者IDによるビューを生成します。宣伝はしませんが、何か他のソフトウェアでこれを取り込んでスタッフの業績ページを作成することができるでしょう。
{ id=>"person", allow_null=>0, fields=>"authors.id/editors.id", nohtml=>1, nolink=>1, noindex=>1, include=>1, order=>"-year/title" }
たとえば、私の個人id「wh」を例にとると、/view/person/wh.includeというWebページが生成されます(同時に他の著者IDや編者IDのファイルも作成されます)。これを外部の自動システムで取り込むことができます。
ユーザ権限設定を使って、どんなタイプのユーザは、何ができて、何ができないかを設定することができます。 ユーザのホームページは、そのユーザが操作できるオプションだけを表示します。
新しいユーザタイプと、そのユーザタイプが自分についてのどのデータを編集できるのかは、metadata-fields.xmlで設定します。
権限はユーザの「タイプ」に対して設定します。デフォルトでは3種類のタイプ(「user」、「editor」、「admin」)のユーザが存在します。
adminは、デフォルトの設定では、あらゆることをすることができます。
メタデータはデータに関するデータです。格納する情報は、システムの各レコード(イープリント)を記述します。 ユーザもメタデータを持っています。
このモジュールはメタデータの設定に使用します。このモジュールはおそらくシステムでもっとも重要な部分です。
すべての設定オプションについてはメタデータに関する章を参照してください。
ファイルのこの部分は、ユーザ、ドキュメント、イープリントのデフォルト値を設定する際に呼ばれるサブルーチンを含んでいます。
これらの関数はフィールドに値を自動的に設定します。 これによりアイテム(ユーザ/イープリント/ドキュメント)がデータベースにコミットされるたびにフィールドが自動的に更新されるようになります。
また、「複合」フィールドを作成することができます。複合フィールドとは、直接編集されるのではなく他のフィールドの値を処理することにより作成されるフィールドです。
たとえば、著者数を持つ整数の自動設定フィールドを作りたい場合は、set_eprint_automatic_fields関数に以下を追加します。
# no authors at all will be undef, not [] so check first if( $eprint->is_set( "authors" )) { my $auths = $eprint->get_value( "authors" ); $eprint->set_value( "authcount" , scalar @{$auths} ); } else { $eprint->set_value( "authcount" , 0 ); }
このモジュールはOAIプロトコルによりアーカイブデータをどのようにエクスポートするかを設定します。
OAIに関するさらなる情報はhttp://www.openarchives.org/を参照してください。
ハーベスタはOAIを使ってあなたのアーカイブやその他のアーカイブにメタデータを要求して、横断検索を提供することができます。 ハーベスタがあなたのアーカイブをもう一度ハーベストする際は、前回のハーベスト以後に変更されたり、追加されたりしたアイテムを要求するだけですみます。
EPrintsの現行バージョンは、OAI1.1とOAI2.0の両者をサポートしています。
OAI v1.1インターフェースのベースURLは、http://archivepath/perl/oaiです。
OAI v2.0インターフェースのベースURLは、http://archivepath/perl/oai2です。
OAIシステムを使用する場合は、運営方針やアーカイブのOAI-idなどの空欄を埋める必要があります。
ArchiveConfig.pmの「ブラウズビュー」と同じ方法でOAIセットを作成することができます。
EPrintsによるダブリンコアのマッピングを変更したい場合は、make_metadata_oai_dc関数を変更してください。なお、この関数はDOM XMLオブジェクトを返します。
新しいメタデータタイプを追加したい場合は、新しいマッピング関数を作成して、ファイルの先頭あたりにある名前空間、スキーマ、マッピング関数に関するアイテムにエントリを追加する必要があります。
このモジュールは、Webに表示するためにデータをXHTMLに変換する関数を含んでいます。
ユーザ情報ページや「要約」ページの表示法を変更したい場合は、このモジュールを変更します。
内部変数やオブジェクトをすべて表示する「完全」版の関数もあります。これは編集者や管理者が見るページです。
XHMTLはDOM(Document Object Model)を使って生成しますが、EPrintsはXHTML DOMを簡単に生成する関数を提供しています。 使用する必要のあるDOMメソッドはappendChildだけです。このメソッドは現在の要素に要素を追加します
すべての文字列はUTF-8であることに注意してください。
例)
my $page = $session->make_doc_fragment(); my $h1 = $session->make_element( "h1" ); $h1->appendChild( $session->make_text( "Title" )); $page->appendChild( $h1 ); $page->appendChild( $session->make_element( "img", src=>"/images/cheese.gif", width=>128, height=>53 ));
$pageの内容は以下のようになります。
<h1>Title</h1><img src="/images/cheese.gif" width="128" height="53" />
今ではEPrintsの多くのモジュールはちゃんとした
説明文書を持っています。たとえば、次のように実行してみてください。
% perldoc /opt/eprints2/perl_lib/EPrints/Archive.pm
以下、情報を抽出したり、加工したりするための非常に便利な関数を説明します。
$session->make_text( $text )
$session->make_doc_fragment()
$session->make_element( $name, %opts )
たとえば、 <h1 class="foo">...</h1>
を作成する場合は、次のように書きます。
$session->make_element( "h1", class=>"foo" );
$session->render_ruler();
$session->render_link( $uri, $target )
<a href="uri"></a>
これをappendChildの引数として使うことができます。$targetが指定されている場合は、新規ウィンドウをポップアップさせるためのtarget属性が付きます。
$item->render_value( $fieldname, $showall )
$fieldnameは加工したいフィールドの名前です。$showallを1にすると、多言語フィールドのすべての値が加工されます。
$item->render_citation( $style )
$styleが指定されている場合は、アイテムタイプのサイテーションの代わりに指定したidを持つサイテーションを使用します。
$item->render_citation_link( $style )
$item->render_description()
$session->html_phrase( $phraseid, %opts )
まず、現在の言語のアーカイブ用フレーズファイルを捜します。
次に英語のアーカイブ用フレーズファイルを探します。
次に現在の言語のシステムフレーズファイルを探します。
最後に英語のシステムフレーズファイルを探します。
%optsは一連のDOM要素で、フレーズファイルにある「ピン」アイテムを置き換えます。
$item->get_value( $fieldname, $no_id )
$item->is_set( $fieldname )
$eprint->get_all_documents()
EPrintsが検索用に文字列から単語を抽出する方法を変更したい場合以外は、このモジュールを変更する必要はないでしょう。
レコードがシステムに追加されると、EPrintsはこのモジュールを使って、文字列を切り分けて、索引に使用する値のリストを作成します。 デフォルトでは、この値はあらかじめ定義したストップワードを除いた3文字以上の単語です。 なお、音標符号の付いた文字は音標文字を取ります。
検索文字列にも同じ処理が行われて、これらの索引を捜すことになります。
例)
The rain in spain falls mainly on the plains.
この文字列から(デフォルトでは)次の索引が作成されます。
rain spain fall mainly plain
従って、「rain」、「plain」、「plains」、「MaiNlY」のいずれで検索してもこの文字列にマッチすることになります。
このモジュールを変更するのは、たとえば、独自の「ストップワード」を追加したい場合です。 たとえば、アナグマに関するアーカイブを運営している場合、単語「アナグマ」による検索ではほとんどすべてのレコードがヒットすることになるでしょう。
もっと複雑な例では、非ヨーロッパ系の文字セットの処理(どのようなデフォルト設定をすればこれがうまくいくのか私にはわかりませんが)を追加したい場合です。 あるいは、ステミング処理をしたい場合です。ステミングとは、単語の最後の「ed」や「ing」、「ies」などを除去して、「land」が「land」だけでなく「landed」や「landing」、「lands」にもマッチするようにすることです。(現在は最後の「s」を除去しているだけです。)
また、soundexのような、似たような単語をマッチさせる技術を使用することも考えられます。
稼動システムの索引化方法を変えた場合は、reindexスクリプトを使って索引を再作成する必要があります(そうしないと、検索結果に間違いが生じるでしょう)。
このモジュールはユーザが入力したデータの妥当性を検証します。各サブルーチンの詳細については、モジュール自身に記述されています。
各サブルーチンはDOM要素のリストを返します。個々のDOM要素には、1つの問題が記述されています。 どんな問題であっても、その問題を解決しない限りユーザは処理を続けることができません。
データ加工関数同様、複数言語をサポートしない場合は、単に、$session->make_text( "problem explanation" )を呼び出してDOMアイテムを作成することができます。
イープリントとドキュメントのための検証関数はフラグ$for_archiveを持っています。このフラグが1の場合は、アイテムがアーカイブに追加される前にチェックされることを示します。 これを使って、ユーザが入力しなかったフィールドに編集者が必ず入力するようにすることができます。
サイテーションファイルは、アイテム(イープリント/ユーザ/その他)をXHTMLの断片に加工する方法を記述しています。各サイテーションは「タイプ」属性を持っています。 次の3種類のサイテーションがあります。
サイテーションファイルはサイテーション要素のリストを持っています。
<ep:citation type="...">
各要素は、テキストとタグを持つことができます。テキストは、加工するレコードのフィールド名を持つこともできます。 この名前はシンボル@で囲まなければなりません。たとえば、@authors@や@title@といった感じです。 これは加工の際にフィールド値で置換えられます。(何らかの理由で@自体が必要な場合は、@1つを連続する2つの@で表します。)
注意)@title@スタイルはEPrints2.2で導入されました。それ以前は、&title;のようにXMLエンティティを使用していました。 これは問題を引き起こしていましたが、解決策がありませんでした。エンティティの使用は現在もサポートされていますが、使用しないでください。
さらに、XHTML要素とEPrints名前空間の次の要素を使用することもできます。これらの要素は加工後に除去されますが、その内容を保存するかどうかを決定します。 条件分岐要素はバージョン2.2から互いに入れ子にすることができるようになりました。
<ep:linkhere>
たとえば、
@year@<ep:ifmatch name="year" value="-1949"> (approx)</ep:ifmatch>
この例では、yearが1950より前の場合、yearの後ろに(approx)が付きます。良いでしょう。
このファイルを使って、イープリント、ユーザ、ドキュメントの各タイプ、および、ドキュメントのセキュリティレベルを設定することができます。
新しいタイプを追加する場合は、その名前をアーカイブ用フレーズファイルに追加する必要があります。フレーズidは「データセット_typename_タイプ名」、たとえば、「document_typename_pdf」です。 また、新しいサイテーションをサイテーションファイルに追加しなければなりません。サイテーションに必須ではないフィールドを指定する場合は<ep:ifset>の内部におくべきです。 そうすれば、それが指定されていない場合も「UNSPECIFIED」という表示を見ることがなくなります。
主要素は「metadatatypes」です。この要素は、name属性を持つ「dataset」要素のリストを持ちます。
ユーザとイープリントの「dataset」要素にある「type」要素は、「field」要素のリストを持ちます。 field要素は、このタイプで編集できるフィールドと、その画面上での表示順を記述します。
このリストにシステムフィールドを含めることもできますが、そうする場合は注意して行ってください。
オプションとして、フィールドリストに<page name=``pagename'' />要素を追加することができます。 これは投稿プロセスを複数の小さなステージに分割します。pagenameは、データの妥当性の検証などでサブページを識別するために使用します。 page要素が使えるのはイープリントだけで、ユーザやドキュメントなどでは使用できません。
メタデータについて説明した章を参照してください。
セキュリティレベルを定義するのに便利な場所です。name属性を持たないタイプは特別で、「公開用の」セキュリティタイプです。 その他のタイプはすべて有効なユーザ名とパスワードを必要とします。 そのユーザ名が指定したドキュメントをアクセスできるかどうかは、ArchiveConfig.pmにあるcan_user_view_documentサブルーチンで定義されています。
デフォルトでは、EPrintsがイープリントを妥当とするには、psファイル、pdf、テキストファイル、htmlファイルのうち少なくとも1つがアップロードされていることが必要です。 このファイルのファイル種別のリストは、ArchiveConfig.pmで変更することができます。 なお、これより複雑な条件はイープリント検証サブルーチンでチェックする必要があります。
このファイルにはXMLによる「フレーズ」のリストが含まれています。EPrintsがユーザに「伝える」すべてのものは、このファイルか、システムフレーズファイルに格納されています。 複数言語でサイトを運営したい場合は、言語毎に1つずつフレーズファイルを用意する必要があります
フレーズファイルはXMLで書かれており、トップレベルは「phrases」要素です。この要素はフレーズのリストを含んでいます。
各フレーズは、フレーズを識別する「ref」属性を持ち、テキストとオプションのXHTMLタグを含んでいます。 また、&archivename;のようなEPrintsエンティティを含めることもできます。さらに、後で説明する「ピン」要素を含んでいるフレーズもあります。
アーカイブ用フレーズファイルにあるフレーズは、そのアーカイブ固有のフレーズです。一方、システムフレーズファイルは特定のアーカイブに限らないフレーズを持っています。 アーカイブ用フレーズファイルのフレーズidのほとんどは、フィールドやデータセット、タイプなどのidから作られています。
アーカイブ用フレーズファイルには次のデータが含まれています。データセットタイプ名、メタデータフィールド名、メタデータフィールド入力用のヘルプメッセージ、「セット」フィールドのオプション名、検索結果表示順オプションに関する記述、ブラウズビュー名、加工ルーチンおよび検証ルーチンで使用されるフレーズ、EPrintsが送付するメール文、システムフレーズを置き換えるフレーズ。
EPrintsに値を挿入する場所を示すために「ピン」要素が必要なフレーズがあります。 一般に、ピン要素は要素を持ちませんが、リンクを置く場所を表す際にまれに要素を持つことがあります。
システムフレーズファイルのフレーズが気に入らない場合は、アーカイブ用フレーズファイルに同じ「ref」を持つフレーズを作成することで置き変えることができます。
システムフレーズファイルを編集しないでください。EPrintsを新バージョンにバージョンアップする際に、システムフレーズファイルは上書きされてしまうからです
EPrintsは、ユーザがパスワードを登録・変更した場合や、メールアドレスを変更した場合、 投稿されたアイテムが編集者により棄却・削除された場合、システムリソースが不足した場合などにメールを送信します。 これらのメール文はフレーズファイルでカスタマイズすることができます。
テキストは必ずパラグラフタグ<p>で囲んでください。<hr />要素はメール文中ではダッシュ線で置き換えられます。
EPrintsがメールを送る際は、ラテン-1要素が含まれている場合を除いて、プレーンテキストで送信します。ラテン-1要素がある場合は、ラテン-1符号化をして送信します。 ラテン-1文字セットではなく、ユニコード文字が含まれている場合は、utf-8符号化をして送信します。
EPrintsが使用する横罫線を設定します。EPrintsは、&ruler;の位置にこれを挿入します。
<hr>による横罫線で問題ない場合は、変更する必要はありません。
このファイルでは、&frontpage;のようなエンティティは使用することができません。
このディレクトリにはサイトの静的なページ、すなわち、フロントページ、ヘルプページ、画像、スタイルシートなど、が含まれています。
static/
は、たとえば、en/
のように、言語毎に1つのディレクトリを持ちます。
さらに、画像やスタイルシートのように翻訳する必要がないファイルを収めるgeneral/
ディレクトリを持ちます。
generate_static
コマンドを実行すると各言語用のファイルが各言語用のディレクトリに、さらにgeneralディレクトリがコピーされます。
詳細については、generate_static
コマンドの説明文書を参照してください。
このファイルは、EPrintsのコアシステムでは使用されません。import_subjectsコマンドを使って、サブジェクトを初期構築する際に使用されます。 詳細については、import_subjectsコマンドの説明文書を参照してください。
このファイルはシステムのすべてのページの骨組みとなるものです。これはおおよそ普通のXHTMLファイルですが、&foo;という形式のEPrintsエンティティを使うことができます。 また、フレーズのように「ピン」要素を含めるべきです。含めるべきピンは以下のとおりです。
<ep:pin ref="title" />
<ep:pin ref="head" />
<ep:pin ref="pagetop" />
<ep:pin ref="page" />
EPrints 2.3技術文書 - アーカイブ設定ファイル |