Manual page generation on master broken

laanwj commented at 11:44 am on August 11, 2021: member

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

0Bitcoin Core version v0.21.2.0-89d148c8c65b3e6b6a8fb8b722efb4b6a7d0a375

to

0Bitcoin 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 d3bd5410f64e96d106486643e3d4300a9fb0ee71:

0+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.13.
1+.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.

laanwj added the label Docs on Aug 11, 2021

laanwj added this to the milestone 22.0 on Aug 11, 2021

achow101 commented at 5:29 pm on August 11, 2021: member

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 commented at 11:39 am on August 16, 2021: member

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 commented at 11:44 am on August 16, 2021: member

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 commented at 12:06 pm on August 16, 2021: member

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

0-nblocks and maxtries arguments. Example: bitcoin-cli \fBgenerate\fR 4
1+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 commented at 12:09 pm on August 16, 2021: member

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)

laanwj renamed this:
~~Manual page generation on 22.x includes rc~~
Manual page generation on 22.x broken
on Aug 16, 2021

dongcarl commented at 4:20 pm on August 16, 2021: member

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:

 0diff --git a/doc/release-process.md b/doc/release-process.md
 1index 1b6472e812..05fa2af378 100644
 2--- a/doc/release-process.md
 3+++ b/doc/release-process.md
 4@@ -6,13 +6,14 @@ Release Process
 5 ### Before every release candidate
 6 
 7 * Update translations see [translation_process.md](https://github.com/bitcoin/bitcoin/blob/master/doc/translation_process.md#synchronising-translations).
 8-* Update manpages, see [gen-manpages.sh](https://github.com/bitcoin/bitcoin/blob/master/contrib/devtools/README.md#gen-manpagessh).
 9 * Update release candidate version in `configure.ac` (`CLIENT_VERSION_RC`).
10+* Update manpages, see [gen-manpages.sh](https://github.com/bitcoin/bitcoin/blob/master/contrib/devtools/README.md#gen-manpagessh).
11 
12 ### Before every major and minor release
13 
14 * 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).
15 * Update version in `configure.ac` (don't forget to set `CLIENT_VERSION_RC` to `0`).
16+* Update manpages, see [gen-manpages.sh](https://github.com/bitcoin/bitcoin/blob/master/contrib/devtools/README.md#gen-manpagessh).
17 * Write release notes (see "Write the release notes" below).
18 
19 ### Before every major release

laanwj commented at 11:53 am on August 19, 2021: member

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 referenced this in commit c1c79f4c81 on Aug 26, 2021

laanwj commented at 12:58 pm on August 26, 2021: member

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 c1c79f4c816fa1224ad593f2af90752160fabb09 on the 22.x branch. 86de56776aaef9fc043c22200a88f3a9513234fb brings back correct hypen-ization.

laanwj removed this from the milestone 22.0 on Sep 8, 2021

laanwj renamed this:
~~Manual page generation on 22.x broken~~
Manual page generation on master broken
on Sep 8, 2021

laanwj added this to the milestone 23.0 on Sep 8, 2021

laanwj commented at 2:20 pm on September 8, 2021: member

Removing the milestone as this was fixed (well…) on the 22.x branch and is not a blocker. Needs a proper fix for the next major release. Probably consisting of deleting most of the script as suggested by @dongcarl .

laanwj referenced this in commit d192325732 on Feb 4, 2022

laanwj referenced this in commit 91d813a82d on Feb 4, 2022

laanwj referenced this in commit 42c202893b on Feb 4, 2022

luke-jr referenced this in commit 1872236a51 on Feb 7, 2022

fanquake closed this on Feb 21, 2022

fanquake referenced this in commit bd6b1d0238 on Feb 21, 2022

hmel referenced this in commit 09257a36e7 on Feb 22, 2022

DrahtBot locked this on Feb 21, 2023

Manual page generation on master broken #22681