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 ' $' -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>:22: warning: trailing space in the line
an.tmac:<stdin>:43: style: 1 leading space(s) on input line
an.tmac:<stdin>:45: style: 1 leading space(s) on input line
an.tmac:<stdin>:52: style: 1 leading space(s) on input line
an.tmac:<stdin>:54: style: 1 leading space(s) on input line
an.tmac:<stdin>:129: style: 1 leading space(s) on input line
an.tmac:<stdin>:130: style: 3 leading space(s) on input line
an.tmac:<stdin>:131: style: 3 leading space(s) on input line
an.tmac:<stdin>:132: style: 3 leading space(s) on input line
an.tmac:<stdin>:133: style: 3 leading space(s) on input line
an.tmac:<stdin>:134: style: 3 leading space(s) on input line
an.tmac:<stdin>:135: style: 3 leading space(s) on input line
an.tmac:<stdin>:136: style: 3 leading space(s) on input line
an.tmac:<stdin>:137: style: 3 leading space(s) on input line
an.tmac:<stdin>:138: style: 3 leading space(s) on input line
an.tmac:<stdin>:139: style: 3 leading space(s) on input line
an.tmac:<stdin>:140: style: 5 leading space(s) on input line
an.tmac:<stdin>:141: style: 5 leading space(s) on input line
an.tmac:<stdin>:142: style: 5 leading space(s) on input line
an.tmac:<stdin>:143: style: 5 leading space(s) on input line
an.tmac:<stdin>:144: style: 5 leading space(s) on input line
an.tmac:<stdin>:145: style: 3 leading space(s) on input line
an.tmac:<stdin>:146: style: 3 leading space(s) on input line
an.tmac:<stdin>:147: style: 3 leading space(s) on input line
an.tmac:<stdin>:148: style: 3 leading space(s) on input line
an.tmac:<stdin>:149: style: 5 leading space(s) on input line
an.tmac:<stdin>:150: style: 5 leading space(s) on input line
an.tmac:<stdin>:151: style: 5 leading space(s) on input line
an.tmac:<stdin>:152: style: 5 leading space(s) on input line
an.tmac:<stdin>:153: style: 5 leading space(s) on input line
an.tmac:<stdin>:154: style: 5 leading space(s) on input line
an.tmac:<stdin>:155: style: 5 leading space(s) on input line
an.tmac:<stdin>:156: style: 5 leading space(s) on input line
an.tmac:<stdin>:157: style: 5 leading space(s) on input line
an.tmac:<stdin>:158: style: 5 leading space(s) on input line
an.tmac:<stdin>:159: style: 5 leading space(s) on input line
an.tmac:<stdin>:160: style: 3 leading space(s) on input line
an.tmac:<stdin>:161: style: 3 leading space(s) on input line
an.tmac:<stdin>:162: style: 3 leading space(s) on input line
an.tmac:<stdin>:163: style: 5 leading space(s) on input line
an.tmac:<stdin>:164: style: 5 leading space(s) on input line
an.tmac:<stdin>:165: style: 5 leading space(s) on input line
an.tmac:<stdin>:166: style: 5 leading space(s) on input line
an.tmac:<stdin>:167: style: 5 leading space(s) on input line
an.tmac:<stdin>:168: style: 5 leading space(s) on input line
an.tmac:<stdin>:169: style: 3 leading space(s) on input line
an.tmac:<stdin>:170: style: 3 leading space(s) on input line
an.tmac:<stdin>:171: style: 3 leading space(s) on input line
an.tmac:<stdin>:172: style: 3 leading space(s) on input line
an.tmac:<stdin>:173: style: 3 leading space(s) on input line
an.tmac:<stdin>:174: style: 3 leading space(s) on input line
an.tmac:<stdin>:175: style: 1 leading space(s) on input line
an.tmac:<stdin>:176: style: 3 leading space(s) on input line
an.tmac:<stdin>:177: style: 3 leading space(s) on input line
an.tmac:<stdin>:178: style: 3 leading space(s) on input line
an.tmac:<stdin>:179: style: 3 leading space(s) on input line
an.tmac:<stdin>:180: style: 3 leading space(s) on input line
an.tmac:<stdin>:181: style: 3 leading space(s) on input line
an.tmac:<stdin>:182: style: 3 leading space(s) on input line
an.tmac:<stdin>:183: style: 3 leading space(s) on input line
an.tmac:<stdin>:184: style: 3 leading space(s) on input line
an.tmac:<stdin>:185: style: 3 leading space(s) on input line
an.tmac:<stdin>:186: style: 1 leading space(s) on input line
an.tmac:<stdin>:187: style: 1 leading space(s) on input line
an.tmac:<stdin>:188: style: 3 leading space(s) on input line
an.tmac:<stdin>:189: style: 3 leading space(s) on input line
an.tmac:<stdin>:190: style: 1 leading space(s) on input line
an.tmac:<stdin>:191: style: 1 leading space(s) on input line
an.tmac:<stdin>:192: style: 1 leading space(s) on input line
an.tmac:<stdin>:201: 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)
Versions of packages menu depends on:
ii libc6 2.40-6
ii libgcc-s1 14.2.0-16
ii libstdc++6 14.2.0-16
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 menufile.5
Output from "mandoc -T lint menufile.5": (shortened list)
1 empty block: RS
6 whitespace at end of input line
-.-.
Output from "test-groff -mandoc -t -ww -z menufile.5": (shortened list)
1 Use macro '.B' for one argument or split argument.
1 .BR is for at least 2 arguments, got 1
5 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
6
-.-.
Use "\e" to print the escape character instead of "\\" (which gets
interpreted in copy mode).
178:?package(mypackage):needs="X11" section="Applications" \\
-.-.
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.
16:Menu files add entries to the Debian menu system. The system administrator
can
25:contains the programs listed in them. In it, you can list several
27:structure. Each menu entry specifies which packages it depends on; if
55:Specify what kind of environment the program require. This variable must be
76:The section in which the menu entry should appear. See \fBMENU LAYOUT\fP for
82:An icon for this menu entry. If no icon is available, just don't
86:The title of the program that will appear on the menus. Keep it short.
88:best fits the available display will be used. So in the example above
101:Debian Menu sub-policy document which is part of the Debian Policy package.
The
102:menu structure below is included only for convenience. Please do not put
your
209: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 37, length 95
?package(dosemu):needs="text" section="Applications/Emulators" title="Dosemu"
command="dosemu"
Line 38, length 92
?package(dosemu):needs="X11" section="Applications/Emulators" title="Dosemu"
command="xdos"
Line 43, length 98
?package(dosemu):needs="text" section="Applications/Emulators" title="Dosemu"
command="dosemu -A"
Line 44, length 96
?package(dosemu):needs="X11" section="Applications/Emulators" title="Dosemu"
command="xdos -A"
-.-.
The name of a man page is typeset in bold and the section in roman
(see man-pages(7)).
29:\fBupdate-menus(1)\fP.
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
menufile.5:66:Program requires a Linux console (i.e.: svgalib programs)
-.-.
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.
2:.TH MENUFILE 5 "File Formats" "DEBIAN"
-.-.
Space character after a macro call.
36:.PP
-.-.
Section headings (.SH and .SS) do not need quoting.
99:.SH "MENU LAYOUT"
213:.SH "SEE ALSO"
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
troff:<stdin>:21: warning: trailing space in the line
an.tmac:<stdin>:37: style: 1 leading space(s) on input line
an.tmac:<stdin>:38: style: 1 leading space(s) on input line
an.tmac:<stdin>:43: style: 1 leading space(s) on input line
an.tmac:<stdin>:44: style: 1 leading space(s) on input line
troff:<stdin>:83: warning: trailing space in the line
troff:<stdin>:103: warning: trailing space in the line
an.tmac:<stdin>:108: style: 1 leading space(s) on input line
an.tmac:<stdin>:109: style: 3 leading space(s) on input line
an.tmac:<stdin>:110: style: 3 leading space(s) on input line
an.tmac:<stdin>:111: style: 3 leading space(s) on input line
an.tmac:<stdin>:112: style: 3 leading space(s) on input line
an.tmac:<stdin>:113: style: 3 leading space(s) on input line
an.tmac:<stdin>:114: style: 3 leading space(s) on input line
an.tmac:<stdin>:115: style: 3 leading space(s) on input line
an.tmac:<stdin>:116: style: 3 leading space(s) on input line
an.tmac:<stdin>:117: style: 3 leading space(s) on input line
an.tmac:<stdin>:118: style: 3 leading space(s) on input line
an.tmac:<stdin>:119: style: 5 leading space(s) on input line
an.tmac:<stdin>:120: style: 5 leading space(s) on input line
an.tmac:<stdin>:121: style: 5 leading space(s) on input line
an.tmac:<stdin>:122: style: 5 leading space(s) on input line
an.tmac:<stdin>:123: style: 5 leading space(s) on input line
an.tmac:<stdin>:124: style: 3 leading space(s) on input line
an.tmac:<stdin>:125: style: 3 leading space(s) on input line
an.tmac:<stdin>:126: style: 3 leading space(s) on input line
an.tmac:<stdin>:127: style: 3 leading space(s) on input line
an.tmac:<stdin>:128: style: 5 leading space(s) on input line
an.tmac:<stdin>:129: style: 5 leading space(s) on input line
an.tmac:<stdin>:130: style: 5 leading space(s) on input line
an.tmac:<stdin>:131: style: 5 leading space(s) on input line
an.tmac:<stdin>:132: style: 5 leading space(s) on input line
an.tmac:<stdin>:133: style: 5 leading space(s) on input line
an.tmac:<stdin>:134: style: 5 leading space(s) on input line
an.tmac:<stdin>:135: style: 5 leading space(s) on input line
an.tmac:<stdin>:136: style: 5 leading space(s) on input line
an.tmac:<stdin>:137: style: 5 leading space(s) on input line
an.tmac:<stdin>:138: style: 5 leading space(s) on input line
an.tmac:<stdin>:139: style: 3 leading space(s) on input line
an.tmac:<stdin>:140: style: 3 leading space(s) on input line
an.tmac:<stdin>:141: style: 3 leading space(s) on input line
an.tmac:<stdin>:142: style: 5 leading space(s) on input line
an.tmac:<stdin>:143: style: 5 leading space(s) on input line
an.tmac:<stdin>:144: style: 5 leading space(s) on input line
an.tmac:<stdin>:145: style: 5 leading space(s) on input line
an.tmac:<stdin>:146: style: 5 leading space(s) on input line
an.tmac:<stdin>:147: style: 5 leading space(s) on input line
an.tmac:<stdin>:148: style: 3 leading space(s) on input line
an.tmac:<stdin>:149: style: 3 leading space(s) on input line
an.tmac:<stdin>:150: style: 3 leading space(s) on input line
an.tmac:<stdin>:151: style: 3 leading space(s) on input line
an.tmac:<stdin>:152: style: 3 leading space(s) on input line
an.tmac:<stdin>:153: style: 3 leading space(s) on input line
an.tmac:<stdin>:154: style: 1 leading space(s) on input line
an.tmac:<stdin>:155: style: 3 leading space(s) on input line
an.tmac:<stdin>:156: style: 3 leading space(s) on input line
an.tmac:<stdin>:157: style: 3 leading space(s) on input line
an.tmac:<stdin>:158: style: 3 leading space(s) on input line
an.tmac:<stdin>:159: style: 3 leading space(s) on input line
an.tmac:<stdin>:160: style: 3 leading space(s) on input line
an.tmac:<stdin>:161: style: 3 leading space(s) on input line
an.tmac:<stdin>:162: style: 3 leading space(s) on input line
an.tmac:<stdin>:163: style: 3 leading space(s) on input line
an.tmac:<stdin>:164: style: 3 leading space(s) on input line
an.tmac:<stdin>:165: style: 1 leading space(s) on input line
an.tmac:<stdin>:166: style: 1 leading space(s) on input line
an.tmac:<stdin>:167: style: 3 leading space(s) on input line
an.tmac:<stdin>:168: style: 3 leading space(s) on input line
an.tmac:<stdin>:169: style: 1 leading space(s) on input line
an.tmac:<stdin>:170: style: 1 leading space(s) on input line
an.tmac:<stdin>:171: style: 1 leading space(s) on input line
an.tmac:<stdin>:179: style: 1 leading space(s) on input line
troff:<stdin>:208: warning: trailing space in the line
troff:<stdin>:209: warning: trailing space in the line
an.tmac:<stdin>:215: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
--- menufile.5 2025-02-13 22:22:20.371323384 +0000
+++ menufile.5.new 2025-02-13 23:02:49.675335061 +0000
@@ -1,5 +1,5 @@
.\" -*- nroff -*-
-.TH MENUFILE 5 "File Formats" "DEBIAN"
+.TH MENUFILE 5 "File Formats" DEBIAN
.SH NAME
menufile \- entry in the Debian menu system
.SH SYNOPSIS
@@ -13,38 +13,53 @@ menufile \- entry in the Debian menu sys
.PP
.B /usr/share/menu/default/*
.SH DESCRIPTION
-Menu files add entries to the Debian menu system. The system administrator can
-place menu files in /etc/menu/ to override menu files that packages add to
-/usr/share/menu/ . The user can place menu files in ~/.menu/ to override all
-other menu files.
+Menu files add entries to the Debian menu system.
+The system administrator can place menu files in /etc/menu/
+to override menu files that packages add to /usr/share/menu/.
+The user can place menu files in ~/.menu/ to override all other menu
+files.
.PP
-Please read the Debian menu manual available in /usr/share/doc/menu/html
+Please read the Debian menu manual available in /usr/share/doc/menu/html
for the complete specification of menu files.
.PP
-The menu files are usually named after the Debian package that
-contains the programs listed in them. In it, you can list several
-"menu entries" that specify a specific item in the menu
-structure. Each menu entry specifies which packages it depends on; if
-that package are not installed, the menu entry will be ignored by
-\fBupdate-menus(1)\fP.
-(In a menu entry you can specify pseudo-packages that start
-with "local."; update-menus will always use those menu entries).
-If you wish to remove an item from the menu entirely, make an empty menu
-file with the same name as the file you want to override.
+The menu files are usually named after the Debian package
+that contains the programs listed in them.
+In it,
+you can list several "menu entries"
+that specify a specific item in the menu structure.
+Each menu entry specifies which packages it depends on;
+if that package are not installed,
+the menu entry will be ignored by
+\fBupdate-menus\fP(1).
+(In a menu entry you can specify pseudo-packages
+that start with "local.";
+update-menus will always use those menu entries).
+If you wish to remove an item from the menu entirely,
+make an empty menu file with the same name
+as the file you want to override.
.SH Examples
Dosemu could install the following menu file as /usr/share/menu/dosemu:
-.PP
- ?package(dosemu):needs="text" section="Applications/Emulators" title="Dosemu"
command="dosemu"
- ?package(dosemu):needs="X11" section="Applications/Emulators" title="Dosemu"
command="xdos"
.PP
-The system administrator wants to override this file to change how dosemu is
-run, so /etc/menu/dosemu is created:
+.nf
+ ?package(dosemu):needs="text" section="Applications/Emulators" \e
+title="Dosemu" command="dosemu"
+ ?package(dosemu):needs="X11" section="Applications/Emulators" \e
+title="Dosemu" command="xdos"
+.fi
+.PP
+The system administrator wants to override this file
+to change how dosemu is run,
+so /etc/menu/dosemu is created:
+.PP
+.nf
+ ?package(dosemu):needs="text" section="Applications/Emulators" \e
+title="Dosemu" command="dosemu -A"
+ ?package(dosemu):needs="X11" section="Applications/Emulators" \e
+title="Dosemu" command="xdos -A"
+.fi
.PP
- ?package(dosemu):needs="text" section="Applications/Emulators" title="Dosemu"
command="dosemu -A"
- ?package(dosemu):needs="X11" section="Applications/Emulators" title="Dosemu"
command="xdos -A"
-.PP
-A user does not want Dosemu to appear in the menus at all, so the user creates
-an empty file named \fI~/.menu/dosemu\fP.
+A user does not want Dosemu to appear in the menus at all,
+so the user creates an empty file named \fI~/.menu/dosemu\fP.
.SH FORMAT
A menu file consists of 0 or more lines of the following format:
.RS
@@ -52,8 +67,9 @@ A menu file consists of 0 or more lines
\fB?package(package-name):var1=value1 var2=value2 \fR ...
.TP
needs
-Specify what kind of environment the program require. This variable must be
-defined, and should be one of the following:
+Specify what kind of environment the program require.
+This variable must be defined,
+and should be one of the following:
.RS
.TP
needs="text"
@@ -63,7 +79,8 @@ needs="x11"
Program requires a X server
.TP
needs="vc"
-Program requires a Linux console (i.e.: svgalib programs)
+Program requires a Linux console
+(i.e.: svgalib programs)
.TP
needs="wm"
The program is a window manager.
@@ -73,37 +90,43 @@ The program is a fvwm compatible module.
.RE
.TP
section
-The section in which the menu entry should appear. See \fBMENU LAYOUT\fP for
-preferred section names.
-.RS
-.RE
+The section in which the menu entry should appear.
+See \fBMENU LAYOUT\fP for preferred section names.
.TP
icon
-An icon for this menu entry. If no icon is available, just don't
-define this.
+An icon for this menu entry.
+If no icon is available,
+just don't define this.
.TP
title
-The title of the program that will appear on the menus. Keep it short.
-If two menu entries share the same title and section, the one that
-best fits the available display will be used. So in the example above
-with two menu entries that both have the menu id "title", if X is
-available, the X11 one will be used; otherwise the text one will be used.
+The title of the program that will appear on the menus.
+Keep it short.
+If two menu entries share the same title and section,
+the one that best fits the available display will be used.
+So in the example above with two menu entries
+that both have the menu id "title",
+if X is available,
+the X11 one will be used;
+otherwise the text one will be used.
Must be defined.
.TP
command
The command to be executed when this menu entry is selected.
.TP
hints
-A comma-separated list of hints on how grouping menu entries; see the manual.
+A comma-separated list of hints on how grouping menu entries;
+see the manual.
.RE
-.SH "MENU LAYOUT"
+.SH MENU LAYOUT
The \fBauthoritative\fP list of Debian's menu structure is maintained in the
-Debian Menu sub-policy document which is part of the Debian Policy package. The
-menu structure below is included only for convenience. Please do not put your
-packages into any other sections.
+Debian Menu sub-policy document which is part of the Debian Policy package.
+The menu structure below is included only for convenience.
+Please do not put your packages into any other sections.
-Use `/' to separate sub-menu names, for example, "Applications/Editors" or
-"Games/Arcade".
+Use `/' to separate sub-menu names,
+for example,
+"Applications/Editors"
+or "Games/Arcade".
.PP
\fIApplications\fP
\fIAccessibility\fP
@@ -171,15 +194,19 @@ Use `/' to separate sub-menu names, for
\fIWindow Maker\fP
.SH NOTES
-If you want to specify an icon or hotkey for a sub-menu (for example,
-the Editors sub-menu), just use the same syntax but leave the command
-empty:
+If you want to specify an icon
+or hotkey for a sub-menu (for example,
+the Editors sub-menu),
+just use the same syntax but leave the command empty:
-?package(mypackage):needs="X11" section="Applications" \\
+.nf
+?package(mypackage):needs="X11" section="Applications" \e
icon="/usr/share/pixmaps/icon.xpm" hotkey="E" title="Editors"
+.fi
.PP
-Whenever any menu files are changed, you must run
+Whenever any menu files are changed,
+you must run
.BR update-menus (1)
.SH FILES
(Earlier listed files override later files with the same names.)
@@ -205,11 +232,13 @@ Architecture-independant menu files prov
Menu files provided by the menu package.
.RE
.SH AUTHORS
-Joost Witteveen <joos...@debian.org>, based on work by
-Lars Wirzenius <l...@iki.fi>. Now maintained by
+Joost Witteveen <joos...@debian.org>,
+based on work by
+Lars Wirzenius <l...@iki.fi>.
+Now maintained by
Bill Allombert <ballo...@debian.org>.
.PP
(Man page by Joey Hess, <jo...@debian.org>)
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR update-menus (1),
-.BR /usr/share/doc/menu/html/index.html
+.B /usr/share/doc/menu/html/index.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 -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)
-.-
