Bug 990906

Summary:	invalid NAME section in nmcli(1) man page
Product:	[Fedora] Fedora	Reporter:	Michal Hlavinka <mhlavink>
Component:	NetworkManager	Assignee:	Jirka Klimes <jklimes>
Status:	CLOSED CURRENTRELEASE	QA Contact:	Fedora Extras Quality Assurance <extras-qa>
Severity:	low	Docs Contact:
Priority:	unspecified
Version:	rawhide	CC:	cjwatson, dcbw, jklimes, pschiffe, rkhan
Target Milestone:	---	Keywords:	EasyFix
Target Release:	---
Hardware:	All
OS:	Linux
Whiteboard:
Fixed In Version:		Doc Type:	Bug Fix
Doc Text:		Story Points:	---
Clone Of:		Environment:
Last Closed:	2014-02-11 13:53:23 UTC	Type:	Bug
Regression:	---	Mount Type:	---
Documentation:	---	CRM:
Verified Versions:		Category:	---
oVirt Team:	---	RHEL 7.3 requirements from Atomic Host:
Cloudforms Team:	---	Target Upstream Version:
Embargoed:

Description Michal Hlavinka 2013-08-01 07:47:37 UTC

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 09:12:43 UTC

Don't do that.  The "-" is a syntactic separator, not a typographical one.

Comment 2 Michal Hlavinka 2013-08-01 10:09:05 UTC

(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 10:23:17 UTC

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 14:49:36 UTC

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 10:12:59 UTC

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.