Bug 237514 - ZFS(8) Section "SUBCOMMANDS" does not contain names of sub-commands
Summary: ZFS(8) Section "SUBCOMMANDS" does not contain names of sub-commands
Status: Closed FIXED
Alias: None
Product: Documentation
Classification: Unclassified
Component: Manual Pages (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Some People
Assignee: Alexander Motin
URL: https://reviews.freebsd.org/D21009
Keywords:
: 237721 (view as bug list)
Depends on:
Blocks:
 
Reported: 2019-04-24 06:02 UTC by mikhail.maximov
Modified: 2019-07-31 21:23 UTC (History)
7 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
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 freebsd_committer 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 freebsd_committer 2019-04-24 17:36:04 UTC
Hey wosch@, can you take a look at man.cgi and fix it?
Comment 3 Wolfram Schneider freebsd_committer 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 freebsd_committer 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 freebsd_committer 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 freebsd_committer 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