Autoupdate man page rev/date info upon git-archive

[sanmai-NL]

See #25689, in particular this comment
r? @brson

This PR ensures that version-related references in man pages coming with ‘non-working copies’ of the source tree are kept in sync automatically. For copies created with git archive, including tagged releases (as probably consumed by packagers), the bottom line of the man pages for rustc and rustdoc will automatically read something like in man:

At rev. a9d08eb                               2016-06-13 09:44:18 +0200                                     RUSTC(1)

Instead of (at Rust 1.9.0):

rustc 1.2.0                                          August 2015                                            RUSTC(1)

This solution isn't dependent on manual creation of man pages; that can be reconsidered and this trick can be reused or replaced with whatever future means of autoproduction of man pages. In my view, being precise and current in docs also encourages keeping them current, and increases user confidence that they are indeed reliable and current.

A limitation of the solution is that it doesn't translate the git revision and date to some more readily understood ‘discrete’ tag, such as a version triple. This is AFAICT only possible when you bundle such documentation as an extra release artifact built and added automatically upon tagging. I've done that before for another project, but that must be agreed on first ...

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @nikomatsakis (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[reeze]

This didn't seems good enough. A released version of rustc should not use a hash rev I think.

Maybe something like rustc 1.7.0 (a9d08eb)

[sanmai-NL]

@reeze: suggestion how to do that?

[reeze]

There seems no way to auto update the version. but I think we could use a shell to get the current version when trying to generate RELEASES.md.

[sanmai-NL]

git describe --tags --long does that, but keep in mind that this line I'm now talking about, at the bottom of the man pages is a different topic than mentioning the version tag elsewhere such as in RELEASE.md. The version should not matter as the man page should also list historical changes to command line options, from that and the date of the tagged commit the manpage references it should be obvious what the relevant Rust version is. Tags can change and differ between copies of a repo, so this is probably why git log does not deal with them.

[hanna-kruppe]

The version number is set in the makefiles (specifically mk/main.mk), variable CFG_RELEASE_NUM. I'm not sure what's the best way to get it into the man page, but that may just be because I know literally nothing about man page preparation.

Beyond the scope of this PR, the state of the man page has bothered me any time I run across it. It needs some love. Putting the current version in there is a good start: it was definitely updated since 1.2. Additionally it could also use an audit (if all information in there is still accurate) and update (it's likely missing stuff).

[brson]

To get version numbers in our releases the template will need to be filled in by our build system - the tarballs produced by git and published by github are incomplete and not used for any purpose. The general outline of how to do this would be:

• Add placeholders to the makefiles, though not necessarily as written in this patch since we won't use git to fill them in
• Modify mk/prepare.mk to, instead of copying the manfiles directly, copy them while substituting the correct values.

The version number is in mk/main.mk as CFG_RELEASE. The date is not, though perhaps we can just change the manfiles to not include the date.

[brson]

rustbuild also needs to change to do the same thing.

[nikomatsakis]

r? @brson (bot must have missed this)

[brson]

Triage: my previous comments still stand. The approach here needs to be elaborated further.

[sanmai-NL]

@brson:
What about automatically applying a patch with patch upon a release that replaces placeholders here and there, from within a CI pipeline? I hope to find time at some point to implement this.

[bors]

☔ The latest upstream changes (presumably #35407) made this pull request unmergeable. Please resolve the merge conflicts.

[brson]

@sanmai-NL Using patch is probably ok, as long as it existst on mingw and works the same on all platforms, though ISTM sed would be easier. In either case the modification should be done inside the build system (both build systems...).

[sanmai-NL]

@brson: I'm weighing the options a bit before proceeding. What about using some very small standard CPython 2/3 code? I have some code ready for placeholder substitution (fully using their standard library). Advantage would be a reduced platform dependency compared to sed and patch and a bit greater robustness (e.g., an exception if specified placeholder wasn't found in input).

[brson]

@sanmai-NL I'm fine with Python 2. The script would go in src/etc. Regarding platform dependency, we've already got multiple sed dependencies on every platform, tying is to unixy build environments.

[brson]

With python you have to be careful to invoke the correct one using the $CFG_PYTHON variable.

[alexcrichton]

Closing due to inactivity, but feel free to resubmit with a rebase!