Skip to content

Commit 08c9757

Browse files
committed
Merge branch 'ma/doc-diff-doc-vs-doctor-comparison'
Dev support update to make it easier to compare two formatted results from our documentation. * ma/doc-diff-doc-vs-doctor-comparison: doc-diff: add `--cut-header-footer` doc-diff: support diffing from/to AsciiDoc(tor) doc-diff: let `render_tree()` take an explicit directory name Doc: auto-detect changed build flags
2 parents 3221177 + e605077 commit 08c9757

File tree

3 files changed

+90
-20
lines changed

3 files changed

+90
-20
lines changed

Documentation/.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,4 @@ mergetools-*.txt
1313
manpage-base-url.xsl
1414
SubmittingPatches.txt
1515
tmp-doc-diff/
16+
GIT-ASCIIDOCFLAGS

Documentation/Makefile

Lines changed: 17 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -331,6 +331,15 @@ mergetools-list.made: ../git-mergetool--lib.sh $(wildcard ../mergetools/*)
331331
show_tool_names can_merge "* " || :' >mergetools-merge.txt && \
332332
date >$@
333333

334+
TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK))
335+
336+
GIT-ASCIIDOCFLAGS: FORCE
337+
@FLAGS='$(TRACK_ASCIIDOCFLAGS)'; \
338+
if test x"$$FLAGS" != x"`cat GIT-ASCIIDOCFLAGS 2>/dev/null`" ; then \
339+
echo >&2 " * new asciidoc flags"; \
340+
echo "$$FLAGS" >GIT-ASCIIDOCFLAGS; \
341+
fi
342+
334343
clean:
335344
$(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7
336345
$(RM) *.texi *.texi+ *.texi++ git.info gitman.info
@@ -340,13 +349,14 @@ clean:
340349
$(RM) SubmittingPatches.txt
341350
$(RM) $(cmds_txt) $(mergetools_txt) *.made
342351
$(RM) manpage-base-url.xsl
352+
$(RM) GIT-ASCIIDOCFLAGS
343353

344-
$(MAN_HTML): %.html : %.txt asciidoc.conf asciidoctor-extensions.rb
354+
$(MAN_HTML): %.html : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
345355
$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
346356
$(TXT_TO_HTML) -d manpage -o $@+ $< && \
347357
mv $@+ $@
348358

349-
$(OBSOLETE_HTML): %.html : %.txto asciidoc.conf asciidoctor-extensions.rb
359+
$(OBSOLETE_HTML): %.html : %.txto asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
350360
$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
351361
$(TXT_TO_HTML) -o $@+ $< && \
352362
mv $@+ $@
@@ -358,12 +368,12 @@ manpage-base-url.xsl: manpage-base-url.xsl.in
358368
$(QUIET_XMLTO)$(RM) $@ && \
359369
$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
360370

361-
%.xml : %.txt asciidoc.conf asciidoctor-extensions.rb
371+
%.xml : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
362372
$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
363373
$(TXT_TO_XML) -d manpage -o $@+ $< && \
364374
mv $@+ $@
365375

366-
user-manual.xml: user-manual.txt user-manual.conf asciidoctor-extensions.rb
376+
user-manual.xml: user-manual.txt user-manual.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
367377
$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
368378
$(TXT_TO_XML) -d book -o $@+ $< && \
369379
mv $@+ $@
@@ -373,7 +383,8 @@ technical/api-index.txt: technical/api-index-skel.txt \
373383
$(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh
374384

375385
technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
376-
$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt asciidoc.conf
386+
$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt \
387+
asciidoc.conf GIT-ASCIIDOCFLAGS
377388
$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt
378389

379390
SubmittingPatches.txt: SubmittingPatches
@@ -430,7 +441,7 @@ $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt
430441
WEBDOC_DEST = /pub/software/scm/git/docs
431442

432443
howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
433-
$(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt
444+
$(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt GIT-ASCIIDOCFLAGS
434445
$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
435446
sed -e '1,/^$$/d' $< | \
436447
$(TXT_TO_HTML) - >$@+ && \

Documentation/doc-diff

Lines changed: 72 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -12,16 +12,26 @@ OPTIONS_SPEC="\
1212
doc-diff [options] <from> <to> [-- <diff-options>]
1313
doc-diff (-c|--clean)
1414
--
15-
j=n parallel argument to pass to make
16-
f force rebuild; do not rely on cached results
17-
c,clean cleanup temporary working files
15+
j=n parallel argument to pass to make
16+
f force rebuild; do not rely on cached results
17+
c,clean cleanup temporary working files
18+
from-asciidoc use asciidoc with the 'from'-commit
19+
from-asciidoctor use asciidoctor with the 'from'-commit
20+
asciidoc use asciidoc with both commits
21+
to-asciidoc use asciidoc with the 'to'-commit
22+
to-asciidoctor use asciidoctor with the 'to'-commit
23+
asciidoctor use asciidoctor with both commits
24+
cut-header-footer cut away header and footer
1825
"
1926
SUBDIRECTORY_OK=1
2027
. "$(git --exec-path)/git-sh-setup"
2128

2229
parallel=
2330
force=
2431
clean=
32+
from_program=
33+
to_program=
34+
cut_header_footer=
2535
while test $# -gt 0
2636
do
2737
case "$1" in
@@ -31,6 +41,22 @@ do
3141
clean=t ;;
3242
-f)
3343
force=t ;;
44+
--from-asciidoctor)
45+
from_program=-asciidoctor ;;
46+
--to-asciidoctor)
47+
to_program=-asciidoctor ;;
48+
--asciidoctor)
49+
from_program=-asciidoctor
50+
to_program=-asciidoctor ;;
51+
--from-asciidoc)
52+
from_program=-asciidoc ;;
53+
--to-asciidoc)
54+
to_program=-asciidoc ;;
55+
--asciidoc)
56+
from_program=-asciidoc
57+
to_program=-asciidoc ;;
58+
--cut-header-footer)
59+
cut_header_footer=-cut-header-footer ;;
3460
--)
3561
shift; break ;;
3662
*)
@@ -79,6 +105,22 @@ then
79105
ln -s "$dots/config.mak" "$tmp/worktree/config.mak"
80106
fi
81107

108+
construct_makemanflags () {
109+
if test "$1" = "-asciidoc"
110+
then
111+
echo USE_ASCIIDOCTOR=
112+
elif test "$1" = "-asciidoctor"
113+
then
114+
echo USE_ASCIIDOCTOR=YesPlease
115+
fi
116+
}
117+
118+
from_makemanflags=$(construct_makemanflags "$from_program") &&
119+
to_makemanflags=$(construct_makemanflags "$to_program") &&
120+
121+
from_dir=$from_oid$from_program$cut_header_footer &&
122+
to_dir=$to_oid$to_program$cut_header_footer &&
123+
82124
# generate_render_makefile <srcdir> <dstdir>
83125
generate_render_makefile () {
84126
find "$1" -type f |
@@ -94,36 +136,52 @@ generate_render_makefile () {
94136
done
95137
}
96138

97-
# render_tree <committish_oid>
139+
# render_tree <committish_oid> <directory_name> <makemanflags>
98140
render_tree () {
99141
# Skip install-man entirely if we already have an installed directory.
100142
# We can't rely on make here, since "install-man" unconditionally
101143
# copies the files (spending effort, but also updating timestamps that
102144
# we then can't rely on during the render step). We use "mv" to make
103145
# sure we don't get confused by a previous run that failed partway
104146
# through.
105-
if ! test -d "$tmp/installed/$1"
147+
oid=$1 &&
148+
dname=$2 &&
149+
makemanflags=$3 &&
150+
if ! test -d "$tmp/installed/$dname"
106151
then
107-
git -C "$tmp/worktree" checkout --detach "$1" &&
152+
git -C "$tmp/worktree" checkout --detach "$oid" &&
108153
make -j$parallel -C "$tmp/worktree" \
154+
$makemanflags \
109155
GIT_VERSION=omitted \
110156
SOURCE_DATE_EPOCH=0 \
111-
DESTDIR="$tmp/installed/$1+" \
157+
DESTDIR="$tmp/installed/$dname+" \
112158
install-man &&
113-
mv "$tmp/installed/$1+" "$tmp/installed/$1"
159+
mv "$tmp/installed/$dname+" "$tmp/installed/$dname"
114160
fi &&
115161

116162
# As with "installed" above, we skip the render if it's already been
117163
# done. So using make here is primarily just about running in
118164
# parallel.
119-
if ! test -d "$tmp/rendered/$1"
165+
if ! test -d "$tmp/rendered/$dname"
120166
then
121-
generate_render_makefile "$tmp/installed/$1" "$tmp/rendered/$1+" |
167+
generate_render_makefile "$tmp/installed/$dname" \
168+
"$tmp/rendered/$dname+" |
122169
make -j$parallel -f - &&
123-
mv "$tmp/rendered/$1+" "$tmp/rendered/$1"
170+
mv "$tmp/rendered/$dname+" "$tmp/rendered/$dname"
171+
172+
if test "$cut_header_footer" = "-cut-header-footer"
173+
then
174+
for f in $(find "$tmp/rendered/$dname" -type f)
175+
do
176+
tail -n +3 "$f" | head -n -2 |
177+
sed -e '1{/^$/d}' -e '${/^$/d}' >"$f+" &&
178+
mv "$f+" "$f" ||
179+
return 1
180+
done
181+
fi
124182
fi
125183
}
126184

127-
render_tree $from_oid &&
128-
render_tree $to_oid &&
129-
git -C $tmp/rendered diff --no-index "$@" $from_oid $to_oid
185+
render_tree $from_oid $from_dir $from_makemanflags &&
186+
render_tree $to_oid $to_dir $to_makemanflags &&
187+
git -C $tmp/rendered diff --no-index "$@" $from_dir $to_dir

0 commit comments

Comments
 (0)