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>:78: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' 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.options.5
Output from "mandoc -T lint Xsession.options.5": (shortened list)
-.-.
Output from "test-groff -mandoc -t -ww -z Xsession.options.5": (shortened list)
1 Use macro '.B' for one argument or split argument.
1 .BR is for at least 2 arguments, got 1
-.-.
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.options 5 "2004\-10\-31" "Debian Project"
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
an.tmac:<stdin>:78: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
-.-
Shorten lines, see attachment "general.bugs".
--- Xsession.options.5 2025-02-18 06:49:38.068115174 +0000
+++ Xsession.options.5.new 2025-02-18 07:11:35.139749696 +0000
@@ -16,13 +16,14 @@
.\" 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.options 5 "2004\-10\-31" "Debian Project"
+.TH Xsession.options 5 2004\-10\-31 "Debian Project"
.SH NAME
Xsession.options, Xsession.options.d \- configuration options for
.BR Xsession (5)
.SH DESCRIPTION
-\fI/etc/X11/Xsession.options\fR and \fI/etc/X11/Xsession.options.d/*.conf\fR
-contain options that determine some of the behavior of the
+\fI/etc/X11/Xsession.options\fR
+and \fI/etc/X11/Xsession.options.d/*.conf\fR contain options
+that determine some of the behavior of the
.BR Xsession (5)
Bourne shell
.RB ( sh (1))
@@ -32,68 +33,82 @@ See the
manpage for further information.
.PP
These configuration files
-may contain comments, which begin with a hash mark (\(oq#\(cq) and end at
-the next newline, just like comments in shell scripts.
-The rest of the file consists of options which are expressed as words
-separated by hyphens, with only one option per line.
-Options are enabled by simply placing them in the file; they are disabled
-by prefixing the option name with \(oqno\-\(cq.
+may contain comments,
+which begin with a hash mark (\(oq#\(cq)
+and end at the next newline,
+just like comments in shell scripts.
+The rest of the file consists of options
+which are expressed as words separated by hyphens,
+with only one option per line.
+Options are enabled by simply placing them in the file;
+they are disabled by prefixing the option name with \(oqno\-\(cq.
.PP
-Options are read from \fI/etc/X11/Xsession.options\fR, followed by
-\fI/etc/X11/Xsession.options.d/*.conf\fR in sorted order; later occurrences of
-an option (with or without the \(oqno\-\(cq prefix) take precedence over
earlier
-occurrences.
+Options are read from \fI/etc/X11/Xsession.options\fR,
+followed by
+\fI/etc/X11/Xsession.options.d/*.conf\fR in sorted order;
+later occurrences of an option
+(with or without the \(oqno\-\(cq prefix)
+take precedence over earlier occurrences.
.PP
Available options are:
.TP
.B allow\-failsafe
If the \(oqfailsafe\(cq argument is passed to the
.I Xsession
-script, an emergency X session is invoked, consisting of only an
+script,
+an emergency X session is invoked,
+consisting of only an
.BR x\-terminal\-emulator (1)
in the upper\-left hand corner of the screen.
No window manager is started.
If an
.B x\-terminal\-emulator
-program is not available, the session exits immediately.
+program is not available,
+the session exits immediately.
.TP
.B allow\-user\-resources
If users have a file called
.I .Xresources
-in their home directories, these resources will be merged with the default
+in their home directories,
+these resources will be merged with the default
X resources when they log in.
.TP
.B allow\-user\-xsession
If users have an executable file called
.I .xsession
-in their home directories, it can be used as the startup program for the X
-session (see
+in their home directories,
+it can be used as the startup program for the X session
+(see
.BR Xsession (5)).
-If the file is present but not executable, it may still be used, but is
-assumed to be a Bourne shell script, and executed with
+If the file is present but not executable,
+it may still be used,
+but is assumed to be a Bourne shell script,
+and executed with
.BR sh (1).
.TP
.B use-session-dbus
If the
-.BR dbus
-package is installed, the session bus will be activated at X session
-launch.
+.B dbus
+package is installed,
+the session bus will be activated at X session launch.
.TP
.B use\-ssh\-agent
If the
.BR ssh\-agent (1)
-program is available and no agent process appears to be running already,
+program is available
+and no agent process appears to be running already,
the X session will be invoked by exec'ing
.B ssh\-agent
-with the startup command, instead of the startup command directly.
+with the startup command,
+instead of the startup command directly.
.PP
All of the above options are enabled by default.
Additional options may be supported by the local administrator.
.BR Xsession (5)
describes how this is accomplished.
.SH AUTHORS
-Stephen Early, Mark Eichin, and Branden Robinson developed Debian's X
-session handling scripts.
+Stephen Early, Mark Eichin,
+and Branden Robinson developed Debian's X session handling scripts.
Branden Robinson wrote this manual page.
.SH SEE ALSO
.BR Xsession (5),
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)
-.-
