Bug 1027027
Summary: | Incorrect xfsdump reference in xfs man page | ||
---|---|---|---|
Product: | Red Hat Enterprise Linux 6 | Reporter: | Jacquelynn East <jeast> |
Component: | xfsprogs | Assignee: | Eric Sandeen <esandeen> |
Status: | CLOSED WONTFIX | QA Contact: | Filesystem QE <fs-qe> |
Severity: | unspecified | Docs Contact: | |
Priority: | unspecified | ||
Version: | 6.5 | CC: | pschiffe, rlandman, zab |
Target Milestone: | rc | Keywords: | 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
$ rpm -qf $(man -w xfs) xfsprogs-3.1.10-2.fc19.x86_64 [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. 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. 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). 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 @@ .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: 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?) 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 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 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 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. |