Package: gv
Version: 1:3.7.4-3.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 ' $' -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>:38: warning: trailing space in the 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.17-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 gv depends on:
ii ghostscript 10.04.0~dfsg-2+b1
ii libc6 2.41-4
ii libx11-6 2:1.8.10-2
ii libxinerama1 2:1.1.4-3+b3
ii libxmu6 2:1.1.3-3+b4
ii libxt6t64 1:1.2.1-1.2+b2
ii xaw3dg 1.5+F-2+b1
gv recommends no packages.
gv suggests no packages.
-- no debconf information
Input file is gv-update-userconfig.1
Output from "mandoc -T lint gv-update-userconfig.1": (shortened list)
1 input text line longer than 80 bytes: by using the optiona...
1 input text line longer than 80 bytes: recommended for usin...
1 input text line longer than 80 bytes: removes all resource...
1 whitespace at end of input line
Remove trailing space with: sed -e 's/ *$//'
-.-.
Output from "test-nroff -mandoc -t -ww -z gv-update-userconfig.1": (shortened
list)
1 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
1
-.-.
Add a "\&" (or a comma (Oxford comma)) after "e.g." and "i.e.",
or use English words
(man-pages(7)).
Abbreviation points should be marked as such and protected against being
interpreted as an end of sentence, if they are not, and that independent
of the current place on the line.
20:the current version of GNU gv (i.e. the one the version of this program
-.-.
Wrong distance (not two spaces) 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.
Lines with only one (or two) space(s) between sentences could be split,
so latter sentences begin on a new line.
Use
#!/usr/bin/sh
sed -e '/^\./n' \
-e 's/\([[:alpha:]]\)\. */\1.\n/g' $1
to split lines after a sentence period.
Check result with the difference between the formatted outputs.
See also the attachment "general.bugs"
17:by using the optional filename argument. This is useful if the environment
variable XUSERSEARCHPATH is used.
20:the current version of GNU gv (i.e. the one the version of this program
32:switches to alternative navigation by adding resp. updating navigation
resources
33:to \fI~\fP\fB/.gv\fP, i. e. after each page switch (except if selected by the
34:page number) the page is scrolled to top (if switching forward) resp. to the
38:switches to standard navigation by adding resp. updating navigation
resources
46:updates translation file. Using the optional filename parameter is strongly
47:recommended for using this option. This option cannot be used together with
any of
68:This manpage is Copyright \(co 2008 Bernhard R. Link
71:This is free software; see the source for copying conditions. There is NO
-.-.
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 17, length 108
by using the optional filename argument. This is useful if the environment
variable XUSERSEARCHPATH is used.
Line 29, length 127
removes all resources from \fI~\fP\fB/.gv\fP that equal the default resources
being shipped with GNU gv (ignoring whitespaces).
Line 47, length 82
recommended for using this option. This option cannot be used together with any
of
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
gv-update-userconfig.1:29:removes all resources from \fI~\fP\fB/.gv\fP that
equal the default resources being shipped with GNU gv (ignoring whitespaces).
gv-update-userconfig.1:34:page number) the page is scrolled to top (if
switching forward) resp. to the
gv-update-userconfig.1:35:bottom (if switching backward).
gv-update-userconfig.1:56:resource value (loaded from
\fI$(HOME)\fP\fB/.Xresources\fP at login time
gv-update-userconfig.1:60:This GNU gv will notice old (or missing) version
information in this
-.-.
Only one space character after a possible end of sentence
(after a punctuation, that can end a sentence).
gv-update-userconfig.1:17:by using the optional filename argument. This is
useful if the environment variable XUSERSEARCHPATH is used.
gv-update-userconfig.1:20:the current version of GNU gv (i.e. the one the
version of this program
gv-update-userconfig.1:32:switches to alternative navigation by adding resp.
updating navigation resources
gv-update-userconfig.1:33:to \fI~\fP\fB/.gv\fP, i. e. after each page switch
(except if selected by the
gv-update-userconfig.1:34:page number) the page is scrolled to top (if
switching forward) resp. to the
gv-update-userconfig.1:38:switches to standard navigation by adding resp.
updating navigation resources
gv-update-userconfig.1:46:updates translation file. Using the optional filename
parameter is strongly
gv-update-userconfig.1:47:recommended for using this option. This option cannot
be used together with any of
gv-update-userconfig.1:68:This manpage is Copyright \(co 2008 Bernhard R. Link
gv-update-userconfig.1:71:This is free software; see the source for copying
conditions. There is NO
-.-.
Put a subordinate sentence (after a comma) on a new line.
gv-update-userconfig.1:25:\fB\-h\fR, \fB\-\-help\fR, \fB\-\-usage\fR
gv-update-userconfig.1:33:to \fI~\fP\fB/.gv\fP, i. e. after each page switch
(except if selected by the
gv-update-userconfig.1:55:The values in there are used, if there is no
display-specific
gv-update-userconfig.1:69:and can be used, copied, distributed and/or modified
without restrictions.
-.-.
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.
gv-update-userconfig.1:1:.TH GV 1 "2008-07-31" "gv" "User Commands"
-.-.
Section headings (.SH and .SS) do not need quoting their arguments.
63:.SH "SEE ALSO"
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
troff:<stdin>:38: warning: trailing space in the line
-.-.
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
--- gv-update-userconfig.1 2025-03-14 15:03:06.849207806 +0000
+++ gv-update-userconfig.1.new 2025-03-14 16:58:49.490149814 +0000
@@ -1,4 +1,4 @@
-.TH GV 1 "2008-07-31" "gv" "User Commands"
+.TH GV 1 2008-07-31 gv "User Commands"
.SH NAME
gv\-update\-userconfig \- update ~/.gv config file
.SH SYNOPSIS
@@ -14,11 +14,13 @@ to the current version of
You can specify a file which is used instead of
.B .gv
-by using the optional filename argument. This is useful if the environment
variable XUSERSEARCHPATH is used.
+by using the optional filename argument.
+This is useful if the environment variable XUSERSEARCHPATH is used.
This is done by removing all entries known to cause problems with
-the current version of GNU gv (i.e. the one the version of this program
-belongs to) and updating the version information in that file.
+the current version of GNU gv
+(i.e.\& the one the version of this program belongs to)
+and updating the version information in that file.
This resets all problematic items back to the default values.
.TP
@@ -26,16 +28,22 @@ This resets all problematic items back t
displays a short help message
.TP
\fB\-r\fR
-removes all resources from \fI~\fP\fB/.gv\fP that equal the default resources
being shipped with GNU gv (ignoring whitespaces).
+removes all resources from \fI~\fP\fB/.gv\fP
+that equal the default resources being shipped with GNU gv
+(ignoring whitespaces).
.TP
\fB\-n\fR
-switches to alternative navigation by adding resp. updating navigation
resources
-to \fI~\fP\fB/.gv\fP, i. e. after each page switch (except if selected by the
-page number) the page is scrolled to top (if switching forward) resp. to the
-bottom (if switching backward).
+switches to alternative navigation by adding resp.\& updating navigation
+resources to \fI~\fP\fB/.gv\fP,
+i.\& e.\& after each page switch
+(except if selected by the page number)
+the page is scrolled to top
+(if switching forward)
+resp.\& to the bottom
+(if switching backward).
.TP
\fB\-N\fR
-switches to standard navigation by adding resp. updating navigation resources
+switches to standard navigation by adding resp.\& updating navigation resources
to \fI~\fP\fB/.gv\fP.
.TP
\fB\-s\fR
@@ -43,30 +51,40 @@ removes navigation resources from \fI~\f
standard navigation.
.TP
\fB\-i\fR
-updates translation file. Using the optional filename parameter is strongly
-recommended for using this option. This option cannot be used together with
any of
-the other options.
+updates translation file.
+Using the optional filename parameter is strongly recommended for using this
+option.
+This option cannot be used together with any of the other options.
.SH BACKGROUND
The \fI$(HOME)\fP\fB/.gv\fP file is written by GNU gv when activating the
\fBSave\fP button in one of the configuration dialogs.
-The values in there are used, if there is no display-specific
-resource value (loaded from \fI$(HOME)\fP\fB/.Xresources\fP at login time
+The values in there are used,
+if there is no display-specific resource value
+(loaded from \fI$(HOME)\fP\fB/.Xresources\fP at login time
or manually \fBxrdb\fP(1)).
Sometimes older values miss things needed by the new GNU gv to work properly.
-This GNU gv will notice old (or missing) version information in this
-file and refuse to start until fixed.
+This GNU gv will notice old
+(or missing)
+version information in this file
+and refuse to start until fixed.
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR gv (1),
.BR xrdb (1).
.SH COPYRIGHT
-This manpage is Copyright \(co 2008 Bernhard R. Link
-and can be used, copied, distributed and/or modified without restrictions.
+This manpage is Copyright \(co 2008 Bernhard R.\& Link
+and can be used,
+copied,
+distributed
+and/or modified without restrictions.
.br
-This is free software; see the source for copying conditions. There is NO
-warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+This is free software;
+see the source for copying conditions.
+There is NO warranty;
+not even for MERCHANTABILITY
+or FITNESS FOR A PARTICULAR PURPOSE.
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)
-.-
