--- Begin Message ---
Package: xorg-docs-core
Version: 1:1.7.1-1.2
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?
troff:<stdin>:54: warning: trailing space in the line
an.tmac:<stdin>:1086: style: 1 leading space(s) on input line
* 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)
xorg-docs-core depends on no packages.
xorg-docs-core recommends no packages.
Versions of packages xorg-docs-core suggests:
pn xorg-docs <none>
-- no debconf information
Input file is X.7
Output from "mandoc -T lint X.7": (shortened list)
1 input text line longer than 80 bytes: a display server and...
1 input text line longer than 80 bytes: a font server and re...
1 input text line longer than 80 bytes: a variety of differe...
1 input text line longer than 80 bytes: keyboard description...
-.-.
Output from "test-groff -mandoc -t -ww -z X.7": (shortened list)
1 trailing space in the line
Remove trailing space with: sed -e 's/ *$//'
-.-.
Use "\e" to print the escape character instead of "\\" (which gets
interpreted in copy mode).
1003: /etc/X11/%L/%T/%N%C%S:\\
1004: /etc/X11/%l/%T/%N%C%S:\\
1005: /etc/X11/%T/%N%C%S:\\
1006: /etc/X11/%L/%T/%N%S:\\
1007: /etc/X11/%l/%T/%N%S:\\
1008: /etc/X11/%T/%N%S:\\
1009: /usr/share/X11/%L/%T/%N%C%S:\\
1010: /usr/share/X11/%l/%T/%N%C%S:\\
1011: /usr/share/X11/%T/%N%C%S:\\
1012: /usr/share/X11/%L/%T/%N%S:\\
1013: /usr/share/X11/%l/%T/%N%S:\\
1014: /usr/share/X11/%T/%N%S:\\
1015: /usr/lib/x86_64-linux-gnu/X11/%L/%T/%N%C%S:\\
1016: /usr/lib/x86_64-linux-gnu/X11/%l/%T/%N%C%S:\\
1017: /usr/lib/x86_64-linux-gnu/X11/%T/%N%C%S:\\
1018: /usr/lib/x86_64-linux-gnu/X11/%L/%T/%N%S:\\
1019: /usr/lib/x86_64-linux-gnu/X11/%l/%T/%N%S:\\
1044: $XAPPLRESDIR/%L/%N%C:\\
1045: $XAPPLRESDIR/%l/%N%C:\\
1046: $XAPPLRESDIR/%N%C:\\
1047: $HOME/%N%C:\\
1048: $XAPPLRESDIR/%L/%N:\\
1049: $XAPPLRESDIR/%l/%N:\\
1050: $XAPPLRESDIR/%N:\\
-.-.
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.
Split (sometimes) lines after a punctuation mark; before a conjunction.
N.B.
The number of lines affected can be too large to be in a patch.
Lines with only one (or two) space(s) between sentences are split,
so latter sentences begin on a new line.
[List of affected lines removed]
-.-
Split lines longer than 80 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
Add "\:" to split the string for the output, "\<newline>" in the source.
Line 99, length 93
a font server and related utilities, \fIxfs\fP, \fIfsinfo\fP, \fIfslsfonts\fP,
\fIfstobdf\fP;
Line 100, length 82
a display server and related utilities, \fIXserver\fP, \fIrgb\fP,
\fImkfontdir\fP;
Line 102, length 83
keyboard description compiler and related utilities, \fIxkbcomp\fP,
\fIsetxkbmap\fP
Line 360, length 87
a variety of different user interfaces can be built. The X.Org Foundation
distribution
Line 414, length 83
\fI\-adobe\-courier\-medium\-r\-normal\-\-10\-100\-75\-75\-m\-60\-iso8859\-1\fP
Line 427, length 83
% xlsfonts \-fn
\&'\-*\-courier\-medium\-r\-normal\-\-*\-100\-*\-*\-*\-*\-*\-*'
Line 500, length 95
\fI<red>\fP, \fI<green>\fP, \fI<blue>\fP := \fIh\fP | \fIhh\fP |
\fIhhh\fP | \fIhhhh\fP
-.-.
Protect "^From " from forcing a mail software to use "quoted-printable"
encoding, by adding "\&" in front of it.
150:From the user's perspective, every X server has a \fIdisplay name\fP of the
-.-.
No need for "\&" to be in front of a period (.),
if there is a character in front of it
747:Binding = "\&." | "*"
756:Curly braces ({\&.\&.\&.}) indicate zero or more repetitions
758:Square brackets ([\&.\&.\&.\&]) indicate that the enclosed element is
optional.
759:Quotes ("\&.\&.\&.\&") are used around literal characters.
-.-.
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.
218:.I "local"
-.-.
Section headings (.SH and .SS) do not need quoting.
116:.SH "STARTING UP"
149:.SH "DISPLAY NAMES"
231:.SH "ACCESS CONTROL"
280:.SH "GEOMETRY SPECIFICATIONS"
352:.SH "WINDOW MANAGERS"
367:.SH "FONT NAMES"
450:.SH "FONT SERVER NAMES"
466:.SH "COLOR NAMES"
1187:.SH "SEE ALSO"
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
troff:<stdin>:54: warning: trailing space in the line
an.tmac:<stdin>:1082: style: 1 leading space(s) on input line
-.-.
Additionally:
Table: use left alignment as the differences in the width of data is
substantial.
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
--- X.7 2025-02-20 22:31:53.811727516 +0000
+++ X.7.new 2025-02-20 23:08:44.421483740 +0000
@@ -47,7 +47,7 @@ referring to this software:
.sp
.TS
center;
-c.
+l.
X
X Window System
X Version 11
@@ -96,10 +96,13 @@ utilities for listing information about
screen image manipulation utilities, \fIxwd\fP, \fIxwud\fP, and \fIxmag\fP;
a performance measurement utility, \fIx11perf\fP;
a font compiler, \fIbdftopcf\fP;
-a font server and related utilities, \fIxfs\fP, \fIfsinfo\fP, \fIfslsfonts\fP,
\fIfstobdf\fP;
-a display server and related utilities, \fIXserver\fP, \fIrgb\fP,
\fImkfontdir\fP;
+a font server and related utilities, \fIxfs\fP, \fIfsinfo\fP,
+\fIfslsfonts\fP, \fIfstobdf\fP;
+a display server and related utilities, \fIXserver\fP, \fIrgb\fP,
+\fImkfontdir\fP;
a clipboard manager, \fIxclipboard\fP;
-keyboard description compiler and related utilities, \fIxkbcomp\fP,
\fIsetxkbmap\fP
+keyboard description compiler and related utilities, \fIxkbcomp\fP,
+\fIsetxkbmap\fP
\fIxkbprint\fP, \fIxkbbell\fP, \fIxkbevd\fP, \fIxkbvleds\fP, and
\fIxkbwatch\fP;
a utility to terminate clients, \fIxkill\fP;
a firewall security proxy, \fIxfwp\fP;
@@ -113,7 +116,7 @@ Many other utilities, window managers, g
as user-contributed software in the X.Org Foundation distribution, or are
available on the Internet.
See your site administrator for details.
-.SH "STARTING UP"
+.SH STARTING UP
There are two main ways of getting the X server and an initial set of
client applications started. The particular method used depends on what
operating system you are running and whether or not you use other window
@@ -146,8 +149,8 @@ runs another to start up any desired cli
finish. Since either or both of the user-specified programs may be a shell
script, this gives substantial flexibility at the expense of a
nice interface. For this reason, \fIxinit\fP is not intended for end users.
-.SH "DISPLAY NAMES"
-From the user's perspective, every X server has a \fIdisplay name\fP of the
+.SH DISPLAY NAMES
+\&From the user's perspective, every X server has a \fIdisplay name\fP of the
form:
.sp
.RS
@@ -215,7 +218,7 @@ type of channel
(also called a transport layer) to be used. X servers generally
support the following types of connections:
.TP 8
-.I "local"
+.I local
.br
The hostname part of the display name should be the empty string.
For example: \fI:0\fP, \fI:1\fP, and \fI:0.1\fP. The most efficient
@@ -228,7 +231,7 @@ hostname or IP address. Full Internet n
addresses, and IPv6 addresses are all allowed. For example:
\fIx.org:0\fP, \fIexpo:0\fP, \fI[::1]:0\fP,
\fI198.112.45.11:0\fP, \fIbigmachine:1\fP, and \fIhydra:0.1\fP.
-.SH "ACCESS CONTROL"
+.SH ACCESS CONTROL
An X server can use several types of access control. Mechanisms provided
in Release 7 are:
.TS
@@ -277,7 +280,7 @@ data to know if this is actually a probl
.PP
For more information on access control, see the
\fIXsecurity\fP(7) manual page.
-.SH "GEOMETRY SPECIFICATIONS"
+.SH GEOMETRY SPECIFICATIONS
One of the advantages of using window systems instead of
hardwired terminals is that
applications don't have to be restricted to a particular size or location
@@ -349,7 +352,7 @@ hand corner:
xload \-geometry 48x48\-96+0 &
xbiff \-geometry 48x48\-48+0 &
.fi
-.SH "WINDOW MANAGERS"
+.SH WINDOW MANAGERS
The layout of windows on the screen is controlled by special programs called
\fIwindow managers\fP. Although many window managers will honor geometry
specifications as given, others may choose to ignore them (requiring the user
@@ -357,14 +360,15 @@ to explicitly draw the window's region o
example).
.PP
Since window managers are regular (albeit complex) client programs,
-a variety of different user interfaces can be built. The X.Org Foundation
distribution
+a variety of different user interfaces can be built.
+The X.Org Foundation distribution
comes with a window manager named \fItwm\fP which supports overlapping windows,
popup menus, point-and-click or click-to-type input models, title bars, nice
icons (and an icon manager for those who don't like separate icon windows).
.PP
See the user-contributed software in the X.Org Foundation distribution for
other
popular window managers.
-.SH "FONT NAMES"
+.SH FONT NAMES
Collections of characters for displaying text and symbols in X are known as
\fIfonts\fP. A font typically contains images that share a common appearance
and look nice together (for example, a single size, boldness, slant, and
@@ -447,7 +451,7 @@ replace it with a specific size in decip
the inch) to name a font at that size.
The last zero is an average width field, measured in tenths of pixels;
some servers will anamorphically scale if this value is specified.
-.SH "FONT SERVER NAMES"
+.SH FONT SERVER NAMES
One of the following forms can be used to name a font server that
accepts TCP connections:
.sp
@@ -463,7 +467,7 @@ The \fIcataloguelist\fP specifies a list
with \&'+' as a separator.
.PP
Examples: \fItcp/x.org:7100\fP, \fItcp/198.112.45.11:7100/all\fP.
-.SH "COLOR NAMES"
+.SH COLOR NAMES
Most applications provide ways of tailoring (usually through resources or
command line arguments) the colors of various elements
in the text and graphics they display.
@@ -744,7 +748,7 @@ IncludeFile = "#" WhiteSpace "
FileName = <valid filename for operating system>
ResourceSpec = WhiteSpace ResourceName WhiteSpace ":" WhiteSpace Value
ResourceName = [Binding] {Component Binding} ComponentName
-Binding = "\&." | "*"
+Binding = "." | "*"
WhiteSpace = {<space> | <horizontal tab>}
Component = "?" | ComponentName
ComponentName = NameChar {NameChar}
@@ -753,10 +757,10 @@ Value = {<any character
.fi
.PP
Elements separated by vertical bar (|) are alternatives.
-Curly braces ({\&.\&.\&.}) indicate zero or more repetitions
+Curly braces ({...\&}) indicate zero or more repetitions
of the enclosed elements.
-Square brackets ([\&.\&.\&.\&]) indicate that the enclosed element is optional.
-Quotes ("\&.\&.\&.\&") are used around literal characters.
+Square brackets ([...\&]) indicate that the enclosed element is optional.
+Quotes ("...\&") are used around literal characters.
.PP
IncludeFile lines are interpreted by replacing the line with the
contents of the specified file. The word "include" must be in lowercase.
@@ -1000,23 +1004,23 @@ This must contain a colon separated list
will search for resource files. The default value consists of
.sp
.nf
- /etc/X11/%L/%T/%N%C%S:\\
- /etc/X11/%l/%T/%N%C%S:\\
- /etc/X11/%T/%N%C%S:\\
- /etc/X11/%L/%T/%N%S:\\
- /etc/X11/%l/%T/%N%S:\\
- /etc/X11/%T/%N%S:\\
- /usr/share/X11/%L/%T/%N%C%S:\\
- /usr/share/X11/%l/%T/%N%C%S:\\
- /usr/share/X11/%T/%N%C%S:\\
- /usr/share/X11/%L/%T/%N%S:\\
- /usr/share/X11/%l/%T/%N%S:\\
- /usr/share/X11/%T/%N%S:\\
- /usr/lib/x86_64-linux-gnu/X11/%L/%T/%N%C%S:\\
- /usr/lib/x86_64-linux-gnu/X11/%l/%T/%N%C%S:\\
- /usr/lib/x86_64-linux-gnu/X11/%T/%N%C%S:\\
- /usr/lib/x86_64-linux-gnu/X11/%L/%T/%N%S:\\
- /usr/lib/x86_64-linux-gnu/X11/%l/%T/%N%S:\\
+ /etc/X11/%L/%T/%N%C%S:\e
+ /etc/X11/%l/%T/%N%C%S:\e
+ /etc/X11/%T/%N%C%S:\e
+ /etc/X11/%L/%T/%N%S:\e
+ /etc/X11/%l/%T/%N%S:\e
+ /etc/X11/%T/%N%S:\e
+ /usr/share/X11/%L/%T/%N%C%S:\e
+ /usr/share/X11/%l/%T/%N%C%S:\e
+ /usr/share/X11/%T/%N%C%S:\e
+ /usr/share/X11/%L/%T/%N%S:\e
+ /usr/share/X11/%l/%T/%N%S:\e
+ /usr/share/X11/%T/%N%S:\e
+ /usr/lib/x86_64-linux-gnu/X11/%L/%T/%N%C%S:\e
+ /usr/lib/x86_64-linux-gnu/X11/%l/%T/%N%C%S:\e
+ /usr/lib/x86_64-linux-gnu/X11/%T/%N%C%S:\e
+ /usr/lib/x86_64-linux-gnu/X11/%L/%T/%N%S:\e
+ /usr/lib/x86_64-linux-gnu/X11/%l/%T/%N%S:\e
/usr/lib/x86_64-linux-gnu/X11/%T/%N%S
.fi
.sp
@@ -1041,13 +1045,13 @@ where libXt will search for user depende
value is:
.sp
.nf
- $XAPPLRESDIR/%L/%N%C:\\
- $XAPPLRESDIR/%l/%N%C:\\
- $XAPPLRESDIR/%N%C:\\
- $HOME/%N%C:\\
- $XAPPLRESDIR/%L/%N:\\
- $XAPPLRESDIR/%l/%N:\\
- $XAPPLRESDIR/%N:\\
+ $XAPPLRESDIR/%L/%N%C:\e
+ $XAPPLRESDIR/%l/%N%C:\e
+ $XAPPLRESDIR/%N%C:\e
+ $HOME/%N%C:\e
+ $XAPPLRESDIR/%L/%N:\e
+ $XAPPLRESDIR/%l/%N:\e
+ $XAPPLRESDIR/%N:\e
$HOME/%N
.fi
.sp
@@ -1079,7 +1083,8 @@ The default value is\fI /usr/share/X11/X
.TP
.B XCMSDB
This must point to a color name database file. The default value is
-\fI /usr/lib/x86_64-linux-gnu/X11/Xcms.txt\fP.
+.ti \n(INu+\n(TSu+4m
+\fI/usr/lib/x86_64-linux-gnu/X11/Xcms.txt\fP.
.TP
.B RESOURCE_NAME
This serves as main identifier for resources belonging to the program
@@ -1184,7 +1189,7 @@ the appropriate instance name can be pla
.nf
xterm*StringConversionWarnings: on
.fi
-.SH "SEE ALSO"
+.SH SEE ALSO
.\" introductions
.BR XOrgFoundation (7),
.BR XStandards (7),
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)
-.-
--- End Message ---
pgpg8xAzm6KAc.pgp
