Makefile: generate doc versions via GIT-VERSION-GEN
The documentation we generate embeds information for the exact Git version used as well as the date of the commit. This information is injected by injecting attributes into the build process via command line argument. Refactor the logic so that we write the information into "asciidoc.conf" and "asciidoctor-extensions.rb" via `GIT-VERSION-GEN` for AsciiDoc and AsciiDoctor, respectively. Signed-off-by: Patrick Steinhardt <ps@pks.im> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Patrick Steinhardt committed
Dec 6, 2024 at 14:24 UTC
a38edab7c88b5503bb2b5f5cbd49f6b97e9a6a4e
5 files changed
+25
-15
Documentation/.gitignore
+2
@@ -15,3 +15,5 @@ tmp-doc-diff/
15
GIT-ASCIIDOCFLAGS
16
/.build/
17
/GIT-EXCLUDED-PROGRAMS
18
+/asciidoc.conf
19
+/asciidoctor-extensions.rb
Documentation/Makefile
+16
-9
@@ -1,6 +1,8 @@
1
# Import tree-wide shared Makefile behavior and libraries
2
include ../shared.mak
3
4
+.PHONY: FORCE
5
+
6
# Guard against environment variables
7
MAN1_TXT =
8
MAN5_TXT =
@@ -148,16 +150,12 @@ man5dir = $(mandir)/man5
150
man7dir = $(mandir)/man7
151
# DESTDIR =
152
151
-GIT_DATE := $(shell git show --quiet --pretty='%as')
152
-
153
ASCIIDOC = asciidoc
154
ASCIIDOC_EXTRA =
155
ASCIIDOC_HTML = xhtml11
156
ASCIIDOC_DOCBOOK = docbook
157
ASCIIDOC_CONF = -f asciidoc.conf
158
-ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \
159
- -amanmanual='Git Manual' -amansource='Git $(GIT_VERSION)' \
160
- -arevdate='$(GIT_DATE)'
158
+ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF)
159
ASCIIDOC_DEPS = asciidoc.conf GIT-ASCIIDOCFLAGS
160
TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)
161
TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK)
@@ -210,6 +208,14 @@ ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
208
DBLATEX_COMMON =
209
XMLTO_EXTRA += --skip-validation
210
XMLTO_EXTRA += -x manpage.xsl
211
+
212
+asciidoctor-extensions.rb: asciidoctor-extensions.rb.in FORCE
213
+ $(QUIET_GEN)GIT_USER_AGENT="$(GIT_USER_AGENT)" $(SHELL_PATH) ../GIT-VERSION-GEN "$(shell pwd)/.." $< $@+
214
+ @if cmp $@+ $@ >/dev/null 2>&1; then $(RM) $@+; else mv $@+ $@; fi
215
+else
216
+asciidoc.conf: asciidoc.conf.in FORCE
217
+ $(QUIET_GEN)GIT_USER_AGENT="$(GIT_USER_AGENT)" $(SHELL_PATH) ../GIT-VERSION-GEN "$(shell pwd)/.." $< $@+
218
+ @if cmp $@+ $@ >/dev/null 2>&1; then $(RM) $@+; else mv $@+ $@; fi
219
endif
220
221
ASCIIDOC_DEPS += docinfo.html
@@ -341,6 +347,7 @@ clean:
347
$(RM) SubmittingPatches.txt
348
$(RM) $(cmds_txt) $(mergetools_txt) *.made
349
$(RM) GIT-ASCIIDOCFLAGS
350
+ $(RM) asciidoc.conf asciidoctor-extensions.rb
351
352
docinfo.html: docinfo-html.in
353
$(QUIET_GEN)$(RM) $@ && cat $< >$@
@@ -364,7 +371,7 @@ manpage-cmd = $(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
371
%.xml : %.txt $(ASCIIDOC_DEPS)
372
$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<
373
367
-user-manual.xml: user-manual.txt user-manual.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
374
+user-manual.xml: user-manual.txt user-manual.conf $(ASCIIDOC_DEPS)
375
$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d book -o $@ $<
376
377
technical/api-index.txt: technical/api-index-skel.txt \
@@ -373,7 +380,7 @@ technical/api-index.txt: technical/api-index-skel.txt \
380
381
technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
382
$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt \
376
- asciidoc.conf GIT-ASCIIDOCFLAGS
383
+ $(ASCIIDOC_DEPS)
384
$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt
385
386
SubmittingPatches.txt: SubmittingPatches
@@ -416,13 +423,13 @@ $(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml
423
howto-index.txt: howto-index.sh $(HOWTO_TXT)
424
$(QUIET_GEN)'$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(HOWTO_TXT)) >$@
425
419
-$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt
426
+$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt $(ASCIIDOC_DEPS)
427
$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt
428
429
WEBDOC_DEST = /pub/software/scm/git/docs
430
431
howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
425
-$(patsubst %.txt,%.html,$(HOWTO_TXT)): %.html : %.txt GIT-ASCIIDOCFLAGS
432
+$(patsubst %.txt,%.html,$(HOWTO_TXT)): %.html : %.txt $(ASCIIDOC_DEPS)
433
$(QUIET_ASCIIDOC) \
434
sed -e '1,/^$$/d' $< | \
435
$(TXT_TO_HTML) - >$@
Documentation/asciidoc.conf.in
renamed
+3
@@ -21,6 +21,9 @@ tilde=~
21
apostrophe='
22
backtick=`
23
litdd=--
24
+manmanual='Git Manual'
25
+mansource='Git @GIT_VERSION@'
26
+revdate='@GIT_DATE@'
27
28
ifdef::backend-docbook[]
29
[linkgit-inlinemacro]
Documentation/asciidoctor-extensions.rb.in
renamed
+2
-6
@@ -29,13 +29,9 @@ module Git
29
class DocumentPostProcessor < Asciidoctor::Extensions::Postprocessor
30
def process document, output
31
if document.basebackend? 'docbook'
32
- mansource = document.attributes['mansource']
33
- manversion = document.attributes['manversion']
34
- manmanual = document.attributes['manmanual']
32
new_tags = "" \
36
- "<refmiscinfo class=\"source\">#{mansource}</refmiscinfo>\n" \
37
- "<refmiscinfo class=\"version\">#{manversion}</refmiscinfo>\n" \
38
- "<refmiscinfo class=\"manual\">#{manmanual}</refmiscinfo>\n"
33
+ "<refmiscinfo class=\"source\">@GIT_VERSION@</refmiscinfo>\n" \
34
+ "<refmiscinfo class=\"manual\">Git Manual</refmiscinfo>\n"
35
output = output.sub(/<\/refmeta>/, new_tags + "</refmeta>")
36
end
37
output
GIT-VERSION-GEN
+2
@@ -53,6 +53,7 @@ fi
53
54
GIT_VERSION=$(expr "$VN" : v*'\(.*\)')
55
GIT_BUILT_FROM_COMMIT=$(git -C "$SOURCE_DIR" rev-parse -q --verify HEAD 2>/dev/null)
56
+GIT_DATE=$(git -C "$SOURCE_DIR" show --quiet --format='%as' 2>/dev/null)
57
if test -z "$GIT_USER_AGENT"
58
then
59
GIT_USER_AGENT="git/$GIT_VERSION"
@@ -72,6 +73,7 @@ sed -e "s|@GIT_VERSION@|$GIT_VERSION|" \
73
-e "s|@GIT_PATCH_LEVEL@|$GIT_PATCH_LEVEL|" \
74
-e "s|@GIT_BUILT_FROM_COMMIT@|$GIT_BUILT_FROM_COMMIT|" \
75
-e "s|@GIT_USER_AGENT@|$GIT_USER_AGENT|" \
76
+ -e "s|@GIT_DATE@|$GIT_DATE|" \
77
"$INPUT" >"$OUTPUT"+
78
79
if ! test -f "$OUTPUT" || ! cmp "$OUTPUT"+ "$OUTPUT" >/dev/null