Editorial review of XDM section.

Sponsored by:	iXsystems

1 files changed, 97 insertions, 187 deletions

diff --git a/en_US.ISO8859-1/books/handbook/x11/chapter.xml b/en_US.ISO8859-1/books/handbook/x11/chapter.xml
index eb6e01229b..790cd43003 100644
--- a/en_US.ISO8859-1/books/handbook/x11/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/x11/chapter.xml
@@ -804,91 +804,66 @@ dbus_enable="YES"</programlisting>
   </sect1>
 
   <sect1 xml:id="x-xdm">
-    <!--
-    <sect1info>
+    <info>
+    <title>The X Display Manager</title>
+
       <authorgroup>
 	<author>
+	<personname>
 	  <firstname>Seth</firstname>
 	  <surname>Kingsley</surname>
+	  </personname>
 	  <contrib>Contributed by </contrib>
 	</author>
       </authorgroup>
-    </sect1info>
-    -->
-    <title>The X Display Manager</title>
-
-    <sect2>
-      <title>Overview</title>
+    </info>
 
       <indexterm><primary>X Display Manager</primary></indexterm>
-      <para>The X Display Manager (<application>XDM</application>)
-	is an optional part of the X Window System that is used for
-	login session management.  This is useful for several types
-	of situations, including minimal <quote>X Terminals</quote>,
-	desktops, and large network display servers.  Since the X
-	Window System is network and protocol independent, there are
-	a wide variety of possible configurations for running X
-	clients and servers on different machines connected by a
-	network.  <application>XDM</application> provides a graphical
-	interface for choosing which display server to connect to,
-	and entering authorization information such as a login and
+      <para><application>&xorg;</application> provides an X Display
+	Manager, <application>XDM</application>, which can be used for
+	login session management.  <application>XDM</application> provides a graphical
+	interface for choosing which display server to connect to
+	and for entering authorization information such as a login and
 	password combination.</para>
 
-      <para>Think of <application>XDM</application> as providing the
-	same functionality to the user as the &man.getty.8; utility
-	(see <xref linkend="term-config"/> for details).  That is, it
-	performs system logins to the display being connected to and
-	then runs a session manager on behalf of the user (usually an
-	X window manager).  <application>XDM</application> then waits
-	for this program to exit, signaling that the user is done and
-	should be logged out of the display.  At this point,
-	<application>XDM</application> can display the login and
-	display chooser screens for the next user to login.</para>
-    </sect2>
+      <para>  This section demonstrates how to configure the X Display
+	Manager on &os;.  Some desktop environments provide their own
+	graphical login manager.  Refer to <xref
+	  linkend="x11-wm-gnome"/> for instructions on how to
+	configure the GNOME Display Manager and <xref
+	  linkend="x11-wm-kde"/> for instructions on how to configure
+	the KDE Display Manager.</para>
 
     <sect2>
-      <title>Using XDM</title>
-
-      <para>To start using <application>XDM</application>, install
-	the <package>x11/xdm</package> port (it is not installed by
-	default in recent versions of
-	<application>&xorg;</application>).  The
-	<application>XDM</application> daemon program may then be
-	found in <filename>/usr/local/bin/xdm</filename>.  This
-	program can be run at any time as <systemitem
-	  class="username">root</systemitem> and it will start
-	managing the X display on the local machine.  If
-	<application>XDM</application> is to be run every time the
-	machine boots up, a convenient way to do this is by adding an
-	entry to <filename>/etc/ttys</filename>.  For more information
-	about the format and usage of this file, see <xref
-	  linkend="term-etcttys"/>.  There is a line in the default
-	<filename>/etc/ttys</filename> file for running the
-	<application>XDM</application> daemon on a virtual
-	terminal:</para>
+      <title>Configuring <application>XDM</application></title>
+
+      <para>To install <application>XDM</application>, use the
+	<package>x11/xdm</package> package or port.  Once installed,
+	<application>XDM</application> can be configured to run when the 
+	machine boots up by editing this
+	entry in <filename>/etc/ttys</filename>:</para>
 
       <screen>ttyv8   "/usr/local/bin/xdm -nodaemon"  xterm   off secure</screen>
 
-      <para>By default this entry is disabled; in order to enable it
-	change field 5 from <literal>off</literal> to
-	<literal>on</literal> and restart &man.init.8; using the
-	directions in <xref linkend="term-hup"/>.  The first field,
-	the name of the terminal this program will manage, is
-	<literal>ttyv8</literal>.  This means that
-	<application>XDM</application> will start running on the 9th
+      <para>Change the <literal>off</literal> to
+	<literal>on</literal> and save the edit.  The
+	<literal>ttyv8</literal> in this entry indicates that
+	<application>XDM</application> will run on the ninth
 	virtual terminal.</para>
-    </sect2>
-
-    <sect2>
-      <title>Configuring XDM</title>
 
       <para>The <application>XDM</application> configuration directory
-	is located in <filename>/usr/local/lib/X11/xdm</filename>.  In
-	this directory there are several files used to change the
-	behavior and appearance of <application>XDM</application>.
-	Typically these files will be found:</para>
+	is located in <filename>/usr/local/lib/X11/xdm</filename>.
+	This directory contains several files used to change the
+	behavior and appearance of <application>XDM</application>, as
+	well as a few scripts and programs used to set up the desktop
+	when <application>XDM</application> is running. <xref
+	  linkend="xdm-config-files"/> summarizes the function of
+	each of these files.  The exact syntax and usage of these
+	files is described in &man.xdm.1;.</para>
+
+      <table frame="none" pgwide="1" xml:id="xdm-config-files">
+	<title>XDM Configuration Files</title>
 
-      <informaltable frame="none" pgwide="1">
 	<tgroup cols="2">
 	  <thead>
 	    <row>
@@ -900,29 +875,54 @@ dbus_enable="YES"</programlisting>
 	  <tbody>
 	    <row>
 	      <entry><filename>Xaccess</filename></entry>
-	      <entry>Client authorization ruleset.</entry>
+	      <entry>The protocol for connecting to
+		<application>XDM</application> is called the X Display
+		Manager Connection Protocol (<acronym>XDMCP</acronym>)
+		This file is a client authorization ruleset for
+		controlling <acronym>XDMCP</acronym> connections from
+		remote machines.  By default, this file does not allow
+		any remote clients to connect.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>Xresources</filename></entry>
-	      <entry>Default X resource values.</entry>
+	      <entry>This file controls the look and feel of the
+		<application>XDM</application> display chooser and
+		login screens.  The default configuration is a simple
+		rectangular login window with the hostname of the
+		machine displayed at the top in a large font and 
+		<quote>Login:</quote> and <quote>Password:</quote>
+		prompts below.  The format of this file is identical
+		to the app-defaults file described in the
+		<application>&xorg;</application>
+		documentation.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>Xservers</filename></entry>
-	      <entry>List of remote and local displays to
-		manage.</entry>
+	      <entry>The list of local and remote displays the chooser
+		should provide as login choices.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>Xsession</filename></entry>
-	      <entry>Default session script for logins.</entry>
+	      <entry>Default session script for logins which is run by
+		<application>XDM</application> after a user has logged
+		in.  Normally each user will have a customized session
+		script in <filename>~/.xsession</filename> that
+		overrides this script</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>Xsetup_</filename>*</entry>
-	      <entry>Script to launch applications before the login
-		interface.</entry>
+	      <entry>Script to automatically launch applications
+		before displaying the chooser or login interfaces.
+		There is a script for each display being used, named
+		<filename>Xsetup_*</filename>, where
+		<literal>*</literal> is the local display number.
+		Typically these scripts run one or two programs in the
+		background such as
+		<command>xconsole</command>.</entry>
 	    </row>
 
 	    <row>
@@ -933,137 +933,47 @@ dbus_enable="YES"</programlisting>
 
 	    <row>
 	      <entry><filename>xdm-errors</filename></entry>
-	      <entry>Errors generated by the server program.</entry>
+	      <entry>Contains errors generated by the server program.
+		If a display that <application>XDM</application> is
+		trying to start hangs, look at this file for error
+		messages.  These messages are also written to the
+		user's <filename>~/.xsession-errors</filename> file on
+		a per-session basis.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>xdm-pid</filename></entry>
-	      <entry>The process ID of the currently running
-		XDM.</entry>
+	      <entry>The running process <acronym>ID</acronym> of
+		<application>XDM</application>.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
-      </informaltable>
-
-      <para>Also in this directory are a few scripts and programs
-	used to set up the desktop when <application>XDM</application>
-	is running.  The purpose of each of these files will be
-	briefly described.  The exact syntax and usage of all of these
-	files is described in &man.xdm.1;.</para>
-
-      <para>The default configuration is a simple rectangular login
-	window with the hostname of the machine displayed at the top
-	in a large font and <quote>Login:</quote> and
-	<quote>Password:</quote> prompts below.  This is a good
-	starting point for changing the look and feel of
-	<application>XDM</application> screens.</para>
-
-      <sect3>
-	<title>Xaccess</title>
-
-	<para>The protocol for connecting to
-	  <application>XDM</application>-controlled displays is
-	  called the X Display Manager Connection Protocol (XDMCP).
-	  This file is a ruleset for controlling XDMCP connections
-	  from remote machines.  It is ignored unless the
-	  <filename>xdm-config</filename> is changed to listen for
-	  remote connections.  By default, it does not allow any
-	  clients to connect.</para>
-      </sect3>
-
-      <sect3>
-	<title>Xresources</title>
-
-	<para>This is an application-defaults file for the display
-	  chooser and login screens.  In it, the appearance
-	  of the login program can be modified.  The format is
-	  identical to the app-defaults file described in the
-	  <application>&xorg;</application> documentation.</para>
-      </sect3>
-
-      <sect3>
-	<title>Xservers</title>
-
-	<para>This is a list of the remote displays the chooser should
-	  provide as choices.</para>
-      </sect3>
-
-      <sect3>
-	<title>Xsession</title>
-
-	<para>This is the default session script for
-	  <application>XDM</application> to run after a user has
-	  logged in.  Normally each user will have a customized
-	  session script in <filename>~/.xsession</filename> that
-	  overrides this script.</para>
-      </sect3>
-
-      <sect3>
-	<title>Xsetup_*</title>
-
-	<para>These will be run automatically before displaying the
-	  chooser or login interfaces.  There is a script for each
-	  display being used, named <filename>Xsetup_</filename>
-	  followed by the local display number (for instance
-	  <filename>Xsetup_0</filename>).  Typically these scripts
-	  will run one or two programs in the background such as
-	  <command>xconsole</command>.</para>
-      </sect3>
-
-      <sect3>
-	<title>xdm-config</title>
-
-	<para>This contains settings in the form of app-defaults
-	  that are applicable to every display that this installation
-	  manages.</para>
-      </sect3>
-
-      <sect3>
-	<title>xdm-errors</title>
-
-	<para>This contains the output of the X servers that
-	  <application>XDM</application> is trying to run.  If a
-	  display that <application>XDM</application> is trying to
-	  start hangs for some reason, this is a good place to look
-	  for error messages.  These messages are also written to the
-	  user's <filename>~/.xsession-errors</filename> file on a
-	  per-session basis.</para>
-      </sect3>
+      </table>
     </sect2>
 
     <sect2>
-      <title>Running a Network Display Server</title>
+      <title>Configuring Remote Access</title>
+
+      <para>By default, only users on the same system can login using
+	<application>XDM</application>.  To enable users on
+	other systems to connect to the display
+	server, edit the access control rules and enable
+	the connection listener.</para>
 
-      <para>In order for other clients to connect to the display
-	server, you must edit the access control rules and enable
-	the connection listener.  By default these are set to
-	conservative values.  To make <application>XDM</application>
-	listen for connections, first comment out a line in the
-	<filename>xdm-config</filename> file:</para>
+      <para>To configure <application>XDM</application> to
+	listen for any remote connection, comment out the
+	<literal>DisplayManager.requestPort</literal> line in
+	<filename>/usr/local/lib/X11/xdm/xdm-config</filename> by
+	putting a <literal>!</literal> in front of it:</para>
 
       <screen>! SECURITY: do not listen for XDMCP or Chooser requests
 ! Comment out this line if you want to manage X terminals with xdm
 DisplayManager.requestPort:     0</screen>
 
-      <para>and then restart <application>XDM</application>.
-	Remember that comments in app-defaults files begin with a
-	<quote>!</quote> character, not the usual <quote>#</quote>.
-	More strict access controls may be desired &mdash; look at the
-	example entries in <filename>Xaccess</filename>, and refer to
-	the &man.xdm.1; manual page for further information.</para>
-    </sect2>
-
-    <sect2>
-      <title>Replacements for XDM</title>
-
-      <para>Several replacements for the default
-	<application>XDM</application> program exist.  One of them,
-	<application>KDM</application> (bundled with
-	<application>KDE</application>) is described later in this
-	chapter.  The <application>KDM</application> display manager
-	offers many visual improvements and cosmetic frills, as well
-	as the functionality to allow users to choose their window
-	manager of choice at login time.</para>
+      <para>Save the edits and restart <application>XDM</application>.
+	To restrict remote access, look at the
+	example entries in <filename>/usr/local/lib/X11/xdm/Xaccess</filename> and refer to
+	&man.xdm.1; for further information.</para>
     </sect2>
   </sect1>