starred/asciinema

Fork 0

mirror of https://github.com/asciinema/asciinema.git synced 2026-04-25 16:05:52 +03:00

[GH-ISSUE #627] Generate man page #936

New issue

Closed

opened 2026-03-15 11:03:53 +03:00 by kerem · 6 comments

kerem commented

2026-03-15 11:03:53 +03:00

Owner

Originally created by @alerque on GitHub (Apr 24, 2024).
Original GitHub issue: https://github.com/asciinema/asciinema/issues/627

I just started playing around with updating the Arch Linux packaging in preparation for the v3 release. It looks like one regression over the Python package is that there is no man page.

Since the Rust rewrite is using Clap it should be pretty easy to generate a correct and in sync man page from the CLI interface setup using clap_mangen. There is not reason this has to make the final v3 cut, but I figured whether early or late a tracking issue is warranted so downstream packages know if it is or isn't available and how it is generated.

Originally created by @alerque on GitHub (Apr 24, 2024). Original GitHub issue: https://github.com/asciinema/asciinema/issues/627 I just started playing around with [updating the Arch Linux packaging](https://gitlab.archlinux.org/archlinux/packaging/packages/asciinema/-/merge_requests/1) in preparation for the v3 release. It looks like one regression over the Python package is that there is no man page. Since the Rust rewrite is using Clap it should be pretty easy to generate a correct and in sync man page from the CLI interface setup using clap_mangen. There is not reason this *has to* make the final v3 cut, but I figured whether early or late a tracking issue is warranted so downstream packages know if it is or isn't available and how it is generated.

kerem closed this issue

2026-03-15 11:03:58 +03:00

kerem commented

2026-03-15 11:04:04 +03:00

Author

Owner

@ku1ik commented on GitHub (Apr 24, 2024):

Hey! Awesome that you're already looking into it 😍

Both man page generation and shell completions are on my list of things to do before cutting the final v3, hope to get to this very soon.

Not sure whether build-time or run-time generation of a man page would be better here, but I think the build-time generation as described in [clap_mangen's example](https://github.com/clap-rs/clap/blob/master/clap_mangen/README.md should be good enough. This would produce both the binary and the man page, putting them both in the same out dir, easy for packaging. What do you think?

@ku1ik commented on GitHub (Apr 24, 2024): Hey! Awesome that you're already looking into it :heart_eyes: Both man page generation and shell completions are on my list of things to do before cutting the final v3, hope to get to this very soon. Not sure whether build-time or run-time generation of a man page would be better here, but I think the build-time generation as described in [clap_mangen's example](https://github.com/clap-rs/clap/blob/master/clap_mangen/README.md should be good enough. This would produce both the binary and the man page, putting them both in the same out dir, easy for packaging. What do you think?

kerem commented

2026-03-15 11:04:09 +03:00

Author

Owner

@alerque commented on GitHub (Apr 24, 2024):

Personally (as a distro packager) I much prefer build-time generation for these sort of assets. The argument in favor of run-time is for folks who cargo install on whatever in their user space rather than installing system packages, but my experience is those folks are much less likely to expect or use a man page in the first place.

And yes having the man page generated to the Cargo OUT_DIR is fine.

@alerque commented on GitHub (Apr 24, 2024): Personally (as a distro packager) I *much* prefer build-time generation for these sort of assets. The argument in favor of run-time is for folks who `cargo install` on whatever in their user space rather than installing system packages, but my experience is those folks are much less likely to expect or use a man page in the first place. And yes having the man page generated to the Cargo OUT_DIR is fine.

kerem commented

2026-03-15 11:04:14 +03:00

Author

Owner

@ku1ik commented on GitHub (Apr 24, 2024):

but my experience is those folks are much less likely to expect or use a man page in the first place.

This is my experience as well.

@ku1ik commented on GitHub (Apr 24, 2024): > but my experience is those folks are much less likely to expect or use a man page in the first place. This is my experience as well.

kerem commented

2026-03-15 11:04:19 +03:00

Author

Owner

@ku1ik commented on GitHub (Apr 29, 2024):

You can now generate man page during build by setting ASCIINEMA_GEN_DIR env var - the file will be saved as $ASCIINEMA_GEN_DIR/man/asciinema.1.

@ku1ik commented on GitHub (Apr 29, 2024): You can now generate man page during build by setting `ASCIINEMA_GEN_DIR` env var - the file will be saved as `$ASCIINEMA_GEN_DIR/man/asciinema.1`.

kerem commented

2026-03-15 11:04:24 +03:00

Author

Owner

@xfgusta commented on GitHub (May 13, 2024):

I noticed that the man page seems a bit empty compared to the old one. There are mentions of other man pages for the subcommands, but these man pages are not generated. I'm not sure if this is intended.

$ man asciinema
[...]
SUBCOMMANDS
       asciinema-rec(1)
              Record a terminal session

       asciinema-play(1)
              Replay a terminal session
[...]

$ man asciinema-rec
No manual entry for asciinema-rec

@xfgusta commented on GitHub (May 13, 2024): I noticed that the man page seems a bit empty compared to the old one. There are mentions of other man pages for the subcommands, but these man pages are not generated. I'm not sure if this is intended. ```console $ man asciinema [...] SUBCOMMANDS asciinema-rec(1) Record a terminal session asciinema-play(1) Replay a terminal session [...] ``` ```console $ man asciinema-rec No manual entry for asciinema-rec ```

kerem commented

2026-03-15 11:04:29 +03:00

Author

Owner

@ku1ik commented on GitHub (May 15, 2024):

@xfgusta good catch, thanks for the PR!

@ku1ik commented on GitHub (May 15, 2024): @xfgusta good catch, thanks for the PR!