|Summary:||ZFS(8) Section "SUBCOMMANDS" does not contain names of sub-commands|
|Component:||Manual Pages||Assignee:||Alexander Motin <mav>|
|Severity:||Affects Some People||CC:||aepalea, allanjude, bcr, doc, dvl, freebsd.org, mav, wosch|
Description mikhail.maximov 2019-04-24 06:02:06 UTC
Bug report for FreeBSD documentation in HTML format Page ZFS(8) Section "SUBCOMMANDS" does not contain names of sub-commands before their descriptions. Incorrect: https://www.freebsd.org/cgi/man.cgi?query=zfs&manpath=FreeBSD+13-current https://www.freebsd.org/cgi/man.cgi?query=zfs&manpath=FreeBSD+12.0-RELEASE Last correct: https://www.freebsd.org/cgi/man.cgi?query=zfs&manpath=FreeBSD+11.2-RELEASE
Comment 1 Allan Jude 2019-04-24 17:23:53 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.
Comment 2 Benedict Reuschling 2019-04-24 17:36:04 UTC
Hey wosch@, can you take a look at man.cgi and fix it?
Comment 3 Wolfram Schneider 2019-04-26 16:44:37 UTC
I can confirm the report. The latest manpages itself looks good, there are no major changes. I will investigate whats wrong.
Comment 4 Wolfram Schneider 2019-04-30 08:53:51 UTC
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).
Comment 5 John D. 2019-05-03 16:15:16 UTC
*** Bug 237721 has been marked as a duplicate of this bug. ***
Comment 6 aepalea 2019-07-29 18:58:36 UTC
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.
Comment 7 Wolfram Schneider 2019-07-29 19:06:25 UTC
(In reply to aepalea from comment #6) yes, it should be merged after we fixed it in current.
Comment 8 commit-hook 2019-07-31 21:22:14 UTC
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
Comment 9 Dan Langille 2020-06-25 14:16:16 UTC
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.