[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][TOP]
Re: gconf intro-article.sgml
こんにちわ、相花と申します。
既に岡さんが公開下さっています、
GConf のドキュメントで担当分ができあがりましたので、
ここに公開させて頂きます。
# 少々大きなサイズとなっていますが、ご了承ください。
誤訳などありましたら、岡さん担当分同様、ご指摘下さい。
# 先に公開されました岡さんの記述や語句の用法に
# なるべく合わせたつもりです。
宜しくお願い致します。
---
(相花)
<!DOCTYPE BOOK PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
<!entity GConfClient SYSTEM "sgml/gconf-client.sgml">
<!entity gconf-gconf-backend SYSTEM "sgml/gconf-backend.sgml">
<!entity gconf-gconf-engine SYSTEM "sgml/gconf-engine.sgml">
<!entity gconf-gconf-error SYSTEM "sgml/gconf-error.sgml">
<!entity gconf-gconf-internals SYSTEM "sgml/gconf-internals.sgml">
<!entity gconf-gconf-listeners SYSTEM "sgml/gconf-listeners.sgml">
<!entity gconf-gconf-schema SYSTEM "sgml/gconf-schema.sgml">
<!entity gconf-gconf-sources SYSTEM "sgml/gconf-sources.sgml">
<!entity gconf-gconf-value SYSTEM "sgml/gconf-value.sgml">
<!entity gconf-gconf SYSTEM "sgml/gconf.sgml">
<!entity gconf-gconf-locale SYSTEM "sgml/gconf-locale.sgml">
<!entity gconf-gconf-changeset SYSTEM "sgml/gconf-changeset.sgml">
]>
<book id="index">
<bookinfo>
<authorgroup>
<author>
<firstname>Havoc</firstname>
<surname>Pennington</surname>
<affiliation>
<orgname>Red Hat Advanced Development Labs</orgname>
</affiliation>
<authorblurb>
<para>
<email>hp@xxxxxxxxxx</email>
</para>
</authorblurb>
</author>
</authorgroup>
<copyright>
<year>1999</year>
<holder>Havoc Pennington</holder>
</copyright>
<!-- GConf -->
<!-- <title>GConf Manual</title> -->
<title>GConf マニュアル</title>
<abstract>
<para>
<!--
GConf is a system for storing configuration information, that is,
key-value pairs. GConf provides a notification service so applications
can be notified when a key's value is changed. GConf also allows for
pluggable storage mechanisms (text files, databases, etc.); allows
administrators to install default values; and allows application authors
to document their configuration keys for the benefit of administrators.
-->
GConf は設定データを格納するシステムで、それはキーと値のペアで構成
されます。GConf はキーに対応する値が変更された場合にアプリケーションに
通知されるサービスを提供します。GConf は更にプラグイン形式の
ストレージメカニズム(テキストファイルや、データベースなど)向けであり、
システム管理者にデフォルト値をインストールさせたり、アプリケーションの作者に
システム管理者のためになる設定キーを文書化したりします。
</para>
</abstract>
<legalnotice>
<para>
<!--
This document may be distributed subject to the terms and
conditions set forth in the Open Publication License, v1.0 or
later (the latest version is presently available at <ulink
url=" http://www.opencontent.org/openpub/"
type="http">http://www.opencontent.org/openpub/</ulink> )
-->
このドキュメントは Open Publication License v1.0 かそれ以上
のバージョンの中の項目で述べられる条件で配布されます。
(最新バージョンは <ulink
url=" http://ww.opencontent.org/openpub/"
type="http">http://www.opencontent.org/openpub/</ulink>
で公開されています。)
</para>
</legalnotice>
</bookinfo>
<!-- Introduction to GConf -->
<chapter>
<!-- <title>Introduction to GConf</title> -->
<title>GConf の紹介</title>
<para>
<!--
This chapter introduces GConf, including the basic terms and
concepts. After reading it, if you're a GNOME programmer looking
to dive in quickly, you might skip to <xref
linkend="gconfclient-example">. If you want to have
comprehensive knowledge of GConf, you might want to read the
whole manual.
-->
この章では基本事項と概念を含んだ GConf 全体を紹介します。
この後で、貴方が GNOME プログラマとして先にどんどん進みたい
というなら、ここを飛ばして <xref linkend="gconfclient-example">
に進んでみてください。もし貴方が GConf について全ての知識を知りたいと
思うならばこのマニュアル全体に目を通して下さい。
</para>
<!-- Motivation -->
<sect1>
<!-- <title>Motivation</title> -->
<title>事の始まり</title>
<para>
<!--
GConf is intended to store key-value pairs, where keys are
located in an infinite tree-structured namespace (similar to the
UNIX filesystem). It offers several useful features:
<itemizedlist mark="bullet">
-->
GConf はツリー構造となっている無限の(UNIX ファイルシステムに似た)
名前空間上に存在するキーとその値のペアを保存するためのものです。
これには幾つかの利点を追求する意図があります:
<itemizedlist mark="bullet">
<listitem>
<para>
<!--
Users can select a variety of data storage backends, such as XML
text files, ACAP, or databases (LDAP, DB, etc.). This makes it
easy to adapt GConf to local needs. It also avoids the age-old
"text files vs. binary registry" debate. (Note: the current GConf
only has an XML backend implemented, other backends are easy to
write though.)
-->
ユーザーは XML テキストファイル、ACAPまたはデータベース(LDAP、DB、等々)の
様々なデータストレージバックエンドを選択する事が 可能です。
これは GConf がローカルなニーズに応えやすくするものです。
これはまた、長年繰り広げられている "テキストファイル 対 バイナリレジストリ"
論争を回避することも意図しています。
(追記: 現在の GConf は XML バックエンドのみ実装されており、他の
バックエンドはこれを通して記述し易いものになっています。)
</para>
</listitem>
<listitem>
<para>
<!--
GConf offers a notification service, so applications can
ask to be notified when the value of a key changes.
This allows settings to be applied to groups of
applications, without restarting them and without
ugly hacks. It also allows a clean model-view
architecture for applications.
-->
GConf はアプリケーションにそのキーに対する値が変更された旨を
知らせるといったような通知サービスを提供します。
これはアプリケーションの再起動や嫌なハッキング無しに、その
設定がアプリケーションのグループに適用されることを意味して
います。更にアプリケーションがクリーンなモデルビュー構造に
なるようにしています。
</para>
</listitem>
<listitem>
<para>
<!--
Each user has a "GConf search path" which is a list of
configuration sources to scan for each value.
For example, the configuration engine might look for
values first in the local machine's database and
then in a network-wide database.
-->
各ユーザーは 各値を調べるための設定ファイルのリストである、
1つの"GConf 検索パス" を持っています。
例えば、設定エンジンはローカルマシンのデータベースを検索
したり、ネットワーク規模のデータベースを検索することになる
でしょう。
</para>
</listitem>
<listitem>
<para>
<!--
GConf is implemented as a per-user daemon, which makes
locking a non-issue and allows aggressive caching.
-->
GConf は 1 ユーザー 1 デーモンとして実装されており、これは
該当しない項目をロックさせたり積極的なキャッシングの利用
を可能にさせます。
</para>
</listitem>
<listitem>
<para>
<!--
The client API is simple and very abstract, which allows us to
change its implementation at a later time without a big headache.
Because a good implementation is a complex problem, this is
important.
-->
クライアント API はシンプルであり非常に抽象的で、後でさほど悩まずに
実装変更ができるようになっています。
なぜなら、良い実装とは難しい問題であり、これは重要なことだから
です。
</para>
</listitem>
</itemizedlist>
</para>
<para>
<!--
GConf was inspired by Wichert Akkerman's configuration system
specification, originally developed for the Debian project. See <ulink
url="http://www.debian.org/~wakkerma/config6"
type="http">http://www.debian.org/~wakkerma/config6</ulink> for his
specification. Other sources of ideas include the Windows registry,
the ACAP specification, and Emacs customize mode (try typing
<literal>M-x customize-browse</literal> in Emacs).
-->
GConf は Wichert Akkerman の設定システムから生み出されました。これは Debian
プロジェクト向けに開発されたオリジナルな仕様です。この仕様については、<ulink
url="http://www.debian.org/~wakkerma/config6"
type="http">http://www.debian.org/~wakkerma/config6</ulink> を参照して
下さい。このアイディアの他のソースには Windows のレジストリ概念、
ACAP 仕様、そして Emacs のカスタマイズモード (Emacs で次のようにタイプ
してみて下さい; <literal>M-x customize-browse</literal>) の概念を含んでいます。
</para>
</sect1>
<!-- Terms and Concepts -->
<sect1>
<!-- <title>Terms and Concepts</title> -->
<title>条件とコンセプト</title>
<para>
<!--
This section introduces the basic GConf structure and terminology.
-->
ここでは GConf の基本と使用する用語について紹介します。
</para>
<sect2>
<!-- <title>Namespace</title> -->
<title>名前空間</title>
<para>
<!--
The GConf namespace is almost exactly like the UNIX filesystem; that
is, a tree structured directory hierarchy. Each name is either a
"file" (a configuration key storing a value) or a "directory" (a list
of child configuration key names). A name is specified with a
slash-separated path. A full path is referred to as a
<firstterm>key</firstterm>. Characters in a path should be
alphanumeric or underscore. Path components may not start with a
period.
-->
GConf の名前空間は大方 UNIX ファイルシステムのようなものです。つまり、
ツリー構造となったディレクトリ階層です。各名前は "ファイル"(値を格納する
設定キー) かまたは "ディレクトリ"(下層の設定キー名を示すリスト)のどちらか
です。1 つの名前は '/'(スラッシュ)で分割されたパスで指定されます。
1 つのフルパス名は 1 つの<firstterm>キー</firstterm>として参照されます。
パスに含まれる文字はアルファベット・数字または '_'(アンダースコア)でなけれ
ばなりません。パス名を構成するものは '.'(ピリオド) で始まってはいけません。
</para>
</sect2>
<!-- Data Types -->
<sect2>
<!-- <title>GConf Data Types</title> -->
<title>GConf のデータ型</title>
<para>
<!--
GConf can only store a small, fixed set of data types. This keeps the
database implementation simple and efficient. GConf should
<emphasis>not</emphasis> be used to store data files or any other
large amount of information; <emphasis>it is designed for simple
configuration data only</emphasis>. There are any number of better
solutions available for storing documents and other large data
chunks. You might want to store a filename, URL, or Bonobo moniker in
GConf pointing to a larger piece of data, if you need the GConf
notification facilities.
-->
GConf はデータ型を小さくかつ固定型で格納します。これはデータベースの
実装をシンプルにかつ効果的に実装させるためです。GConf はデータファイル
または何か多くの情報を格納するために<emphasis>使われるべきではありません</emphasis>。
<emphasis>それはシンプルな設定データのみ対象として設計されたものです</emphasis>。
ドキュメントや大規模データの格納に有効な概念は沢山あります。貴方が
GConf による通知の利便性を必要とするならば、ファイル名、URL、GConf
が示す大規模なデータの塊の Bonobo moniker を格納したいはずです。
</para>
<para>
<!-- Here are the GConf datatypes: -->
ここでは GConf のデータ型について説明します:
<variablelist>
<varlistentry>
<!-- <term>Integer</term> -->
<term>整数型</term>
<listitem><para>
<!--
Integer values are simple C-style integers, that is, they are
limited to 32 bits and can be positive or negative.
-->
整数型はシンプルな C言語スタイルの整数と同じで、これは 32 ビット
を上限とし、正の数または負の数を表現する事が可能です。
</para></listitem>
</varlistentry>
<varlistentry>
<!--
<term>String</term> <listitem><para> String values can contain any
text you like, but not binary data (such as the NULL character).
GConf should handle any string the C library string functions can
handle. </para></listitem>
-->
<term>文字型</term> <listitem><para> 文字型は何か好きなテキストを
含むことができますが、バイナリデータ(NULL文字のようなもの)は含む
ことができません。
GConf は Cライブラリ関数が操作できる文字列を操作すべきです。</para></listitem>
</varlistentry>
<varlistentry>
<!--
<term>Float</term> <listitem><para> Float values are floating
point numbers. Given differences between machine architectures
and C libraries, there is no guaranteed degree of precision, other
than "a reasonable degree."
</para></listitem>
-->
<term>浮動小数点型</term> <listitem><para> 浮動小数点型は浮動小数点付きの
数字です。アーキテクチャと Cライブラリとの間に違いを与えてしまうと、
他の"手ごろな精度"よりも正確な精度を保証できなくなります。
</para></listitem>
</varlistentry>
<varlistentry>
<!-- <term>Bool</term> -->
<term>論理型</term>
<listitem><para>
<!--
Boolean values are true or false.
-->
論理型は真または偽をもちます。
</para></listitem>
</varlistentry>
<varlistentry>
<!-- <term>Schema</term> -->
<term>スキーマ型</term>
<listitem><para>
<!--
Schemas store a <structname>GConfSchema</structname>
data type, which contains meta-information about a key, such
as documentation and its type.
-->
スキーマ型は <structname>GConfShema</structname>型のデータを
格納し、キーについて文書やキーの型といったメタ情報を
含んでいます。
</para></listitem>
</varlistentry>
<varlistentry>
<!-- <term>List</term> -->
<term>リスト型</term>
<!--
<listitem><para> List values store a group of
values. All values in a list must have the same primitive
type. Heterogeneous lists are not allowed. Lists of lists and
lists of pairs are not allowed.
</para></listitem>
-->
<listitem><para> リスト型は値のグループを
格納します。リスト中の値は全て同じプリミティブな型である
必要があります。異種のデータ型を含むリストは許されていません。
リストの中のリストや対のリストは許されていません。
</para></listitem>
</varlistentry>
<varlistentry>
<!-- <term>Pair</term> -->
<term>ペア型</term>
<!--
<listitem><para> Pairs store two primitive
values. The two values do not necessarily have the same
type. Pairs can not contain pairs or lists, only primitive types.
</para></listitem>
-->
<listitem><para> ペア型は 2 つのプリミティブな値を
格納します。2 つの値は同じ型である必要はありません。
ペアの中にペアを含んだり、リストの中のペアは許されません。
プリミティブな型だけです。
</para></listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
<!-- Sources -->
<sect2>
<!-- <title>Configuration Sources</title> -->
<title>設定ファイルについて</title>
<!--
<para> Users can specify <firstterm>configuration sources</firstterm>
which will be used by the <application>gconfd</application> per-user
configuration server. <application>gconfd</application> loads the
file <filename>/etc/gconf/path</filename> (or
<filename>${sysconfdir}/gconf/path</filename>) on startup; this file
contains a list of <firstterm>configuration source
addresses</firstterm>. A source address is similar to a URL; it
contains a "protocol" name (in this case, the name of the backend to
use), followed by a colon, standard flags separated by commands,
another colon, and then backend-specific information. For example, the
address <filename> xml:readonly:/home/hp/.gconf.xml</filename> refers
to an XML backend file tree rooted at
<filename>/home/hp/.gconf.xml</filename> that should be "mounted
readonly" so that no data is written to it.
</para>
-->
<para> ユーザーは <firstterm>設定ファイル</firstterm>を指定できます。
これは ユーザー設定サーバーである、<application>gconfd</application>
によって使用されます。<application>gconfd</application>は起動時に
<filename>/etc/gconf/path</filename>(または <filename>${sysconfdir}/gconf/path</filename>)
のファイルを読み込みます。このファイルは <firstterm>設定ファイルのアドレス</firstterm>
のリストを持っています。ファイルアドレスは URL に似ています。この
アドレスは "プロトコル"名(この場合は、使用するバックエンドの名前)を含んで
おり、':'(コロン)に続いてコマンド、コロンで区切られた標準フラグがあり、
それからバックエンド仕様情報が続きます。例えば、アドレス
<filename> xml:readonly:/home/hp/.gconf.xml</filename>は、
何もデータが書き込まれていない "読み込み専用(readonly)でマウントされた"、
<filename>/home/hp/.gconf.xml</filename>がルートの XML バックエンド
ファイルを参照します。
</para>
<para>
<!--
<filename>/etc/gconf/path</filename> stores a list of
addresses, which form a <firstterm>configuration source
path</firstterm>. When looking up a value, GConf will begin
with the first source in the path, and continue checking
each source until the value is found or there are no more
sources. When setting a value, GConf will use the first
<emphasis>writeable</emphasis> source. System
administrators can impose <emphasis>mandatory</emphasis>
settings on their users by placing a read-only source at the
front of the path (note that "mandatory" only means that
existing programs won't let them change the value, users
could hack their own copy of GConf that ignored system
settings). If a key has a value in a read-only source placed
before the first user-writeable source, user applications
attempting to set that value will receive an error.
Administrators can provide <emphasis>default</emphasis>
values by placing a systemwide source at the end of the
configuration source path.
-->
<filename>/etc/gconf/path</filename> はアドレスを格納しており、
このアドレスは <firstterm>設定ファイルパス</firstterm>の
フォームです。値を検索しようした場合、GConf はこのパス上の
最初の設定ファイルから開始し、それから値が見つかるかもしくは
設定ファイルが無くなるまで各設定ファイルを検索し続けます。
値を設定する場合、GConf は最初の <emphasis>書き込み可能な</emphasis>
設定ファイルを使用します。システム管理者はパスの前に
読み込み専用ファイルを置くことにより、ユーザーが設定を
<emphasis>強制的に</emphasis>(注: "強制的に" はプログラムが
値を変更させない、ユーザーがシステム設定を無視して GConf の
コピーをハックしたりさせないことを意味してしています。)
設定する事がないようにできます。もし最初のユーザー書き込みが
可能な設定ファイルの前にある読み込み専用ファイルの中で
既にキーが値を保持していたら、ユーザーアプリケーションは値が
エラーを受け取るようにセットしようとします。
システム管理者は設定ファイルのパスの最後にシステム規模の設定
ファイルを記述することにより <emphasis>デフォルト</emphasis>
の値をセットする事ができます。
</para>
<para>
<!--
The source configuration file can contain "include" statements and
some magic variables; you can use this to include a .gconf.path file
from the user's home directory. Variables are placed in
<symbol>$()</symbol>. Two variables are built-in to GConf:
<symbol>$(HOME)</symbol> is the user's home directory, and
<symbol>$(USER)</symbol> is the username. You can also access any
environment variable by prepending <symbol>ENV_</symbol> to the
variable name. For example, <symbol>$(ENV_FOO)</symbol> will be
replaced by the <symbol>FOO</symbol> environment variable.
-->
設定ファイルは文や幾つかのマジック変数を"挿入"することができます。
これらをユーザーのホームディレクトリから .gconf.path ファイルに
挿入する事ができます。変数は<symbol>$()</symbol>の中に記述します。
次の 2 つの変数は GConf の中で既に組み込まれています:
<symbol>$(HOME)</symbol> はユーザーのホームを、そして
<symbol>$(USER)</symbol> はユーザー名を表しています。ユーザーは
<symbol>ENV_</symbol>を変数名の前に付けることで幾つかの環境変数に
アクセスすることが可能です。例えば、<symbol>$(ENV_FOO)</symbol> は
環境変数 <symbol>FOO</symbol> によって置き換わります。
</para>
<para>
<!--
So once everything is working a
<filename>/etc/gconf/path</filename> file might look like
this:
-->
ファイル <filename>/etc/gconf/path</filename> は次のように
1 度だけ動作します:
<programlisting>
<!--
# GConf configuration path file with an include statement
xml:readonly:/etc/gconf.xml.mandatory
include "$(HOME)/.gconf.path"
xml:readonly:/etc/gconf.xml.defaults
# imaginary, no LDAP backend exists right now
ldap::/foo/bar/whatever/ldap/address
-->
# GConf 設定パスは文を含むことが可能です。
xml:readonly:/etc/gconf.xml.mandatory
include "$(HOME)/.gconf.path"
xml:readonly:/etc/gconf.xml.defaults
# 実在しない、LDAP でないバックエンドが存在します。
ldap::/foo/bar/whatever/ldap/address
</programlisting>
</para>
<para>
<!--
Note that particular backend modules may have their own special
configuration. For example, you may need to configure the details of
an LDAP backend.
-->
特にバックエンドモジュールがそれ自身で特別な設定を持っているかもしれない
ことに注意して下さい。例えば、LDAP バックエンドには詳細な設定情報が必要かも
しれません。
</para>
</sect2>
<!-- Schemas -->
<sect2 id="concepts-schemas">
<!-- <title>Schemas</title> -->
<title>スキーマ</title>
<para>
<!--
A <firstterm>schema</firstterm> describes some configuration
key. Its primary purpose is to provide documentation about
the key to system administrators manipulating the GConf
database. Secondarily, schemas contain a good default value
for the key; GConf will automatically return this value when
a key is unset. Schemas also include the name of the
application that created a key (useful when trying to clean
old junk out of the database, for example).
-->
<firstterm>スキーマ</firstterm> は幾つかの設定キーを記述しま
す。この第一の目的はシステム管理者に GConf データベースを操作
するための文書を提供することにあります。
第二の目的として、スキーマはキーに対応したデフォルト値を持って
います。GConf はキーが無効になった時にに自動的にこの値を返します。
スキーマはキーによって生成されたアプリケーション名も保持しています。
(例えば、データベースの外にある古いデータの塊をクリアしようとする
場合に便利です。)
</para>
<para>
<!--
Schemas are normally installed from special schema
description files; the <application>gconftool</application>
program knows how to read these and install the schemas into
the GConf database. Normally, schemas are not installed by
application code, though the interface for doing so is a
public part of the GConf API.
-->
スキーマは通常、特別なスキーム記述ファイルからインストールされ
ます。<application>gconftool</application> プログラムはスキーマ
の読み方を知っており、これらのスキーマを GConf データベースの中に
インストールします。通常、スキーマはアプリケーションによって
インストールされるものではなく、GConf API の公開されたインタフェース
を通して行われます。
</para>
</sect2>
</sect1>
</chapter>
<!-- Client Library -->
<chapter>
<!-- <title>C Language Client Library</title> -->
<title>C 言語クライアントライブラリ</title>
<para>
<!--
The GConf client library is used by applications
to store or retrieve configuration data. This library presents
the lowest-level (but still fairly convenient) mode of access
to the GConf database; the GConf database does not speak a
public protocol and can not be accessed directly.
-->
GConf クライアントライブラリは設定データを格納したり取得するために
アプリケーションによって使用されます。このライブラリは GConf
データベースにアクセスする低レベル(ですが、未だに大変便利なものです)
モードを提供します。GConf データベースは公のプロトコルを使えないし、
また直接アクセスすることもできません。
</para>
<para>
<!--
Convenience wrappers for the GConf client library are possible.
Right now a nice wrapper based on the GTK+ object system exists;
see <xref linkend="gtk-wrapper">.
-->
GConf クライアントライブラリ向けの便利なラッパーツールがあります。
存在する GTK+ オブジェクトシステムを基にした有用なラッパーツールを
今すぐ見て下さい。<xref linkend="gtk-wrapper">
</para>
<para>
<!--
Note that this is only a brief tutorial-style introduction to
the client library; have a look at <xref
linkend="gconf-reference"> for a complete reference.
-->
これはクライアントライブラリについての紹介をチュートリアル形式で
与えただけであることに注意して下さい。完全なリファレンス情報に
ついては <xref linkend="gconf-reference"> を参照して下さい。
</para>
<!-- Error Handling -->
<sect1>
<!-- <title>Error Handling</title> -->
<title>エラーハンドリング</title>
<para>
<!--
Error handling isn't exciting but it's unfortunately
necessary. Because even the initialization of the GConf
library can fail, we have to cover error handling first.
-->
エラーハンドリングはエキサイトするほどのものでは無いですが、
不幸なことに必要不可欠です。なぜなら GConf ライブラリの
初期化に失敗する度に、我々はまず先にそのエラーをハンドルしなければ
ならないからです。
</para>
<para>
<!--
Errors are returned in a <structname>GConfError</structname> object.
<structname>GConfError</structname> has two public fields:
<structfield>str</structfield> is an error message, and
<structfield>num</structfield> is an <symbol>errno</symbol>-style
enumerated value with type <symbol>GConfErrNo</symbol>, useful for
switching on an error and taking different actions depending on the
exact error that occurred.
-->
エラーは <structname>GConfError</structname>オブジェクトの中に返されます。
<structname>GConfError</structname> は 2 つのパブリックな領域を持っています。
<structfield>str</structfield> はエラーメッセージであり、そして
<structfield>num</structfield> は 1 つの <symbol>errno</symbol> スタイルの
<symbol>GConfErrNo</symbol> 型で列挙された値で、エラーの分岐に有用であり
引き起こされたエラーそのものに基づく異なった処理ができます。
</para>
<para>
<!--
GConf functions that potentially fail accept a
<symbol>GConfError**</symbol> argument, where they store a
<structname>GConfError</structname> object if the operation
fails. If no error occurs, the location pointed to by the
<symbol>GConfError**</symbol> is left unchanged. In all cases,
you can pass <symbol>NULL</symbol> as the
<symbol>GConfError**</symbol>, to ignore any errors. Needless
to say, normally you should report errors instead of ignoring
them.
-->
GConf 関数は <symbol>GConfError**</symbol> 引数や、また操作が
失敗した場合に <structname>GConfError</structname> オブジェクト
を格納する場所を受け入れて潜在的にエラーを起こす。何もエラーが
起こらなかった場合、<symbol>GConfError**</symbol>が指す場所は
変更されない。全ての場合で 全てのエラーを無視して、
<symbol>GConfError**</symbol> をパスすることができます。必要ならば、
通常無視されたエラーの代わりにエラーの報告をしなければなりません。
</para>
<para>
<!-- If an error is returned, you must free it with -->
もしエラーが返されたら、そのエラーを解放する必要があります
<function>gconf_error_destroy()</function>:
<funcsynopsis>
<funcsynopsisinfo>#include <gconf/gconf.h></funcsynopsisinfo>
<funcdef>void
<function>gconf_error_destroy</function>
</funcdef>
<paramdef>GConfError* <parameter>error</parameter></paramdef>
</funcsynopsis>
</para>
<para>
<!-- Thus, a complete error-checking sequence might work like this: -->
従って、コンパイル時のエラーチェック処理は次のように動作します。
<programlisting>
GConfError* err = NULL;
if (!gconf_init(&err))
{
fprintf(stderr, _("Failed to init GConf: %s\n"), err->str);
gconf_error_destroy(err);
err = NULL;
}
</programlisting>
<!--
Note that <function>gconf_init()</function> returns
<symbol>TRUE</symbol> on success and <symbol>FALSE</symbol> on failure,
other functions may have different ways of indicating
success/failure. Also note that the <symbol>err</symbol> variable is
initialized to <symbol>NULL</symbol>; this is
<emphasis>required</emphasis>.
-->
<function>gconf_init()</function> は 成功時に <symbol>真</symbol> を、
失敗時に <symbol>偽</symbol> を返し、他の関数は成功/失敗を別の方法で
知らせることに注意してください。また、<symbol>err</symbol> 変数は
<symbol>NULL</symbol>で初期化されることにも注意してください。
これは <emphasis>必要条件</emphasis> です。
</para>
<para>
<!--
Error checking is slightly inconvenient to use because we have to be
thread-safe; GConf originally had a system similar to
<symbol>errno</symbol>, but that doesn't work with threads. GConf still
isn't thread-safe, but the API isn't inherently unsafe.
-->
エラーチェック処理は使うには少々不便なものである。なぜならスレッドセーフ
にする必要があるからである。元来 GConf は <symbol>errno</symbol>に似た
システムを持っているが、それはスレッド付きでは動作しません。GConf は
まだスレッドセーフに対応しておらず、その API は本来セーフではありません。
</para>
<para>
<!-- The available values for <symbol>GConfErrNo</symbol> are: -->
<symbol>GConfErrNo</symbol>に有効なもの :
<variablelist>
<varlistentry><term>GCONF_SUCCESS</term>
<listitem>
<para>
<!-- Indicates that there was no error. -->
エラーが無いことを知らせます。
</para>
</listitem>
</varlistentry>
<varlistentry><term>GCONF_FAILED</term>
<listitem>
<para>
<!--
Indicates that the operation fatally failed for
some fairly unpredictable and idiosyncratic reason
not covered by the more specific error values.
The error message will give details.
-->
処理が最終的に全く予知できず、そして特別な理由が
更に多くの特別なエラーによってカバーされなかった
ことによるものであることを知らせます。
そのエラーメッセージは詳細な情報を与えてくれます。
</para>
</listitem>
</varlistentry>
<varlistentry><term>GCONF_NO_SERVER</term>
<listitem>
<para>
<!--
The <application>gconfd</application> configuration server
could not be contacted, and we couldn't or didn't
respawn it for whatever reason. The error message
may give more details. This probably means either a
bug in <application>gconfd</application> or a hosed local
configuration.
-->
<application>gconfd</application> 設定サーバーが通信すること
ができず、いかなる理由でも respawn 出来なかった/しなかった。
エラーメッセージは更に詳細な情報を与えてくれます。これは
おそらく <applicaton>gconfd</application>の中にあるバグか
もしくはローカル設定に水がまかれたことを意味します。
</para>
</listitem>
</varlistentry>
<varlistentry><term>GCONF_NO_PERMISSION</term>
<listitem>
<para>
<!--
User was denied permission to access some resource
at some point; perhaps a file in a file-based
configuration backend, perhaps some authentication
tokens are wrong. The error message will give more details.
-->
幾つかのポイントで幾つかのリソースに対するユーザーのアクセス権が
拒否されました。おそらくファイルベースの設定バックエンド、幾つかの
認証が間違っています。エラーメッセージはその詳細を与えてくれます。
</para>
</listitem>
</varlistentry>
<varlistentry><term>GCONF_BAD_ADDRESS</term>
<listitem>
<para>
<!-- A configuration source address was invalid. -->
設定ファイルのアドレスが不正である。
</para>
</listitem>
</varlistentry>
<varlistentry><term>GCONF_BAD_KEY</term>
<listitem>
<para>
<!-- A configuration key was invalid. -->
設定キーが不正である。
</para>
</listitem>
</varlistentry>
<varlistentry><term>GCONF_PARSE_ERROR</term>
<listitem>
<para>
<!--
Something had to be parsed, and it couldn't
be. Typically, a string representation of a config
value found in a config file or obtained from the
user. Error message will often have more details.
-->
何かが解析され、そしてそれが存在することが出来なかった。
設定ファイルまたはユーザーから得たものから設定値の文字列
の塊が見つかった典型的なケースです。エラーメッセージは時々
詳細な情報を与えてくれます。
</para>
</listitem>
</varlistentry>
<varlistentry><term>GCONF_CORRUPT</term>
<listitem>
<para>
<!--
Typically means that the text files or binary database
used by some backend have gotten hosed. Most backends
will try to self-repair, within reason. If they can't
they will bail with this error.
-->
典型的なケースとして、幾つかのバックエンドが使用した
テキストファイルまたはバイナリデータベースが水をまいてしまった。
ほとんどのバックエンドが理由無しで自分で復帰しようと努め
ます。バックエンドがくみ出すことが出来なかったら、
このエラーでくみ出すことになります。
</para>
</listitem>
</varlistentry>
<varlistentry><term>GCONF_TYPE_MISMATCH</term>
<listitem>
<para>
<!--
Some routines in the GConf libraries impose type
constraints; if these are violated you get this error.
For example, <function>gconf_get_int()</function>
returns this error if the value found is actually a
string.
-->
GConf ライブラリの幾つかのルーチンが無理強いした。
もし邪魔があればこのエラーを取得します。
例えば、値が文字列の中に存在すると、
<function>gconf_get_int()</function>はこのエラーを返します。
</para>
</listitem>
</varlistentry>
<varlistentry><term>GCONF_IS_DIR</term>
<listitem>
<para>
<!--
This error is returned if you try to perform a key
operation on a name that turns out to be a directory.
Some backends don't check for this error, they just
report that the key isn't set...
-->
ディレクトリと分かっている名前に対してキー操作を行おうと
すると、このエラーが返されます。幾つかのバックエンドは
このエラーをチェックせず、バックエンドはキーが設定されて
いません...と報告するだけです。
</para>
</listitem>
</varlistentry>
<varlistentry><term>GCONF_IS_KEY</term>
<listitem>
<para>
<!--
This error is returned if you try to perform a
directory operation on a name that turns out to be
a key. Some backends don't check for this error...
-->
キーだと分かっている名前に対してディレクトリの操作を
行おうとすると、このエラーが返されます。幾つかのバックエンド
はこのエラーをチェックしません...
</para>
</listitem>
</varlistentry>
<varlistentry><term>GCONF_OVERRIDDEN</term>
<listitem>
<para>
<!--
This means that you tried to set a value, and a
read-only configuration source found before the first
user-writeable source in the path has already set the
value. That is, setting the value would have no
effect because the read-only source's setting would
override the new value. You should report to the user
that their setting will not take effect.
-->
値をセットして読み込み専用設定ファイルが既に値がセット
されているパスの中で、最初のユーザー書き込み可能な設定
ファイルの前に見つかったことを意味します。
これは、設定した値が何も効果を持っていないことを表します。
なぜなら読み込み専用のファイルの設定が新しい値を上書き
するためです。ユーザーにその設定に意味が無いことを報告
する必要があります。
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!--
<function>gconf_error_new()</function> is used inside the
library and inside the library backends. It is typically not
useful to clients. It simply creates a new error, from a
<symbol>GConfErrNo</symbol> and a
<function>printf()</function>-style format and variable
argument list.
-->
<function>gconf_error_new()</function> がライブラリ内部と
ライブラリバックエンドの内部で使われています。クライアントが
有効ではない典型的なケースです。<symbol>GConfErrNo</symbol>
と <function>printf()</function> スタイルのフォーマット、変数
リストから新しいエラーを生成します。
<funcsynopsis>
<funcsynopsisinfo>#include <gconf/gconf.h></funcsynopsisinfo>
<funcdef>void
<function>gconf_error_new</function>
</funcdef>
<paramdef>GConfErrNo <parameter>en</parameter></paramdef>
<paramdef>const gchar*
<parameter>format</parameter></paramdef>
<paramdef><parameter>...</parameter></paramdef>
</funcsynopsis>
</para>
</sect1>
<!-- Initialization -->
<sect1>
<!-- <title>Initialization</title> -->
<title>初期化</title>
<para>
<!--
The GConf client library must be initialized before use.
Initialization establishes a connection to the ORB (because
CORBA is currently used to implement GConf, though clients
never have to see this) and sets up some global data
structures. The arguments to <function>gconf_init()</function>
are an argc/argv pair to check for CORBA-related command line
options, and a location to place any error that
occurs. <function>gconf_init()</function> returns
<symbol>TRUE</symbol> on success.
-->
GConf クライアントライブラリは使用する前に必ず初期化する必要があります。
初期化処理は ORB (CORBA が GConf を実装するために使用されていますが、クライアント
は決して CORBA を気にすることが無いのです) への接続と幾つかのグローバル
データ構造の設定を確立します。<function>gconf_init()</function>への
引数は CORBA に関係するコマンドラインオプションをチェックする 1 組の
argc/argv と引き起こる幾つかのエラーが置かれる場所です。
<function>gconf_init()</function> は成功したときに <symbol>真</symbol>
を返します。
</para>
<para>
<!-- You can check whether GConf is initialized with -->
次の関数を使って、GConf が初期化されたかどうかを確認することが出来ます。
<function>gconf_initialized()</function>.
</para>
</sect1>
<!-- GConfEngine object -->
<sect1>
<!-- <title>The <structname>GConfEngine</structname> object</title> -->
<title><structname>GConfEngine</structname> オブジェクト</title>
<para>
<!--
A <structname>GConfEngine</structname> object represents your
connection to a configuration database. Normally the database
you're connecting to is the user's default database, defined
by all the sources in their configuration source
path. <function>gconf_engine_get_default()</function> returns a handle to
this default
database. <function>gconf_engine_get_default_with_address()</function>
returns a handle to a single configuration source; normally,
applications will not use this function—it's intended
for system configuration tools and the like.
-->
<structname>GConfEngine</structname> オブジェクトは設定データベース
への接続を証明します。通常接続するデータベースはユーザーのデフォルト
データベースで、設定ファイルパスの中で全てのソースが定義されています。
<function>gconf_engine_get_default()</function> はこのデフォルトデータベース
へのハンドルを返します。<function>gconf_engine+get_default_with_address()</function>
は単一の設定ファイルへのハンドルを返します。通常、アプリケーションは
この関数&mdash を使うことはありません。システム設定ツールやそれに似た
ものが使います。
</para>
<note>
<para>
<!-- In a GNOME context, you should use -->
GNOME コンテキストの中で利用すべきもの
<!--
<structname>GConfClient</structname> instead of
<structname>GConfEngine</structname>.
-->
<structname>GConfEngine</structname> の代わりの
<structname>GConfClient</structname>
</para>
</note>
<para>
<funcsynopsis>
<funcsynopsisinfo>#include <gconf/gconf.h></funcsynopsisinfo>
<funcdef>GConfEngine*
<function>gconf_engine_get_default</function>
</funcdef>
<void>
</funcsynopsis>
<funcsynopsis>
<funcsynopsisinfo>#include <gconf/gconf.h></funcsynopsisinfo>
<funcdef>GConfEngine*
<function>gconf_engine_get_default_with_address</function>
</funcdef>
<paramdef>const gchar* <parameter>address</parameter></paramdef>
</funcsynopsis>
</para>
<para>
<!--
The <structname>GConfEngine</structname> object is reference
counted; it begins with a count of 1, and is destroyed when
the count reaches 0. In other words, the creator of the
<structname>GConfEngine</structname> "owns" a reference to the
<structname>GConfEngine</structname> as soon as it's created, and
should call <function>gconf_engine_unref()</function> to make it
go away. <function>gconf_engine_ref()</function> creates a new
reference to the <structname>GConfEngine</structname>.
-->
<structname>GConfEngine</structname> オブジェクトはカウントされる
参照です。それは 1 から始まり、カウンタが 0 になったら破棄されます。
言い換えると、<structname>GConfEngine</structname>を生成したものが
<structname>GConfEngine</structname> が生成されたらすぐにそれへの参照を
"負う"ことになり、そして、それを解放するために
<function>gconf_engine_unref()</function> を呼び出します。
<function>gconf_engine_ref()</function> は <structname>GConfEngine</structname>
への新しい参照を作成します。
<funcsynopsis>
<funcsynopsisinfo>#include <gconf/gconf.h></funcsynopsisinfo>
<funcdef>void
<function>gconf_engine_ref</function>
</funcdef>
<paramdef>GConfEngine* <parameter>conf</parameter></paramdef>
</funcsynopsis>
<funcsynopsis>
<funcsynopsisinfo>#include <gconf/gconf.h></funcsynopsisinfo>
<funcdef>void
<function>gconf_engine_unref</function>
</funcdef>
<paramdef>GConfEngine* <parameter>conf</parameter></paramdef>
</funcsynopsis>
</para>
</sect1>
<!-- GConfValue -->
<sect1>
<!-- <title>The <structname>GConfValue</structname> Datatype</title> -->
<title><structname>GConfValue</structname> データ型</title>
<para>
<!--
The <structname>GConfValue</structname> struct represents
a value that can be obtained from or stored in the
configuration database. It is simply a type marker
and a union of several value types, with constructor,
destructor, "setter" and "getter" functions. When possible
the GConf library allows you to deal with simple C types
instead of a <structname>GConfValue</structname>, but
sometimes there is simply no way to know the type of an
object in advance. The <filename>libgnome/gnome-config.h</filename>
interface simply returns strings in this case, for the
programmer to parse manually; this was phenomenally broken and
GConf fixes it with <structname>GConfValue</structname>.
-->
<structname>GConfValue</structname> 構造体は設定データベース
から取得されるもしくは、格納される値を表します。それはシンプルな
マーカーであり幾つかの値の型からなるコンストラクタ、デストラクタ、
と "setter(設定子)" と "getter(取得子)" を持った共有体です。
<structname>GConfValue</structname> の代わりにシンプルな C 型を
扱うことが出来る GConf ライブラリが有効な場合に、時々ですが
前もって 1 個のオブジェクトの型を知る簡単な方法がなくなります。
この場合、<filename>libgnome/gnome-config.h</filename>
インタフェースがプログラマがマニュアルで解析するために文字列を返し
ます。これは 現実的に使えなくなりそして GConf は
<structname>GConfValue</structname>でそれを解決します。
</para>
<sect2>
<!-- <title>Accessing <structname>GConfValue</structname></title> -->
<title><structname>GConfValue</structname> へのアクセス方法</title>
<para>
<!--
To read a <structname>GConfValue</structname>, you first
determine its type and then read the value using one
of its accessor macros. The following useless code should
demonstrate this:
-->
<structname>GConfValue</structname>を読むには、その型を
決定してからその値にアクセスするマクロを使って値を読みます。
次に示す使い物にならないコードはこれを証明して見せます。
<programlisting>
void
print_value(GConfValue* value)
{
switch (value->type)
{
case GCONF_VALUE_STRING:
printf("%s\n", gconf_value_string(value));
break;
case GCONF_VALUE_INT:
printf("%d\n", gconf_value_int(value));
break;
case GCONF_VALUE_FLOAT:
printf("%g\n", gconf_value_float(value));
break;
case GCONF_VALUE_BOOL:
printf("%s", gconf_value_bool(value) ? "true" : "false");
break;
case GCONF_VALUE_SCHEMA:
{
GConfSchema* schema = gconf_value_schema(value);
/* printing a schema would be complicated, you get the idea */
}
break;
case GCONF_VALUE_LIST:
{
GSList* iter = gconf_value_list(value);
while (iter != NULL)
{
GConfValue* element = iter->data;
print_value(element);
iter = g_slist_next(iter);
}
}
break;
case GCONF_VALUE_PAIR:
print_value(gconf_value_car(value));
print_value(gconf_value_cdr(value));
break;
case GCONF_VALUE_INVALID:
/* This is used internally by GConf, you can also
use it yourself to indicate errors and such. It
won't be returned from GConf functions though. */
printf("invalid value");
break;
default:
g_assert_not_reached();
break;
}
}
</programlisting>
</para>
<para>
<!--
A special note about values of type <symbol>GCONF_VALUE_LIST</symbol>:
the list contains <structname>GConfValue</structname> objects, and all
objects in the list must have the same type. You can get the type of
the list with the <function>gconf_value_list_type()</function> macro.
-->
<symbol>GCONF_VALUE_LIST</symbol> 型の値について特別に注意する事:
<structname>GConfValue</structname> オブジェクトが持っているリストと
リストの中の全てのオブジェクトは同じ型を持つ必要があります。
<function>gconf_value_list_type()</function> マクロでリストの型を取得
することが可能です。
</para>
</sect2>
<sect2>
<!-- <title>Creating/destroying a <structname>GConfValue</structname></title> -->
<title><structname>GConfValue</structname> の生成/破棄</title>
<para>
<!--
Often you obtain a <structname>GConfValue</structname> from
a GConf routine such as <function>gconf_get()</function>,
but you can also create them yourself with
<function>gconf_value_new()</function>.
<function>gconf_value_new()</function> takes a single
argument, the type of the newly-created value. Value types
can't be changed after creating the value.
-->
時々 <function>gconf_get()</function> のような GConf ルーチン
から <structname>GConfValue</structname>を取得するが、
<function>gconf_value_new()</function> を使って自分自身で
作成する事も出来ます。
<function>gconf_value_new()</function> 関数は新しく作成した値
の型を引数をとります。値の型は値を生成した後には変更する事が
出来ません。
<funcsynopsis>
<funcsynopsisinfo>#include <gconf/gconf-value.h></funcsynopsisinfo>
<funcdef>GConfValue*
<function>gconf_value_new</function>
</funcdef>
<paramdef>GConfValueType <parameter>type</parameter></paramdef>
</funcsynopsis>
<!--
Note that <filename>gconf/gconf-value.h</filename> is
automatically included by <filename>gconf/gconf.h</filename>.
-->
<filename>gconf/gconf-value.h</filename> は
<filename>gconf/gconf.h</filename> によって自動的にインクルード
されることに注意して下さい。
</para>
<!-- <warning><title>You must initialize your values</title> -->
<warning><title>値を初期化しなければなりません</title>
<para>
<!--
Newly-constructed values are invalid; if you use the accessor macros
before you set the contents of the value, the results are
undefined. Use <function>gconf_value_set_int()</function>,
<function>gconf_value_set_string()</function>, and so on to
initialize the value.
-->
新しく生成された値は不正です。値の目次を設定する前に
アクセスマクロを使った場合、その結果は不定な値です。
<function>gconf_value_set_int()</function> 、
<function>gconf_value_set_string()</function> を使って
値を初期化して下さい。
</para>
</warning>
<para>
<!--
You can destroy a <structname>GConfValue</structname> with
<function>gconf_value_destroy()</function>, and copy one
with <function>gconf_value_copy()</function>. The copy is a
deep copy, that is, child values contained in lists or
pairs are also copied.
-->
<structname>GConfValue</structname> を <fuction>gconf_value_destroy()</function>
を使って破棄でき、また <function>gconf_value_copy()</function> を
使ってその構造体をコピー出来ます。そのコピーは再帰的なコピーとなり、
子の値(下層の値)は更にリストをまたは、コピーされた対を持つことになります。
<funcsynopsis>
<funcsynopsisinfo>#include <gconf/gconf-value.h></funcsynopsisinfo>
<funcdef>GConfValue*
<function>gconf_value_copy</function>
</funcdef>
<paramdef>GConfValue* <parameter>src</parameter></paramdef>
<funcdef>void
<function>gconf_value_destroy</function>
</funcdef>
<paramdef>GConfValue* <parameter>value</parameter></paramdef>
</funcsynopsis>
</para>
</sect2>
</sect1>
<!-- Reading configuration values -->
<sect1>
<!-- <title>Reading/Writing Configuration Values</title> -->
<title>設定値の読み込み/書き込み</title>
<sect2>
<!-- <title>Reading</title> -->
<title>読み込み</title>
<para>
<!--
The "raw" function for obtaining the value stored at a given key in the
configuration database is <function>gconf_get()</function>.
<function>gconf_get()</function> returns a
<structname>GConfValue</structname> if the key was set, or
<symbol>NULL</symbol> if the key was unset or an error occurred. If an
error occurred a <structname>GConfError</structname> is returned in the
location given as the final argument.
-->
値を取得するために設定データベースの中の与えられたキーに値を格納する
関数は <function>gconf_get()</function> です。
<function>gconf_get()</function> はキーがセットされている場合は
<structname>GConfValue</structname> を、キーがセットされていないか
エラーが発生した場合は <symbol>NULL</symbol> を返します。もしエラーが
発生した場合は <structname>GConfError</structname> が最後の引数として
与えられた場所に返されます。
</para>
<para>
<!--
There are also convenience functions that automatically convert
<structname>GConfValue</structname> to primitive C types. These include
<function>gconf_get_int()</function>,
<function>gconf_get_bool()</function>, and so on.
-->
自動的に <structname>GConfValue</structname> をプリミティブな C の型に変換する、
便利な関数もあります。<function>gconf_get_int()</function> に含まれている、
<function>gconf_get_bool()</function> などなど。
</para>
</sect2>
<sect2>
<!-- <title>Writing</title> -->
<title>書き込み</title>
<para>
</para>
</sect2>
</sect1>
</chapter>
<!-- GTK Object wrapper -->
<chapter id="gtk-wrapper">
<!-- <title><structname>GtkObject</structname> Convenience Wrapper</title> -->
<title><structname>GtkObject</structname> の便利なラッパー</title>
<para>
<!--
<structname>GConfClient</structname> is a
<structname>GtkObject</structname> subclass that replaces
<structname>GConfEngine</structname> in GNOME programs.
-->
<structname>GConfClient</structname> は GNOME プログラムの中の
<structname>GConfEngine</structname> に置き換わる、
<structname>GtkObject</structname> のサブクラスです。
</para>
<sect1 id="gconfclient-example">
<!-- <title>A Complete Example</title> -->
<title>完全な例</title>
<para>
</para>
</sect1>
</chapter>
<chapter id="conventions">
<!-- <title>GConf Conventions</title> -->
<title>GConf の慣例(しきたり)</title>
<para>
<!--
This chapter describes <emphasis>conventions</emphasis> that
GConf clients should obey, though the library does not enforce
them.
-->
この章では Gconf クライアントが従うべき <emphasis>慣例</emphasis>
について記述していますが、ライブラリは対象外です。
</para>
<sect1>
<!-- <title>Namespace division</title> -->
<title>名前空間の分割</title>
<para>
<!-- When choosing GConf keys, you should follow these conventions. -->
GConf キーを選択している場合、これらの慣例に従うべきです。
</para>
<para>
<itemizedlist mark="bullet">
<listitem>
<para>
<!--
Schemas should go under the <literal>/schemas</literal>
toplevel directory. Under <literal>/schemas</literal>,
the normal GConf namespace should be mirrored. So, if you have a
key <literal>/foo/bar/baz</literal>, the schema for that key should
be at <literal>/schemas/foo/bar/baz</literal>. If you apply the same
schema to multiple keys, then obviously the schema name will have
to differ from the key names; but you should mirror as much of the
key names as possible. For example, <literal>/foo/bar/baz</literal>
and <literal>/foo/bar/boo</literal> might have the schema
<literal>/schemas/foo/bar/baz_and_boo</literal>.
-->
スキーマは トップレベルディレクトリが <literal>/schemas</literal> の下に
格納されているべきです。<literal>/schemas</literal> 配下で、通常の
GConf 名前空間はミラーされているべきです。そうすることで、もしキー
<literal>/foo/bar/baz</literal> を持っている場合、そのキーに対するスキーマが
<literal>/schemas/foo/bar/baz</literal>に存在している必要があります。
同じスキーマを複数のキーに適用した場合、明らかにスキーマ名はキー名からの
差分を持つことになります。しかし複数のキー名があるならミラーした方が良いでしょう。
例えば、<literal>/foo/bar/baz</literal> と <literal>/foo/bar/boo<literal>
はスキーマ <literal>/schemas/foo/bar/baz_and_boo</literal> を持っているかも
しれません。
</para>
</listitem>
<listitem>
<para>
<!--
The GNOME libraries may store preferences for GNOME apps
under the
<literal>/apps/gnome-settings/<replaceable>appname</replaceable></literal>
directory.
<literal><replaceable>appname</replaceable></literal> will be
replaced with the name of your app, as passed in to
<function>gnome_init()</function> (perhaps canonicalized to be a
legal GConf key). You should not put your own
settings in this directory, because you may get notifications when
gnome-libs keys change and gnome-libs may get notifications when
your keys change. This would be confusing.
-->
GNOME ライブラリ群は GNOME アプリケーション向けに優先的にディレクトリ
<literal>/apps/gnome-settings/<replaceable>appname</replaceable></literal>
配下に格納する。
<literal><replaceable>appname</replaceable></literal> は
<function>gnome_init()</function> (おそらく定められた GConf キーに
なることが正当化されている)を通して、貴方のアプリケーション名で置き換えられます。
このディレクトリの中にプライベートな設定を書き込むべきではありません。
なぜなら gnome-libs キーが変更する時に通知を受けるかもしれないし、更に
貴方のキーが変更する時に gnome-libs がその通知を得るかもしれないからです。
これでは混乱してしまいます。
</para>
</listitem>
<listitem>
<para>
<!--
Preferences for applications should go under an
<literal>/apps/<replaceable>appname</replaceable></literal>
directory. Try to make
<literal><replaceable>appname</replaceable></literal> match the
one passed to <function>gnome_init()</function>, also used in the
<literal>/apps/gnome-settings/<replaceable>appname</replaceable></literal>
directory. Vendors are encouraged to include their vendor name in
<replaceable>appname</replaceable>, to avoid namespace clashes.
-->
アプリケーションに対する設定情報は、ディレクトリ
<literal>/apps/<replaceable>appname</replcceable></literal>
配下に置くべきです。
<literal><replaceable>appname</replaceable></literal> を
<function>gnome_init()</function> に渡して、ディレクトリ
<literal>/apps/gnome-settings/<replaceable>appname</replaceable></literal>
の中でも使われている名前に一致させてみて下さい。
ベンダーは名前空間のクラッシュを避けるために、ベンダー名を
<replaceable>appname</replaceable>の中に入れることを奨励します。
</para>
</listitem>
<listitem>
<para>
<!--
Preferences for the desktop environment should go under
<literal>/desktop</literal>. None should be immediately
under <literal>/desktop</literal>, however. GNOME-specific
preferences should be under <literal>/desktop/gnome</literal>.
Settings standardized among multiple desktops should go under
<literal>/desktop/standard</literal>. Other specific desktops should
select a directory to use (<literal>/desktop/kde</literal>,
<literal>/desktop/xfce</literal>, etc.)
-->
デスクトップ環境に対する設定情報は <literal>/desktop</literal>
配下に置くべきです。<literal>/desktop</literal> に直に
置くべきではありません。なぜなら、GNOMEが指定する設定情報は、
<literal>/desktop/gnome</literal> 配下に置かれるからです。
複数のデスクトップ間で標準化された設定情報は
<literal>/desktop/standard</literal> 配下に置くべきでしょう。
その他の特定のデスクトップ情報は利用するディレクトリ
( <literal>/desktop/kde</literal> や <literal>/desktop/xfce</literal> 等)
を選択する必要があります。
</para>
</listitem>
<listitem>
<para>
<!--
System-level preferences (such as the host name, though
I'm sure that specific example will never be in GConf) should go
under <literal>/system</literal>. None should be
immediately under <literal>/system</literal>, however; select a
descriptive subdirectory.
-->
システムレベルの設定情報(ホスト名のようなものですが、GConf の中に
は無い特別なものと私は思っています)は、<literal>/system</literal>
配下に置くべきでしょう。<literal>/system</literal> 配下に直に置く
べきではありません。先に述べたサブディレクトリを選択して下さい。
</para>
</listitem>
<listitem>
<para>
<!--
In general, keys under <literal>/system</literal> and
<literal>/desktop</literal> are for use by multiple applications,
and keys under
<literal>/apps/<replaceable>appname</replaceable></literal> are
for use by a single application.
-->
一般的に、<literal>/system</literal> や <literal>/desktop</literal>
配下のキーは複数のアプリケーションによって使われるためのもので、
<literal>/apps/<replaceable>appname</replaceable></literal> 配下の
キーは単一のアプリケーションによって使われるためのものです。
</para>
</listitem>
<listitem>
<para>
<!--
If you have a "weird" key that doesn't fit into any of the above
categories, please mail me (<email>hp@xxxxxxxxxx</email>) and ask
for a new directory to be invented. Alternatively, place your key
under the <literal>/extra</literal> toplevel directory.
-->
どのカテゴリにも属さない "妙な" キーを持っていたら、
私 (<email>hp@xxxxxxxxxx</email>) にメールを下さい。そして作られた
新しいディレクトリについて尋ねて下さい。トップディレクトリが
<literal>/extra</literal>であるディレクトリに置いてみて下さい。
</para>
</listitem>
</itemizedlist>
</para>
</sect1>
</chapter>
<!-- gconftool -->
<chapter id="gconftool">
<!-- <title><application>gconftool</application> Utility Program</title> -->
<title><application>gconftool</application> ユーティリティプログラム</title>
<para>
<!--
<application>gconftool</application> is used to control GConf
from the command line.
-->
<application>gconftool</application> はコマンドラインから
GConf を制御するために使われます。
</para>
</chapter>
<!-- Schema Files -->
<chapter>
<!-- <title>Schema Files</title> -->
<title>スキーマファイル</title>
<para>
<!--
This chapter covers the mechanics of writing and installing the
GConf schema files. Schema files describe your configuration
data and provide default values for it. See <xref
linkend="concepts-schemas"> for an explanation of schemas. The
schema file is not understood by the GConf client library;
rather, <application>gconftool</application> (see <xref
linkend="gconftool">) knows how to parse it, and then uses the GConf
client library to install the information in the GConf database.
-->
この章では書き込みのメカニズムから GConf スキーマのインストールまで
を記述しています。スキーマファイルは設定データを記述してそのデフォルト値
を提供します。スキーマについては <xref
linkend="concepts-schemas"> を参照して下さい。
スキーマファイルは GConf クライアントライブラリでは理解しません。
<application>gconftool</application> (<xref
linkend="gconftool"> を参照して下さい。) はそれを解析する方法を
知っており、また GConf データベースの中に情報をインストールするために
GConf クライアントライブラリを利用します。
</para>
<sect1>
<!-- <title>Schema File Format</title> -->
<title>スキーマファイルフォーマット</title>
<para>
<!--
Here is a sample schema file for a hypothetical application,
<application>basic-gconf-app</application>, one of the
examples that comes with the GConf distribution.
-->
ここでは仮のアプリケーションとして <application>basic-gconf-app</application>
を用意しそれに対するサンプルスキーマを用意しました。そのサンプルの
１つは GConf が配布するものです。
<example>
<!-- <title>Sample schema file</title> -->
<title>サンプルスキーマファイル</title>
<programlisting>
<gconfschemafile>
<schemalist>
<schema>
<key>/schemas/apps/basic-gconf-app/fooandbar</key>
<applyto>/apps/basic-gconf-app/foo</applyto>
<applyto>/apps/basic-gconf-app/bar</applyto>
<owner>basic-gconf-app</owner>
<type>string</type>
<locale name="C">
<default>Blah blah blurgh</default>
<short>short description in C locale</short>
<long>long description of foo and bar in C locale</long>
</locale>
<locale name="no">
<default>some thing in norwegian</default>
<short>short description in Norway</short>
<long>Long description in Norway. long long long. this is a long sentence.</long>
</locale>
</schema>
<schema>
<key>/schemas/apps/basic-gconf-app/baz</key>
<applyto>/apps/basic-gconf-app/baz</applyto>
<owner>basic-gconf-app</owner>
<type>string</type>
<locale name="C">
<default>Zzzzzzzzzz</default>
<short>short description in C locale</short>
<long>long description of baz in C locale</long>
</locale>
<locale name="no">
<default>some thing in norwegian</default>
<short>short description in Norway</short>
<long>Long description in Norway. long long long. this is a long sentence.</long>
</locale>
</schema>
<schema>
<key>/schemas/apps/basic-gconf-app/blah</key>
<applyto>/apps/basic-gconf-app/blah</applyto>
<owner>basic-gconf-app</owner>
<type>string</type>
<locale name="C">
<default>bllllllaaaaaaaaaaaaaaaaarrrrrrggggggghhhhh</default>
<short>short description in C locale</short>
<long>long description of blah in C locale</long>
</locale>
<locale name="no">
<default>some thing in norwegian</default>
<short>short description in Norway</short>
<long>Long description in Norway. long long long. this is a long sentence.</long>
</locale>
</schema>
</schemalist>
</gconfschemafile>
</programlisting>
</example>
</para>
<para>
<!--
The file format is straightforward. The root node must be
called <literal><gconfschemafile></literal>. This
element contains one or more <literal><schemalist></literal>
elements; I can't think of a reason to use multiple
<literal><schemalist></literal> elements, but you can if
you want, and <application>gconftool</application> will load
each one. The <literal><schemalist></literal> in turn
contains one or more <literal><schema></literal>
elements. Each of these describes a single schema.
-->
ファイルフォーマットは簡単です。ルートのノードは
<literal><gconfschemafile></literal> と呼ばれるもの
にしなければなりません。この要素は 1 個以上の <literal><schemalist></literal>
要素を持っています。複数の <literal><schemalist></literal> 要素を
利用する理由を考えませんが、必要であればそれは可能で、
<application>gconftool</application> が各要素をロードします。
逆に、<literal><schemalist></literal> は 1 個以上の
<literal><schema></literal> 要素を持っています。
それぞれは単一のスキーマを記述します。
</para>
<warning>
<para>
<!--
<application>gconftool</application> is not very tolerant
about whitespace right now; in particular it won't strip
whitespace from around key names, type names, etc. This is
broken and will be fixed, just watch out for now.
-->
<application>gconftool</application> は空白の扱いが全く
寛容でない。特にキー名、型名等から空白を取り除きません。
これは壊れており将来的に見直す予定で、今のところは気を
付けて下さい。
</para>
</warning>
<para>
<!--
Here are the fields of the <literal><schema></literal>
element:
-->
ここでは <literal><schema></literal>要素のフィールドについて
述べます。
<informaltable pgwide=1 frame="none">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>
<row>
<entry><key></entry>
<!--
<entry>The key <emphasis>where the schema will be stored</emphasis>;
see <xref linkend="conventions"> for naming
conventions. There may be only one key per schema.
</entry>
-->
<entry><enphasis>スキーマが格納されている</emphasis>キー;
名前付けの慣例(しきたり)については <xref linkend="conventions"> を
参照してください。スキーマに 1 個に付き 1 個だけのキーがあるかもしれません。
</entry>
</row>
<row>
<entry><applyto></entry>
<!--
<entry>A key <emphasis>the schema will be applied to</emphasis>; that
is, this schema <emphasis>describes</emphasis> this
key. See <xref linkend="conventions"> for naming
conventions. There may be multiple <applyto>
elements.</entry>
-->
<entry><emphasis>スキーマが適用される</emphasis> 1 個のキー;
それは、このスキーマがこのキーを <emphasis>記述します</emphasis>。
名前付けの慣例(しきたり)については <xref linkend="conventions"> を
参照してください。複数の <applyto> 要素が
あるかもしれません。</entry>
</row>
<row>
<entry><owner></entry>
<!--
<entry>Name of the application that uses this schema; may be the
command line name, or a human-readable name. However
you should use the same value for <owner> for
all schemas your app installs. The primary purpose
of this field is to enable sysadmins to locate the
keys belonging to a given application.
</entry>
-->
<entry>このスキーマを使うアプリケーション名; おそらく
コマンドライン名もしくは 判読可能な名前です。しかし
<owner> のためにまた、アプリケーションが
インストールする全てのスキーマのために、同じ値を使う
べきでしょう。このフィールドの第一の目的はシステム管理者が
与えられたアプリケーションに属するキーの位置を決めることが
できることです。
</entry>
</row>
<row>
<entry><type></entry>
<!--
<entry>The type of values described by this schema. i.e. keys
the schema is applied to should store values of this type.
Allowed values are: <literal>string</literal>, <literal>int</literal>,
<literal>bool</literal>, <literal>float</literal>,
<literal>list</literal>, <literal>pair</literal>
</entry>
-->
<entry>このスキーマによって記述された値の型。すなわち、
キースキーマはこの型の値を格納するよう適用されている。
許可される値は: <literal>文字列型</literal>、<literal>整数型</literal>、
<literal>リスト型</literal>、<literal>ペア型</literal>
</entry>
</row>
<row>
<entry><default></entry>
<!--
<entry>The <literal><default></literal> element may
appear below <literal><schema></literal> (a default for all
locales, often suitable for numeric values),
<emphasis>OR</emphasis> below a <literal><locale></literal>
element, if the default should be localized. It simply contains the
default value for the keys the schema is applied to.
</entry>
-->
<entry><literal><default></literal> 要素は
<literal><schema></literal> (全てのローケルのデフォルト、
時々適当な数字の値)の下にあるかもしれず、
デフォルトがローカライズされていたら <literal><locale></literal>
の下で <emphasis>OR</emphasis> かもしれません。適用されたキースキーマ向けの
デフォルト値を含んでいます。
</entry>
</row>
<row>
<entry><locale></entry>
<!--
<entry>
The <literal><locale></literal> element
contains locale-specific data, including the
human-readable short and long descriptions,
and optionally the default value
(<literal><default></literal> may also be
placed directly underneath the
<literal><schema></literal> element).
There should be one
<literal><locale></literal> element for each
locale, with a <literal>name</literal> attribute
specifying the locale name.
</entry>
-->
<entry>
<literal><locale></literal> 要素は
ローカル指定のデータを含んでおり、判読可能な長短の
記述が挿入され、オプションとしてデフォルト値
(<literal><schema></literal> 要素のディレクトリ
の最下部に置かれている
<literal><default></literal> かもしれません)
を持っています。
各ローケルに付き 1 個の <literal><locale></literal>
要素であるべきで、空白を挟んでローカル名を持つ
属性 <literal>name</literal> が付いています。
</entry>
</row>
</tbody></tgroup></informaltable>
<!--
A <literal><locale></literal> element can contain
a locale-specific <literal><default></literal>, and may also
contain short and long descriptions as follows:
-->
<literal><locale></literal> 要素は
ローカル指定の <literal><default></literal> を持つことができ、また
長短の記述を次のように持つことができます:
<informaltable pgwide=1 frame="none">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>
<row>
<entry><short></entry>
<!--
<entry>A short description of the purpose of this key, around
40 characters long (about half a line).
</entry>
-->
<entry>このキーの目的であるある短い記述、
およそ 40 文字の長さ (およそ 1 行の半分)。
</entry>
</row>
<row>
<entry><long></entry>
<!--
<entry>A long description of the configuration key, around a paragraph
or two. Should describe the possible values of the
key and their effect on the application.
</entry>
-->
<entry>設定キーの長い記述、およそ段落が
1 ないし 2 個くらい。ここにはキーの値とアプリケーション上での
の使い道を記述してください。
</entry>
</row>
</tbody></tgroup></informaltable>
</para>
</sect1>
<sect1>
<!-- <title>Installing Schemas</title> -->
<title>スキーマのインストール</title>
<para>
<!--
There are several things that need to happen at "<literal>make
install</literal>" time.
-->
"<literal>make install</literal>" の時点で起こりそうなことが幾つかあります。
<itemizedlist mark="bullet">
<listitem>
<para>
The schemas should be installed into a GConf
configuration source; either the default source, or a
source specified by the user with a
<filename>configure</filename> option called
<literal>--enable-gconf-source</literal>.
スキーマは GConf 設定ファイルの中にインストールされる
必要があります。デフォルトファイルまたは
<literal>--enable-gconf-source</literal> で呼ばれる
<filename>configure</filename> のオプション付きの
ユーザーによって指定された設定ファイルのどちらかです。
</para>
</listitem>
<listitem>
<para>
<!--
The schema files should be installed to
<filename>$(sysconfdir)/gconf/schemas/</filename>,
making it easy for sysadmins to browse them or
bulk-reinstall them into a new configuration source.
-->
スキーマファイルは
<filename>$(sysconfdir)/gconf/schemas/</filename>
にインストールされる必要があり、それを参照したり
スキーマ新しい設定ファイルにバルクインストールする
ようなシステム管理者にとって簡単なものになります。
</para>
</listitem>
</itemizedlist>
</para>
<para>
<!--
FIXME give snippets of configure.in and Makefile.am
-->
!!実装して下さい!! configure.in と Makefile.am の断片を与えて下さい。
</para>
</sect1>
<sect1>
<!-- <title>Schema File DTD</title> -->
<title>スキーマファイル DTD</title>
<para>
<!--
The following DTD was contributed by Mirko Streckenbach.
-->
次の DTD は Mirko Streckenbach 氏から提供されました。
</para>
<para>
<programlisting>
<!ELEMENT gconfschemafile (schemalist)>
<!ELEMENT schemalist (schema)*>
<!ELEMENT schema (key,applyto*,owner?,type,locale*)>
<!ELEMENT key (#PCDATA)>
<!ELEMENT applyto (#PCDATA)>
<!ELEMENT owner (#PCDATA)>
<!ELEMENT type (#PCDATA)>
<!ELEMENT locale (default?,short?,long?)>
<!ATTLIST locale name CDATA #REQUIRED>
<!ELEMENT short (#PCDATA)>
<!ELEMENT long (#PCDATA)>
<!ELEMENT default (#PCDATA)>
</programlisting>
</para>
</sect1>
</chapter>
<!-- Checklist/Summary -->
<chapter>
<!-- <title>Checklist/Summary</title> -->
<title>チェックリスト/概要</title>
<para>
<!--
This chapter summarizes the things to consider and actions to
take when adding GConf support to an application.
-->
この章ではアプリケーションを GConf 対応にするための考え方と
やり方についてその概要を記します。
</para>
<para>
</para>
</chapter>
<!-- GConf reference -->
<chapter id="gconf-reference">
<!-- <title>GConf Reference Documentation</title> -->
<title>GConf リファレンス</title>
&gconf-gconf-engine;
&gconf-gconf;
&gconf-gconf-error;
&gconf-gconf-value;
&gconf-gconf-schema;
&gconf-gconf-changeset;
</chapter>
<!-- GConfClient reference -->
<chapter id="gconf-client-reference">
<!-- <title><structname>GtkObject</structname> Wrapper Reference (<structname>GConfClient</structname>)</title> -->
<title><structname>GtkObject</structname> ラッパーリファレンス (<structname>GConfClient</structname>)</title>
&GConfClient;
</chapter>
<!-- GConf Internals Reference -->
<chapter id="gconf-internals-reference">
<!-- <title>GConf Internal Reference</title> -->
<title>GConf 内部リファレンス</title>
&gconf-gconf-backend;
&gconf-gconf-internals;
&gconf-gconf-listeners;
&gconf-gconf-locale;
&gconf-gconf-sources;
</chapter>
</book>
<!-- Keep this comment at the end of the file
Local variables:
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
sgml-auto-insert-required-elements:t
sgml-balanced-tag-edit:t
sgml-normalize-trims:t
sgml-set-face:t
sgml-parent-document:nil
End:
-->