search

yonaskolb / Mint

A package manager that installs and runs executable Swift packages
MIT License
2.29k stars 123 forks source link

install man-pages with mint install #50

Open toshi0383 opened 6 years ago

toshi0383 commented 6 years ago

Mint could support installing man-pages.

To support this, mint install need to

SeeAlso:

yonaskolb commented 6 years ago

Man-pages aren't really a standard among Swift command line tools. Many just rely on the help generators of various CLI libraries. For that reason I don't quite see the need to build something like this into Mint. If you have some evidence otherwise though, and are happy to open PR be my guest 😄

Mint is primarily designed to easily install Swift Package Manager command line tools. If a tool has extra resources, tools, or mechanisms around it, which are outside of Swift PM, they should probably find another way to distribute their tool.

toshi0383 commented 6 years ago

IMO, Swift CLI community should adapt to man-page distribution already. There is a man-page for swift, too. We can say that man-page is a standard. I think a lot of terminal users expect a CLI tool to have corresponding man-page.

Many just rely on the help generators of various CLI libraries.

Yea I used to rely on help generator of Commander too, but I've quit it because I wanted to distribute more descriptive and readable documentation page to terminal users. I think the help generators are useful for short help pages, but not for detailed documentations.

toshi0383 commented 6 years ago

If a tool has extra resources, tools, or mechanisms around it, which are outside of Swift PM, they should probably find another way to distribute their tool.

So currently Mint provides Package.resources support outside of Swift PM. I guess it makes sense to support man-page, too.

My use case is my tool cmdshelf. It spawns $PAGER to show man-pages instead of help message by default. https://github.com/toshi0383/cmdshelf/blob/master/Sources/cmdshelf/Commands.swift#L120 If user used Mint to install, then currently user would see nothing for help command.

Anyways, I'm going to work on this feature. 👌

toshi0383 commented 6 years ago

Looks like Cargo is going to support manpages as well. https://github.com/rust-lang/cargo/issues/2729 They have on-going rfc proposal for this and looks like the format is going to be install.rs to be executed for arbitrary purpose (including copying manpages and so on).

For us, I propose a roadmap below. Each can be released separately.

  1. Support default manpages location at doc/man/*( a bit simplified from which I described above ).
  2. Update Package.resources format to support arbitrary manpages location. Maybe like this, but in yaml format?
  3. [Optional] Add install.swift support being inspired by install.rs.
toshi0383 commented 6 years ago

FYI: Just found out that Rust community has a library which is just like Commander , but even generates man-pages automatically. https://github.com/clap-rs/clap