Add a man page (again)

[harkabeeparolus]

I wish there was a manpage for Unix and macOS.

Whenever I'm trying to remember the CLI syntax and options for a specific command, it really helps to be able to type Alt-h or ESC h in the shell to get a manpage reference.

I guess it should be possible to auto generate a manpage with mkdocs-manpage, using pandoc.

For previous discussions, see:

• Add a man page Add a man page #696
• Compression of Docs Into Single Document Compression of Docs Into Single Document #884

[twpayne]

I'm happy for someone to add this functionality, as long it does not result in duplicated documentation in the source repository.

@harkabeeparolus do you want to implement this?

[halostatue]

It would be better to look at using https://github.com/spf13/cobra/blob/main/site/content/docgen/man.md

[twpayne]

My concern with using cobra's man page generator is that it includes only the reference documentation already available through chezmoi --help and not any other text, i.e. it omits the high level overview, user guide, and other useful information that often appears in man pages.

[halostatue]

One downside to this would be that Cobra doesn't generate single manpages when there are subcommands, it creates multiple man pages (chezmoi-apply).

[harkabeeparolus]

@harkabeeparolus do you want to implement this?

Honestly I probably don't have the time right now, and I'm not familiar with the project beyond being a casual user. So realistically, not at this time. 😔 But thanks for asking! 😊

[twpayne]

OK, maybe you will get lucky and someone will do the work for you.

[harkabeeparolus]

One downside to this would be that Cobra doesn't generate single manpages when there are subcommands, it creates multiple man pages (chezmoi-apply).

That's not necessarily a downside by itself. The man command handles this style of subcommands just fine (e.g. man git pull), as can the Alt-h keybinding in shells, such as fish or zsh.

But that's perhaps a little more ambitious than I had in mind... 😬 It's not a bad thing, it's just a bigger project.

[harkabeeparolus]

My concern with using cobra's man page generator is that it includes only the reference documentation already available through chezmoi --help and not any other text, i.e. it omits the high level overview, user guide, and other useful information that often appears in man pages.

Honestly, though, that's still better than nothing in my opinion. It would work as a first iteration, with the possibility for later improvements. And it would actually be helpful for interactive shell use with Alt-h. At least that's what I think. 😊