Generate man page as part of release process

[julianandrews]

Right now I generate the man page by manually running scripts/generate-man.sh, and include the gzipped man page in the repo. Ideally there shouldn't be generated files in the repo, and instead, generating the man page should be part of the release generation process.

It'll take a little poking around to figure out the cleanest way to do this.

[julianandrews]

Thinking about this a little, ideally this would be part of the build process rather than the release generation process. That way cargo deb will generate the man page correctly. This probably belongs as logic in build.rs.

[julianandrews]

The one complication is that if help2man isn't installed I can't generate the man page. I think the solution here is to try to run it, and if help2man isn't installed catch the error and print a warning, but proceed. That way builds will still work, but cargo deb will (presumably) fail when it can't find the generated man page.

So changes I need to make:

• add a generate_man() function to build.rs that never fails, but prints a warning if it fails
• update the release github action to install help2man before running build
• delete the existing man generation script and generated man page

[julianandrews]

Revised plan! I had forgotten that help2man needs the binary to be built to generate the output. So this can't happen in the build script. Ideally this would be a post-build script, but at least for now, there are no post build scripts.

I still would really like cargo deb to just work, so I'm going to look into using cargo deb itself to run some logic post-build, but pre deb generation.

[julianandrews]

Ok! cargo-deb is out. I think I really just need to abandon the idea of making cargo-deb just work.

I can write a shell script to generate the Debian package. If I remove the man page from the repo, cargo-deb will conveniently fail:

$ cargo deb
   Compiling sgf-render v3.2.2 (/home/julian/Code/sgf-render)
    Finished `release` profile [optimized] target(s) in 2.72s
cargo-deb: Asset file path does not match any files: /home/julian/Code/sgf-render/man/sgf-render.1.gz

so at least I don't need to worry about it producing a broken package silently.

[julianandrews]

Hmm, actually, I still can generate a broken package if I don't consistently clean up the generated file.

Ideally I'd generate the file in a tempdir (mktemp -d), and that way there'd be no danger of building the deb with an out of date man page, but as far as I can tell I need to hardcode the path to the man page in the assets in Cargo.toml, so I don't think I can do that.

So I'm not seeing an easy way to guarantee that cargo deb fails if the man page isn't fresh, but that's not the end of the world.

[julianandrews]

Fixed now! I can't see any reason to make a new release for the change, but I tested the CI by pushing the v3.2.2-test-ci tag to github.