Bug 990906 - invalid NAME section in nmcli(1) man page
invalid NAME section in nmcli(1) man page
Status: CLOSED CURRENTRELEASE
Product: Fedora
Classification: Fedora
Component: NetworkManager (Show other bugs)
rawhide
All Linux
unspecified Severity low
: ---
: ---
Assigned To: Jirka Klimes
Fedora Extras Quality Assurance
: EasyFix
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2013-08-01 03:47 EDT by Michal Hlavinka
Modified: 2016-01-04 01:03 EST (History)
5 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2014-02-11 08:53:23 EST
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Michal Hlavinka 2013-08-01 03:47:37 EDT
Description of problem:
mandb, lexgrog,... understand only ordinary dash. This was enough several years ago, when we had only one type of dash. Now, we have several types of dash(es) different one for different use and it confuses mandb utils.
mandb uses ' - ' as separator in NAME section to create whatis database.
When different type of dash is used, like '–' (which is \(en in groff notation) instead of ordinary '-', it fails.

Version-Release number of selected component (if applicable):
man-db-2.6.3-6.fc19.x86_64

How reproducible:
always

Steps to Reproduce:
a)
$ lexgrog -d /usr/share/man/man1/nmcli.1.gz

ult_src: File /usr/share/man/man1/nmcli.1.gz in mantree /usr/share/man
trying encoding UTF-8 -> UTF-8//IGNORE
record = 'nmcli – command - line tool for controlling NetworkManager'
/usr/share/man/man1/nmcli.1.gz: parse failed

b)
$ mandb
$ whatis nmcli
nmcli (1)            - (unknown subject)


Actual results:
lexgrog: parse failed
whatis: (unknown subject)


Expected results:
lexgrog: no error
whatis: nmcli (1) - command‐line tool for controlling NetworkManager

Additional info:
NAME section from nmcli:

.SH NAME
nmcli \(en command\(hyline tool for controlling NetworkManager
Comment 1 Colin Watson 2013-08-01 05:12:43 EDT
Don't do that.  The "-" is a syntactic separator, not a typographical one.
Comment 2 Michal Hlavinka 2013-08-01 06:09:05 EDT
(In reply to Colin Watson from comment #1)
> The "-" is a syntactic separator, not a typographical one.

just curious, do you have some url for that?

> Don't do that.  

I don't do that. I just had a (different) problem with lexgrog and checked what other packages have problem with whatis.

find /usr/share/man/ -type f | while read f
do
m=${f%%.*};
m=${m##*/} ;
if whatis $m 2>/dev/null | grep -q '(unknown subject)' #whatis does not work
then
  #check if there is a chance that NAME section contains useful information
  zgrep -A1 -E '^.SH[ "]+NAME' $f | grep -v NAME | grep -q -E '[^, ] [^ ].{5,}' && echo "broken: $f"
fi
done


and different dash was one of the culprits
Comment 3 Colin Watson 2013-08-01 06:23:17 EDT
lexgrog(1), which indeed notes that the correct form is "\-" not just "-".  Also I'm the upstream maintainer.

You should file bugs about incorrect separators against the packages that use the incorrect separators.
Comment 4 Peter Schiffer 2013-09-24 10:49:36 EDT
Please fix nmcli(1) (and nm-connection-editor(1) from network-manager-applet package) man pages to have correct NAME section (according to lexgrog(1)):

.SH NAME
foo \- program to do something

Thanks,

peter
Comment 5 Jirka Klimes 2013-10-07 06:12:59 EDT
The '\(en' was changed back to '\-' in upstream master branch, but we forgot to do that in branches for 0.9.8 too. (bug 948450).

Fixed now:
a6def6b8a84c1f4e3dbe700e8b10c82aa9a07816 (nm-0-9-8)
fcf1298c8ab21088b1df7b62a945058a76972331 (nma-0-9-8)

It will propagate to Fedora in the next release.

Note You need to log in before you can comment on or make changes to this bug.