X Strike Force XFree86 SVN commit: r1508 - in trunk/debian: . local
Author: branden
Date: 2004-06-03 22:06:28 -0500 (Thu, 03 Jun 2004)
New Revision: 1508
Modified:
trunk/debian/CHANGESETS
trunk/debian/changelog
trunk/debian/local/Xsession.5
Log:
Update Xsession(5) manpage to document the file specifications of the X
session "scriptlets" that are shipped by default. Make other cosmetic and
stylistic improvements.
Modified: trunk/debian/CHANGESETS
===================================================================
--- trunk/debian/CHANGESETS 2004-06-03 17:52:39 UTC (rev 1507)
+++ trunk/debian/CHANGESETS 2004-06-04 03:06:28 UTC (rev 1508)
@@ -66,4 +66,9 @@
in behavior in Xsession(5).
1507
+Update Xsession(5) manpage to document the file specifications of the X
+session "scriptlets" that are shipped by default. Make other cosmetic and
+stylistic improvements.
+ 1508
+
vim:set ai et sts=4 sw=4 tw=80:
Modified: trunk/debian/changelog
===================================================================
--- trunk/debian/changelog 2004-06-03 17:52:39 UTC (rev 1507)
+++ trunk/debian/changelog 2004-06-04 03:06:28 UTC (rev 1508)
@@ -73,8 +73,12 @@
session error file once it is successfully opened. Document this change
in behavior in Xsession(5).
- -- Branden Robinson <branden@debian.org> Thu, 3 Jun 2004 12:48:08 -0500
+ * Update Xsession(5) manpage to document the file specifications of the X
+ session "scriptlets" that are shipped by default. Make other cosmetic and
+ stylistic improvements.
+ -- Branden Robinson <branden@debian.org> Thu, 3 Jun 2004 14:14:49 -0500
+
xfree86 (4.3.0.dfsg.1-4) unstable; urgency=medium
* The "thanks for the 'testing'" release.
Modified: trunk/debian/local/Xsession.5
===================================================================
--- trunk/debian/local/Xsession.5 2004-06-03 17:52:39 UTC (rev 1507)
+++ trunk/debian/local/Xsession.5 2004-06-04 03:06:28 UTC (rev 1508)
@@ -1,4 +1,4 @@
-.\" This manpage is copyright 1998--2003 Branden Robinson
+.\" This manpage is copyright 1998--2004 Branden Robinson
.\" <branden@debian.org>.
.\"
.\" This is free software; you may redistribute it and/or modify
@@ -17,7 +17,7 @@
.\" Suite 330, Boston, MA 02111-1307 USA
.\"
.\" $Id$
-.TH Xsession 5 "2004\-06\-03" "Debian GNU/Linux"
+.TH Xsession 5 "2004\-06\-03" "Debian Project"
.SH NAME
Xsession \- initialize X session
.SH SYNOPSIS
@@ -47,8 +47,8 @@
is not intended to be invoked directly by the user; to be effective it
needs to run in a special environment associated with X server
initialization.
-.BR startx (1x),
-.BR xdm (1x),
+.BR startx ,
+.BR xdm ,
.BR xinit (1x),
and other similar programs handle this.
.PP
@@ -60,7 +60,7 @@
.BR startx .
To change this for
.BR xdm,
-edit the "DisplayManager*session" resource in the
+edit the \(oqDisplayManager*session\(cq resource in the
.I /etc/X11/xdm/xdm\-config
file; for
.BR startx ,
@@ -72,18 +72,24 @@
.I Xsession
script is quite flexible, and extensive customization of the X startup
procedure is possible without modifying the script itself. See
-"CUSTOMIZING THE STARTUP PROCEDURE" below.
-.SS SESSION TYPES
+\(lqCUSTOMIZING THE STARTUP PROCEDURE\(rq below.
+.SS "SESSION TYPES"
.I Xsession
may optionally be passed a single argument indicating the type of X
session to be started. It is up to the display manager to set the
-argument. By default, three different arguments are supported:
+argument, and there is no way to pass
+.I Xsession
+an argument from
+.B startx
+or
+.BR xinit .
+By default, three different arguments are supported:
.IP failsafe
invokes a session consisting solely of
.I /usr/bin/x\-terminal\-emulator
(no window manager is launched). If the x\-terminal\-emulator program cannot
-be found, the session exits. The "failsafe" argument is ignored if there
-is no "allow\-failsafe" line in
+be found, the session exits. The \(oqfailsafe\(cq argument is ignored if
+there is no \(oqallow\-failsafe\(cq line in
.IR Xsession.options .
.IP default
produces the same behavior as if no session type argument had been given at
@@ -98,27 +104,27 @@
is not found, the
.I Xsession
script proceeds with its default behavior. This argument is ignored if
-there is no "allow\-user\-xsession" line in
+there is no \(oqallow\-user\-xsession\(cq line in
.IR Xsession.options .
-(The reason being, if the administrator does not want users writing their
-own
+(If the administrator does not want users writing their own
.I .Xsession
files, it makes little sense to permit them to specify the names of
arbitrary programs to run.)
-.SS DEFAULT STARTUP PROCEDURE
+.SS "DEFAULT STARTUP PROCEDURE"
Initially,
.I Xsession
performs some housekeeping. It declares a set of built\-in functions (see
-"BUILT\-IN SHELL FUNCTIONS" below) and variables, then attempts to create a
-log file for the X session, or append to an existing one. Historically
-this is called an "error" file, but it catches all sorts of diagnostic
-output from various X clients run in the user's session, not just error
-messages. If it is impossible to write to an error file, the script (and
-thus the X session) aborts. For convenience, once the error file is
-successfully opened,
+\(lqBUILT\-IN SHELL FUNCTIONS\(rq below) and variables, then attempts to
+create a log file for the X session, or append to an existing one.
+Historically this is called an \(oqerror\(cq file, but it catches all sorts
+of diagnostic output from various X clients run in the user's session, not
+just error messages. If it is impossible to write to an error file, the
+script (and thus the X session) aborts. For convenience, once the error
+file is successfully opened,
.I Xsession
reports the fact that the session has started, the invoking username, and
-the date to the error file.
+the date to the error file. This makes it easier to discern which X
+session produced a particular line of output in the file.
.PP
.I Xsession
next confirms that its script directory,
@@ -131,35 +137,39 @@
to identify files in that directory that should be sourced (executed) in
the shell's environment. Only files named in a certain way are sourced;
see the
-.BR run\-parts (1)
+.B run\-parts
manual page for a description of valid characters in the filename. (This
restriction enables the administrator to move experimental or problematic
files out of the way of the script but keep them in an obvious place, for
-instance by renaming them with ".old" or ".broken" appended to the
-filename.)
-.PP
-Five scripts are provided by default:
-.PP
-1) Argument processing. Arguments are processed as described in "SESSION
-TYPES" above. The startup program, if one is identified at this point, is
-merely stored for later reference, and not immediately executed.
-.PP
-2) Merging of X resources. The internal
-.BR run\-parts (1)
+instance by renaming them with \(oq.old\(cq or \(oq.broken\(cq appended to
+the filename.)
+.SS "SUPPLIED SCRIPTS"
+Five shell script portions are supplied by default to handle the details of
+the session startup procedure.
+.TP
+.I /etc/X11/Xsession.d/20xfree86\-common_process\-args
+Arguments are processed as described in \(lqSESSION TYPES\(rq above. The
+startup program, if one is identified at this point, is merely stored for
+later reference, and not immediately executed.
+.TP
+.I /etc/X11/Xsession.d/30xfree86\-common_xresources
+X resources are merged. The internal
+.B run\-parts
is again used, this time to identify files in the
.I /etc/X11/Xresources
-directory that should be processed with "xrdb \-merge". Next, if the line
-"allow\-user\-resources" is present in
+directory that should be processed with \(oqxrdb \-merge\(cq. Next, if the
+line \(oqallow\-user\-resources\(cq is present in
.IR Xsession.options ,
the user's
.I $HOME/.Xresources
file is merged in the same way.
-.PP
-3) Determine startup program. The X client to launch as the controlling
+.TP
+.I /etc/X11/Xsession.d/50xfree86\-common_determine\-startup
+Determine startup program. The X client to launch as the controlling
process (the one that, upon exiting, causes the X server to exit as well)
is determined next. If a program or failsafe argument was given and is
allowed (see above), it is used as the controlling process. Otherwise, if
-the line "allow\-user\-xsession" is present in
+the line \(oqallow\-user\-xsession\(cq is present in
.IR Xsession.options ,
a user\-specified session program or script is used. In the latter case,
two historically popular names for user X session scripts are searched for:
@@ -169,7 +179,7 @@
(note the difference in case). The first one found is used. If the script
is not executable, it is marked to be executed with the Bourne shell
interpreter,
-.BR sh (1).
+.BR sh .
Finally, if none of the above succeeds, the following programs are searched
for:
.IR /usr/bin/x\-session\-manager ,
@@ -179,80 +189,68 @@
The first one found is used. If none are found,
.I Xsession
aborts with an error.
-.PP
-4) Start ssh\-agent, if needed. If the line "use\-ssh\-agent" is present in
+.TP
+.I /etc/X11/Xsession.d/90xfree86\-common_ssh\-agent
+Start
+.BR ssh\-agent (1),
+if needed. If the line \(oquse\-ssh\-agent\(cq is present in
.IR Xsession.options ,
-and no ssh agent process appears to be running already,
-.BR ssh\-agent (1)
+and no SSH agent process appears to be running already,
+.B ssh\-agent
is marked to be used to execute the startup program determined previously.
.I Note: this functionality may move to the ssh package in the future.
-.PP
-5) Start the X session. Finally, the startup program is executed, inside a
-Bourne shell if necessary, and inside an ssh\-agent if necessary. The
+.TP
+.I /etc/X11/Xsession.d/99xfree86\-common_start
+Start the X session. The startup program is executed, inside a Bourne
+shell if it is not executable, and inside an ssh\-agent if necessary. The
shell's
.B exec
command is used to spare a slot in the process table.
-.SS CUSTOMIZING THE STARTUP PROCEDURE
-Of course, any of the existing files can be edited in\-place.
+.SS "CUSTOMIZING THE STARTUP PROCEDURE"
+Of course, any of the existing files can be edited in place.
.PP
Because the order in which the various scripts in
.I /etc/X11/Xsession.d
are executed is important, files to be added to this directory should
have a well\-formed name. The following format is recommended:
.PP
-.PD 0
-* a two\-digit number denoting sequence
+* a two\-digit number denoting sequence;
.PP
-* the name of the package providing the script
+* the name of the package providing the script;
+.HP
+* an underscore;
.PP
-* an underscore
-.PP
* a description of the script's basic function, using only characters allowed
by
-.BR run\-parts (1).
-.PD
+.BR run\-parts .
.PP
Here is an example of how one might write a script, named
.IR 40custom_load\-xmodmap ,
to invoke
.BR xmodmap (1x):
.PP
-.PD 0
-SYSMODMAP=/etc/X11/Xmodmap
-.PP
-USRMODMAP=$HOME/.Xmodmap
-.PD
-.PP
-.PD 0
+.nf
+SYSMODMAP="/etc/X11/Xmodmap"
+USRMODMAP="$HOME/.Xmodmap"
+
if [ \-x /usr/bin/X11/xmodmap ]; then
-.PP
- if [ \-f $SYSMODMAP ]; then
-.PP
- xmodmap $SYSMODMAP
-.PP
- fi
-.PP
+ if [ \-f "$SYSMODMAP" ]; then
+ xmodmap "$SYSMODMAP"
+ fi
fi
-.PD
-.PP
-.PD 0
+
if [ \-x /usr/bin/X11/xmodmap ]; then
-.PP
- if [ \-f $USRMODMAP ]; then
-.PP
- xmodmap $USRMODMAP
-.PP
- fi
-.PP
+ if [ \-f "$USRMODMAP" ]; then
+ xmodmap "$USRMODMAP"
+ fi
fi
-.PD
+.fi
.PP
Those writing scripts for
.I Xsession
to execute should avail themselves of its built\-in shell functions,
described below.
-.SS BUILT\-IN SHELL FUNCTIONS
-.PP
+.SS "BUILT\-IN SHELL FUNCTIONS"
.B message
is used for communicating with the user. It is a wrapper for the
.BR echo (1)
@@ -270,7 +268,7 @@
.PP
.B message_nonl
is used for communicating with the user when a trailing newline is
-undesirable; it omits a trailing newling from the message text. It
+undesirable; it omits a trailing newline from the message text. It
otherwise works as
.BR message .
.PP
@@ -285,23 +283,23 @@
The following environment variables affect the execution of
.IR Xsession :
.TP
-HOME
+.B HOME
The user's home directory; various files are searched for here.
.TP
-TMPDIR
+.B TMPDIR
Default directory for temporary files; if the standard X session error file
cannot be opened, this variable is used to locate a place for one.
.TP
-COLUMNS
+.B COLUMNS
Width of terminal device, in character cells. Used for formatting
diagnostic messages.
-.SH INPUT FILES
+.SH "INPUT FILES"
.TP
.I /etc/X11/Xsession.d/
is a directory containing Bourne shell scripts to be executed by
.IR Xsession .
Files in this directory are matched using
-.BR run\-parts (1)
+.B run\-parts
and are
.BR source d,
not executed in a subshell.
@@ -312,7 +310,7 @@
corresponding package. The settings are loaded with
.BR "xrdb \-merge" .
Files in this directory are matched using
-.BR run\-parts (1).
+.BR run\-parts .
.TP
.I /etc/X11/Xsession.options
contains configuration options for the
@@ -343,7 +341,7 @@
for tips on writing an
.I .Xsession
file.
-.SH OUTPUT FILES
+.SH "OUTPUT FILES"
.TP
.I $HOME/.xsession\-errors
Where standard output and standard error for
@@ -355,7 +353,7 @@
.I $HOME/.xsession\-errors
cannot be opened. The filename is provided by
.BR tempfile (1).
-.SH SEE ALSO
+.SH "SEE ALSO"
.BR Xsession.options (5),
.BR X (7x),
.BR run\-parts (1),
Reply to: