Man page generation wrong in latest release

[dionysius]

There's a difference between cobra 0.0.5 and 0.0.6 negatively affecting the resulting man files:

Example: https://play.golang.org/p/zcjf0eQ35xj (copy it locally to compare with v0.0.5)

diff --git a/tmp/man-from-005/prog.8 b/tmp/man-from-006/prog.8
index 166d0d1..afda3e3 100644
--- a/tmp/man-from-005/prog.8
+++ b/tmp/man-from-006/prog.8
@@ -1,7 +1,7 @@
-.TH "FOO" "8" "Mar 2020" "The Team" "System Manager's Manual" 
 .nh
-.ad l
-
+.TH FOO(8)Mar 2020
+The Team
+System Manager's Manual

The resulting visual representation is wrong: see man -l /tmp/man-from-006/prog.8.

While we're at it, can we maybe have a golden file/dir for GenMan and GenManTree to detect syntax changes?

I also get the following during execution locally, which might be related (when using GenManTree):

WARNING: go-md2man does not handle node type HTMLSpan

[github-actions]

This issue is being marked as stale due to a long period of inactivity

[MichaelEischer]

I've bisected this to 77e4d5a (thanks for the example code), which updates md2man to v2.0.0 .

[dionysius]

I'm still using v0.0.5 because of that...

[elboulangero]

Seems like we are facing the same issue when while building the docker package in Debian. Since the go-md2man v2 transition, we can't build the documentation anymore:

dh_installman: warning: Section for ./.gopath/src/github.com/docker/cli/man/man1/docker-attach.1 is computed as "2020", which is not a valid section
dh_installman: error: Could not determine section for ./.gopath/src/github.com/docker/cli/man/man1/docker-attach.1
dh_installman: error: Aborting due to earlier error
make: *** [debian/rules:40: binary] Error 25

For the full bug report: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=971789

After some investigation, I observe the same changes in the man pages as the one showed above by @dionysius. And that's why dh_installman (the tool that checks the man pages while creating the Debian package) chokes, it's because something is wrong with the man page.

We solved that by patching doc/man_docs.go, as can be seen here: https://salsa.debian.org/docker-team/docker/-/blob/master/debian/patches/cli-fix-spf13-cobra-man-docs.patch

This patch applies to the lines:

cobra/doc/man_docs.go

Lines 148 to 152 in b97b5ea

	buf.WriteString(fmt.Sprintf(`%% %s(%s)%s
	%% %s
	%% %s
	# NAME
	`, header.Title, header.Section, header.date, header.Source, header.Manual))

Note that I'm not familiar with cobra so I can't claim this is the right fix. However, one thing for sure is that the .TH field of a man page is supposed to have 2 mandatory fields + 3 optional fields. The fields can be surrounded by double-quotes in case a field contain a space. For reference: https://liw.fi/manpages/

[drakkan]

@elboulangero thank you. Do you mind opening a PR? Perhaps this way there is a better chance that the bug will be fixed

[MichaelEischer]

I've noticed further changes in the generated manpages (to be precise: I've only looked at the generated manpages for restic). A CLI option used to look like this:

       -e, --exclude=[]
           exclude a pattern (can be specified multiple times)

Whereas now its

       -e, --exclude=[]      exclude a pattern (can be specified multiple times)

with a different indentation level for each option description, which looks really chaotic, e.g.

       --ignore-inode[=false]      ignore inode number changes when checking for modified files

[elboulangero]

Do you mind opening a PR

PR opened at #1256

[satta]

Do you mind opening a PR

PR opened at #1256

Ah, I already opened one for that (#1255)

[thaJeztah]

Also opened cpuguy83/go-md2man#65 to make go-md2man accept the format (reviews welcome!)

[jpmcb]

Version 1.1.1 is live: https://github.com/spf13/cobra/releases/tag/v1.1.1

Feel free to re-open this issue if there are still problems!