[gnome-user-docs] sysadm: dconf edits, change key file to keyfile

[Michael Hill <mdhill src gnome org>]

commit 1a172ac37339fdb6f5badb9b567f37104f436fc0
Author: Michael Hill <mdhill gnome org>
Date:   Wed Aug 7 22:18:13 2013 -0400

    sysadm: dconf edits, change key file to keyfile

 system-admin-guide/C/automatic-logout.page         |   10 +++--
 system-admin-guide/C/background.page               |   16 +++----
 system-admin-guide/C/dconf-custom-defaults.page    |   14 ++++---
 .../C/dconf-favorite-applications.page             |   12 +++---
 system-admin-guide/C/dconf-keyfiles.page           |   44 ++++++++++++++++++-
 system-admin-guide/C/dconf.page.stub               |   12 +++---
 system-admin-guide/C/login-background.page         |   20 +++++----
 system-admin-guide/C/login-banner.page             |   14 +++----
 system-admin-guide/C/login-logo.page               |   13 ++----
 9 files changed, 97 insertions(+), 58 deletions(-)
---
diff --git a/system-admin-guide/C/automatic-logout.page b/system-admin-guide/C/automatic-logout.page
index 32920b9..5bcd111 100644
--- a/system-admin-guide/C/automatic-logout.page
+++ b/system-admin-guide/C/automatic-logout.page
@@ -24,11 +24,10 @@
   <p>User sessions that have been idle for a specific period of time can be
   ended automatically. You can set different behaviour based on whether the
   machine is running from a battery or from mains power by setting the
-  corresponding dconf key, then locking it.</p>
-
-  <p>To set automatic logout for a mains powered machine:</p>
+  corresponding <sys its:translate="no">dconf</sys> key, then locking it.</p>
 
   <steps>
+    <title>Set automatic logout for a mains powered machine</title>
     <item>
       <p>Create a <code>user</code> profile in <file>/etc/dconf/profile/user</file>:</p>
       <listing>
@@ -63,7 +62,10 @@ sleep-inactive-ac-type='logout'
 </listing>
     </item>
     <item>
-      <p>Run <cmd>dconf update</cmd>.</p>
+      <p>Update the system databases:</p>
+      <screen its:translate="no">
+        <output style="prompt"># </output><input>dconf update</input>
+      </screen>
     </item>
   </steps>
 
diff --git a/system-admin-guide/C/background.page b/system-admin-guide/C/background.page
index 3e3bfcb..0c59dd4 100644
--- a/system-admin-guide/C/background.page
+++ b/system-admin-guide/C/background.page
@@ -22,18 +22,16 @@
 
   <title>Set the default desktop background</title>
 
-  <p>To set the default desktop background, you need to override the original
-  default setting. To do so, use the
-  <cmd>org.gnome.desktop.background.picture-uri</cmd> gsettings key. Below is
-  a concrete example how to do so in the terminal.</p>
+  <p>To set the default desktop background, you need to override the default
+  setting using the <cmd>org.gnome.desktop.background.picture-uri</cmd>
+  <sys its:translate="no">GSettings</sys> key.</p>
 
 <steps>
+<title>Change the desktop background</title>
   <item><p>Insert the picture you would like to have as the desktop background
-  in the <file>/usr/share/backgrounds/gnome/</file> directory.</p></item>
-  <item><p>Open the terminal.</p></item>
-  <item><p>Run the
-  <cmd>gsettings set org.gnome.desktop.background picture-uri 
'file:///usr/share/backgrounds/beefy-miracle/default/beefy-miracle.xml'</cmd>
-  command.</p></item>
+  in the directory <file>/usr/share/backgrounds/gnome/</file>.</p></item>
+  <item><p>In a terminal window, run the command <cmd>gsettings set org.gnome.desktop.background picture-uri 
'file:///usr/share/backgrounds/beefy-miracle/default/beefy-miracle.xml'</cmd></p>
+  </item>
 </steps>
 
 </page>
diff --git a/system-admin-guide/C/dconf-custom-defaults.page b/system-admin-guide/C/dconf-custom-defaults.page
index c7dd315..e914d67 100644
--- a/system-admin-guide/C/dconf-custom-defaults.page
+++ b/system-admin-guide/C/dconf-custom-defaults.page
@@ -36,7 +36,8 @@
       <years>2013</years>
     </credit>
 
-    <desc>Set system-wide default settings using <sys its:translate="no">dconf</sys> profiles.</desc>
+    <desc>Set system-wide default settings using <sys its:translate="no">dconf</sys>
+    profiles.</desc>
 
   </info>
 
@@ -74,9 +75,8 @@ system-db:local</code>
       <sys its:translate="no">dconf</sys> database.</p>
     </item>
     <item>
-      <p>Create a <em>key file</em> for the
-      <input its:translate="no">local</input> database which contains the
-      default settings:</p>
+      <p>Create a <em>keyfile</em> for the <input its:translate="no">local</input>
+      database which contains the default settings:</p>
       <listing its:translate="no">
         <title><file>/etc/dconf/db/local.d/01-background</file></title>
 <code># <span its:translate="yes">dconf path</span>
@@ -90,8 +90,10 @@ secondary-color='FFFFFF'</code>
       </listing>
     </item>
     <item>
-      <p>Run <input its:translate="no">dconf update</input> to update the
-      <sys its:translate="no">dconf</sys> databases.</p>
+      <p>Update the system databases:</p>
+      <screen its:translate="no">
+        <output style="prompt"># </output><input>dconf update</input>
+      </screen>
     </item>
   </steps>
 
diff --git a/system-admin-guide/C/dconf-favorite-applications.page 
b/system-admin-guide/C/dconf-favorite-applications.page
index 7898f9a..7607ab3 100644
--- a/system-admin-guide/C/dconf-favorite-applications.page
+++ b/system-admin-guide/C/dconf-favorite-applications.page
@@ -75,16 +75,16 @@
   database files using <sys its:translate="no">dconf</sys>. System database
   files are found in <file its:translate="no">/etc/dconf/db</file>, but cannot
   be edited because they are written in GVDB format. In order to change system
-  settings using a text editor, you can modify key files found in
-  key file directories. Each key file directory corresponds to a particular
+  settings using a text editor, you can modify keyfiles found in
+  keyfile directories. Each keyfile directory corresponds to a particular
   system database file and has the same name as the database file, appended
-  with a '.d' extension. All key file directories are found in
+  with a '.d' extension. All keyfile directories are found in
   <file its:translate="no">/etc/dconf/db</file>. The following code snippets
   edit the <sys its:translate="no">dconf</sys> profile and then create a
   keyfile to set default favorite applications for all employees
   in the first floor of an organization.</p>
 
-  <!--The code itself need not be translated but the comments withing the
+  <!--The code itself need not be translated but the comments within the
   code have to be translated.-Aruna-->
 
   <listing>
@@ -118,10 +118,10 @@
   </listing>
 
   <note style="important">
-    <p><cmd>dconf-update</cmd> has to be run whenever you modify a key file.
+    <p><cmd>dconf-update</cmd> has to be run whenever you modify a keyfile.
     When you do this, <sys its:translate="no">dconf</sys> compares the time
     stamp on a system database file with the time stamp on the corresponding
-    key file directory. If the time stamp on the key file directory is more
+    keyfile directory. If the time stamp on the keyfile directory is more
     recent than the one on the database file,
     <sys its:translate="no">dconf</sys> regenerates the
     <code>system-db</code> file and sends a notification to the system
diff --git a/system-admin-guide/C/dconf-keyfiles.page b/system-admin-guide/C/dconf-keyfiles.page
index ee8e0b3..211ff0e 100644
--- a/system-admin-guide/C/dconf-keyfiles.page
+++ b/system-admin-guide/C/dconf-keyfiles.page
@@ -13,12 +13,16 @@
       <email its:translate="no">desrt desrt ca</email>
       <years>2012</years>
     </credit>
+    <credit type="author">
+      <name>Aruna Sankaranarayanan</name>
+      <email its:translate="no">aruna evam gmail com</email>
+    </credit>
 
-    <desc>Use <sys its:translate="no">dconf</sys> <em>key files</em>
-    to configure specific settings with a text editor.</desc>
+    <desc>Use <sys its:translate="no">dconf</sys> <em>keyfiles</em> to
+    configure specific settings with a text editor.</desc>
   </info>
 
-  <title>Control system settings with key files</title>
+  <title>Control system settings with keyfiles</title>
 
   <comment>
     <cite date="2013-08-06" href="mailto:mdhillca gmail com">Michael Hill</cite>
@@ -27,4 +31,38 @@
     example?</p>
   </comment>
 
+  <p>To support the ability to configure the system with a text editor, 
+  <sys its:translate="no">dconf</sys> has introduced
+  <em>keyfile directories</em>. For any given system database, a corresponding
+  directory can be created (with ".d" added to the filename, for example
+  <file>/etc/dconf/db/local.d</file>). This directory contains keyfiles in a
+  special format that can be compiled into the
+  <sys its:translate="no">dconf</sys> database.</p>
+
+  <listing>
+    <title>A keyfile in this directory will look something like this:</title>
+      <code>
+# Some useful default settings for our site
+
+[system/proxy/http]
+host='172.16.0.1'
+enabled=true
+
+[org/gnome/desktop/background]
+picture-uri='file:///usr/local/rupert-corp/company-wallpaper.jpeg'
+      </code>
+  </listing>
+
+  <note style="important">
+    <p><cmd>dconf-update</cmd> has to be run whenever you modify a keyfile.
+    When you do this, <sys its:translate="no">dconf</sys> compares the time
+    stamp on a system database file with the time stamp on the corresponding
+    keyfile directory. If the time stamp on the keyfile directory is more
+    recent than the one on the database file,
+    <sys its:translate="no">dconf</sys> regenerates the
+    <code>system-db</code> file and sends a notification to the system
+    <sys>Dbus</sys>, which in turn notifies all running applications to
+    reread their settings.</p>
+  </note>
+
 </page>
diff --git a/system-admin-guide/C/dconf.page.stub b/system-admin-guide/C/dconf.page.stub
index 039866a..034b1be 100644
--- a/system-admin-guide/C/dconf.page.stub
+++ b/system-admin-guide/C/dconf.page.stub
@@ -38,10 +38,10 @@
   <!-- TODO: improve wording -->
   <p>A <em>profile</em> is a list of configuration databases. The first
   database in a profile is the write-to database and the remaining databases
-  are read-only. Each of the read-only databases is generated from a key file
-  directory. Each key file directory contains one or more key files. Each key
-  file contains at least one dconf patch and one or more keys and the
-  corresponding values.</p>
+  are read-only. Each of the read-only databases is generated from a keyfile
+  directory. Each keyfile directory contains one or more keyfiles. Each keyfile
+  contains at least one dconf patch and one or more keys and the corresponding
+  values.</p>
 
   <!-- TODO: databases -->
   <p></p>
@@ -71,8 +71,8 @@ system-db:<input>site</input></code>
 
 </section>
 
-<section id="key file">
-  <!-- TODO: explain the key file syntax (maybe new page) -->
+<section id="keyfile">
+  <!-- TODO: explain the keyfile syntax (maybe new page) -->
   <p></p>
 
 </section>
diff --git a/system-admin-guide/C/login-background.page b/system-admin-guide/C/login-background.page
index f1bb6e4..7fb38df 100644
--- a/system-admin-guide/C/login-background.page
+++ b/system-admin-guide/C/login-background.page
@@ -28,23 +28,26 @@
   <title>Change the background of the login screen</title>
 
 <section id="change-background">
-<title>Change your background</title>
 
   <comment>
     <cite date="2012-11-07" href="mailto:mdhillca gmail com">Michael Hill</cite>
     <p>Adapted from l-g-o SysAdminGuide page.</p>
   </comment>
 
-  <p>Change of the background of the login screen is controlled by the
+  <p>The background of the login screen is controlled by the
   <cmd>org.gnome.desktop.background.picture-uri</cmd>
   <sys its:translate="no">GSettings</sys> key. <app>GDM</app> uses its own
-  <sys its:translate="no">dconf</sys> profile. To change settings in this profile,
-  follow these steps:</p>
+  <sys its:translate="no">dconf</sys> profile.</p>
 
 <steps>
-<title>Change settings in the <sys its:translate="no">dconf</sys> profile</title>
+<title>Change settings in the <app>GDM</app> <sys its:translate="no">dconf</sys> profile</title>
   <item><p>Place a keyfile in the <file>/etc/dconf/db/gdm.d</file> directory.</p></item>
-  <item><p>Run the <input>dconf update</input> command.</p></item>
+    <item>
+      <p>Update the system databases:</p>
+      <screen its:translate="no">
+        <output style="prompt"># </output><input>dconf update</input>
+      </screen>
+    </item>
 </steps>
 
   <p>Here is an example keyfile that you can store as
@@ -56,8 +59,9 @@ picture-uri='file:///<input its:translate="yes">opt/corp/background.jpg</input>'
 </code>
 
   <note>
-    <p><sys its:translate="no">dconf</sys> key files are slightly different
-    from <sys its:translate="no">GSettings</sys> override files.</p>
+    <p><sys its:translate="no">dconf</sys>
+    <link xref="dconf-keyfiles">keyfiles</link> are slightly different from
+    <sys its:translate="no">GSettings</sys> override files.</p>
   </note>
 </section>
 
diff --git a/system-admin-guide/C/login-banner.page b/system-admin-guide/C/login-banner.page
index baefd48..2c75687 100644
--- a/system-admin-guide/C/login-banner.page
+++ b/system-admin-guide/C/login-banner.page
@@ -41,25 +41,23 @@
     <p>Adapted from l-g-o SysAdminGuide page.</p>
   </comment>
 
-<section id="display-login-banner">
-  <title>Display a text banner</title>
   <p>The text banner on the login screen is controlled by the following
   <sys its:translate="no">GSettings</sys> keys:</p>
 
 <terms>
   <item>
       <title><code>org.gnome.login-screen.banner-message-enable</code></title>
-      <p>enables showing the banner message</p>
+      <p>enables showing the banner message.</p>
   </item>
   <item>
   <title><code>org.gnome.login-screen.banner-message-text</code></title>
-      <p>shows the text banner message in the login window</p>
+      <p>shows the text banner message in the login window.</p>
   </item>
 </terms>
 
 <steps>
   <title>Display a text banner on the login screen:</title>
-  <item><p>Add a key file to the
+  <item><p>Add a keyfile to the
   <file its:translate="no">/etc/dconf/db/gdm.d</file> directory and name it,
   for example, <file>01-banner-message</file>.</p></item>
   <item><p>Add the following content to the file:</p>
@@ -72,10 +70,10 @@ banner-message-text='<input its:translate="yes">Type the banner message here.</i
 </steps>
 
 <note>
-  <p><sys its:translate="no">dconf</sys> key files are slightly different
-  from <sys its:translate="no">GSettings</sys> override files.</p>
+  <p><sys its:translate="no">dconf</sys>
+  <link xref="dconf-keyfiles">keyfiles</link> are slightly different from
+  <sys its:translate="no">GSettings</sys> override files.</p>
 </note>
-</section>
 
 <section id="troubleshooting-banner">
 <title>Troubleshooting: what if the banner message does not update?</title>
diff --git a/system-admin-guide/C/login-logo.page b/system-admin-guide/C/login-logo.page
index d8e41a9..781cb4d 100644
--- a/system-admin-guide/C/login-logo.page
+++ b/system-admin-guide/C/login-logo.page
@@ -42,9 +42,6 @@
     <p>Adapted from l-g-o SysAdminGuide page.</p>
   </comment>
 
-<section id="greeter-logo">
-  <title>Add a greeter logo</title>
-
   <p>The logo on the login screen is controlled by the
   <cmd>org.gnome.login-screen.logo</cmd>
   <sys its:translate="no">GSettings</sys> key. Since
@@ -54,8 +51,8 @@
   screen.</p>
 
 <steps>
-  <title>Change settings in the <sys its:translate="no">dconf</sys> profile.</title>
-  <item><p>Add a key file to the <file its:translate="no">/etc/dconf/db/gdm.d</file>
+  <title>Change settings in the <sys its:translate="no">dconf</sys> profile</title>
+  <item><p>Add a keyfile to the <file its:translate="no">/etc/dconf/db/gdm.d</file>
   directory.</p></item>
   <item><p>Run the <cmd its:translate="no">dconf update</cmd> command.</p></item>
 </steps>
@@ -67,10 +64,10 @@ logo='<input>/usr/share/pixmaps/logo/greeter-logo.png</input>'
 </code>
 
   <note>
-    <p><sys its:translate="no">dconf</sys> key files are slightly different
-    from <sys its:translate="no">GSettings</sys> override files.</p>
+    <p><sys its:translate="no">dconf</sys>
+    <link xref="dconf-keyfiles">keyfiles</link> are slightly different from
+    <sys its:translate="no">GSettings</sys> override files.</p>
   </note>
-</section>
 
 <section id="troubleshooting-logo">