1 <?xml version="1.0" encoding="UTF-8"?><!-- -*- indent-tabs-mode: nil -*- -->
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
4 <!ENTITY legal SYSTEM "legal.xml">
5 <!ENTITY appversion "2.8">
6 <!ENTITY manrevision "2.8">
7 <!ENTITY date "September 2004">
8 <!ENTITY app "Configuration Editor">
11 (Do not remove this comment block.)
12 Maintained by the GNOME Documentation Project
13 http://developer.gnome.org/projects/gdp
14 Template version: 2.0 beta
15 Template last modified Feb 12, 2002
18 <article id="index" lang="en">
19 <!-- please do not change the id; for translations, change lang to -->
20 <!-- appropriate code -->
22 <title>Configuration Editor Manual</title>
25 <holder>Sun Microsystems</holder>
27 <!-- translators: uncomment this:
30 <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
34 <publisher role="maintainer">
35 <publishername>GNOME Documentation Project</publishername>
39 <!-- This file contains link to license for the documentation (GNU FDL), and
40 other legal stuff such as "NO WARRANTY" statement. Please do not change
45 <firstname>Sun</firstname>
46 <surname>GNOME Documentation Team</surname>
47 <affiliation><orgname>Sun Microsystems</orgname></affiliation>
50 <firstname>Angela</firstname>
51 <surname>Boyle</surname>
53 <orgname>GNOME Documentation Project</orgname>
57 <firstname>Shaun</firstname>
58 <surname>McCance</surname>
60 <orgname>GNOME Documentation Project</orgname>
63 <!-- This is appropriate place for other contributors: translators,
64 maintainers, etc. Commented out by default.
65 <othercredit role="translator">
66 <firstname>Latin</firstname>
67 <surname>Translator 1</surname>
69 <orgname>Latin Translation Team</orgname>
70 <address> <email>translator@gnome.org</email> </address>
72 <contrib>Latin translation</contrib>
76 <abstract role="description"><para>&app; can be used to change configuration options used by applications that may not be available through Preference dialogs</para></abstract>
80 <revnumber>Version &manrevision;</revnumber>
83 <para role="author">GNOME Documentation Project</para>
84 <para role="publisher">GNOME Documentation Project</para>
85 <para role="status">unreviewed</para>
89 <revnumber>Version 2.1</revnumber>
90 <date>August 2004</date>
92 <para role="author">Sun GNOME Documentation Team</para>
93 <para role="publisher">GNOME Documentation Project</para>
97 <revnumber>Version 2.0.1</revnumber>
98 <date>January 2004</date>
100 <para role="author">Sun GNOME Documentation Team</para>
101 <para role="publisher">GNOME Documentation Project</para>
105 <releaseinfo>This manual describes version &appversion; of &app;.</releaseinfo>
107 <title>Feedback</title>
108 <para>To report a bug or make a suggestion regarding the &app; application or
109 this manual, follow the directions in the
110 <ulink url="ghelp:gnome-feedback"
111 type="help">GNOME Feedback Page</ulink>.
113 <!-- Translators may also add here feedback address for translations -->
118 <primary>GConf Editor</primary>
121 <sect1 id="introduction">
122 <title>Introduction</title>
123 <para>The GNOME Desktop and many applications use
124 <application>GConf</application> to store user preferences and
125 system configuration data. <application>GConf</application>
126 provides a central storage location for preferences, simplifying
127 configuration management for users and system administrators. More
128 information about <application>GConf</application> can be found in the
129 <ulink url="ghelp:system-admin-guide#gconf-0">GNOME System
130 Administrator's Guide</ulink>.</para>
131 <para><application>&app;</application> allows users to modify their
132 preferences for the entire GNOME Desktop and any applications which
133 use <application>GConf</application>. Additionally, system administrators
134 can use <application>&app;</application> to set default and mandatory
135 settings which will affect all users.</para>
136 <para>Preferences are stored in <application>GConf</application> in a
137 hierarchy of keys. Each key has an associated value which specifies
138 your setting for that preference. For instance, the key
139 <literal>/apps/glines/preferences/ball_theme</literal> stores which theme
140 you use in the game <application>Five or More</application>.</para>
141 <caution><para><application>&app;</application> enables you to modify your
142 configuration source directly. If you are not an experienced user, do not
143 use <application>&app;</application> to set preferences for the GNOME
144 Desktop. Instead, use the preference tools in the GNOME Desktop. For
145 information about how to use preference tools, see the latest version
146 of the <ulink url="ghelp:user-guide">GNOME Desktop User Guide</ulink> for
147 your platform.</para></caution>
150 <sect1 id="getting-started">
151 <title>Getting Started</title>
153 <sect2 id="to-start">
154 <title>To Start &app;</title>
155 <para>You can start <application>&app;</application> in the following
159 <term><guimenu>Applications</guimenu> menu</term>
161 <para>Choose <menuchoice><guisubmenu>System Tools</guisubmenu>
162 <guimenuitem>Configuration Editor</guimenuitem></menuchoice>.</para>
163 <note><para>Some distributions hide this menu. In this case, use the
164 second method described below.</para></note>
168 <term>Command line</term>
170 <para>Execute the following command:
171 <command>gconf-editor</command></para>
177 <sect2 id="when-you-start">
178 <title>When You Start &app;</title>
179 <para>When you start <application>&app;</application>, the following
180 window is displayed.</para>
181 <figure id="gconf_editor_window">
182 <title><application>&app;</application> Window</title>
186 <imagedata fileref="figures/gconf_editor_anno_window.png"
190 <phrase>Shows GConf Editor window. Callouts: Tree pane,
191 Modification pane, Documentation pane.</phrase>
196 <para>The <application>&app;</application> window contains
197 the following panes:</para>
200 <term>Tree pane</term>
201 <listitem><para>Enables you to navigate the hierarchy of keys in
202 <application>GConf</application>. Use this pane to display the keys
203 that you want to modify in the modification pane. The tree pane is on
204 the left side of the window.</para></listitem>
207 <term>Modification pane</term>
209 <para>Displays the keys in the selected
210 <application>GConf</application> location in the tree pane. Use
211 this pane to select keys that you want to modify and to modify the
212 values of keys. The modification pane is in the upper part of the
213 right side of the window.</para>
214 <para>The icons beside the keys in the modification pane indicate
215 what type of value you can enter for the key. For example, the check
217 <literal>/system/http_proxy/use_http_proxy</literal> key indicates
218 that you can enter a Boolean value (true or false) for the key. See
219 <xref linkend="icons"/> for more information on each icon.</para>
223 <term>Documentation pane</term>
224 <listitem><para>Displays documentation for the currently selected
225 key. Use this pane to read more information about the
226 <application>GConf</application> preference keys.</para>
230 <term>Results pane (not shown)</term>
231 <listitem><para>Enables you to view the results of a search or to
232 search through the list of your recently viewed key names. The rest
233 of the window will show the information for whichever key you have
234 selected in this pane. The results pane will appear on the bottom of
235 the window when you list the recent keys or perform a search.</para>
242 <sect1 id="workwindows">
243 <title>Working with Windows</title>
244 <sect2 id="workwindows-opennew">
245 <title>Opening New Windows</title>
246 <para>There are a three types of window you can open in
247 <application>&app;</application>: <application>Settings</application>,
248 <application>Defaults</application>, and <application>Mandatory</application>.
249 What values <application>&app;</application> sets depends on what type
250 of window you have open. You can open each type of window with the
251 appropriate item under the <guimenu>File</guimenu> menu.</para>
252 <note><para>Since the settings in <application>Defaults</application> and
253 <application>Mandatory</application> windows affect all users of the
254 computer, only a system administrator can use these types of windows.
255 To change your preferences, you should use the
256 <application>Settings</application> window.</para></note>
259 <term><application>Settings</application></term>
260 <listitem><para>You can use the <application>Settings</application>
261 window to set your personal preferences. Changes made in the
262 <application>Settings</application> window only affect your desktop.
263 You cannot change the settings that the system administrator has
264 made mandatory.</para></listitem>
269 <term><application>Defaults</application></term>
270 <listitem><para>If you are a system administrator, you can use the
271 <application>Defaults</application> window to edit the default
272 settings for all users. If a user does not set the value of a key
273 explicitly, the value will be taken from the default settings. Users
274 can always override the default settings.</para></listitem>
277 <term><application>Mandatory</application></term>
278 <listitem><para>If you are a system administrator, you can use the
279 <application>Mandatory</application> window to edit the mandatory
280 settings for all users. When a mandatory value is set for a key,
281 users are not able to change that value. This can be used to lock
282 down certain options.</para></listitem>
287 <sect2 id="workwindows-close">
288 <title>Closing and Quitting</title>
289 <para>You can close a <application>&app;</application> window by selecting
290 <menuchoice><guimenu>File</guimenu><guimenuitem>Close Window</guimenuitem>
291 </menuchoice> in that window. To close all <application>&app;</application>
292 windows and quit the application completely, select <menuchoice>
293 <guimenu>File</guimenu><guimenuitem>Quit</guimenuitem></menuchoice> in any
294 <application>&app;</application> window.</para>
298 <sect1 id="workkeys">
299 <title>Working with Keys</title>
300 <para>Keys are a way of looking up a value. Every preference stored in
301 <application>GConf</application> is assigned to a key. Applications which
302 use <application>GConf</application> access the values of keys to determine
303 how to look and behave. When you change something in the
304 <guilabel>Preferences</guilabel> of an application, you are changing the
305 value associated to a key in <application>GConf</application>.</para>
307 <sect2 id="copy-key">
308 <title>Copying a Key Name</title>
309 <para>To copy a key name to the clipboard, select the key name you want to
310 copy in the modification pane. Choose <menuchoice><guimenu>Edit</guimenu>
311 <guimenuitem>Copy Key Name</guimenuitem></menuchoice>. You can paste the
312 key name into any other application.</para>
314 <sect2 id="list-key">
315 <title>Viewing Recent Key Names</title>
316 <para>To view recent key names, choose <menuchoice><guimenu>Edit</guimenu>
317 <guimenuitem>List Recent Keys</guimenuitem></menuchoice>. This action will
318 open the results pane at the bottom of the current window. You can move
319 through the results list by scrolling up and down with the scroll bar or
320 the arrow keys. The information for the selected key or folder will appear
321 in the rest of the window.</para>
322 <para>Viewing recent keys is useful if you need to get back to a key you
323 just changed and don't remember where it is.</para>
325 <remark>A screenshot may be in order. In particular, The close, copy, and
326 clear buttons on the results pane should be explained.</remark>
328 <sect2 id="modify-key">
329 <title>Modifying the Value of a Key</title>
330 <para>The icons next to the key name show what kind of value that key can
331 take. See <xref linkend="icons"/> for more information on each icon. To
332 modify the value of a key, perform the following steps:</para>
334 <step><para>Use the tree pane to display the key that you want to modify
335 in the modification pane.</para></step>
336 <step><para>Select the key to modify in the modification pane.</para></step>
338 <para>To change the value of an integer key or a string key, click
339 in the <guilabel>Value</guilabel> column of the key. Type the new value
340 for the key. Alternatively, right-click on the key and select
341 <guimenuitem>Edit Key</guimenuitem> from the popup menu.</para>
342 <para>To change the value of a Boolean key, click in the
343 <guilabel>Value</guilabel> column of the key to select or
344 deselect the check box. Alternatively, right-click on the
345 key and select <guimenuitem>Edit Key</guimenuitem> from the
347 <para>To change the value of a list key, right-click on the key and
348 select <guimenuitem>Edit Key</guimenuitem> from the popup menu. The
349 <application>Edit Key</application> dialog provides a list of the
350 values associated to that key. You can use this dialog to edit each
351 particular value in the list, add or remove values from the list, and
352 move each value up or down in the list.</para>
355 <para>Your system administrator may have locked down certain keys by
356 providing mandatory values. If the selected key has a mandatory value
357 set, you will not be able to edit the value. The documentation pane
358 will display the label <guilabel>This key is not writable</guilabel>
359 if you are not allowed to edit the value of that key.</para>
364 <title>Finding Keys Quickly</title>
365 <para>To locate keys quickly, <application>&app;</application> allows you
366 to search the key names in <application>GConf</application>. Additionally,
367 you can use bookmarks to find directories of keys that you need to access
370 <sect2 id="using-bookmark">
371 <title>Using Bookmarks</title>
372 <para>To access a directory location in your bookmarks, choose the location
373 from the <guimenu>Bookmarks</guimenu> menu. You can add and remove directory
374 locations to your <guimenu>Bookmarks</guimenu> menu.</para>
375 <para>To add a bookmark, select the location that you want to bookmark in the
376 tree pane. Choose <menuchoice><guimenu>Bookmarks</guimenu><guimenuitem>Add
377 Bookmark</guimenuitem></menuchoice>.</para>
378 <para>To delete a bookmark, perform the following steps:</para>
380 <step><para>Choose <menuchoice><guimenu>Bookmarks</guimenu>
381 <guimenuitem>Edit bookmarks</guimenuitem></menuchoice>.</para></step>
382 <step><para>Select the bookmark in the
383 <application>Edit bookmarks</application> dialog, then click
384 <guibutton>Delete</guibutton>.</para></step>
385 <step><para>Click <guibutton>Close</guibutton>.</para></step>
389 <title>Searching for Keys</title>
390 <para>To search for keys, perform the following steps:</para>
392 <step><para>Choose <menuchoice><guimenu>Edit</guimenu>
393 <guimenuitem>Find</guimenuitem></menuchoice>.</para></step>
394 <step><para>Enter the keyword you want to search for in the
395 <guilabel>Search for</guilabel> field. You can also select the
396 optional check boxes <guilabel>Search also in key names</guilabel>
397 and <guilabel>Search also in key values</guilabel>. If these check boxes
398 are not selected, the search will only be performed on folder names.
399 Selecting these boxes will expand the search parameters.</para></step>
400 <step><para>Click <guibutton>Find</guibutton>.</para></step>
402 <para>The results from the search will appear in the results pane. To move
403 through the results list, first select that pane. Then you can move through
404 the results with the scroll bar or the arrow keys. The information for the
405 selected key or folder will appear in the rest of the window.</para>
407 <remark>A screenshot may be in order. In particular, The close, copy, and
408 clear buttons on the results pane should be explained.</remark>
412 <sect1 id="defaults-mandatory">
413 <title>Default and Mandatory Settings</title>
414 <para>If you are a system administrator, you can set default and mandatory
415 settings in <application>GConf</application> which will affect all users.
416 Default settings are used when the user has not set a value explicitly, and
417 users can always override them. Mandatory settings are always used for all
418 users, and they cannot override them.</para>
419 <para>You can use the <application>Defaults</application> and
420 <application>Mandatory</application> windows to edit and remove default
421 and mandatory settings. The <application>Defaults</application> and
422 <application>Mandatory</application> windows will only show you those
423 settings which have already been made default or mandatory. You cannot
424 use these windows to create new default and mandatory settings. Instead,
425 you can set settings from the <application>Settings</application> window
426 to be default or mandatory.</para>
427 <para>To open a <application>Defaults</application> window, choose
428 <menuchoice><guimenu>File</guimenu><guimenuitem>New Defaults
429 Window</guimenuitem></menuchoice>. To open a
430 <application>Mandatory</application> window, choose <menuchoice>
431 <guimenu>File</guimenu><guimenuitem>New Mandatory Window</guimenuitem>
432 </menuchoice>.</para>
434 <sect2 id="creating-defaults">
435 <title>Creating Default Settings</title>
436 <para>To create a default setting, perform the following steps:</para>
438 <step><para>In the <application>Settings</application> window, use the
439 tree pane to display the key that you want to set as default.</para></step>
440 <step><para>Right-click on the key and select <guimenuitem>Set as
441 Default</guimenuitem> from the popup menu.</para></step>
444 <sect2 id="creating-mandatory">
445 <title>Creating Mandatory Settings</title>
446 <para>To create a mandatory setting, perform the following steps:</para>
448 <step><para>In the <application>Settings</application> window, use the
449 tree pane to display the key that you want to set as
450 mandatory.</para></step>
451 <step><para>Right-click on the key and select <guimenuitem>Set as
452 Mandatory</guimenuitem> from the popup menu.</para></step>
455 <sect2 id="modifying-defaults-mandatory">
456 <title>Modifying and Removing Default and Mandatory Settings</title>
457 <para>You can use the <application>Defaults</application> and
458 <application>Mandatory</application> windows to modify and remove
459 default and mandatory settings. To modify a default or mandatory
460 setting, use the appropriate window and modify the key as you would
461 for keys in the <application>Settings</application> window. See
462 <xref linkend="modify-key"/> for more information on modifying
464 <para>To remove a default or mandatory key, perform the following
467 <step><para>In the appropriate window, use the tree pane to display
468 the key that you want to remove from the default or mandatory
469 settings.</para></step>
470 <step><para>Right-click on the key and select <guimenuitem>Unset
471 Key</guimenuitem> from the popup menu.</para></step>
477 <title>Icons and Key Types</title>
478 <para>The icons beside the keys in the modification pane indicate what type
479 of value you can enter for the key. The following list shows the possible
480 icons and what types of values they represent.</para>
483 <term><inlinemediaobject><imageobject>
484 <imagedata fileref="figures/entry-bool.png" format="PNG"/>
485 </imageobject></inlinemediaobject> Boolean key</term>
486 <listitem><para>Can be either true or false.
487 <application>&app;</application> will provide a check box for
488 this type of key.</para></listitem>
491 <term><inlinemediaobject><imageobject>
492 <imagedata fileref="figures/entry-number.png" format="PNG"/>
493 </imageobject></inlinemediaobject> Number key</term>
494 <listitem><para>Can hold numbers. These can be either integer or
495 floating point (fractional) numbers.</para></listitem>
498 <term><inlinemediaobject><imageobject>
499 <imagedata fileref="figures/entry-string.png" format="PNG"/>
500 </imageobject></inlinemediaobject> String key</term>
501 <listitem><para>Can hold any string of text.</para></listitem>
504 <term><inlinemediaobject><imageobject>
505 <imagedata fileref="figures/entry-schema.png" format="PNG"/>
506 </imageobject></inlinemediaobject> Schema key</term>
507 <listitem><para>Used for documenting other keys. The documentation
508 for each key is provided by a seperate key, typically under the
509 <literal>/schemas</literal> directory. Users and system administrators
510 usually will not need to work with schema keys directly.</para></listitem>
513 <term><inlinemediaobject><imageobject>
514 <imagedata fileref="figures/entry-list.png" format="PNG"/>
515 </imageobject></inlinemediaobject> List key</term>
516 <listitem><para>Lists of arbitrary length. Each element of the list must
517 be of the same type, and one of the primitive types of boolean, number, or
518 string.</para></listitem>
521 <term><inlinemediaobject><imageobject>
522 <imagedata fileref="figures/entry-blank.png" format="PNG"/>
523 </imageobject></inlinemediaobject> Pair key</term>
524 <listitem><para>Can hold exactly two values. The two values must
525 be one of the primitive types, but they do not have to be the same
526 type. Currently, <application>&app;</application> is unable to edit
527 pair keys.</para></listitem>
530 <term><inlinemediaobject><imageobject>
531 <imagedata fileref="figures/entry-blank.png" format="PNG"/>
532 </imageobject></inlinemediaobject> Blank</term>
533 <listitem><para>Used when <application>&app;</application> does not
534 understand the type of key. The blank icon is also currently used
535 for pair keys.</para></listitem>