EPrints 2.3技術文書 - アーカイブ設定ファイル


アーカイブの設定

この章では、EPrintsシステムにおいて1アーカイブを設定するファイルをすべて説明します。

主たるアーカイブ設定ファイル

EPrintsアーカイブを作成すると、入力された情報は/opt/eprints2/archives/にあるarchiveid.xmlという名前のXMLファイルに保存されます。 このファイルについては後ほど説明します。

アーカイブ用設定ファイルディレクトリ

アーカイブ用の設定ファイル群が/opt/eprints2/defaultcfg/から、アーカイブ用設定ファイルディレクトリ(通常、/opt/eprints2/archives/archiveid/cfg/)にコピーされます。 このディレクトリには一般に、次のファイルおよびディレクトリが存在します。

apache.conf
このファイルは、generate_apacheconfコマンドにより作成されます。詳細は、generate_apacheconfの説明文書を参照してください。

apachevhost.conf(バージョン2.2で追加)
このファイルは、generate_apacheconfコマンドにより作成されます。詳細は、generate_apacheconfの説明文書を参照してください。

ArchiveConfig.pm
他に置くのはふさわしくない一般的な設定項目はこのPerlモジュールに置かれます。詳細については後ほど説明します。 このモジュールは以下の5つのPerlモジュールを「必要」とします。 これらのモジュールは処理を簡単にするためにファイルを分けたものです。

ArchiveMetadataFieldsConfig.pm
このモジュールはメタデータフィールドとそのデフォルト値を設定します。

ArchiveOAIConfig.pm
このモジュールはOAI-PMHでアーカイブをエクスポートする方法を設定します。

ArchiveRenderConfig.pm
このモジュールはデータをWebページとして表示するXHTMLファイルを作成するためのサブルーチンを含んでいます。

ArchiveTextIndexingConfig.pm
このモジュールはUTF8によるテキスト文字列をフリーワードで検索できるように索引語のリストに変換します。

ArchiveValidateConfig.pm
このモジュールはメタデータが問題ないかどうかをチェックするサブルーチンを含んでいます。

auto-apache.conf
このファイルは、generate_apacheconfコマンドにより作成・上書きされます。直接編集しないでください。詳細は、generate_apacheconfの説明文書を参照してください。

citations-languageid.xml
このアーカイブでサポートするlanguageid毎に1つ、このファイルを用意します。 このXMLファイルは、アイテムのメタデータから引用形を作る際にどのようにマークアップするかを記述します。 詳細については後ほど説明します。

entities-languageid.dtd
このアーカイブでサポートするlanguageid毎に1つ、このファイルが用意されます。 このDTDファイルはEPrintsがアーカイブの設定をロードする直前に自動的に生成されます。直接編集しないでください。

metadata-types.xml
このXMLファイルは、イープリントやユーザなどの様々なタイプと、各タイプに必須の、あるいは関連するメタデータフィールドを記述します。 詳細については後ほど説明します。

phrases-languageid.xml
このアーカイブでサポートするlanguageid毎に1つ、このファイルを用意します。 このXMLファイルは、メタデータフィールドの名称など、このアーカイブに特有なフレーズのすべてを含んでいます。 詳細については後ほど説明します。

ruler.xml
このXMLファイルは、システムで生成されるWebページで使用する横罫線のみを含んでいます。 詳細については後ほど説明します。

static/
このディレクトリは、ホームページやアバウトページなどの静的なWebページを作成するために必要なデータを含んでいます。 詳細については後ほど説明します。

subjects
このファイルは、システムで使用するサブジェクトの初期値を含んでいます。 詳細については、後ほどimport_subjectsの項で説明します。

template-languageid.xml
このアーカイブでサポートするlanguageid毎に1つ、このファイルを用意します。 このXML/XHTMLファイルはこのシステムで生成するWebページの輪郭を記述します。 詳細については後ほど説明します。


EPrintsにおけるXML設定ファイル

この節では、XML形式のアーカイブ設定ファイルであるtemplate、phrases、ruler、citationsについて一般的な説明をします。metadata-types.xmlもXMLファイルですが、ここでの説明は当てはまりません。

XHTML

このファイルはHTML要素(とその他の要素)を使用します。XHTMLはHTMLのまったく新しいバージョンであり、HTML4と後方互換性がありますが、SGMLではなくXMLを使って書かれています。 これは厳格ですが、あいまい性がなく、構文解析や変更が容易であることを意味しています。HTMLはご存知だと思いますが、主な相違点は以下のとおりです。

タグは必ず閉じていなければなりません
すべてのタグは、たとえ<li>のようなものであっても、閉じていなければなりません。 <br> <img src="foo"> のようにHTMLでは終了タグを持たないタグについても、たとえば、 <img src="foo"></img> のように閉じる必要があります。 なお、これを <img src="foo" /> のようにさっぱりとした形に簡略化することができます。

タグと属性名はすべて小文字でなければなりません
読んで字の如しです。

タグの出現位置が厳密に定義されています
EPritnsでは実際はチェックしていません。 妥当なXMLであれば、どんなガラクタも見逃すでしょう。 しかしだからといって、規則に外れてもいいという理由にはなりません。

属性値はすべて引用符で囲まなければなりません
HTMLでは属性値を引用符で囲む必要はありませんでしたが、XML(それゆえ、XHTML)では囲む必要があります。

属性はすべて値を持っていなければなりません
HTMLでは値を設定する必要のない属性もありました。たとえば、 <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を使用します。 エンティティは、&amp;のように「&」で始まり、「;」で終わるXML(あるいはHTML)のアイテムです。 これらの追加エンティティは、generate_entitiesコマンドで作成されるエンティティDTDファイルに定義されています。 DTDは言語毎に1つ作成されます。ただし、今のところ違うのはアーカイブ名だけです。

&archivename;
現在の言語によるアーカイブの名前です。

&adminemail;
管理者のメールアドレスです。

&base_url;
システムのベースURL(最後のスラッシュは除く)です。

&perl_url;
CGIディレクトリのベースURL(最後のスラッシュは除く)です。

&frontpage;
EPrintsシステムのホームページのURLです。

&userhome;
ユーザホームページのURLです。

&version;
使用しているEPrintsのバージョンです。

&ruler;
標準罫線のXHTMLです。

任意のXHTML文字エンティティ(EPrintsバージョン2.1以降)
任意のXHTML文字エンティティ(たとえば、&nbsp; &eacute; &euro;)を使うことができます。

ユーザ定義エンティティ
ArchiveConfig.pmにあるエンティティを生成する関数を変更することによりユーザ独自のエンティティを生成することができます。

これらのエンティティは、citationsファイルとrulerファイルでは利用できないことに注意してください。

名前空間とXHTML

これらのファイルではカスタムタグと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>

以下のタグを順不同で指定します。

<host>
このアーカイブのホスト名です。

<alias redirect=``yes-or-no''>
オプションで繰り返し可能です。"yes"か"no"を設定する属性「redirect」を持ちます。これはどんなバーチャルホストをサポートするか、また、バーチャルホストを主たる <host>にリダイレクトするか否かを指定します。

<language>
このアーカイブでサポートする言語のISOコードです。繰り返し可能です。これらのうち1つはデフォルト言語でなければなりません。下を参照してください。

<port>
サーバが稼動するポート番号です。通常、80です。

<urlpath>
サーバ名のルート相対のディレクトリパスです。通常、/です。

<archiveroot>
その他のアーカイブ設定ファイルのファイルシステム上のパスです。

<configmodule>
主たる設定ファイルであるPerlモジュール(ArchiveConfig.pm)のパスです。

<dbname>
MySQLデータベースの名前です。通常、アーカイブIDと同じです。

<dbhost>
MySQLが稼動しているホストです。通常、localhostです。

<dbport>
MySQL用のポートで、オプションです。標準的なポート以外を使用する場合に指定します。デフォルトのポートを使う場合は空欄にします。

<dbsock>
MySQL用のソケットで、オプションです。デフォルトのソケットを使う場合は空欄にします。

<dbuser>
MySQLに接続する際に使用するユーザ名です。通常、「eprints」です。

<dbpass>
MySQLに接続する際に使用するパスワードです。

<defaultlanguage>
サポートする言語の1つで、このアーカイブのデフォルト言語となります。

<adminemail>
アーカイブ管理者のメールアドレスです。個人のメールアドレスではなく、別名にすることを強く勧めます。 たとえば、「bob@footle.edu」を指定すると、Webページのすべてにこのアドレスが表示されることになり、担当がボブからビルに代わった場合、「bill@footle.edu」を表示するようにすべてのページを再作成しなければなりません。 もっと良い方法は、別名を定義するか、「archive-support@footle.edu」から転送するようにして、(現在のところは)ボブにメールが届くように設定することです。 経験者の言葉は聞くものですよ。

<archivename language=``langcode''>
アーカイブの名称です。ISOの言語IDを値とする属性「language」を持ちます。 サポートする言語毎にこのarchivename要素を持つ必要があります。以下がその例です。
    <archivename language="en">White Lemur</archivename>
    <archivename language="fr">La Archive d'Lemur Blanc</archivename>

(フランス人の皆さん、すいません。フランス語は苦手ですので)

<securehost>(バージョン2.2以降)
実験的なhttpsサポートで使用します。

<securepath>(バージョン2.2以降)
実験的なhttpsサポートで使用します。


ArchiveConfig.pm

このモジュールは他に5つのPerlモジュールをインポートします。 このモジュールを使って多くの点でシステムを調整できます。詳細については、すべてプログラムに記述されています。

不要な機能を隠したり、ブラウズや検索、購読誌機能をカスタマイズしたりするオプションがあります。

また、各タイプのユーザは何ができて、何ができないか、また、パスワードをどのように認証するかについて、カスタマイズすることができます。

この設定ファイルは、セッションの開始時と終了時に呼び出され、ログを出力したり、エンティティファイルのエンティティを生成したり、非公開ファイルのセキュリティを確保したりするPerlメソッドを含んでいます。

ブラウズビュー

ブラウズビューは、「generate_views」コマンドで生成されます。このコマンドで何をするかは設定ファイルの「browse_views」アイテムで指定します。

このアイテムは、無名ハッシュ{}を要素とする無名配列[]へのリファレンスです。

ハッシュは3つの必須属性と多くのオプション属性を持ちます。

id(必須)
このビューのIDです。ビューは、この名前でサブディレクトリ/views/に置かれます。 また、IDはフレーズファイルにおいてこのビューの正式名を識別するためにも使用されます。 たとえば、 id=>"foo" は、その名称をフレーズ「viewname_eprint_foo」から得ます。

fields(必須)
ブラウズするフィールド名をスラッシュ「/」でつなげたリストです。ただし、2つのフィールドの値をマージさせたい場合を除いて、通常は1つのフィールドを指定することになるはずです。 フィールドのID部分は、フィールド名に「.id」をつけて指定します。

order(必須)
ソート対象フィールドを優先順にスラッシュ「/」でつなげたリストです。 そのフィールドを逆順にソートする場合は、フィールド名の前にマイナス符号「-」をつけます。

allow_null
フィールド値が「未設定」のページを作成するか否かを指定します。フィールドyearでブラウズページを作成する場合は値が未設定のアイテムのページも有益な場合がありますが、その他のフィールドの場合は意味がないでしょう。 作成する場合は、1を設定します。

include
フィールド値ごとに、レコードの引用形とレコード数を表すXHTMLを「.include」で終わるファイル名で生成します。ただし、XHTMLはサイトの標準テンプレートで囲まれません。

nohtml
一般に、「include」の項で述べたように、システムはサイトの標準テンプレートで囲まれた .htmlで終わる名前を持つページを生成します。 この属性に1を設定すると、このファイルを生成しません。

citation
一般に使用される引用形はイープリントの「タイプ」別に用意されているものです。 (citationsファイルにあるcitationを)この属性に設定すると、その引用形をすべてのアイテムに使用できるようになります。 これをうまく使って、他のWebサイトに埋め込むページを作ることができます。

一般にシステムは各引用形の周りにパラグラフタグを付けますが、カスタムcitationを使うとこのタグは付きません。

nocount
ページのトップにアイテム数を表示しません。

nolink
システムは利用可能なすべてのブラウズビューのリストを持つindex.html/view/に生成します。 nolinkに1を設定すると、この項目を隠します。

noindex
すべてのビュー値とそのページへのリンクをリストアップするindex.htmlファイルを/view/foo/に生成しません。

notimestamp(バージョン2.2以降)
ビューページの下部にタイムスタンプを表示しません。

hideempty(バージョン2.2以降)
サブジェクトにのみ指定できます。このオプションはレコードを持たないサブジェクトの表示を抑制します。これはまだ「若い」アーカイブで有効です。つまり、大きなサブジェクト・ツリーを定義していて、登録されたレコードが数件の場合、3つか4つのサブジェクトしかレコードを持たないことになるからです。

最も一般的なビューは、サブジェクトによりブラウズするものです。

 { 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のファイルも作成されます)。これを外部の自動システムで取り込むことができます。

ユーザ権限(User Priv)

ユーザ権限設定を使って、どんなタイプのユーザは、何ができて、何ができないかを設定することができます。 ユーザのホームページは、そのユーザが操作できるオプションだけを表示します。

新しいユーザタイプと、そのユーザタイプが自分についてのどのデータを編集できるのかは、metadata-fields.xmlで設定します。

権限はユーザの「タイプ」に対して設定します。デフォルトでは3種類のタイプ(「user」、「editor」、「admin」)のユーザが存在します。

adminは、デフォルトの設定では、あらゆることをすることができます。

subscription(EPrintsバージョン2.1以降)
このオプションを指定すると、このタイプのユーザは購読誌を作成することができます。

set-password
Web登録システムを使ってパスワードを再設定することができます。

deposit
アーカイブにアイテムを投稿することができます。

view-status
アーカイブのステータスページを見ることができます。

editor
投稿されたアイテムを編集してアーカイブへの受入を承認することができます。また、投稿されたアイテムを削除したり、投稿者に送り返したりすることもできます。 さらに、修正のためにアイテムをアーカイブから編集バッファに戻すことやレコードを(削除アイテムとして)削除テーブルに移すこともできます。

staff-view
ユーザレコードあるいはイープリントレコードに対して「スタッフ用検索」を実行でき、すべてのメタデータを見ることができます。

edit-subject
オンラインインターフェースを使ってサブジェクト・ツリーを編集することができます。

edit-user
他のユーザのレコードを変更できます。

change-email
Webインターフェースを使ってメールアドレスを変更できます。 これは直接変更できるようにするより安全です。なぜなら、(ユーザに確認用の暗証番号を送付することで)確実にメールを受け取ることのできるアドレスしか設定できなくするからです。

change-user
誰か別の人としてログインできるようになる不吉な機能を可能にします。ただし、パスワードは必要です。 スーパーユーザとして管理業務を行った後に、一般ユーザとしてログインしてアイテムをデポジットしたいような場合に有効な機能です。

no_edit_own_record(EPrintsバージョン2.2以降)
オプション「私のユーザレコードを編集する」を抑制します。 Webによる登録を無効にし、何か他のデータベースからユーザレコードをインポートする場合に有効な機能でしょう。


ArchiveMetadataFieldsConfig.pm

フィールド設定

メタデータはデータに関するデータです。格納する情報は、システムの各レコード(イープリント)を記述します。 ユーザもメタデータを持っています。

このモジュールはメタデータの設定に使用します。このモジュールはおそらくシステムでもっとも重要な部分です。

すべての設定オプションについてはメタデータに関する章を参照してください。

デフォルト値設定関数

ファイルのこの部分は、ユーザ、ドキュメント、イープリントのデフォルト値を設定する際に呼ばれるサブルーチンを含んでいます。

自動設定関数

これらの関数はフィールドに値を自動的に設定します。 これによりアイテム(ユーザ/イープリント/ドキュメント)がデータベースにコミットされるたびにフィールドが自動的に更新されるようになります。

また、「複合」フィールドを作成することができます。複合フィールドとは、直接編集されるのではなく他のフィールドの値を処理することにより作成されるフィールドです。

たとえば、著者を持つ整数の自動設定フィールドを作りたい場合は、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 );
 }


ArchiveOAIConfig.pm

このモジュールは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オブジェクトを返します。

新しいメタデータタイプを追加したい場合は、新しいマッピング関数を作成して、ファイルの先頭あたりにある名前空間、スキーマ、マッピング関数に関するアイテムにエントリを追加する必要があります。


ArchiveRenderConfig.pm

このモジュールは、Webに表示するためにデータをXHTMLに変換する関数を含んでいます。

ユーザ情報ページや「要約」ページの表示法を変更したい場合は、このモジュールを変更します。

内部変数やオブジェクトをすべて表示する「完全」版の関数もあります。これは編集者や管理者が見るページです。

XHMTLはDOM(Document Object Model)を使って生成しますが、EPrintsはXHTML DOMを簡単に生成する関数を提供しています。 使用する必要のあるDOMメソッドはappendChildだけです。このメソッドは現在の要素に要素を追加します

XHTMLオブジェクトを返すEPrints API関数

すべての文字列は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 )
テキストを表すDOMオブジェクトを返します。

$session->make_doc_fragment()
文書断片を返します。これは何かを加工するものではなく、オブジェクトを追加するためのコンテナです。

$session->make_element( $name, %opts )
1つのXHTML要素を作成します。%optsは0個以上の属性で、オプションです。

たとえば、 <h1 class="foo">...</h1> を作成する場合は、次のように書きます。

 $session->make_element( "h1", class=>"foo" );

$session->render_ruler();
アーカイブのデフォルト罫線を(ruler.xmlから)返します。

$session->render_link( $uri, $target )
(URIを正しくエスケープした)XHTML要素を返します。
  <a href="uri"></a>

これをappendChildの引数として使うことができます。$targetが指定されている場合は、新規ウィンドウをポップアップさせるためのtarget属性が付きます。

$item->render_value( $fieldname, $showall )
$itemは、イープリント、ユーザ、ドキュメントのいずれかです。

$fieldnameは加工したいフィールドの名前です。$showallを1にすると、多言語フィールドのすべての値が加工されます。

$item->render_citation( $style )
サイテーションファイルで定義されている、そのアイテムタイプのサイテーションを使ってアイテムの引用形を作成します。

$styleが指定されている場合は、アイテムタイプのサイテーションの代わりに指定したidを持つサイテーションを使用します。

$item->render_citation_link( $style )
上と同様に引用形を作成しますが、アイテムのURLへのリンクも引用形に追加します。

$item->render_description()
このデータセット用のデフォルトのサイテーション(たとえば、イープリントは「イープリント」タイプのサイテーション)を使ってアイテムの簡単な記述を作成します。

$session->html_phrase( $phraseid, %opts )
フレーズファイルからアイテムを返します。多言語をサポートしない場合は、これの代わりにmake_textを使ってください。その方が簡単です。

まず、現在の言語のアーカイブ用フレーズファイルを捜します。

次に英語のアーカイブ用フレーズファイルを探します。

次に現在の言語のシステムフレーズファイルを探します。

最後に英語のシステムフレーズファイルを探します。

%optsは一連のDOM要素で、フレーズファイルにある「ピン」アイテムを置き換えます。

その他の便利な関数

$item->get_value( $fieldname, $no_id )
アイテムのフィールド$fieldnameの値を返します。オプションの第2引数($no_id)に1を設定すると、「id」部分なしの値を返します。こちらの方が望ましい場合もあるでしょう。

$item->is_set( $fieldname )
アイテムの指定したフィールドに値が設定されている場合はtrueを、そうでない場合はfalseを返します。

$eprint->get_all_documents()
このイープリントに含まれているドキュメント・オブジェクトの配列を返します。


ArchiveTextIndexingConfig.pm

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スクリプトを使って索引を再作成する必要があります(そうしないと、検索結果に間違いが生じるでしょう)。


ArchiveValidateConfig.pm

このモジュールはユーザが入力したデータの妥当性を検証します。各サブルーチンの詳細については、モジュール自身に記述されています。

各サブルーチンはDOM要素のリストを返します。個々のDOM要素には、1つの問題が記述されています。 どんな問題であっても、その問題を解決しない限りユーザは処理を続けることができません。

データ加工関数同様、複数言語をサポートしない場合は、単に、$session->make_text( "problem explanation" )を呼び出してDOMアイテムを作成することができます。

イープリントとドキュメントのための検証関数はフラグ$for_archiveを持っています。このフラグが1の場合は、アイテムがアーカイブに追加される前にチェックされることを示します。 これを使って、ユーザが入力しなかったフィールドに編集者が必ず入力するようにすることができます。

検証関数

validate_field
すべてのフィールドについて呼び出されます。個々のフィールド値をチェックするために使用します。 デフォルトでは、URLが正しいかどうかをチェックします。

validate_eprint_meta
イープリントのメタデータをチェックします。フィールド間の依存関係をテストするために使用します。たとえば、フィールド「A」とフィールド「B」のいずれかが設定されていなければならないなどです。

validate_eprint
イープリント全体の妥当性を検証します。イープリントの検証で最後に呼び出されます。

validate_document_meta
(eprint_metaと同様に)ドキュメントのメタデータの妥当性を検証します。

validate_document
ドキュメント全体、すなわち、ファイルやメタデータの妥当性を検証します。

validate_user
ユーザレコードの妥当性を検証します。


citations-languageid.xml

サイテーションファイルは、アイテム(イープリント/ユーザ/その他)をXHTMLの断片に加工する方法を記述しています。各サイテーションは「タイプ」属性を持っています。 次の3種類のサイテーションがあります。

デフォルト・サイテーション
アイテムのきわめて短い記述です。一般に「タイトルか、それがない場合はid」です。タイプidはデータセットの名前、たとえば、「eprint」です。

タイプ・サイテーション
より詳細な記述で、イープリント、ユーザ、ドキュメント、それぞれのタイプにより異なります。タイプidは、データセット_タイプ、たとえば、「eprint_preprint」です。

その他のサイテーション
カスタムブラウズビューで使用します。タイプidには、好きな名前を使用することができます。

サイテーションファイルはサイテーション要素のリストを持っています。

 <ep:citation type="...">

各要素は、テキストとタグを持つことができます。テキストは、加工するレコードのフィールド名を持つこともできます。 この名前はシンボル@で囲まなければなりません。たとえば、@authors@や@title@といった感じです。 これは加工の際にフィールド値で置換えられます。(何らかの理由で@自体が必要な場合は、@1つを連続する2つの@で表します。)

注意)@title@スタイルはEPrints2.2で導入されました。それ以前は、&title;のようにXMLエンティティを使用していました。 これは問題を引き起こしていましたが、解決策がありませんでした。エンティティの使用は現在もサポートされていますが、使用しないでください。

さらに、XHTML要素とEPrints名前空間の次の要素を使用することもできます。これらの要素は加工後に除去されますが、その内容を保存するかどうかを決定します。 条件分岐要素はバージョン2.2から互いに入れ子にすることができるようになりました。

<ep:linkhere>
この要素はアイテムへリンクするXHTMLアンカーに置き換えられます。このサイテーションがリンクなしで加工される場合は、単に除去されます(内容は残ります)。

<ep:iflink>
この要素の内容は、このサイテーションをリンクとして加工する場合に限り保存されます。リンクを持たないアイコンを表示したくない場合などに使用できるでしょう。

<ep:ifnotlink>
iflinkの逆です。

<ep:ifset ref=``fieldname''>
この要素の内容は、フィールド「fieldname」が値を持つ場合に限り保存されます。

<ep:ifnotset ref=``fieldname''>
この要素の内容は、フィールド「fieldname」が値を持たない場合に限り保存されます。

<ep:ifmatch name=``fieldname(s)'' value=``searchparam''>
これは条件付加工の世界におけるスイス製アーミーナイフです。ただし、少し複雑なので、これを使う必要があるケースはまれでしょう。 実際、1つの検索要素のように働きます。属性は次の通りです。
name
1つ以上のフィールド名で、検索フィールド設定と同じ形式で指定します。たとえば、「title/abstract」のように。

value
検索する値です。検索フィールドに入力された値のように扱われます。

merge(オプション)
ANYかALLを指定します。検索フォームにおける「すべてにマッチ」と同じ意味です。

match(オプション)
IN、EQ、EX. IN、Equal、Exactのいずれかを指定します。サブジェクト・フィールドにおけるExactは、サブジェクトそのもので、その階層以下のサブジェクトは含まないことを意味します。

たとえば、


 @year@<ep:ifmatch name="year" value="-1949"> 
(approx)</ep:ifmatch>

この例では、yearが1950より前の場合、yearの後ろに(approx)が付きます。良いでしょう。

<ep:ifnotmatch name=``fieldname(s)'' value=``searchparam''>
ifmatchと同じですが、検索がマッチしない場合に限り内部の値が含まれることになります。


metadata-types.xml

このファイルを使って、イープリント、ユーザ、ドキュメントの各タイプ、および、ドキュメントのセキュリティレベルを設定することができます。

新しいタイプを追加する場合は、その名前をアーカイブ用フレーズファイルに追加する必要があります。フレーズidは「データセット_typename_タイプ名」、たとえば、「document_typename_pdf」です。 また、新しいサイテーションをサイテーションファイルに追加しなければなりません。サイテーションに必須ではないフィールドを指定する場合は<ep:ifset>の内部におくべきです。 そうすれば、それが指定されていない場合も「UNSPECIFIED」という表示を見ることがなくなります。

主要素は「metadatatypes」です。この要素は、name属性を持つ「dataset」要素のリストを持ちます。

ユーザとイープリントの「dataset」要素にある「type」要素は、「field」要素のリストを持ちます。 field要素は、このタイプで編集できるフィールドと、その画面上での表示順を記述します。

このリストにシステムフィールドを含めることもできますが、そうする場合は注意して行ってください。

メタデータのページ分割(バージョン2.3.0以降)

オプションとして、フィールドリストに<page name=``pagename'' />要素を追加することができます。 これは投稿プロセスを複数の小さなステージに分割します。pagenameは、データの妥当性の検証などでサブページを識別するために使用します。 page要素が使えるのはイープリントだけで、ユーザやドキュメントなどでは使用できません。

メタデータについて説明した章を参照してください。

「field」要素の属性

name(省略不可)
メタデータフィールドの名前です。

required
「yes」にすると、このフィールドは必須フィールドになります。システムフィールドの中にはこの属性に関わらず常に必須のものがあります。

staffonly
このフィールドは「編集者」用のイープリント編集画面にのみ現れます。ユーザ用の画面には現れません。 たとえば、ユーザデータセットの場合、スタッフ用ユーザ編集画面にのみ現れます。

「security」データセット

セキュリティレベルを定義するのに便利な場所です。name属性を持たないタイプは特別で、「公開用の」セキュリティタイプです。 その他のタイプはすべて有効なユーザ名とパスワードを必要とします。 そのユーザ名が指定したドキュメントをアクセスできるかどうかは、ArchiveConfig.pmにあるcan_user_view_documentサブルーチンで定義されています。

「document」データセット

デフォルトでは、EPrintsがイープリントを妥当とするには、psファイル、pdf、テキストファイル、htmlファイルのうち少なくとも1つがアップロードされていることが必要です。 このファイルのファイル種別のリストは、ArchiveConfig.pmで変更することができます。 なお、これより複雑な条件はイープリント検証サブルーチンでチェックする必要があります。


phrases-languageid.xml

このファイルにはXMLによる「フレーズ」のリストが含まれています。EPrintsがユーザに「伝える」すべてのものは、このファイルか、システムフレーズファイルに格納されています。 複数言語でサイトを運営したい場合は、言語毎に1つずつフレーズファイルを用意する必要があります

フレーズファイルはXMLで書かれており、トップレベルは「phrases」要素です。この要素はフレーズのリストを含んでいます。

各フレーズは、フレーズを識別する「ref」属性を持ち、テキストとオプションのXHTMLタグを含んでいます。 また、&archivename;のようなEPrintsエンティティを含めることもできます。さらに、後で説明する「ピン」要素を含んでいるフレーズもあります。

アーカイブ用フレーズファイルにあるフレーズは、そのアーカイブ固有のフレーズです。一方、システムフレーズファイルは特定のアーカイブに限らないフレーズを持っています。 アーカイブ用フレーズファイルのフレーズidのほとんどは、フィールドやデータセット、タイプなどのidから作られています。

アーカイブ用フレーズファイルには次のデータが含まれています。データセットタイプ名、メタデータフィールド名、メタデータフィールド入力用のヘルプメッセージ、「セット」フィールドのオプション名、検索結果表示順オプションに関する記述、ブラウズビュー名、加工ルーチンおよび検証ルーチンで使用されるフレーズ、EPrintsが送付するメール文、システムフレーズを置き換えるフレーズ。

ピン(pin)

EPrintsに値を挿入する場所を示すために「ピン」要素が必要なフレーズがあります。 一般に、ピン要素は要素を持ちませんが、リンクを置く場所を表す際にまれに要素を持つことがあります。

システムフレーズの置換え

システムフレーズファイルのフレーズが気に入らない場合は、アーカイブ用フレーズファイルに同じ「ref」を持つフレーズを作成することで置き変えることができます。

システムフレーズファイルを編集しないでください。EPrintsを新バージョンにバージョンアップする際に、システムフレーズファイルは上書きされてしまうからです

メール

EPrintsは、ユーザがパスワードを登録・変更した場合や、メールアドレスを変更した場合、 投稿されたアイテムが編集者により棄却・削除された場合、システムリソースが不足した場合などにメールを送信します。 これらのメール文はフレーズファイルでカスタマイズすることができます。

テキストは必ずパラグラフタグ<p>で囲んでください。<hr />要素はメール文中ではダッシュ線で置き換えられます。

EPrintsがメールを送る際は、ラテン-1要素が含まれている場合を除いて、プレーンテキストで送信します。ラテン-1要素がある場合は、ラテン-1符号化をして送信します。 ラテン-1文字セットではなく、ユニコード文字が含まれている場合は、utf-8符号化をして送信します。


ruler.xml

EPrintsが使用する横罫線を設定します。EPrintsは、&ruler;の位置にこれを挿入します。

<hr>による横罫線で問題ない場合は、変更する必要はありません。

このファイルでは、&frontpage;のようなエンティティは使用することができません。


static/ ディレクトリ

このディレクトリにはサイトの静的なページ、すなわち、フロントページ、ヘルプページ、画像、スタイルシートなど、が含まれています。

static/は、たとえば、en/のように、言語毎に1つのディレクトリを持ちます。 さらに、画像やスタイルシートのように翻訳する必要がないファイルを収めるgeneral/ディレクトリを持ちます。

generate_staticコマンドを実行すると各言語用のファイルが各言語用のディレクトリに、さらにgeneralディレクトリがコピーされます。

詳細については、generate_staticコマンドの説明文書を参照してください。


サブジェクト

このファイルは、EPrintsのコアシステムでは使用されません。import_subjectsコマンドを使って、サブジェクトを初期構築する際に使用されます。 詳細については、import_subjectsコマンドの説明文書を参照してください。


template-languageid.xml

このファイルはシステムのすべてのページの骨組みとなるものです。これはおおよそ普通のXHTMLファイルですが、&foo;という形式のEPrintsエンティティを使うことができます。 また、フレーズのように「ピン」要素を含めるべきです。含めるべきピンは以下のとおりです。

<ep:pin ref="title" />
これはページのタイトルを置く場所です。ページヘッダタイトルやbodyの中などで複数回使うことができます。 ページヘッダタイトルで使用する場合は、同時に属性「textonly="yes"」を使用する必要があります。なお、この属性はここにしか使用できません。 この属性はタイトルから画像を除去します(画像付きのタイトルは「Latex」モードの場合生じることがあります)。

<ep:pin ref="head" />
ページヘッダに置きます。EPrintsに「meta」要素あるいは「link」要素を挿入する場所を示します。

<ep:pin ref="pagetop" />
bodyの先頭に置きます。「target」として使用されることがあります。

<ep:pin ref="page" />
ページコンテンツを置く場所です。

 EPrints 2.3技術文書 - アーカイブ設定ファイル