Manual page generation on master broken

[laanwj]

I'm not sure if this is related to other version-related issues, but the -version output (when building from git) changed from

Bitcoin Core version v0.21.2.0-89d148c8c65b3e6b6a8fb8b722efb4b6a7d0a375

to

Bitcoin Core version v22.0rc2

This means that the generated manual pages (using contrib/devtools/gen-manpages.sh) now contain the rc number in the embedded version tag. See d3bd541:

+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.13.
+.TH BITCOIN-CLI "1" "August 2021" "bitcoin-cli v22.0rc2" "User Commands"

No big problem, though it is slightly inconvenient. Up until now we didn't have to regenerate the manual pages between the last rc and -final as there is (by how the process is defined) no code difference, so option won't have changed.

[achow101]

This is just an order of operations issue. Typically the manpages are generated on a commit that is not tagged as the RC. But for the 22.0rc2 manpage update, it was done on the 22.0rc2 tagged commit rather than prior to it. If I run contrib/devtools/gen-manpages.sh on the current head of 22.x (which is not tagged), then the manpages have the expected version.

Perhaps we should update the script to deal with this case, but I wouldn't say that this is an issue that needs to be solved for 22.0.

[laanwj]

The thing is, it didn't use to be necessary to update the manual pages between rcs if there were no changes that affect options. at all. Nor was it needed to do it one final time before -final.

I think adding the rc number into the manual pages is of questionable value at the least. It just creates extra work. And requiring a very specific order of operations tends to make things fragile.

[laanwj]

And requiring a very specific order of operations tends to make things fragile.

Oh, so apparently #22685 made this worse, even the right order of operations doesn't solve it anymore.

[laanwj]

There is a more serious problem with the generated manual pages. It looks like all -'s in the text have been purged; e.g.

-nblocks and maxtries arguments. Example: bitcoin-cli \fBgenerate\fR 4
+nblocks and maxtries arguments. Example: bitcoincli \fBgenerate\fR 4

The cause of this is the sed -i with -${BTCVER[1]} which ends up as empty. So all -'s are replaced with nothing.

Need to add a check whether ${BTCVER[1]} is empty, and if so, skip the sed -i.

[laanwj]

Also footer.h2m ends up empty, somehow, besides the [COPYRIGHT]. I think it's a leftover from then --version contained a copyright message?

(I don't think this one is critical; the copyright message still ends up in DESCRIPTION as it's printed by --help, just not in the COPYRIGHT section)

[dongcarl]

Hmmm... No idea about the copyright footer, but for the versioning: what if we get rid of all our munging in the script and just change the process a bit? We'll just generate man pages after we bump the version. A little extra work between last -rc and -final, but we can get rid of code that looks a bit fragile to me.

Not sure if this diff is the right diff to release-process.md, but something like:

diff --git a/doc/release-process.md b/doc/release-process.md
index 1b6472e812..05fa2af378 100644
--- a/doc/release-process.md
+++ b/doc/release-process.md
@@ -6,13 +6,14 @@ Release Process
 ### Before every release candidate
 
 * Update translations see [translation_process.md](https://github.com/bitcoin/bitcoin/blob/master/doc/translation_process.md#synchronising-translations).
-* Update manpages, see [gen-manpages.sh](https://github.com/bitcoin/bitcoin/blob/master/contrib/devtools/README.md#gen-manpagessh).
 * Update release candidate version in `configure.ac` (`CLIENT_VERSION_RC`).
+* Update manpages, see [gen-manpages.sh](https://github.com/bitcoin/bitcoin/blob/master/contrib/devtools/README.md#gen-manpagessh).
 
 ### Before every major and minor release
 
 * Update [bips.md](bips.md) to account for changes since the last release (don't forget to bump the version number on the first line).
 * Update version in `configure.ac` (don't forget to set `CLIENT_VERSION_RC` to `0`).
+* Update manpages, see [gen-manpages.sh](https://github.com/bitcoin/bitcoin/blob/master/contrib/devtools/README.md#gen-manpagessh).
 * Write release notes (see "Write the release notes" below).
 
 ### Before every major release

[laanwj]

Don't forget to also do a build in between. Just updating configure.ac is not enough. Also commit after updating configure.ac (but before the build!), otherwise you'll get -dirty in the version in the manpages (or maybe this is no longer the case now? i don't know).
(this is why the whole "run it for every RC" feels fragile to me apart from the risk of forgetting to run it)
Ideally we'd have some flexibility on when to run the steps and in what order, also to allow distributing the work.

[laanwj]

There is a more serious problem with the generated manual pages. It looks like all -'s in the text have been purged; e.g.

No idea how we want to fix this eventually, but I hacked around this in c1c79f4 on the 22.x branch. 86de567 brings back correct hypen-ization.