Add man page

[jubalh]

With the inclusion of himalaya to various Linux distributions we should fulfill the requirement of having a manual page for each executable.

I chose to write the man page in markdown for easier editing.

It can then be transformed into a regular man page via pandoc: pandoc --standalone --to man himalaya.1.md -o himalaya.1

A release tarball will only need to ship the himalaya.1 file. I'm not sure whether you prefer to have the tranformation process in some release script. I decided to add both the himalaya.1 and himalaya.1.md file to the repository, and not just the product himalaya.1, so that users who don't have pandoc installed can already view the manpage via man man/himalaya.1 when checking out the git repository.

[jubalh]

Nix build fail seems unrelated to my changes.

[soywod]

Thank you for your initiative, I find it really pertinent. The only drawback I see is that you need to maintain this file manually, it could be nice if it could be auto generated by clap (the rust lib used to generate the CLI). I started to dig and I found this crate that does exactly what we need: https://crates.io/crates/clap_mangen.

[jubalh]

Oh, that's sad (and cool too) :D

I see that would make it easier to keep the options/command descriptions up to date.
I didn't see if there is a way to add general text, descriptions, issue reporting links etc though.

Also https://github.com/clap-rs/clap/issues?q=is%3Aopen+is%3Aissue+label%3AA-man looks like there are still some problems with it that might be relevant to us.

Did you try it out yet and see if it can handle all the cases and what it looks like?

Personally I would suggest to merge this PR and switch to clap when it is more mature.

[soywod]

Next week I will give the clap feature a shot and see how it behaves. If it is good enough then we can use it, otherwise we can merge your PR, what do you think?

[jubalh]

Sounds good!

[soywod]

I will take care of it straight after #433!

[soywod]

The generated man is really close to yours, I think we can keep clap_mangen 🙂 but I do not know when to generate this file? I mean, it is like completion: it is sth you generate when you install the tool. I need to dig this part.

EDIT: you can try clap_mangen on the develop branch with the command himalaya man

[jubalh]

Great! So the next release will contain the man page yes?
In this case I'll remove the one I made from the openSUSE with the next release.

[soywod]

Great! So the next release will contain the man page yes?

It will contain the himalaya man command that generates the man page on the fly on the standard output.

In this case I'll remove the one I made from the openSUSE with the next release.

I still don't know how and when to generate this file? I don't want to commit the generated file (like completions files). Let's say you install himalaya on Debian, should the Debian installer have the responsibility to generate the man file (like the completions files)?

[jubalh]

I still don't know how and when to generate this file? I don't want to commit the generated file (like completions files). Let's say you install himalaya on Debian, should the Debian installer have the responsibility to generate the man file (like the completions files)?

Back in the day most C projects had a make dist target. This created a release tarball of the project. It also contained generated files (like man pages etc). Now on GitHub such projects upload this tarball and downstream used these manually generated tarballs instead of the GitHub autocreated tarballs for tags.
Maybe something similar is possible.

Another way could be that in your commit Release version XXX you add those generated files to the git tree. And in the next commit Start new development cycle you remove them again. Then they would be in the GitHub autogenerated tarball.

Third option would be to mention in some documentation that downstream projects need to run certain commands to generate those files.

[soywod]

Thank you for the details. Actually, releases are built by a GitHub action, so I think it is the best place to generate the manual and pack it within the tarball (which looks like your first option with make dist). Two other questions:

• himalaya man generates the manual for the main command, is it enough or we should also generate manuals for all subcommands? If so, how to organize files for each subcommand?
• should I do the same for completions? I mean, generating completions scripts for all available shells and pack them within the tarball? Or is it "too much"?

[jubalh]

himalaya man generates the manual for the main command, is it enough or we should also generate manuals for all subcommands? If so, how to organize files for each subcommand?

I would say to generate all of them. Like git does. There is man git as well as man git branch etc. I'm not sure what you mean with how to organize them. I thought about putting each of them in the main man page. But if you think this gets too big then files should probably be named himalaya-subcommand1 etc and they should be installed to the default man dir.

Example from git:

/usr/share/man/man1/git-checkout.1.gz
/usr/share/man/man1/git-cherry-pick.1.gz

should I do the same for completions? I mean, generating completions scripts for all available shells and pack them within the tarball? Or is it "too much"?

I guess you could. I probably would do it and then let downstream/distributions decide which one of them they package and how (subpackages for each completion) according to their policies.

I consinder man pages of more importance since users use them to learn about the commands and some distributions have them mandatory for each binary. And the completions are more of a convenience.

[soywod]

I'm not sure what you mean with how to organize them

I meant how to name files, where to place them etc. But you answered the question, I guess it is under /usr/share/man/man1/command-subcommand.1.gz. But this depends on the operating systems used, only package maintainers know the path.

The only drawback I see for generating everything and packing all within the tarball is that it make the tarball "heavier" and messier. After thinking about it, I find it cleaner to add a section in the wiki dedicated to package maintainers on how to generate completions and man files, and let them generate + place them at the right place.

So I resume the 2 remaining tasks:

• Make the man command generate all manuals for all subcommands
• Add instructions for package maintainers

What do you think about it?

[jubalh]

What do you think about it?

That sounds fine. Thank you

[soywod]

I just pushed the changes for the man command to generate all man pages for all subcommands, and I updated the wiki for the completion and the man. Thanks a lot for your precious help and for making this tool better 🙏

[jubalh]

I just wanted to add that maybe some distributions won't like that they will first have to build the binary and then are able to call that binary to create the man pages instead of the man pages being created through some build tool. We will see :)

[soywod]

I understand, let's see how it behaves! Anyway, we can adjust the process any time 🙂

[icp1994]

I just wanted to add that maybe some distributions won't like that they will first have to build the binary and then are able to call that binary to create the man pages instead of the man pages being created through some build tool. We will see :)

I have to agree with this. I have been maintaining himalaya in Void Linux for the past couple of releases. While it's possible to run the built binary to generate manpages and completions, it's a lot cleaner if it's provided in the source archive itself - https://github.com/casey/just for example.

[soywod]

I have to agree with this. I have been maintaining himalaya in Void Linux for the past couple of releases. While it's possible to run the built binary to generate manpages and completions, it's a lot cleaner if it's provided in the source archive itself - https://github.com/casey/just for example.

Then let's pack man pages and completion scripts to the releases, should be easy to do. I opened an [issue]. Thank you for your feedback (and for maintaining himalaya in Void Linux!). [issue]: https://todo.sr.ht/~soywod/pimalaya/43

[soywod]

What is the convention usually? For man pages I guess it is a man/ folder next to the binary, but for completion scripts?

[icp1994]

completions/ and contrib/completions/ are the most common ones but I have seen assets/completions/ and extras/completions/ as well.

[soywod]

`completions/` and `contrib/completions/` are the most common ones but I have seen `assets/completions/` and `extras/completions/` as well.

Perfect, so let's go for `/man` and `/completions`!

[soywod]

Feature implemented on develop, should be available for the next release!

[icp1994]

Nice!