Package: xinit
Version: 1.4.2-1
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 ' $' <file>" to find 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>:57: misuse, warning: .RB is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:86: 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.6-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 xinit depends on:
ii libc6 2.40-5
ii libx11-6 2:1.8.10-2
ii x11-common 1:7.7+23.1
ii xauth 1:1.1.2-1.1
Versions of packages xinit recommends:
ii twm [x-window-manager] 1:1.0.10-1+b1
ii xserver-xorg [xserver] 1:7.7+23.1
ii xterm [x-terminal-emulator] 396-1
xinit suggests no packages.
-- no debconf information
Input file is startx.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
-.-
So any 'generator' should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
This is just a simple quality control measure.
The 'generator' may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Input text line longer than 80 bytes.
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
Not beginning each input sentence on a new line.
Lines should thus be shorter.
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 -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 of 'diff -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)
-.-.
Output from "mandoc -T lint startx.1": (shortened list)
-.-.
Output from "test-groff -mandoc -t -ww -z startx.1": (shortened list)
1 Use macro '.B' for one argument or split argument.
1 Use macro '.I' for one argument or split argument.
1 .IR is for at least 2 arguments, got 1
1 .RB is for at least 2 arguments, got 1
-.-.
Use the word (in)valid instead of (il)legal,
if not related to legal matters.
See "www.gnu.org/prep/standards".
Think about translations into other languages!
startx.1:62:the manual page for your X server to determine which arguments are
legal.
-.-.
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 "\&".
36:\&\.\|.\|. ] [
81:is used to start the X session. All discussion of the
98:for a filename. If that variable is unset, or does not contain a filename,
115:for a filename. If that variable is unset, or does not contain a filename,
162:This variable should contain the location of an xinitrc file. If unset,
169:This variable should contain the location of an xserver file. If unset,
-.-.
Remove reverse slash (\) in front of a period (.) that is to be printed
as such, and can not come a control character in the first column of a line.
Use "\&" to protect the period to avoid that.
This is a sign, that the man page was transformed from another source
file with a program, whose name is NOT mentioned in a comment.
36:\&\.\|.\|. ] [
-.-.
Split a punctuation mark from a single argument for a two-font macro
86:.IR .xsession.
-.-.
Put a subordinate sentence (after a comma) on a new line.
72:Note that in the Debian system, what many people traditionally put in the
98:for a filename. If that variable is unset, or does not contain a filename,
101:in the user's home directory. If that is not found, it uses
107:If command line client options are given, they override this
115:for a filename. If that variable is unset, or does not contain a filename,
118:in the user's home directory. If that is not found, it uses
124:If command line server options are given, they override this
150:This variable, if not already defined, gets set to
152:This is to prevent the X server, if not given the
154:argument, from automatically setting up insecure host-based authentication
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
an.tmac:<stdin>:57: misuse, warning: .RB is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:86: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
--- startx.1 2025-01-12 19:39:05.961362988 +0000
+++ startx.1.new 2025-01-12 19:58:14.030777243 +0000
@@ -33,7 +33,7 @@ startx \- initialize an X session
.I client
]
.I options
-\&\.\|.\|. ] [
+\&.\|.\|.\& ] [
.B \-\^\-
[
.I server
@@ -54,12 +54,12 @@ Arguments immediately following the
command are used to start a client in the same manner as
.BR xinit (1).
The special argument
-.RB '\-\^\-'
+.RB ' \-\^\- '
marks the end of client arguments and the beginning of server options.
It may be convenient to specify server options with startx to change them on a
per-session basis.
Some examples of specifying server arguments follow; consult
-the manual page for your X server to determine which arguments are legal.
+the manual page for your X server to determine which arguments are valid.
.RS
.PP
startx \-\^\- \-depth 16
@@ -69,21 +69,24 @@ startx \-\^\- \-dpi 100
startx \-\^\- \-layout Multihead
.RE
.PP
-Note that in the Debian system, what many people traditionally put in the
+Note that in the Debian system,
+what many people traditionally put in the
.I .xinitrc
file should go in
.I .xsession
-instead; this permits the same X environment to be presented whether
+instead;
+this permits the same X environment to be presented whether
.IR startx ,
.IR xdm ,
or
.I xinit
-is used to start the X session. All discussion of the
+is used to start the X session.
+All discussion of the
.I .xinitrc
file in the
.IR xinit (1)
manual page applies equally well to
-.IR .xsession.
+.IR .xsession .
Keep in mind that
.I .xinitrc
is used only by
@@ -95,36 +98,45 @@ To determine the client to run,
.B startx
first checks the environment variable
.I XINITRC
-for a filename. If that variable is unset, or does not contain a filename,
+for a filename.
+If that variable is unset,
+or does not contain a filename,
it looks for a file called
.I .xinitrc
-in the user's home directory. If that is not found, it uses
-the file
+in the user's home directory.
+If that is not found,
+it uses the file
.I xinitrc
in the
.I xinit
library directory.
-If command line client options are given, they override this
-behavior and revert to the
+If command line client options are given,
+they override this behavior
+and revert to the
.BR xinit (1)
behavior.
To determine the server to run,
.B startx
checks the environment variable
.I XSERVERRC
-for a filename. If that variable is unset, or does not contain a filename,
+for a filename.
+If that variable is unset,
+or does not contain a filename,
it looks for a file called
.I .xserverrc
-in the user's home directory. If that is not found, it uses
-the file
+in the user's home directory.
+If that is not found,
+it uses the file
.I xserverrc
in the
.I xinit
library directory.
-If command line server options are given, they override this
-behavior and revert to the
+If command line server options are given,
+they override this behavior
+and revert to the
.BR xinit (1)
-behavior. Users rarely need to provide a
+behavior.
+Users rarely need to provide a
.I .xserverrc
file.
See the
@@ -147,26 +159,33 @@ connect. Note that this gets
not read.
.TP 25
XAUTHORITY
-This variable, if not already defined, gets set to
+This variable,
+if not already defined,
+gets set to
.IR $(HOME)/.Xauthority .
-This is to prevent the X server, if not given the
+This is to prevent the X server,
+if not given the
.I \-auth
-argument, from automatically setting up insecure host-based authentication
-for the local host. See the
+argument,
+from automatically setting up insecure host-based authentication
+for the local host.
+See the
.BR Xserver (1)
and
.IR Xsecurity (7)
manual pages for more information on X client/server authentication.
.TP 25
XINITRC
-This variable should contain the location of an xinitrc file. If unset,
+This variable should contain the location of an xinitrc file.
+If unset,
.I $(HOME)/.xinitrc
or
.I /etc/X11/xinit/xinitrc
will be used.
.TP 25
XSERVERRC
-This variable should contain the location of an xserver file. If unset,
+This variable should contain the location of an xserver file.
+If unset,
.I $(HOME)/.xinitrc
or
.I /etc/X11/xinit/xserverrc
