Bug 237514
| Summary: | ZFS(8) Section "SUBCOMMANDS" does not contain names of sub-commands | ||
|---|---|---|---|
| Product: | Documentation | Reporter: | mikhail.maximov |
| Component: | Manual Pages | Assignee: | Alexander Motin <mav> |
| Status: | Closed FIXED | ||
| Severity: | Affects Some People | CC: | aepalea, allanjude, bcr, doc, dvl, freebsd.org, ivanngeow, mav, pauamma, wosch |
| Priority: | --- | ||
| Version: | Latest | ||
| Hardware: | Any | ||
| OS: | Any | ||
| URL: | https://reviews.freebsd.org/D21009 | ||
| Bug Depends on: | |||
| Bug Blocks: | 250332 | ||
|
Description
mikhail.maximov
2019-04-24 06:02:06 UTC
The subcommands are there in the man page code, it is a problem with the website rendering. If you view the man page on FreeBSD with the man command, you will see them correctly. We should fix this, I just want to note that the issue is man.cgi and not the man page itself. Hey wosch@, can you take a look at man.cgi and fix it? I can confirm the report. The latest manpages itself looks good, there are no major changes. I will investigate whats wrong. The problem first occurred in commit 184cebbed99a0025594b410876510fc4064c6b0b Author: mav <mav@FreeBSD.org> Date: Mon Jul 30 22:39:30 2018 +0000 MFV r336944: 9286 want refreservation=auto since then groff+mdoc cannot parse the page anymore, and report an error message. It is easily to reproduce $ nroff -man zfs.8 zfs.8:1485: environment stack underflow zfs.8:1485: cannot chop empty macro mdoc warning: Empty input line #1702 mdoc warning: Empty input line #1739 mdoc warning: Empty input line #1739 [...] The issue is around the lines +.Sy reservation +property on pool version 8 or earlier +.Pc +after the volume has been created. where you have a closing bracket (.Pc), but there was not opening bracket (.Po), see the mdoc documentation https://man.freebsd.org/mdoc.samples Since FreeBSD 12 we migrated from groff to mandoc. Apparently, mandoc handle the error differently. Nevertheless, this is an error on the manpage, and you may get a broken output on any OS which use the traditional GNU groff/mdoc (FreeBSD before version 12, any linux distro). *** Bug 237721 has been marked as a duplicate of this bug. *** This issue remains in effect for all 11.3 and 12 series online manual pages. As a more general mitigation, perhaps a link should be placed at the bottom of the generated page saying "this page processed with errors, perhaps other versions of this page might render more accurately". Even better if you can point at the last version that did render without errors. (In reply to aepalea from comment #6) yes, it should be merged after we fixed it in current. A commit references this bug: Author: wosch Date: Wed Jul 31 21:21:35 UTC 2019 New revision: 350486 URL: https://svnweb.freebsd.org/changeset/base/350486 Log: add forgotten opening bracket "(" PR: 237514 Reviewed by: allanjude MFC after: soon for 11.3 and 12 series Differential Revision: https://reviews.freebsd.org/D21009 Changes: head/cddl/contrib/opensolaris/cmd/zfs/zfs.8 This still seems to be a problem at https://www.freebsd.org/cgi/man.cgi?zfs(8) Search for 'Clears the specified property' Immediately before it should be: zfs inherit [-rS] property filesystem|volume|snapshot... To be clear, the man page from the command line is fine. The website is not rendering it. (In reply to commit-hook from comment #8) > MFC after: soon for 11.3 and 12 series Apparently, "soon" hasn't come after 1.5 year. Should the MFC be abandoned? *** Bug 250332 has been marked as a duplicate of this bug. *** |
