| Message ID | 20230413074722.71260-1-felipe.contreras@gmail.com (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | 28fde3a1f4322993d731e2b2b6543ba0e24a5788 |
| Headers | show |
| Series | doc: set actual revdate for manpages | expand |
On Thu, Apr 13, 2023 at 01:47:22AM -0600, Felipe Contreras wrote: > manpages expect the date of the last revision, if that is not found > DocBook Stylesheets go through a series of hacks to generate one with > the format `%d/%d/%Y` which is not ideal. > > In addition to this format not being standard, different tools generate > dates with different formats. > > There's no need for any confusion if we specify the revision date, so > let's do so. That seems like a good goal, and should reduce our asciidoc/asciidoctor diff considerably. > This patch requires [1] to actually work, and has a simple conflict with > [2], so it's written on top of both. > > [1] https://lore.kernel.org/git/20230323221523.52472-1-felipe.contreras@gmail.com/ > [2] https://lore.kernel.org/git/20230408001829.11031-1-felipe.contreras@gmail.com/ I wasted a bit of time trying this out, so let me elaborate on "actually work" for the benefit of other reviewers. Without the patch in [1] (which is 8806120de6c on fc/remove-header-workarounds-for-asciidoc), this patch works as advertised with asciidoctor, but has no effect with asciidoc. The reason is that asciidoc puts the <date> tags in the header, and the custom header removed by 8806120de6c suppresses asciidoc's default header entirely (so a workaround would be to include the <date> tags in our custom header, but I don't see any reason not to just build on top of 8806120de6c, as you did here). > diff --git a/Documentation/Makefile b/Documentation/Makefile > index 3133ea3182..b629176d7d 100644 > --- a/Documentation/Makefile > +++ b/Documentation/Makefile > @@ -144,13 +144,16 @@ man5dir = $(mandir)/man5 > man7dir = $(mandir)/man7 > # DESTDIR = > > +GIT_DATE := $(shell git show --quiet --pretty='%as') What will/should this do in a distribution tarball, where we won't have a Git repository at all? I think we'll just end up with a blank date in the xml file, though it looks like docbook turns that into today's date in the result. That's not _too_ bad, but feels a bit inconsistent (and it uses the format you're trying to get rid of!). It would be nicer to populate the date variable in that case, like we do for GIT_VERSION. I think that could look something like this: diff --git a/Documentation/Makefile b/Documentation/Makefile index 2ccc3a9bc9..307634a94f 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -144,8 +144,6 @@ man5dir = $(mandir)/man5 man7dir = $(mandir)/man7 # DESTDIR = -GIT_DATE := $(shell git show --quiet --pretty='%as') - ASCIIDOC = asciidoc ASCIIDOC_EXTRA = ASCIIDOC_HTML = xhtml11 diff --git a/GIT-VERSION-GEN b/GIT-VERSION-GEN index 9a1111af9b..14903bd261 100755 --- a/GIT-VERSION-GEN +++ b/GIT-VERSION-GEN @@ -10,7 +10,8 @@ LF=' # then try git-describe, then default. if test -f version then - VN=$(cat version) || VN="$DEF_VER" + VN=$(cut -d" " -f1 version) || VN="$DEF_VER" + DN=$(cut -d" " -f2 version) || DN="" elif test -d ${GIT_DIR:-.git} -o -f .git && VN=$(git describe --match "v[0-9]*" HEAD 2>/dev/null) && case "$VN" in @@ -22,19 +23,22 @@ elif test -d ${GIT_DIR:-.git} -o -f .git && esac then VN=$(echo "$VN" | sed -e 's/-/./g'); + DN=$(git log -1 --format=%as HEAD) else VN="$DEF_VER" + DN="" fi VN=$(expr "$VN" : v*'\(.*\)') if test -r $GVF then - VC=$(sed -e 's/^GIT_VERSION = //' <$GVF) + VC=$(sed -ne 's/^GIT_VERSION = //p' <$GVF) else VC=unset fi test "$VN" = "$VC" || { echo >&2 "GIT_VERSION = $VN" echo "GIT_VERSION = $VN" >$GVF + echo "GIT_DATE = $DN" >>$GVF } diff --git a/Makefile b/Makefile index 60ab1a8b4f..fa8db1943c 100644 --- a/Makefile +++ b/Makefile @@ -3573,7 +3573,7 @@ endif dist: git-archive$(X) configure @$(RM) -r .dist-tmp-dir @mkdir .dist-tmp-dir - @echo $(GIT_VERSION) > .dist-tmp-dir/version + @echo $(GIT_VERSION) $(GIT_DATE) > .dist-tmp-dir/version @$(MAKE) -C git-gui TARDIR=../.dist-tmp-dir/git-gui dist-version ./git-archive --format=tar \ $(GIT_ARCHIVE_EXTRA_FILES) \
Jeff King wrote: > On Thu, Apr 13, 2023 at 01:47:22AM -0600, Felipe Contreras wrote: > > > manpages expect the date of the last revision, if that is not found > > DocBook Stylesheets go through a series of hacks to generate one with > > the format `%d/%d/%Y` which is not ideal. > > > > In addition to this format not being standard, different tools generate > > dates with different formats. > > > > There's no need for any confusion if we specify the revision date, so > > let's do so. > > That seems like a good goal, and should reduce our asciidoc/asciidoctor > diff considerably. > > > This patch requires [1] to actually work, and has a simple conflict with > > [2], so it's written on top of both. > > > > [1] https://lore.kernel.org/git/20230323221523.52472-1-felipe.contreras@gmail.com/ > > [2] https://lore.kernel.org/git/20230408001829.11031-1-felipe.contreras@gmail.com/ > > I wasted a bit of time trying this out, so let me elaborate on "actually > work" for the benefit of other reviewers. Without the patch in [1] > (which is 8806120de6c on fc/remove-header-workarounds-for-asciidoc), > this patch works as advertised with asciidoctor, but has no effect with > asciidoc. The reason is that asciidoc puts the <date> tags in the > header, and the custom header removed by 8806120de6c suppresses > asciidoc's default header entirely (so a workaround would be to include > the <date> tags in our custom header, but I don't see any reason not to > just build on top of 8806120de6c, as you did here). Yes, I also "wasted" a bit of time comparing the custom header introduced in 7ef195ba3e (Documentation: Add version information to man pages, 2007-03-25) to what is in asciidoc and the difference is simple: --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -56,6 +56,9 @@ ifdef::backend-docbook[] [header] template::[header-declarations] <refentry> +<refentryinfo> +template::[docinfo] +</refentryinfo> <refmeta> <refentrytitle>{mantitle}</refentrytitle> <manvolnum>{manvolnum}</manvolnum> This is of course not needed if we get rid of that custom header, but I sent the patch anyway for reference in a semi-unrelated patch series [1]. But to me the rationale is simple: the information isn't there because we are overriding the asciidoc header and not putting it there. > > diff --git a/Documentation/Makefile b/Documentation/Makefile > > index 3133ea3182..b629176d7d 100644 > > --- a/Documentation/Makefile > > +++ b/Documentation/Makefile > > @@ -144,13 +144,16 @@ man5dir = $(mandir)/man5 > > man7dir = $(mandir)/man7 > > # DESTDIR = > > > > +GIT_DATE := $(shell git show --quiet --pretty='%as') > > What will/should this do in a distribution tarball, where we won't have > a Git repository at all? I think we'll just end up with a blank date in > the xml file, though it looks like docbook turns that into today's date > in the result. > > That's not _too_ bad, but feels a bit inconsistent (and it uses the > format you're trying to get rid of!). > > It would be nicer to populate the date variable in that case, like we do > for GIT_VERSION. I think that could look something like this: Indeed, that would be better, but that totally can be done in a separate patch, or a separate series even. The perfect doesn't have to be the enemy of the good, and that can be done later. In the meantime something is better than nothing. For the record, the GIT-VERSION-GEN script can be simplified a lot, I had a patch from 2013 around, cleaned it up, and sent it a new series, so it should be easier to implement this on top of that [2]. > diff --git a/Documentation/Makefile b/Documentation/Makefile > index 2ccc3a9bc9..307634a94f 100644 > --- a/Documentation/Makefile > +++ b/Documentation/Makefile > @@ -144,8 +144,6 @@ man5dir = $(mandir)/man5 > man7dir = $(mandir)/man7 > # DESTDIR = > > -GIT_DATE := $(shell git show --quiet --pretty='%as') > - > ASCIIDOC = asciidoc > ASCIIDOC_EXTRA = > ASCIIDOC_HTML = xhtml11 > diff --git a/GIT-VERSION-GEN b/GIT-VERSION-GEN > index 9a1111af9b..14903bd261 100755 > --- a/GIT-VERSION-GEN > +++ b/GIT-VERSION-GEN > @@ -10,7 +10,8 @@ LF=' > # then try git-describe, then default. > if test -f version > then > - VN=$(cat version) || VN="$DEF_VER" > + VN=$(cut -d" " -f1 version) || VN="$DEF_VER" > + DN=$(cut -d" " -f2 version) || DN="" Although this works, I have an issue with doing multiple unnecessary forks. This does the same, no? read VN DN <version Cheers. [1] https://lore.kernel.org/git/20230413115745.116063-3-felipe.contreras@gmail.com/ [2] https://lore.kernel.org/git/20230414121841.373980-1-felipe.contreras@gmail.com/
Jeff King <peff@peff.net> writes: > ... The reason is that asciidoc puts the <date> tags in the > header, and the custom header removed by 8806120de6c suppresses > asciidoc's default header entirely (so a workaround would be to include > the <date> tags in our custom header, but I don't see any reason not to > just build on top of 8806120de6c, as you did here). I agree building on what is in-flight instead of making duplicate effort makes sense. >> diff --git a/Documentation/Makefile b/Documentation/Makefile >> index 3133ea3182..b629176d7d 100644 >> --- a/Documentation/Makefile >> +++ b/Documentation/Makefile >> @@ -144,13 +144,16 @@ man5dir = $(mandir)/man5 >> man7dir = $(mandir)/man7 >> # DESTDIR = >> >> +GIT_DATE := $(shell git show --quiet --pretty='%as') > > What will/should this do in a distribution tarball, where we won't have > a Git repository at all? I think we'll just end up with a blank date in > the xml file, though it looks like docbook turns that into today's date > in the result. > > That's not _too_ bad, but feels a bit inconsistent (and it uses the > format you're trying to get rid of!). > > It would be nicer to populate the date variable in that case, like we do > for GIT_VERSION. I think that could look something like this: I did wonder the same "what about tarball" thing while reading this last night and then stopped, and it is good to see somebody else brought it up ;-). I like the "version" approach, as that is already an established way to deal with the same "the builder somehow wants to force the identifying string to a certain value in the build product". > diff --git a/Documentation/Makefile b/Documentation/Makefile > index 2ccc3a9bc9..307634a94f 100644 > --- a/Documentation/Makefile > +++ b/Documentation/Makefile > @@ -144,8 +144,6 @@ man5dir = $(mandir)/man5 > man7dir = $(mandir)/man7 > # DESTDIR = > > -GIT_DATE := $(shell git show --quiet --pretty='%as') > - > ASCIIDOC = asciidoc > ASCIIDOC_EXTRA = > ASCIIDOC_HTML = xhtml11 > diff --git a/GIT-VERSION-GEN b/GIT-VERSION-GEN > index 9a1111af9b..14903bd261 100755 > --- a/GIT-VERSION-GEN > +++ b/GIT-VERSION-GEN > @@ -10,7 +10,8 @@ LF=' > # then try git-describe, then default. > if test -f version > then > - VN=$(cat version) || VN="$DEF_VER" > + VN=$(cut -d" " -f1 version) || VN="$DEF_VER" > + DN=$(cut -d" " -f2 version) || DN="" Are we sure historical GIT_VERSION strings never had a SP in it? I would be very surprised if we did, but the correctness of the approach depends on that assumption. Thanks.
Junio C Hamano wrote: > Jeff King <peff@peff.net> writes: > > diff --git a/Documentation/Makefile b/Documentation/Makefile > > index 2ccc3a9bc9..307634a94f 100644 > > --- a/Documentation/Makefile > > +++ b/Documentation/Makefile > > @@ -144,8 +144,6 @@ man5dir = $(mandir)/man5 > > man7dir = $(mandir)/man7 > > # DESTDIR = > > > > -GIT_DATE := $(shell git show --quiet --pretty='%as') > > - > > ASCIIDOC = asciidoc > > ASCIIDOC_EXTRA = > > ASCIIDOC_HTML = xhtml11 > > diff --git a/GIT-VERSION-GEN b/GIT-VERSION-GEN > > index 9a1111af9b..14903bd261 100755 > > --- a/GIT-VERSION-GEN > > +++ b/GIT-VERSION-GEN > > @@ -10,7 +10,8 @@ LF=' > > # then try git-describe, then default. > > if test -f version > > then > > - VN=$(cat version) || VN="$DEF_VER" > > + VN=$(cut -d" " -f1 version) || VN="$DEF_VER" > > + DN=$(cut -d" " -f2 version) || DN="" > > Are we sure historical GIT_VERSION strings never had a SP in it? > I would be very surprised if we did, but the correctness of the > approach depends on that assumption. Why would that matter? Supposing a hypothetical tarball with a version '0.99 foo', it would have a corresponding GIT-VERSION-GEN (which didn't check for such file until 1.1.1), and it would know how to parse it. In other words: all three are tied together: the 'version' file, the GIT-VERSION-GEN script, and the tarball that has them both.
Felipe Contreras <felipe.contreras@gmail.com> writes: >> > diff --git a/Documentation/Makefile b/Documentation/Makefile >> > index 3133ea3182..b629176d7d 100644 >> > --- a/Documentation/Makefile >> > +++ b/Documentation/Makefile >> > @@ -144,13 +144,16 @@ man5dir = $(mandir)/man5 >> > man7dir = $(mandir)/man7 >> > # DESTDIR = >> > >> > +GIT_DATE := $(shell git show --quiet --pretty='%as') >> >> What will/should this do in a distribution tarball, where we won't have >> a Git repository at all? I think we'll just end up with a blank date in >> the xml file, though it looks like docbook turns that into today's date >> in the result. >> >> That's not _too_ bad, but feels a bit inconsistent (and it uses the >> format you're trying to get rid of!). >> >> It would be nicer to populate the date variable in that case, like we do >> for GIT_VERSION. I think that could look something like this: > > Indeed, that would be better, but that totally can be done in a separate patch, > or a separate series even. Seeing Peff's change, it sounds so small a thing that it feels a bit unnatural not to do that in the same series, at least to me. Having said that, I think that "we make progress one step at a time" is perfectly acceptable and may even be preferred, as long as the formatted manpages from the tarball would not change between with and without this patch. That way, we make the output from a repository better while keeping the output from a tarball extract intact, and make the latter match the former in a later effort. So, I "wasted" (not really---this was a fruitful validation that is a part of a review process) some time to play with this on top of 'seen' to see how well the tarball extract fares. We get an error message from "git show" complaining about "not a git repository" but that is to be expected ("sh GIT-VERSION-GEN" does not share the problem, though). At least with the versions of toolchain picked by default in my environment, I seem to be getting identical "04/14/2023" in a directory extracted out of a tarball taken from 'seen' (with and without this patch) in the formatted manpages, because we do not have any record in the input either way. Formatted output from a repository working tree changes from "04/14/2023" to "2023-04-13". The value change may be intended, but I am not sure if the format change was intended or even welcome. If we want to correct the date format, it can totally be done in a separate patch, or a separate series even, with some justification in the proposed log message, I think. Thanks.
Junio C Hamano <gitster@pobox.com> writes: > Formatted output from a repository working tree changes from > "04/14/2023" to "2023-04-13". The value change may be intended,... Forgot to mention another thing. While it may be a good idea to tie the datestamp etched in the formatted result to that of the source material, rather than the date the formatter happened to have been run, the committer date is more appropriate than the author date for that purpose, as the former is the date that the change made on the latter date (which is earlier) has become a part of the whole, from which the formatted result was produced. It may not make a big practical difference: * For an individual who is trying out the changes just made, the committer time and the author time are likely identical. * For a release process, what is at the tip of the released branch is likely be the release notes and version bump, recorded by the releaser, and again the committer time and the author time are likely identical. * For results of a pull request, the times are likely identical for the merge commit. but from the philosophical standpoint, it does matter. Using the committer time would give us one more justification to use one single timestamp from the commit, when people complain "this manual page, as opposed to the other one that was changed in the latest release, has not seen any need to be updated for the past 3 years, yet the formatted output for these two manual pages carry the same date".
Felipe Contreras <felipe.contreras@gmail.com> writes: >> Are we sure historical GIT_VERSION strings never had a SP in it? >> I would be very surprised if we did, but the correctness of the >> approach depends on that assumption. > > Why would that matter? Ah, that is true. What I should have worried more about was the distribution package maintainers who may set their own version by writing it in the "version" file themselves. Thanks.
Junio C Hamano wrote: > Felipe Contreras <felipe.contreras@gmail.com> writes: > > >> > diff --git a/Documentation/Makefile b/Documentation/Makefile > >> > index 3133ea3182..b629176d7d 100644 > >> > --- a/Documentation/Makefile > >> > +++ b/Documentation/Makefile > >> > @@ -144,13 +144,16 @@ man5dir = $(mandir)/man5 > >> > man7dir = $(mandir)/man7 > >> > # DESTDIR = > >> > > >> > +GIT_DATE := $(shell git show --quiet --pretty='%as') > >> > >> What will/should this do in a distribution tarball, where we won't have > >> a Git repository at all? I think we'll just end up with a blank date in > >> the xml file, though it looks like docbook turns that into today's date > >> in the result. > >> > >> That's not _too_ bad, but feels a bit inconsistent (and it uses the > >> format you're trying to get rid of!). > >> > >> It would be nicer to populate the date variable in that case, like we do > >> for GIT_VERSION. I think that could look something like this: > > > > Indeed, that would be better, but that totally can be done in a separate patch, > > or a separate series even. > > Seeing Peff's change, it sounds so small a thing that it feels a bit > unnatural not to do that in the same series, at least to me. It should be a small thing, but the GIT-VERSION-GEN script has not been updated since 2008 and has a lot of issues (from my point of view). I think it should be cleaned up first (I already sent a patch series for that), *then* it would be trivial to add another field. But that would add another (unncessary) dependency to this series. > Having said that, I think that "we make progress one step at a time" > is perfectly acceptable and may even be preferred, as long as the > formatted manpages from the tarball would not change between with > and without this patch. That way, we make the output from a > repository better while keeping the output from a tarball extract > intact, and make the latter match the former in a later effort. > > So, I "wasted" (not really---this was a fruitful validation that is > a part of a review process) some time to play with this on top of > 'seen' to see how well the tarball extract fares. We get an error > message from "git show" complaining about "not a git repository" but > that is to be expected ("sh GIT-VERSION-GEN" does not share the > problem, though). > > At least with the versions of toolchain picked by default in my > environment, I seem to be getting identical "04/14/2023" in a > directory extracted out of a tarball taken from 'seen' (with and > without this patch) in the formatted manpages, because we do not > have any record in the input either way. > > Formatted output from a repository working tree changes from > "04/14/2023" to "2023-04-13". The value change may be intended, but > I am not sure if the format change was intended or even welcome. I live in the vast majority of countries where MM/DD/YYYY makes absolutely no sense, so I think it's a plus if any man pages have a sane date. I'm pretty sure I'm not alone on this, but some might disagree. > If we want to correct the date format, it can totally be done in a > separate patch, or a separate series even, with some justification in > the proposed log message, I think. Sure, but in order to do that we would need a way to convert the sane standard git dates to USA-centric dates, and I'm not so sure the tidyness of having both dates wrong is worth it. Would you consider something like this more welcome? GIT_DATE := $(shell git show --quiet --pretty='%as' | sed -e 's|^\(.\+\)-\(.\+\)-\(.\+\)$|\2/\3/\1|'
Junio C Hamano wrote: > Junio C Hamano <gitster@pobox.com> writes: > > > Formatted output from a repository working tree changes from > > "04/14/2023" to "2023-04-13". The value change may be intended,... > > Forgot to mention another thing. While it may be a good idea to tie > the datestamp etched in the formatted result to that of the source > material, rather than the date the formatter happened to have been > run, the committer date is more appropriate than the author date for > that purpose, as the former is the date that the change made on the > latter date (which is earlier) has become a part of the whole, from > which the formatted result was produced. > > It may not make a big practical difference: Or _any_ practical difference. > * For an individual who is trying out the changes just made, the > committer time and the author time are likely identical. > > * For a release process, what is at the tip of the released branch > is likely be the release notes and version bump, recorded by the > releaser, and again the committer time and the author time are > likely identical. > > * For results of a pull request, the times are likely identical for > the merge commit. Agreed that committer == author in these cases. > but from the philosophical standpoint, it does matter. I prefer to focus on the real rather than hypothetical (or philosophical). I do create my own releases (e.g. 2.40.0+fc1) and a real issue with the version script (rather than philosphical) is that it only considers annotated tags, so I have to carry a patch that adds `--tags` to the `git describe` command. Shouldn't dealing with real issues of real people have a higher priority than philosophical issues? For the record, I do agree the committer date feels more proper, but it doesn't make any real difference, I just wonder about the priorities. Cheers.
Junio C Hamano wrote: > Felipe Contreras <felipe.contreras@gmail.com> writes: > > >> Are we sure historical GIT_VERSION strings never had a SP in it? > >> I would be very surprised if we did, but the correctness of the > >> approach depends on that assumption. > > > > Why would that matter? > > Ah, that is true. What I should have worried more about was the > distribution package maintainers who may set their own version by > writing it in the "version" file themselves. In reality they don't do that. I checked Arch Linux, Fedora, and Debian, and all of them leave the version alone. It does make sense becasue for example in Arch Linux `2.40.0-1` means version `2.40.0`, release `1`. I believe all packaging systems use the same semantical distinction. I asked ChatGPT, and this is what it said about `-1`: -1 is the package release number. This number is used by the package maintainers to indicate how many times the package has been built and released. This number is typically incremented each time a new build of the package is released, even if the underlying software has not changed. So it makes sense for `git --version` to return the upstream version, not the package release number, and that's why packagers don't mess with that. Either way, even though I don't think it matters in practice, I generally prefer to separate fields with tabs, or even newlines. If you consider this an issue, we could do: printf '%s\n' $(GIT_VERSION) $(GIT_DATE) >version read -d'' VN DN <version Cheers.
On Fri, Apr 14, 2023 at 06:40:05AM -0600, Felipe Contreras wrote: > > It would be nicer to populate the date variable in that case, like we do > > for GIT_VERSION. I think that could look something like this: > > Indeed, that would be better, but that totally can be done in a separate patch, > or a separate series even. > > The perfect doesn't have to be the enemy of the good, and that can be done > later. > > In the meantime something is better than nothing. Sometimes, as long as it is not making the status quo worse in the meantime. In this case, if the tarball build continues to use the current date (which it appears to), then it's not changing. It does become inconsistent with the output you get from building in-repo, which is unfortunate. But that might be acceptable. If so, it would make sense to document that decision in the commit message. We'd also want to suppress stderr from the Git invocation so that tarball builders don't see a confusing error message. And probably we should avoid using the "git show" porcelain in a script. I think: git rev-list -1 --no-commit-header --format=%as HEAD would do what you want (or %cs; I don't have a strong opinion there). > > --- a/GIT-VERSION-GEN > > +++ b/GIT-VERSION-GEN > > @@ -10,7 +10,8 @@ LF=' > > # then try git-describe, then default. > > if test -f version > > then > > - VN=$(cat version) || VN="$DEF_VER" > > + VN=$(cut -d" " -f1 version) || VN="$DEF_VER" > > + DN=$(cut -d" " -f2 version) || DN="" > > Although this works, I have an issue with doing multiple unnecessary forks. > > This does the same, no? > > read VN DN <version Yeah, that should be fine. The original could probably be using "read" in the first place. In general it's worth micro-optimizing this script because it runs on every single "make" invocation, though this code path in particular is only run for tarball builders (who presumably build a lot less than developers). It might also be worth just putting the two fields in two separate files, if there's any question of spaces in the version field. -Peff
On Fri, Apr 14, 2023 at 09:46:19AM -0700, Junio C Hamano wrote: > So, I "wasted" (not really---this was a fruitful validation that is > a part of a review process) some time to play with this on top of The word "wasted" is appearing in a lot of people's emails in this thread. ;) So let me just clarify that in the original I meant that I spent time puzzling over why it was not working, which was a waste because Felipe had already said it required the other patch. It definitely would have helped if he had explained _why_ the other patch was necessary. But to be fair, the fault was at least as much mine for not heeding what he did say. But reviewers reproducing and tinkering is most certainly not a waste of time in general, and I didn't mean to imply it was (or that the patch itself was a waste of time). > Formatted output from a repository working tree changes from > "04/14/2023" to "2023-04-13". The value change may be intended, but > I am not sure if the format change was intended or even welcome. If > we want to correct the date format, it can totally be done in a > separate patch, or a separate series even, with some justification > in the proposed log message, I think. I think the change is welcome and intended. I would not mind seeing the two changes (format change, and using commit date versus "now") conceptually split, but I think it's much more tangled. Asciidoctor is already producing y-m-d dates, and python asciidoc is using m/d/y. Changing the latter requires passing in not just a format but the actual date. If we want it to be the current date, then we have to get that from somewhere, which may introduce portability questions (e.g., can we rely on "date"?). So doing it all in one patch, though this conversation may indicate that the commit message could do a better job of explaining the goal and implications. -Peff
Jeff King <peff@peff.net> writes: > So doing it all in one patch, though this conversation may indicate that > the commit message could do a better job of explaining the goal and > implications. I can read both formats, and if we are moving in the direction to be consistent between AsciiDoc and asciidoctor, that is good. As long as the design decision is documented well in the proposed commit log message, I would not complain ;-). Thanks.
diff --git a/Documentation/Makefile b/Documentation/Makefile index 3133ea3182..b629176d7d 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -144,13 +144,16 @@ man5dir = $(mandir)/man5 man7dir = $(mandir)/man7 # DESTDIR = +GIT_DATE := $(shell git show --quiet --pretty='%as') + ASCIIDOC = asciidoc ASCIIDOC_EXTRA = ASCIIDOC_HTML = xhtml11 ASCIIDOC_DOCBOOK = docbook ASCIIDOC_CONF = -f asciidoc.conf ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \ - -amanmanual='Git Manual' -amansource='Git $(GIT_VERSION)' + -amanmanual='Git Manual' -amansource='Git $(GIT_VERSION)' \ + -arevdate='$(GIT_DATE)' ASCIIDOC_DEPS = asciidoc.conf GIT-ASCIIDOCFLAGS TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML) TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK)
manpages expect the date of the last revision, if that is not found DocBook Stylesheets go through a series of hacks to generate one with the format `%d/%d/%Y` which is not ideal. In addition to this format not being standard, different tools generate dates with different formats. There's no need for any confusion if we specify the revision date, so let's do so. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> --- This patch requires [1] to actually work, and has a simple conflict with [2], so it's written on top of both. [1] https://lore.kernel.org/git/20230323221523.52472-1-felipe.contreras@gmail.com/ [2] https://lore.kernel.org/git/20230408001829.11031-1-felipe.contreras@gmail.com/ Documentation/Makefile | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-)