Package: x11-common
Version: 1:7.7+24
Severity: minor
Tags: patch
* What led up to the situation?
Checking for defects with a new version
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z < "man
page"
[Use "groff -e ' $' -e '\\~$' <file>" to find obvious trailing spaces.]
["test-groff" is a script in the repository for "groff"; is not shipped]
(local copy and "troff" slightly changed by me).
[The fate of "test-nroff" was decided in groff bug #55941.]
* What was the outcome of this action?
an.tmac:<stdin>:223: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.12.12-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1),
LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)
Versions of packages x11-common depends on:
ii lsb-base 11.6
ii sysvinit-utils [lsb-base] 3.14-1
x11-common recommends no packages.
x11-common suggests no packages.
-- no debconf information
Input file is Xsession.5
Output from "mandoc -T lint Xsession.5": (shortened list)
2 whitespace at end of input line
Remove trailing space with: sed -e 's/ *$//'
-.-.
Output from "test-groff -mandoc -t -ww -z Xsession.5": (shortened list)
1 Use macro '.B' for one argument or split argument.
3 Use macro '.I' for one argument or split argument.
1 .BR is for at least 2 arguments, got 1
3 .IR is for at least 2 arguments, got 1
2 trailing space in the line
Remove trailing space with: sed -e 's/ *$//'
-.-.
Remove space characters (whitespace) at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".
Number of lines affected is
2
-.-.
Add a "\&" after "e.g." and "i.e.", or use English words
(man-pages(7)).
Abbreviation points should be protected against being interpreted as
an end of sentence, if they are not, and that independent of the
current place on the line.
128:Note that the restriction may be easy to bypass, e.g. by using a
-.-.
Wrong distance between sentences in the input file.
Separate the sentences and subordinate clauses; each begins on a new
line. See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").
The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.
Remember coding: Only one command ("sentence") on each (logical) line.
E-mail: Easier to quote exactly the relevant lines.
Generally: Easier to edit the sentence.
Patches: Less unaffected text.
Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
Mark a final abbreviation point as such by suffixing it with "\&".
Some sentences (etc.) do not begin on a new line.
82:It is up to the display manager to set the argument. To pass
128:Note that the restriction may be easy to bypass, e.g. by using a
200:if the file is present. This allows the user to set global environment
-.-.
Split a punctuation mark from a single argument for a two-font macro
61:.BR xdm,
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
Xsession.5:29:.RB ( sh (1))
Xsession.5:207:If a program or failsafe argument was given and is allowed (see
above), it
Xsession.5:307:formatted to the user's terminal width (breaking lines at
whitespace) and
Xsession.5:379:is a relic from X Version 10 (and X11R1) days, before
app\-defaults files
-.-.
FSF office address update. See
https://lists.gnu.org/archive/html/bug-gnulib/2024-09/msg00004.html
18:.\" Suite 330, Boston, MA 02111-1307 USA
-.-.
Remove quotes when there is a printable
but no space character between them
and the quotes are not for emphasis (markup),
for example as an argument to a macro.
19:.TH Xsession 5 "2004\-11\-04" "Debian Project"
-.-.
Section headings (.SH and .SS) do not need quoting.
78:.SS "SESSION TYPES"
131:.SS "DEFAULT STARTUP PROCEDURE"
168:.SS "SUPPLIED SCRIPTS"
252:.SS "CUSTOMIZING THE STARTUP PROCEDURE"
298:.SS "BUILT\-IN SHELL FUNCTIONS"
345:.SH "INPUT FILES"
393:.SH "OUTPUT FILES"
410:.SH "SEE ALSO"
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
an.tmac:<stdin>:61: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
troff:<stdin>:193: warning: trailing space in the line
troff:<stdin>:198: warning: trailing space in the line
an.tmac:<stdin>:199: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:214: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:216: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
--- Xsession.5 2025-02-17 18:57:43.358830142 +0000
+++ Xsession.5.new 2025-02-17 19:25:44.577101394 +0000
@@ -16,7 +16,7 @@
.\" the Debian operating system, in /usr/share/common-licenses/GPL; if
.\" not, write to the Free Software Foundation, Inc., 59 Temple Place,
.\" Suite 330, Boston, MA 02111-1307 USA
-.TH Xsession 5 "2004\-11\-04" "Debian Project"
+.TH Xsession 5 2004\-11\-04 "Debian Project"
.SH NAME
Xsession \- initialize X session
.SH SYNOPSIS
@@ -34,8 +34,8 @@ or a display manager such as
.BR xdm (1).
(Some display managers only invoke
.I Xsession
-when specifically directed to so by the user; see the documentation for
-your display manager to find out more.)
+when specifically directed to so by the user;
+see the documentation for your display manager to find out more.)
Administrators unfamiliar with the Bourne shell will likely find the
.BR Xsession.options (5)
configuration file easier to deal with than
@@ -43,9 +43,9 @@ configuration file easier to deal with t
itself.
.PP
.I Xsession
-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.
+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 ,
.BR xdm ,
.BR xinit (1),
@@ -58,28 +58,32 @@ is used by both common methods of starti
(or another X display manager) and
.BR startx .
To change this for
-.BR xdm,
+.BR xdm ,
edit the \(oqDisplayManager*session\(cq resource in the
.I /etc/X11/xdm/xdm\-config
-file \(em for other display managers, consult their documentation.
+file \(em for other display managers,
+consult their documentation.
To stop
.B startx
from using
.I Xsession
-by default, replace the contents of the
+by default,
+replace the contents of the
.I /etc/X11/xinit/xinitrc
file.
.PP
The
.I Xsession
-script is quite flexible, and extensive customization of the X startup
+script is quite flexible,
+and extensive customization of the X startup
procedure is possible without modifying the script itself.
See \(lqCUSTOMIZING THE STARTUP PROCEDURE\(rq below.
-.SS "SESSION TYPES"
+.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. To pass
+It is up to the display manager to set the argument.
+To pass
.I Xsession
an argument from
.B startx
@@ -88,10 +92,12 @@ or
.I /etc/X11/Xsession
(or
.IR /etc/X11/xinit/xinitrc )
-must be called explicitly with a path, as in
+must be called explicitly with a path,
+as in
.B startx /etc/X11/Xsession
.BR failsafe .
-By default, three different arguments are supported:
+By default,
+three different arguments are supported:
.TP
.B failsafe
invokes a session consisting solely of an
@@ -99,7 +105,8 @@ invokes a session consisting solely of a
(no window manager is launched).
If the
.B x\-terminal\-emulator program cannot
-be found, the session exits.
+be found,
+the session exits.
The \(oqfailsafe\(cq argument is ignored if there is no
\(oqallow\-failsafe\(cq line in
.IR Xsession.options .
@@ -115,7 +122,8 @@ if it can be found in the $PATH.
This is usually a session manager or a very featureful window manager.
If
.I program
-is not found, the
+is not found,
+the
.I Xsession
script proceeds with its default behavior.
This argument is ignored if there is no \(oqallow\-user\-xsession\(cq line
@@ -123,27 +131,35 @@ in
.IR Xsession.options .
(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
+files,
+it makes little sense to permit them to specify the names of
arbitrary programs to run.)
-Note that the restriction may be easy to bypass, e.g. by using a
+Note that the restriction may be easy to bypass,
+e.g.\& by using a
.I .gnomerc
file instead.
-.SS "DEFAULT STARTUP PROCEDURE"
+.SS DEFAULT STARTUP PROCEDURE
Initially,
.I Xsession
performs some housekeeping.
It declares a set of built\-in functions (see
-\(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.
+\(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.
This makes it easier to discern which X session produced a particular line
of output in the file.
.PP
@@ -151,36 +167,43 @@ of output in the file.
next confirms that its script directory,
.IR Xsession.d ,
exists.
-If it does not, the script aborts.
+If it does not,
+the script aborts.
After the script directory is confirmed to be present,
.I Xsession
uses
.BR run\-parts (1)
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
+Only files named in a certain way are sourced;
+see the
.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 \(oq.old\(cq or \(oq.broken\(cq
+place,
+for instance by renaming them with \(oq.old\(cq or \(oq.broken\(cq
appended to the filename.)
-.SS "SUPPLIED SCRIPTS"
+.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/20x11\-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.
+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/30x11\-common_xresources
X resources are merged.
.B run\-parts
-is again used, this time to identify files in the
+is again used,
+this time to identify files in the
.I /etc/X11/Xresources
directory that should be processed with \(oqxrdb \-merge\(cq.
-Next, if the line \(oqallow\-user\-resources\(cq is present in
+Next,
+if the line \(oqallow\-user\-resources\(cq is present in
.IR Xsession.options ,
the user's
.I $HOME/.Xresources
@@ -190,37 +213,46 @@ file is merged in the same way.
Give access to the X server to the same user on the local host.
If the
.I xhost
-command is available, it will use it to allow any process of the same
+command is available,
+it will use it to allow any process of the same
user running on the local host to access the X server.
.TP
.I /etc/X11/Xsession.d/40x11\-common_xsessionrc
Source global environment variables.
-This script will source anything in
-.IR $HOME/.xsessionrc
-if the file is present. This allows the user to set global environment
-variables for their X session, such as locale information.
+This script will source anything in
+.I $HOME/.xsessionrc
+if the file is present.
+This allows the user to set global environment
+variables for their X session,
+such as locale information.
.TP
.I /etc/X11/Xsession.d/50x11\-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 \(oqallow\-user\-xsession\(cq is present in
+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 \(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:
-.IR $HOME/.xsession
+In the latter case,
+two historically popular names for user X session scripts are searched for:
+.I $HOME/.xsession
and
-.IR $HOME/.Xsession
+.I $HOME/.Xsession
(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,
+If the script is not executable,
+it is marked to be executed with the Bourne shell interpreter,
.BR sh .
-Finally, if none of the above succeeds, the following programs are searched
-for:
+Finally,
+if none of the above succeeds,
+the following programs are searched for:
.IR /usr/bin/x\-session\-manager ,
.IR /usr/bin/x\-window\-manager ,
and
@@ -244,18 +276,21 @@ this functionality may move to the ssh p
.TP
.I /etc/X11/Xsession.d/99x11\-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 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.
+are executed is important,
+files to be added to this directory should have a well\-formed name.
The following format is recommended:
.PP
* a two\-digit number denoting sequence;
@@ -265,11 +300,12 @@ locally\-created scripts);
.PP
* an underscore;
.PP
-* a description of the script's basic function, using only characters allowed
-by
+* a description of the script's basic function,
+using only characters allowed by
.BR run\-parts .
.PP
-Here is an example of how one might write a script, named
+Here is an example of how one might write a script,
+named
.IR 40custom_load\-xmodmap ,
to invoke
.BR xmodmap (1):
@@ -295,7 +331,7 @@ Those writing scripts for
.I Xsession
to execute should avail themselves of its built\-in shell functions,
described below.
-.SS "BUILT\-IN SHELL FUNCTIONS"
+.SS BUILT\-IN SHELL FUNCTIONS
.B message
is used for communicating with the user.
It is a wrapper for the
@@ -303,9 +339,10 @@ It is a wrapper for the
command and relies upon
.B echo
for its argument processing.
-This function may be given an arbitrarily long message string, which is
-formatted to the user's terminal width (breaking lines at whitespace) and
-sent to standard error.
+This function may be given an arbitrarily long message string,
+which is formatted to the user's terminal width
+(breaking lines at whitespace)
+and sent to standard error.
If the
.I DISPLAY
environment variable is set and the
@@ -316,7 +353,8 @@ is also used to display the message.
.PP
.B message_nonl
is used for communicating with the user when a trailing newline is
-undesirable; it omits a trailing newline from the message text.
+undesirable;
+it omits a trailing newline from the message text.
It otherwise works as
.BR message .
.PP
@@ -324,7 +362,9 @@ It otherwise works as
is used for indicating an error condition and aborting the script.
It works as
.BR message ,
-above, except that after displaying the message, it will exit
+above,
+except that after displaying the message,
+it will exit
.I Xsession
with status 1.
.SH ENVIRONMENT
@@ -332,17 +372,18 @@ The following environment variables affe
.IR Xsession :
.TP
.B HOME
-specifies the user's home directory; various files are searched for here.
+specifies the user's home directory;
+various files are searched for here.
.TP
.B TMPDIR
-names a 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.
+names a 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
.B COLUMNS
indicates the width of terminal device in character cells.
This value is 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
@@ -354,9 +395,9 @@ and are
not executed in a subshell.
.TP
.I /etc/X11/Xresources/
-is a directory containing files corresponding to Debian package names, each of
-which contains system\-wide X resource settings for X clients from the
-corresponding package.
+is a directory containing files corresponding to Debian package names,
+each of which contains system\-wide X resource settings for X clients
+from the corresponding package.
The settings are loaded with
.BR "xrdb \-merge" .
Files in this directory are matched using
@@ -376,8 +417,10 @@ The settings are loaded with
.BR "xrdb \-merge" .
Note that
.I $HOME/.Xdefaults
-is a relic from X Version 10 (and X11R1) days, before app\-defaults files
-were implemented.
+is a relic from X Version 10
+(and X11R1)
+days,
+before app\-defaults files were implemented.
It has been deprecated for over ten years at the time of this writing.
.I .Xresources
should be used instead.
@@ -390,7 +433,7 @@ See the manual page for
for tips on writing an
.I .xsession
file.
-.SH "OUTPUT FILES"
+.SH OUTPUT FILES
.TP
.I $HOME/.xsession\-errors
is where standard output and standard error for
@@ -401,13 +444,14 @@ script and all X client processes are di
is where the X session error file is placed if
.I $HOME/.xsession\-errors
cannot be opened.
-For security reasons, the exact filename is randomly generated by
+For security reasons,
+the exact filename is randomly generated by
.BR tempfile (1).
.SH AUTHORS
Stephen Early, Mark Eichin, and Branden Robinson developed Debian's X
session handling scripts.
Branden Robinson wrote this manual page.
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR Xsession.options (5),
.BR X (7),
.BR run\-parts (1),
Any program (person), that produces man pages, should check the output
for defects by using (both groff and nroff)
[gn]roff -mandoc -t -ww -b -z -K utf8 <man page>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
Any "autogenerator" should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
It should also check its input files for too long (> 80) lines.
This is just a simple quality control measure.
The "autogenerator" may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
"git" has a "tool" to point out whitespace,
see for example "git-apply(1)" and git-config(1)")
Not beginning each input sentence on a new line.
Line length and patch size should thus be reduced.
The script "reportbug" uses 'quoted-printable' encoding when a line is
longer than 1024 characters in an 'ascii' file.
See man-pages(7), item "semantic newline".
-.-
The difference between the formatted output of the original and patched file
can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -d -u <out1> <out2>
and for groff, using
\"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - \"
instead of 'nroff -mandoc'
Add the option '-t', if the file contains a table.
Read the output from 'diff -d -u ...' with 'less -R' or similar.
-.-.
If 'man' (man-db) is used to check the manual for warnings,
the following must be set:
The option \"-warnings=w\"
The environmental variable:
export MAN_KEEP_STDERR=yes (or any non-empty value)
or
(produce only warnings):
export MANROFFOPT=\"-ww -b -z\"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-
