Package: menu
Version: 2.1.24
Severity: normal
There are a number of editorial errors (typos, grammar errors, and
punctuation errors) in the documentation.
The update-menus(1) manual page says:
* "update-menus will be ran automatically"
That should be "... will be run ..."
* "... when Debian packages ... are installed or removed from the
system"
That should be: " ... installed on or removed from ..."
* "(but this can be overruled by the system administrator/user, see
below)
That comma should actually be a semicolon. (The clauses before
an after the colon are independent clauses (they could have been
separate sentences), so they need to be separated with a semicolon
instead of a comma.)
* "... update-menus execute the menu entry file, and use its stdout"
That "execute" should be "executes" (and "use" should be "uses").
* "... to the list of directory to search..."
That should be "... list of directories ..."
* "In these directory ..."
That should be "these directories ..."
* "files. (if a file ... any more)."
That should be:
"files. (If ... .)"
or
"files (if ... )."
* "... generated system."$wm"rc files ..."
The would be clearer as:
"... system.${wm}rc ..."
The menufile(5) manual page says:
* '... you can list several "menu entries", that specify ...'
That should be
'... "menu entries" that specify ...'
or
'... "menu entries," which specify ...'
* "Each menu entry specifies what package it depends on ..."
That whould be "... which package ..."
* "Each menu entry specifies what package it depends on, if that package
is not installed, the menu entry will be ignored by update-menus(1)."
The first comma should be a semicolon.
* Similar: 'In a menu entry you can specify pseudo-packages that start
with "local.", update-menus will always use those menu entries).'
That comma should also be a semicolon.
* "?package(package-name):var1=value var2=varlue2 ..."
* "needs= What type of display will the program run on?"
That would be better as:
"needs= What type of display the program will run on."
(because other items (section, icon, etc.) are not described
with questions).
(Actually, it would probably be better to say "What type of display
the program needs" (or "... runs on").
(Also, although this isn't an editorial error: The FORMAT section
doesn't seem to document that quotes are allowed (or when they are
required).
Also, that section doesn't document the "hotkey=" option that is
mentioned in the NOTES section.))
* '(icon="none" is also possible, preferably just leave it out)'
The comma should be a semicolon (and there should be a period
right after the word "out").
* "... the X11 one will be used, otherwise the text one will be
used..."
That comma should be a semicolon.
* "... A comma-separated list of hints on how grouping menu
entries, see manual."
That comma should also be a semicolon (and "see manual" would
probably be better as "see the manual").
The install-menu(1) manual page says:
* "menu-information" (several times)
That should be "menu information".
* "menuentries" should be "menu entries".
/usr/share/doc/menu/html/ch2.html says:
* "Basically, you as user don't need to know ...":
That should be "user as a user don't ..." (or "users don't ...").
* "startupfiles" should be "startup files"
* "Update-menus then reads in all menu files in /etc/menu/ /usr/lib/menu
and /usr/share/menu/default, ..."
There should be a comma after "/etc/menu" (between it and
"/usr/lib/menu").
/usr/share/doc/menu/html/ch3.html says:
* "Packages provided menu files should be in /usr/lib/menu/."
That should be "Package-provided ..."
* "The format is"
That should be:
"The format is:"
* "An entry must be terminated by a newline, however you can use \ to
escape a newline."
That comma should be a semicolon. Also, that backslash should be
quoted (although, actually, it would be better to write out the word
"backslash").
* "... meta-character ... be escaped ..."
That should be "... meta-characters ..."
* "You can include several entries in the same files."
I think you mean "... in the same file."
* "The file must be encoded in ASCII 7bit."
That should be "in 7-bit ASCII."
* "... that do not support 8bit."
That should be "8-bit" something, probably "8-bit encodings."
* "... not depended by the package ..."
That should be "... not depended on by the package ..."
* "Users can use pseudo packages names starting by local. which are assumed
to be always installed.
In the above:
- "packages names" should be "package names"
- "pseudo package..." should probably be "pseudo-package..."
- "starting by" should be "starting with"
- the string "local." must be quoted so the period (full stop) doesn't
seem to end the sentence
* "menuentry" should be "menu entry"
* "Two entries must not have the same title."
(This is not an editorial error.) Doesn't that contradict other
documentation that says that two entries can use the same title
if one is meant to replace the other depending on the environment
(e.g., just text vs. full X11)?
* "vc: if it runs under the linux console but not under a virtual terminal."
The term "virtual terminal" should probably be "terminal emulator"
("virtual terminal" sounds too much like "virtual console" and might
confuse readers).
Also, "the linux console" should probably be "a linux console"
(and "linux" should be "Linux" (and "Linux console" possibly should
be "Linux virtual console")).
* "A menu manager can use a special needs named after the package for
menu entries that must only be displayed in this menu manager."
The wording is confusing. Consider:
- saying "a special needs variable" instead of "a special needs"
- saying "in that menu manager" instead of "in this menu manager"
- saying "naming the package" instead of "named after the package"
(e.g.:
A menu manager can use a special needs variable naming the package
for menu entries that must only be displayed in that menu manager.
* "A program like gnumeric which can be run on X11 as well as on a text
terminal should not have an extra entry with needs=X11 because it will
then be next to impossible to configure the window managers to spawn
rxvt instead of the default xterm."
Something doesn't seem to be explained enough here. The issue of
spawning rxvt instead of xterm seems to come up "out of the blue."
* "Though you must remember, that two entries are never allowed to have
the same title."
That's not a complete sentence. Either change "Though" to "However,"
or join it to the previous sentence (change the preceding period to
a comma).
* "The section field hold a / separated list ..."
At least hyphenate that (a "/-separated" list). However, it really
should be "a slash-separated list ..."
* "If it disagree with the structure ..."
That should be "... it disagrees ..."
* This is done by using section="/".
Ah--finally! Exactly the bit of information I was looking for (the
reason I'm reading the menu documentation so closely). (Thanks for
documenting it.) :-)
* "Please, make sure the icons you specify are always available on the
system."
- The comma after "please" probably shouldn't be there.
* "Please, make sure ... So, if you want ..."
The "so" and comma shouldn't be there.
* "to prevent the distribution ... to turn ..."
That should be "to prevent the distribution ... from turning
..."
* "put both vi and emacs in it. (of course, only if you have
hint_optimize=true in your /etc/menu-methods/menu.h file).
That should be:
... (Of course ... file.)
* "However, this allows to specify ..."
That should be
However, this allows specifying ..."
or
However, this allows one to specify ..."
/usr/share/doc/menu/html/ch5.html says:
* "... (i.e. a program ..."
That should be "... (i.e., a program ..."
* 'Please only consider using "depends" if you feel providing reasonable
defaults for systems without menu will make life very difficult for
you.'
That should be "... without menus ..."
/usr/share/doc/menu/html/ch6.html says:
* "his/her" and "he/she"
Using "his or her" and "he or she" is probably less visually disruptive
(there's no punctuation character in the middle ) and easier to read.
* "Including others files"
That should be "... other ..."
(Also, that section should probably be moved to chapter 3, since
the "!include" construct is part of the syntax of menu files, the
rest of which is documented in chapter 3.)
/usr/share/doc/menu/html/ch7.html says:
* "menu-entry-files" should be "menu-entry files"
* "... all menu files in /etc/menu/ /usr/lib/menu
and /usr/share/menu/default, ..."
There should be a comma after "/etc/menu" (between it and
"/usr/lib/menu").
* "works on file bases for old syntax menu entry files"
Did you mean "works on _a_ file _basis_ ..."?
* 'The menu entries of all "installed" packages are added together...'
Assuming you mean the normal meaning of "installed," it should not
be quoted.
* "If update-menus is ran by a user ..."
That should be "is run ...:
Also, "user" should probably be "non-root user" or something like
"regular user" (since root is still a user). (Other occurrences
of "user" in the document probably should also be changed.)
* "... first try to run the scripts in ~/.menu-methods, and only if that
directory doesn't exist, it will run the scripts in /etc/menu-methods)."
(Is that accurate? Is it really true that if directory
~/.menu-method exists, update-menus will avoid running _all_ scripts in
/etc/menu-methods?
Or do you mean that if a file X exists in ~/.menu-methods, then
update-menus will avoid running any script /etc/menu-methods/X, but
may still execute other scripts in /etc/menu-methods?
* "Some window managers don't support an `include' like statement in their
system.*rc files (like m4 or cpp preprocessing), they cannot read the
menudefs.hook file generated by install-menu from their system.*rc config
file.
"an `include' like statement" should probably be" an `include'-like
statement".
The comma should be a semicolon.
* "... copy it's contents ..."
That "it's" should be "its" (yes, English is screwy).
* "... replacing every occurrence ... by the contents ..."
The "replacing ... by ..." should be "replacing ... with ..."
* "If you are wringing a menu method ..."
I think you meant "... writing ..."
* "... to debug it somewhat easier ..."
That should be "... to debug it somewhat more easily ..."
* "The menu-methods ... explaining install-menu how to ..."
That needs to be "... explaining to install-menu how to ..."
(or, better, "... telling install-menu how to ...").
* "by semi-comma character ..."
That should be "by a semicolon character ..."
* "This is an user-supplied function ..."
That should be "... a user-supplied ..." (because of how the "u"
in "user" is pronounced in English).
* "... in a X terminal emulator ..."
That should be "... an X terminal emulator ..." (because of how
"x" as a letter is pronounced (like "eks"--starting with a vowel
sound).
* "You can continue lines on the next line with a \, but do make sure you
don't add any spaces after the \."
It would be better to write out "backslash" (or 'backslash ("\")').
* "... pops up another menu entry."
Should "menu entry" really be "menu"?
* "(Substitution works just like in the supported stuff, see above)."
The comma should be a semicolon.
* "the prefix, every $section variable gets."
That doesn't make any sense. Oh--remove the comma.
* "prerun ... postrun ... The commands to run before resp. after ..."
That should probably be:
prerun ... postrun ... The commands to run before and after,
respectively, ..."
* "the new assignments to treewalk, genmenu, etc to generate"
The "etc" needs a period (full stop).
* "Note: NOT just like prerun etc: prerun etc start a command with
/bin/sh, also_run doesn't exec any other command, just tells
install-menu to also load another binary, and generate the output."
That needs a lot of editing.
* "If set to true, menu will try ..."
Instead of "menu," did you mean "update-menus"? Or maybe
"install-menu"? (Note that there are many other references to "menu"
too.)
* "a way to speedup things" should be "a way to speed things up"
(The noun form is one word (e.g., "the speedup factor"); the verb form is
two words ("to speed things up," "to speed up the process").)
* ".. to the optimization routine, that will calculate ... "
That should be "... routine, which will ..."
* "toplevel" should be "top-level"
/usr/share/doc/menu/html/ch8.html says:
* "Stuff like \n, \t, ... will be substituted for their C expansions ..."
Actually, it is their expansions that will be substituted for
\n, etc. (The quoted statement uses "substitute for" backwards.)
You probably meant:
Stuff like \n, \t, ... will be replaced with ...
* ... their C expansions (But not \0xx, currently).
"expansions (But ...)" should be "expansions (but ...)"
* "(this way you can specify icons of sub-menus)."
That should be:
(This way you can specify icons of sub-menus.)
* "..., ie those that ... " should be "..., i.e., those that ... "
* "Anything matching [a-z,A-Z,_] is taken as a function."
Why is comma (",") in there twice? Actually, it shouldn't be in
there are at, should it?
Also, that matches only a single character. Don't you mean
"[a-z,A-Z,_]+"?
Additionally, none of the functions (or function calls) you
list next match that regular expression. Did you mean that
anything matching "[a-z,A-Z,_]+" is taken as a function name?
I hope that's helpful.
-- System Information:
Debian Release: 3.1
Architecture: i386 (i686)
Kernel: Linux 2.6.8-2-k7-smp
Locale: LANG=C, LC_CTYPE=C (charmap=ANSI_X3.4-1968)
Versions of packages menu depends on:
ii dpkg 1.10.28 Package maintenance system for Deb
ii libc6 2.3.2.ds1-22 GNU C Library: Shared libraries an
ii libgcc1 1:3.4.3-13 GCC support library
ii libstdc++5 1:3.3.5-13 The GNU Standard C++ Library v3
-- no debconf information
--
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
