Bug 1027027

Summary: Incorrect xfsdump reference in xfs man page
Product: Red Hat Enterprise Linux 6 Reporter: Jacquelynn East <jeast>
Component: xfsprogsAssignee: Eric Sandeen <esandeen>
Status: CLOSED WONTFIX QA Contact: Filesystem QE <fs-qe>
Severity: unspecified Docs Contact:
Priority: unspecified    
Version: 6.5CC: pschiffe, rlandman, zab
Target Milestone: rcKeywords: ManPageChange, Reopened
Target Release: ---   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard:
Fixed In Version: Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2013-11-11 19:08:42 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 Jacquelynn East 2013-11-05 23:17:23 UTC
Description of problem:
The xfs man page links to xfs-dump(8) in the reference section. This is incorrect as it should be xfsdump (without the hyphen).

Version-Release number of selected component (if applicable):


How reproducible:
every time


Steps to Reproduce:
1. Run man xfs
2. Scroll down to reference to note that it says xfs-dump(8)
3. Attempt to run man xfs-dump and get a no such man page error

Actual results:
No such man page error

Expected results:
xfs man page reference the correct xfsdump man page

Additional info:

Comment 2 Peter Schiffer 2013-11-06 08:16:18 UTC
$ rpm -qf $(man -w xfs)
xfsprogs-3.1.10-2.fc19.x86_64

Comment 3 Eric Sandeen 2013-11-06 16:46:22 UTC
[root@bp-05 ~]# rpm -q xfsprogs
xfsprogs-3.1.1-14.el6.x86_64
[root@bp-05 ~]# man xfs | col -b | grep xfs-dump
[root@bp-05 ~]# man xfs | col -b | grep xfsdump
       the same UUID, xfsdump(8) may become confused  when  doing  incremental
       and  resumed  dumps.   xfsdump(8) and xfsrestore(8) are recommended for
[root@bp-05 ~]# grep xfs-dump /mnt/test2/git/xfsprogs/man/man5/xfs.5 
[root@bp-05 ~]# 

The manpage source does not contain the string "xfs-dump"

In an 80-col screen, man seems to be auto-splitting & hyphenating on a line wrap.


I have no earthly idea how to prevent that.

Comment 4 Eric Sandeen 2013-11-06 17:13:14 UTC
We refer to it as:

.BR xfsdump (8)

which is best practice, AFAIK.  If there is some other way to refer to manpages & function names such that man won't break them, we could consider it.

For now, I don't think this rises above all the other work we have on our plate, so I'm going to propose that we not worry about it in RHEL6.

Comment 5 Peter Schiffer 2013-11-06 17:21:13 UTC
Hi Eric,

this should work:

--- xfs.5.orig	2013-11-06 18:19:18.757094424 +0100
+++ xfs.5	2013-11-06 18:18:46.589277656 +0100
@@ -107,5 +107,5 @@
 .BR mkfs.xfs (8),
 .BR xfs_info (8),
 .BR xfs_admin (8),
-.BR xfsdump (8),
+.BR \%xfsdump (8),
 .BR xfsrestore (8).

Comment 6 Eric Sandeen 2013-11-06 18:15:45 UTC
Peter, yeah, I found that too, thanks.  But I'd have to do that for every word in every manpage that I don't want hyphenated.  It's a pity that there's no directive or macro to make that easier or automatic; this must be a pretty common occurrence, no?

Comment 7 Zach Brown 2013-11-06 21:10:47 UTC
Can we turn off hyphenation?  Dunno if you can do it site-wide, but you can see the effect it has on a given man page:

--- xfs.5.orig	2013-11-06 13:08:04.949730092 -0800
+++ xfs.5	2013-11-06 13:07:52.033661395 -0800
@@ -2,6 +2,7 @@
 .SH NAME
 xfs \- layout of the XFS filesystem
 .SH DESCRIPTION
+.nh
 An XFS filesystem can reside on a regular disk partition or on a
 logical volume.
 An XFS filesystem has up to three parts:

Comment 8 Eric Sandeen 2013-11-06 22:25:16 UTC
That's better than fixing words one at a time.  :)  Peter, have you seen this problem in other manpages?  (Do you consider it a problem, if function names or manpage names or binary names get hyphenated, or is that just to be expected?)

Comment 9 Peter Schiffer 2013-11-07 10:29:29 UTC
Hi Eric,

hyphenation is usually enabled in man pages and so far I didn't have any problem of this kind. WONTFIX is probably pretty OK option - but in this case, when that word is hyphenated in the reference section when terminal is 80 columns wide (what is really common), I think it could be usability++ if you'd just disable the hyphenating for that one word, on that one place. I wouldn't bother with the rest of man page. But really, it's up to you...

peter

Comment 10 Eric Sandeen 2013-11-11 18:46:27 UTC
Peter, thanks.

Hohum, well, ok I'll fix it upstream, and we'll get it picked up in RHEL7.  It hardly seems worth the process overhead to fix it in RHEL6, clone to RHEL7, etc etc etc.  So I'm going to leave this bug closed.

Thanks for the report, Jacquelynn.

-Eric

Comment 11 Eric Sandeen 2013-11-11 19:08:42 UTC
Actually no.  ;)

I started looking at all xfsprogs manpages, and there are TONS of hyphenated symbols & binary names; we just can't run around fixing all of these.  If it's a problem, we need to do something like disable hyphenation system-wide in manpages.

i.e. in handle(3), the first one I checked:

       attr_list_by_handle, fssetdm_by_handle, free_handle, getparents_by_han-
       dle, getparentpaths_by_handle - file handle operations

       int attr_list_by_handle(void *hanp, size_t hlen, char *buf, size_t buf-
              siz, int flags, struct attrlist_cursor *cursor);

       The free_handle() function frees  the  storage  allocated  for  handles
       returned  by  the following functions: path_to_handle(), path_to_fshan-
       dle(), fd_to_handle(), and handle_to_fshandle()

       The getparentpaths_by_handle() function is  identical  to  the  getpar-
       ents_by_handle() function except that instead of returning the basename



I just don't think it's worth going through & annotating all of these manpages, in a handful of manpages, in one package, for a specific column width, etc.

If it's a problem, it needs to be addressed system-wide.

Thanks,
-Eric

Comment 12 Jacquelynn East 2013-11-11 21:17:15 UTC
It's alight, I didn't realize that was an automated process and, from the comments since, it seems like most of the users are aware of it and can try something else if it doesn't work instead of scratching their head like I did :) Being automated it will definitely be too hard to fix specific cases so I support Eric's decision to close it.