Package: menu
Version: 2.1.50
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?
troff:<stdin>:8: warning: trailing space in the line
troff:<stdin>:9: warning: trailing space in the line
troff:<stdin>:10: warning: trailing space in the line
troff:<stdin>:18: warning: trailing space in the line
troff:<stdin>:23: warning: trailing space in the line
troff:<stdin>:42: warning: trailing space in the line
troff:<stdin>:66: warning: trailing space in the line
an.tmac:<stdin>:67: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
troff:<stdin>:77: warning: trailing space in the line
troff:<stdin>:84: warning: trailing space in the line
troff:<stdin>:87: warning: trailing space in the line
an.tmac:<stdin>:88: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
troff:<stdin>:131: warning: trailing space in the line
troff:<stdin>:167: warning: trailing space in the line
an.tmac:<stdin>:177: 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.9-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 menu depends on:
ii libc6 2.40-5
ii libgcc-s1 14.2.0-12
ii libstdc++6 14.2.0-12
menu recommends no packages.
Versions of packages menu suggests:
pn gksu | kde-cli-tools | ktsuss <none>
pn menu-l10n <none>
-- no debconf information
Input file is update-menus.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
-.-
Output from "mandoc -T lint update-menus.1": (shortened list)
1 input text line longer than 80 bytes: Before the advent of...
1 skipping paragraph macro: PP empty
16 whitespace at end of input line
-.-.
Output from "test-groff -mandoc -t -ww -z update-menus.1": (shortened list)
3 Use macro '.B' for one argument or split argument.
3 .BR is for at least 2 arguments, got 1
12 trailing space in the line
-.-.
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
13
-.-.
Test nr. 8:
Change two HYPHEN-MINUSES (code 0x2D) to an em-dash (\(em),
if one is intended.
" \(em " creates a too big gap in the text (in "troff").
An en-dash is usually surrounded by a space,
while an em-dash is used without spaces.
"man" (1 byte characters in input) transforms an en-dash (\(en) to one
HYPHEN-MINUS,
and an em-dash to two HYPHEN-MINUSES without considering the space
around it.
If "--" are two single "-"
(begin of an option or end of options)
then use "\-\-".
update-menus.1:6:.B update-menus [\-v] [\-d] [\-h|--help] [--version]
[--menufilesdir <dir>] [--menumethod <method>] [--nodefaultdirs] [--stdout]
update-menus.1:39:.IP "-h, --help"
update-menus.1:41:.IP "--menufilesdir <dir>"
update-menus.1:43:.IP "--menumethod <method>"
update-menus.1:45:.IP "--nodefaultdirs"
update-menus.1:47:.IP "--nodpkgcheck"
update-menus.1:50:.IP "--remove"
update-menus.1:51:Remove the menus by calling the menu-methods with
\fB--remove\fP.
update-menus.1:52:.IP "--stdout"
update-menus.1:55:.IP "--version"
-.-.
Use the correct macro for the font change of a single argument or
split the argument into two.
177:.BR /usr/share/doc/menu/html
-.-.
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 "\&".
11:fvwm's menus. The menus could easily become out of sync with what programs
19:managers and other menu programs. It should be run whenever a
29:system administrator/user; see below). If a menu entry file is executable,
36:Verbose output. Shows all arguments to the /etc/menu-methods programs.
38:Debug output. Generates loads of unintelligible output.
64:corresponding /usr/share/menu/$package file isn't read any more). Users
66:~/.menu. See also
72:each individual window manager. For example, one can specify that the
75:run a text-only application like vi). Users who want to override the system
76:wide defaults put their files in ~/.menu-methods. For more info, see
82:menu entries and all window managers. You can specify things like:
84:or `menuentry "gnuplot" should have a title of "GnuTeken"'. Look at the
85:default /etc/menu-methods/translate_menus for an example. Users who want to
89:This should not be used for a full translation of the menu. Use po
95:update-menus. At the moment you can only configure how verbose the
96:output of update-menus is, and where it sends the output. The amount
97:of information is specified by `verbosity=VAL'. Use VAL=quiet to stop
102:`method=stderr', or `method=syslog facility priority'. `Facility' is one
106:authuucp. `priority' is one of emerg, alert, crit, err, warning,
115:Menu files added by the user. (Isn't read if root runs update-menus)
141:to generate menus for the different programs. Also in this directory
159:user. This is usually because the window manager doesn't expect the
161:in /etc/menu-methods). If you see such a thing, and you find a
162:solution, please mail <m...@packages.debian.org>. It should work OK for
167:Lars Wirzenius <l...@iki.fi>. Now maintained by
-.-.
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.
Line 6, length 128
.B update-menus [\-v] [\-d] [\-h|--help] [--version] [--menufilesdir <dir>]
[--menumethod <method>] [--nodefaultdirs] [--stdout]
Line 8, length 84
Before the advent of \fIupdate-menus\fP, when the system administrators
installed a
-.-.
Split a punctuation mark from a single argument for a two-font macro
88:.BR Note:
-.-.
Name of a manual is set in bold, the section in roman.
See man-pages(7).
67:.BR menufile(5)
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
update-menus.1:27:uses the package-supplied menu entry files (in
/usr/share/menu) for
update-menus.1:111:Menu files: (Earlier listed directories override those
listed later.)
update-menus.1:115:Menu files added by the user. (Isn't read if root runs
update-menus)
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
troff:<stdin>:8: warning: trailing space in the line
troff:<stdin>:9: warning: trailing space in the line
troff:<stdin>:10: warning: trailing space in the line
troff:<stdin>:18: warning: trailing space in the line
troff:<stdin>:23: warning: trailing space in the line
troff:<stdin>:42: warning: trailing space in the line
troff:<stdin>:66: warning: trailing space in the line
an.tmac:<stdin>:67: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
troff:<stdin>:77: warning: trailing space in the line
troff:<stdin>:84: warning: trailing space in the line
troff:<stdin>:87: warning: trailing space in the line
an.tmac:<stdin>:88: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
troff:<stdin>:131: warning: trailing space in the line
troff:<stdin>:167: warning: trailing space in the line
an.tmac:<stdin>:177: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
--- update-menus.1 2025-01-20 18:41:00.085980808 +0000
+++ update-menus.1.new 2025-01-20 19:07:47.422242740 +0000
@@ -3,116 +3,151 @@
.SH NAME
update-menus \- generate Debian menu system
.SH SYNOPSIS
-.B update-menus [\-v] [\-d] [\-h|--help] [--version] [--menufilesdir <dir>]
[--menumethod <method>] [--nodefaultdirs] [--stdout]
+.B update-menus [\-v] [\-d] [\-h|\-\-help] [\-\-version] [\-\-menufilesdir \
+<dir>] [\-\-menumethod <method>] [\-\-nodefaultdirs] [\-\-stdout]
.SH DESCRIPTION
-Before the advent of \fIupdate-menus\fP, when the system administrators
installed a
-package onto a Debian system, they would need to edit various window
-manager configuration files to make the new program show up on, for example,
-fvwm's menus. The menus could easily become out of sync with what programs
-were actually available, with some menu items that didn't work, and other
-programs that lacked a menu entry.
+Before the advent of \fIupdate-menus\fP,
+when the system administrators installed a package onto a Debian system,
+they would need to edit various window manager configuration files
+to make the new program show up on,
+for example,
+fvwm's menus.
+The menus could easily become out of sync with what programs
+were actually available,
+with some menu items
+that didn't work,
+and other programs
+that lacked a menu entry.
.I update-menus
and Debian's menu package aim to solve this problem.
.PP
-.I update-menus
-automatically generates menus of installed programs for window
-managers and other menu programs. It should be run whenever a
+.I update-menus
+automatically generates menus of installed programs for window
+managers
+and other menu programs.
+It should be run whenever a
.BR menufile (5)
or menu-method file is changed.
.I update-menus
-will be run automatically when Debian packages that contain menu
-files are installed on or removed from the system.
+will be run automatically
+when Debian packages
+that contain menu files
+are installed on or removed from the system.
.PP
.I update-menus
-uses the package-supplied menu entry files (in /usr/share/menu) for
-its information about the menus (but this can be overruled by the
-system administrator/user; see below). If a menu entry file is executable,
+uses the package-supplied menu entry files
+(in /usr/share/menu)
+for its information about the menus
+(but this can be overruled by the system administrator/user; see below).
+If a menu entry file is executable,
.I update-menus
-executes the menu entry file, and uses its stdout to generate the menu
-database.
+executes the menu entry file,
+and uses its stdout to generate the menu database.
.SH OPTIONS
.IP "-v"
-Verbose output. Shows all arguments to the /etc/menu-methods programs.
+Verbose output.
+Shows all arguments to the /etc/menu-methods programs.
.IP "-d"
Debug output. Generates loads of unintelligible output.
-.IP "-h, --help"
+.IP "\-h, \-\-help"
Display usage help and exit.
-.IP "--menufilesdir <dir>"
-Adds directory <dir> to the list of directories to search for menu files in.
-.IP "--menumethod <method>"
+.IP "\-\-menufilesdir <dir>"
+Adds directory <dir> to the list of directories to search for menu files in.
+.IP "\-\-menumethod <method>"
Process only the menu method <method> instead of all the menu methods found.
-.IP "--nodefaultdirs"
+.IP "\-\-nodefaultdirs"
Disables the search of menu entries in system menu directories.
-.IP "--nodpkgcheck"
+.IP "\-\-nodpkgcheck"
Do not discard menu entries for packages that are not installed according to
\fIdpkg\fP.
-.IP "--remove"
-Remove the menus by calling the menu-methods with \fB--remove\fP.
-.IP "--stdout"
-Output the menu list in a format suitable as input for \fIinstall-menu\fP or a
-menu method file.
-.IP "--version"
+.IP "\-\-remove"
+Remove the menus by calling the menu-methods with \fB\-\-remove\fP.
+.IP "\-\-stdout"
+Output the menu list in a format suitable as input for \fIinstall-menu\fP
+or a menu method file.
+.IP "\-\-version"
Output version information and exit.
.SH CONFIGURATION
There are several ways to tune the operation of update-menus:
.PP
.I per menu entry, in /etc/menu/$package
.RS
-In these directories the system administrator or user can override the default
-menu files (If a file /etc/menu/$package exists, than the
-corresponding /usr/share/menu/$package file isn't read any more). Users
-who want to override the system wide defaults put their files in
-~/.menu. See also
-.BR menufile(5)
+In these directories the system administrator
+or user
+can override the default menu files
+(If a file /etc/menu/$package exists,
+then the corresponding /usr/share/menu/$package file isn't read any more).
+Users
+who want to override the system wide defaults
+put their files in
+~/.menu.
+See also
+.BR menufile (5)
.RE
.I per window-manager in /etc/menu-methods/$wm
.RS
-In these configuration files, one can tune generated system.${wm}rc files for
-each individual window manager. For example, one can specify that the
-wm should ignore any icons that the packages may supply, or set the
-default wrapper for text-only applications (usually, an xterm is started to
-run a text-only application like vi). Users who want to override the system
-wide defaults put their files in ~/.menu-methods. For more info, see
-/usr/share/doc/menu/html.
+In these configuration files,
+one can tune generated system.${wm}rc files for
+each individual window manager.
+For example,
+one can specify that the wm should ignore any icons
+that the packages may supply,
+or set the default wrapper for text-only applications
+(usually, an xterm is started to run a text-only application like vi).
+Users
+who want to override the system wide defaults
+put their files in ~/.menu-methods.
+For more info, see
+/usr/share/doc/menu/html.
.RE
.I globally, in /etc/menu-methods/translate_menus
.RS
This file contains translations that will be performed for all
-menu entries and all window managers. You can specify things like:
+menu entries
+and all window managers.
+You can specify things like:
`All sections that start with "Games" should be mapped to
"Applications/Games"',
-or `menuentry "gnuplot" should have a title of "GnuTeken"'. Look at the
-default /etc/menu-methods/translate_menus for an example. Users who want to
-override the system default translate file, put one in
-~/.menu-methods/translate_menus.
-.BR Note:
-This should not be used for a full translation of the menu. Use po
-files as explained in the source package.
+or `menuentry "gnuplot" should have a title of "GnuTeken"'.
+Look at the default /etc/menu-methods/translate_menus for an example.
+Users who want to override the system default translate file,
+put one in
+~/.menu-methods/translate_menus.
+.BR Note :
+This should not be used for a full translation of the menu.
+Use po files as explained in the source package.
.RE
.I error report configuring, in /etc/menu-methods/menu.config
.RS
This file contains general information for the overall behaviour of
-update-menus. At the moment you can only configure how verbose the
-output of update-menus is, and where it sends the output. The amount
-of information is specified by `verbosity=VAL'. Use VAL=quiet to stop
-update-menu from reporting anything but the most important errors,
+update-menus.
+At the moment you can only configure how verbose the
+output of update-menus is,
+and where it sends the output.
+The amount of information is specified by `verbosity=VAL'.
+Use VAL=quiet to stop update-menu from reporting anything but the most
+important errors,
VAL=normal, VAL=verbose, VAL=debug for progressively more output.
-To specify where the output should go, use `method=stdout',
-`method=stderr', or `method=syslog facility priority'. `Facility' is one
-of auth, authpriv, authcron, authdaemon, authkern, authlocal0, authlocal1,
-authlocal2, authlocal3, authlocal4, authlocal5, authlocal6, authlocal7,
-authlpr, authmail, authnews, authsyslog, authuser,
-authuucp. `priority' is one of emerg, alert, crit, err, warning,
-notice, info, debug.
+To specify where the output should go,
+use `method=stdout',
+`method=stderr',
+or `method=syslog facility priority'.
+`Facility' is one of auth, authpriv, authcron, authdaemon, authkern,
+authlocal0, authlocal1, authlocal2, authlocal3, authlocal4, authlocal5,
+authlocal6, authlocal7, authlpr, authmail, authnews, authsyslog, authuser,
+authuucp.
+`priority' is one of emerg, alert, crit, err, warning, notice, info, debug.
.RE
.SH FILES
-Menu files: (Earlier listed directories override those listed later.)
+Menu files:
+(Earlier listed directories override those listed later.)
.RS
.I ~/.menu/*
.RS
-Menu files added by the user. (Isn't read if root runs update-menus)
+Menu files added by the user.
+(Isn't read if root runs update-menus)
.RE
.I /etc/menu/*
.RS
@@ -128,43 +163,51 @@ Architecture-independant menu files prov
.RE
.I /usr/share/menu/default/*
.RS
-Menu files provided by the menu package.
+Menu files provided by the menu package.
.RE
.RE
Menu methods:
.RS
.I /etc/menu-methods/
.RS
-Executable configuration files that are added by window managers and other menu
-programs, these files are run by
-.I update-menus
-to generate menus for the different programs. Also in this directory
-is the translate_menus file, used for local configuration of the shape of the
-menu trees.
+Executable configuration files
+that are added by window managers
+and other menu programs,
+these files are run by
+.I update-menus
+to generate menus for the different programs.
+Also in this directory is the translate_menus file,
+used for local configuration of the shape of the menu trees.
.RE
.RE
.RS
.I ~/.menu-methods/
.RS
For users to override the system-defaults of /etc/menu-methods.
-If this directory exists, no files in /etc/menu-methods are read
-any more.
+If this directory exists,
+no files in /etc/menu-methods are read any more.
.RE
.RE
.SH DISTRIBUTION
Distribution is subject to the GNU General Public License.
.SH BUGS
.I update-menus
-may not work properly when run by a normal user, to generate menus for that
-user. This is usually because the window manager doesn't expect the
-system.${wm}rc files in the directory (usually ~/.${wm}, configurable
-in /etc/menu-methods). If you see such a thing, and you find a
-solution, please mail <m...@packages.debian.org>. It should work OK for
-fvwm and fvwm2: I usually test the package first as an ordinary user.
-.PP
+may not work properly when run by a normal user,
+to generate menus for that user.
+This is usually
+because the window manager doesn't expect the system.${wm}rc files in the
+directory
+(usually ~/.${wm},
+configurable in /etc/menu-methods).
+If you see such a thing,
+and you find a solution,
+please mail <m...@packages.debian.org>.
+It should work OK for fvwm and fvwm2:
+I usually test the package first as an ordinary user.
.SH AUTHORS
Joost Witteveen <joos...@debian.org>, original idea by
-Lars Wirzenius <l...@iki.fi>. Now maintained by
+Lars Wirzenius <l...@iki.fi>.
+Now maintained by
Bill Allombert <ballo...@debian.org>.
.SH THANKS
To Joey Hess, for a lot of good ideas and pre-release testing, and to
@@ -174,4 +217,4 @@ function, but that's life).
Man page by Joey Hess, <jo...@debian.org>
.SH "SEE ALSO"
.BR menufile (5),
-.BR /usr/share/doc/menu/html
+.B /usr/share/doc/menu/html
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.
Not beginning each input sentence on a new line.
Line length 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 -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 -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)
-.-
