{"action":"created","issue":{"url":"https://api.github.com/repos/spf13/cobra/issues/342","repository_url":"https://api.github.com/repos/spf13/cobra","labels_url":"https://api.github.com/repos/spf13/cobra/issues/342/labels{/name}","comments_url":"https://api.github.com/repos/spf13/cobra/issues/342/comments","events_url":"https://api.github.com/repos/spf13/cobra/issues/342/events","html_url":"https://github.com/spf13/cobra/issues/342","id":174944671,"number":342,"title":"Man page generator generates inconsistent file names and SEE ALSO references","user":{"login":"knz","id":642886,"avatar_url":"https://avatars.githubusercontent.com/u/642886?v=3","gravatar_id":"","url":"https://api.github.com/users/knz","html_url":"https://github.com/knz","followers_url":"https://api.github.com/users/knz/followers","following_url":"https://api.github.com/users/knz/following{/other_user}","gists_url":"https://api.github.com/users/knz/gists{/gist_id}","starred_url":"https://api.github.com/users/knz/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/knz/subscriptions","organizations_url":"https://api.github.com/users/knz/orgs","repos_url":"https://api.github.com/users/knz/repos","events_url":"https://api.github.com/users/knz/events{/privacy}","received_events_url":"https://api.github.com/users/knz/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":{"login":"anthonyfok","id":1274764,"avatar_url":"https://avatars.githubusercontent.com/u/1274764?v=3","gravatar_id":"","url":"https://api.github.com/users/anthonyfok","html_url":"https://github.com/anthonyfok","followers_url":"https://api.github.com/users/anthonyfok/followers","following_url":"https://api.github.com/users/anthonyfok/following{/other_user}","gists_url":"https://api.github.com/users/anthonyfok/gists{/gist_id}","starred_url":"https://api.github.com/users/anthonyfok/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/anthonyfok/subscriptions","organizations_url":"https://api.github.com/users/anthonyfok/orgs","repos_url":"https://api.github.com/users/anthonyfok/repos","events_url":"https://api.github.com/users/anthonyfok/events{/privacy}","received_events_url":"https://api.github.com/users/anthonyfok/received_events","type":"User","site_admin":false},"assignees":[{"login":"anthonyfok","id":1274764,"avatar_url":"https://avatars.githubusercontent.com/u/1274764?v=3","gravatar_id":"","url":"https://api.github.com/users/anthonyfok","html_url":"https://github.com/anthonyfok","followers_url":"https://api.github.com/users/anthonyfok/followers","following_url":"https://api.github.com/users/anthonyfok/following{/other_user}","gists_url":"https://api.github.com/users/anthonyfok/gists{/gist_id}","starred_url":"https://api.github.com/users/anthonyfok/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/anthonyfok/subscriptions","organizations_url":"https://api.github.com/users/anthonyfok/orgs","repos_url":"https://api.github.com/users/anthonyfok/repos","events_url":"https://api.github.com/users/anthonyfok/events{/privacy}","received_events_url":"https://api.github.com/users/anthonyfok/received_events","type":"User","site_admin":false}],"milestone":null,"comments":6,"created_at":"2016-09-04T11:40:57Z","updated_at":"2016-12-29T07:58:36Z","closed_at":null,"body":"We encountered this in CockroachDB (xref https://github.com/cockroachdb/cockroach/issues/4917)\n- `GenManTree` in `doc/man_docs.go` forces the command separator to be `\"_\"`, which causes `GenManTreeFromOpts` to generate file names for man pages to be `like_this.1`\n- Meanwhile, `genMan` replaces spaces in names by `\"-\"` always.\n\nAs a result, when the reader reads the \"SEE ALSO\" section she might see a reference to `this-command(1)` whereas the command she has to type to read that man page is actually `man this_command`.\n\nMay I suggest to use dashes always, that is, set the options in `GenManTree` to use `\"-\"`.\n"},"comment":{"url":"https://api.github.com/repos/spf13/cobra/issues/comments/269594670","html_url":"https://github.com/spf13/cobra/issues/342#issuecomment-269594670","issue_url":"https://api.github.com/repos/spf13/cobra/issues/342","id":269594670,"user":{"login":"anthonyfok","id":1274764,"avatar_url":"https://avatars.githubusercontent.com/u/1274764?v=3","gravatar_id":"","url":"https://api.github.com/users/anthonyfok","html_url":"https://github.com/anthonyfok","followers_url":"https://api.github.com/users/anthonyfok/followers","following_url":"https://api.github.com/users/anthonyfok/following{/other_user}","gists_url":"https://api.github.com/users/anthonyfok/gists{/gist_id}","starred_url":"https://api.github.com/users/anthonyfok/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/anthonyfok/subscriptions","organizations_url":"https://api.github.com/users/anthonyfok/orgs","repos_url":"https://api.github.com/users/anthonyfok/repos","events_url":"https://api.github.com/users/anthonyfok/events{/privacy}","received_events_url":"https://api.github.com/users/anthonyfok/received_events","type":"User","site_admin":false},"created_at":"2016-12-29T07:58:36Z","updated_at":"2016-12-29T07:58:36Z","body":"I agree with @knz, especially this is the way `git` sub-command man pages work too, where `-` dashes are used to represent spaces, and sometimes, actual `-` dashes.\r\n\r\nOn the other hand, `_` underscores means actual underscores in the command name, e.g. `kbd_mode`, `xinput_calibrator`.  I couldn't really find an example (outside of cobra-generated man pages) in my /usr/share/man/man1/ directory where the `_` underscore is used to represent a space.\r\n\r\nSo, yes, I think I will simply go ahead and accept @knz's PR #343."}}
{"actor":{"display_login":"anthonyfok"}}