Red Hat Bugzilla – Bug 1027027
Incorrect xfsdump reference in xfs man page
Last modified: 2015-07-26 18:11:17 EDT
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):
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
No such man page error
xfs man page reference the correct xfsdump man page
$ rpm -qf $(man -w xfs)
[root@bp-05 ~]# rpm -q xfsprogs
[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
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.
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.
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).
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?
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 @@
xfs \- layout of the XFS filesystem
An XFS filesystem can reside on a regular disk partition or on a
An XFS filesystem has up to three parts:
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?)
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...
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.
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.
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.