Package: readline-common
Version: 8.2-6
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
grep -n -e ' $' -e '\\~$' -e ' \\f.$' -e ' \\"' <file>
to find (most) 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>:49: warning: trailing space in the line
an.tmac:<stdin>:54: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
troff:<stdin>:74: warning: trailing space in the line
an.tmac:<stdin>:87: style: use of deprecated macro: .PD
an.tmac:<stdin>:133: style: use of deprecated macro: .PD
an.tmac:<stdin>:150: style: use of deprecated macro: .PD
an.tmac:<stdin>:186: style: use of deprecated macro: .PD
an.tmac:<stdin>:195: style: use of deprecated macro: .PD
an.tmac:<stdin>:275: style: use of deprecated macro: .PD
troff:<stdin>:485: warning: trailing space in the line
troff:<stdin>:486: warning: trailing space in the line
an.tmac:<stdin>:537: style: use of deprecated macro: .PD
an.tmac:<stdin>:553: style: use of deprecated macro: .PD
an.tmac:<stdin>:644: style: use of deprecated macro: .PD
an.tmac:<stdin>:648: style: use of deprecated macro: .PD
an.tmac:<stdin>:650: style: use of deprecated macro: .PD
an.tmac:<stdin>:659: style: use of deprecated macro: .PD
* 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.20-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)
readline-common depends on no packages.
readline-common recommends no packages.
Versions of packages readline-common suggests:
pn readline-doc <none>
-- no debconf information
Input file is history.3readline
Output from "mandoc -T lint history.3readline": (shortened list)
1 input text line longer than 80 bytes: If \fIfilename\fP is...
2 input text line longer than 80 bytes: The GNU History Libr...
2 skipping paragraph macro: PP empty
5 whitespace at end of input line
Find trailing space with:
grep -n -e ' $' -e ' \\f.$' -e ' \\"' <man page>
-.-.
Output from
test-nroff -mandoc -t -ww -z history.3readline: (shortened list)
1 Use macro '.B' for one argument or split argument.
1 .BR is for at least 2 arguments, got 1
4 line(s) with a trailing space
Find trailing space with:
grep -n -e ' $' -e ' \\f.$' -e ' \\"' <man page>
-.-.
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
5
-.-.
Change '-' (\-) to '\(en' (en-dash) for a (numeric) range.
GNU gnulib has recently (2023-06-18) updated its
"build_aux/update-copyright" to recognize "\(en" in man pages.
history.3readline:43:.if t The GNU History Library is Copyright \(co 1989-2020
by the Free Software Foundation, Inc.
history.3readline:44:.if n The GNU History Library is Copyright (C) 1989-2020
by the Free Software Foundation, Inc.
-.-.
Change - to \- if it shall be printed as a minus sign.
history.3readline:547:-1
-.-.
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 43, length 95
.if t The GNU History Library is Copyright \(co 1989-2020 by the Free Software
Foundation, Inc.
Line 44, length 94
.if n The GNU History Library is Copyright (C) 1989-2020 by the Free Software
Foundation, Inc.
Line 384, length 90
.Fn3 "HIST_ENTRY *" replace_history_entry "int which" "const char *line"
"histdata_t data"
Line 514, length 81
If \fIfilename\fP is \fBNULL\fP, then write the history list to
\fI~/.history\fP.
Longest line is number 43 with 95 characters
-.-.
Split a punctuation mark from a single argument for a two-font macro
54:.BR bash.
-.-.
Remove unnecessary double font change (e.g., \fR\fI) in a row or (better)
use a two-fonts macro.
111:.B !?\fIstring\fR\fB[?]\fR
252:.B !?\fIstring\fR\fB[?]\fR
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
history.3readline:265:used in conjunction with `\fB:s\fP' (e.g.,
`\fB:gs/\fIold\fP/\fInew\fP/\fR')
history.3readline:365:field (if any) is set to \fBNULL\fP.
history.3readline:399:maximum number of history entries (as set by
\fBstifle_history()\fP).
history.3readline:599:not have a value (the default), timestamps will not be
written.
-.-.
Put a subordinate sentence (after a comma) on a new line.
[List of affected lines removed.]
-.-.
Space character after a macro call.
644:.PD 0
-.-.
Section headings (.SH and .SS) do not need quoting their arguments.
51:.SH "HISTORY EXPANSION"
276:.SH "PROGRAMMING WITH HISTORY FUNCTIONS"
341:.SH "History Functions"
649:.SH "SEE ALSO"
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
troff:<stdin>:49: warning: trailing space in the line
an.tmac:<stdin>:54: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
troff:<stdin>:74: warning: trailing space in the line
an.tmac:<stdin>:87: style: use of deprecated macro: .PD
an.tmac:<stdin>:133: style: use of deprecated macro: .PD
an.tmac:<stdin>:150: style: use of deprecated macro: .PD
an.tmac:<stdin>:186: style: use of deprecated macro: .PD
an.tmac:<stdin>:195: style: use of deprecated macro: .PD
an.tmac:<stdin>:275: style: use of deprecated macro: .PD
troff:<stdin>:485: warning: trailing space in the line
troff:<stdin>:486: warning: trailing space in the line
an.tmac:<stdin>:537: style: use of deprecated macro: .PD
an.tmac:<stdin>:553: style: use of deprecated macro: .PD
an.tmac:<stdin>:644: style: use of deprecated macro: .PD
an.tmac:<stdin>:648: style: use of deprecated macro: .PD
an.tmac:<stdin>:650: style: use of deprecated macro: .PD
an.tmac:<stdin>:659: style: use of deprecated macro: .PD
-.-.
Additionally:
" -1" changed to " \-1"
-.-
Two mail addresses for bug reports are shown:
[email protected]
[email protected]
-.-
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
--- history.3readline 2025-04-04 11:59:29.961503033 +0000
+++ history.3readline.new 2025-04-04 17:08:31.045049717 +0000
@@ -40,18 +40,18 @@
.SH NAME
history \- GNU History Library
.SH COPYRIGHT
-.if t The GNU History Library is Copyright \(co 1989-2020 by the Free Software
Foundation, Inc.
-.if n The GNU History Library is Copyright (C) 1989-2020 by the Free Software
Foundation, Inc.
+.if t The GNU History Library is Copyright \(co 1989\(en2020 by the Free
Software Foundation, Inc.
+.if n The GNU History Library is Copyright (C) 1989\(en2020 by the Free
Software Foundation, Inc.
.SH DESCRIPTION
Many programs read input from the user a line at a time. The GNU
History library is able to keep track of those lines, associate arbitrary
data with each line, and utilize information from previous lines in
-composing new ones.
+composing new ones.
.PP
-.SH "HISTORY EXPANSION"
+.SH HISTORY EXPANSION
The history library supports a history expansion feature that
is identical to the history expansion in
-.BR bash.
+.BR bash .
This section describes what syntax features are available.
.PP
History expansions introduce words from the history list into
@@ -71,7 +71,7 @@ and the portions of that line that are a
Various \fImodifiers\fP are available to manipulate the selected words.
The line is broken into words in the same fashion as \fBbash\fP
does when reading input,
-so that several words that would otherwise be separated
+so that several words that would otherwise be separated
are considered one word when surrounded by quotes (see the
description of \fBhistory_tokenize()\fP below).
History expansions are introduced by the appearance of the
@@ -273,7 +273,7 @@ An \fBa\fP may be used as a synonym for
Apply the following `\fBs\fP' or `\fB&\fP' modifier once to each word
in the event line.
.PD
-.SH "PROGRAMMING WITH HISTORY FUNCTIONS"
+.SH PROGRAMMING WITH HISTORY FUNCTIONS
This section describes how to use the History library in other programs.
.SS Introduction to History
A programmer using the History library has available functions
@@ -338,7 +338,7 @@ typedef struct _hist_state {
.PP
If the flags member includes \fBHS_STIFLED\fP, the history has been
stifled.
-.SH "History Functions"
+.SH History Functions
This section describes the calling sequence for the various functions
exported by the GNU History library.
.SS Initializing History and State Management
@@ -473,7 +473,7 @@ previous entries, otherwise through subs
If \fIstring\fP is found, then
the current history index is set to that history entry, and the value
returned is the offset in the line of the entry where
-\fIstring\fP was found. Otherwise, nothing is changed, and a -1 is
+\fIstring\fP was found. Otherwise, nothing is changed, and a \-1 is
returned.
.Fn2 int history_search_prefix "const char *string" "int direction"
@@ -482,14 +482,14 @@ offset. The search is anchored: matchin
\fIstring\fP. If \fIdirection\fP is less than 0, then the search is
through previous entries, otherwise through subsequent entries.
If \fIstring\fP is found, then the
-current history index is set to that entry, and the return value is 0.
-Otherwise, nothing is changed, and a -1 is returned.
+current history index is set to that entry, and the return value is 0.
+Otherwise, nothing is changed, and a \-1 is returned.
.Fn3 int history_search_pos "const char *string" "int direction" "int pos"
Search for \fIstring\fP in the history list, starting at \fIpos\fP, an
absolute index into the list. If \fIdirection\fP is negative, the search
proceeds backward from \fIpos\fP, otherwise forward. Returns the absolute
-index of the history element where \fIstring\fP was found, or -1 otherwise.
+index of the history element where \fIstring\fP was found, or \-1 otherwise.
.SS Managing the History File
The History library can read the history from and write it to a file.
@@ -544,7 +544,7 @@ character);
1
if expansions did take place;
.TP
--1
+\-1
if there was an error in expansion;
.TP
2
@@ -641,12 +641,12 @@ It is intended for use by applications l
expansion character for additional purposes.
By default, this variable is set to \fBNULL\fP.
.SH FILES
-.PD 0
+.PD 0
.TP
.FN ~/.history
Default filename for reading and writing saved history
.PD
-.SH "SEE ALSO"
+.SH SEE ALSO
.PD 0
.TP
\fIThe Gnu Readline Library\fP, Brian Fox and Chet Ramey
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>
To find trailing space use
grep -n -e ' $' -e ' \\f.$' -e ' \\"' <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)
-.-
