💾 Archived View for remyabel.flounder.online › 2021-10-23-cargo-man-pages.gmi captured on 2023-06-16 at 16:07:39. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2021-11-30)
-=-=-=-=-=-=-
Let me start off with something amusing:
https://github.com/rust-lang/cargo/issues/2729#issuecomment-755232973
The comment reads as:
> Cargo isn't a package manager.
Then the official description is misleading: https://doc.rust-lang.org/cargo/
Cargo is the Rust package manager.
Indeed, despite language package managers like npm, pip, etc. not replacing distro package maangers (as they should not), they are still recommended as the way to install user-facing binaries. However, they are really more suited for installing libraries. That is why, for example, it is recommended Python developers use poetry for projects and users use pipx.
One of cargo's current deficiencies is that it does not automatically install man pages. There is a lot of waffling about cargo installing to system locations (fortunately this was shot down), even though installing to for example ~/.local/share/man is sufficient. However, it still requires manual effort because it doesn't do it automatically.
It doesn't help when each project has its own method of generating man pages. Let's use two rust-based CLI examples: exa and bat. exa has its man pages in markdown format and requires using a tool called Just (never heard of it) and instructions in a Justfile that converts the markdown pages to man pages. Obviously I just copy/pasted the commands then copied the artifacts over. bat doesn't ship its completion files because of a bug that's been blocking it for over 2 years. Helpfully, the assets can be found in directories like ~/.cargo/registry/src/github.com-1ecc6299db9ec823/bat-0.18.3/target/debug/build/bat-91b2fc92b4b27647/out/assets/manual/. And yes, you have to find the correct directory (or use the find command) after you've built the man pages, then copy it over. I also don't know why it's in the debug folder, I thought cargo install does release by default? But I'm not a rust developer.
This is not an ideal situation I don't think. It requires manual labor and hacky workarounds. Why not just use the distro packages? A few of them are outdated or don't ship the man pages (due to the project's wonky setup). I feel like this issue is a combination of a deficiency in cargo as well as the developers making strange decisions.