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
diff --git a/Documentation/.gitignore b/Documentation/.gitignore
index 3ef54e0..bf2bf27 100644
--- a/Documentation/.gitignore
+++ b/Documentation/.gitignore
@@ -13,3 +13,4 @@
manpage-base-url.xsl
SubmittingPatches.txt
tmp-doc-diff/
+GIT-ASCIIDOCFLAGS
diff --git a/Documentation/Makefile b/Documentation/Makefile
index ccac771..4e4dd7e 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -331,6 +331,15 @@
show_tool_names can_merge "* " || :' >mergetools-merge.txt && \
date >$@
+TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK))
+
+GIT-ASCIIDOCFLAGS: FORCE
+ @FLAGS='$(TRACK_ASCIIDOCFLAGS)'; \
+ if test x"$$FLAGS" != x"`cat GIT-ASCIIDOCFLAGS 2>/dev/null`" ; then \
+ echo >&2 " * new asciidoc flags"; \
+ echo "$$FLAGS" >GIT-ASCIIDOCFLAGS; \
+ fi
+
clean:
$(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7
$(RM) *.texi *.texi+ *.texi++ git.info gitman.info
@@ -340,13 +349,14 @@
$(RM) SubmittingPatches.txt
$(RM) $(cmds_txt) $(mergetools_txt) *.made
$(RM) manpage-base-url.xsl
+ $(RM) GIT-ASCIIDOCFLAGS
-$(MAN_HTML): %.html : %.txt asciidoc.conf asciidoctor-extensions.rb
+$(MAN_HTML): %.html : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
$(TXT_TO_HTML) -d manpage -o $@+ $< && \
mv $@+ $@
-$(OBSOLETE_HTML): %.html : %.txto asciidoc.conf asciidoctor-extensions.rb
+$(OBSOLETE_HTML): %.html : %.txto asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
$(TXT_TO_HTML) -o $@+ $< && \
mv $@+ $@
@@ -358,12 +368,12 @@
$(QUIET_XMLTO)$(RM) $@ && \
$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
-%.xml : %.txt asciidoc.conf asciidoctor-extensions.rb
+%.xml : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
$(TXT_TO_XML) -d manpage -o $@+ $< && \
mv $@+ $@
-user-manual.xml: user-manual.txt user-manual.conf asciidoctor-extensions.rb
+user-manual.xml: user-manual.txt user-manual.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
$(TXT_TO_XML) -d book -o $@+ $< && \
mv $@+ $@
@@ -373,7 +383,8 @@
$(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh
technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
-$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt asciidoc.conf
+$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt \
+ asciidoc.conf GIT-ASCIIDOCFLAGS
$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt
SubmittingPatches.txt: SubmittingPatches
@@ -430,7 +441,7 @@
WEBDOC_DEST = /pub/software/scm/git/docs
howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
-$(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt
+$(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt GIT-ASCIIDOCFLAGS
$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
sed -e '1,/^$$/d' $< | \
$(TXT_TO_HTML) - >$@+ && \
diff --git a/Documentation/doc-diff b/Documentation/doc-diff
index 32c83dd..3355be4 100755
--- a/Documentation/doc-diff
+++ b/Documentation/doc-diff
@@ -12,9 +12,16 @@
doc-diff [options] <from> <to> [-- <diff-options>]
doc-diff (-c|--clean)
--
-j=n parallel argument to pass to make
-f force rebuild; do not rely on cached results
-c,clean cleanup temporary working files
+j=n parallel argument to pass to make
+f force rebuild; do not rely on cached results
+c,clean cleanup temporary working files
+from-asciidoc use asciidoc with the 'from'-commit
+from-asciidoctor use asciidoctor with the 'from'-commit
+asciidoc use asciidoc with both commits
+to-asciidoc use asciidoc with the 'to'-commit
+to-asciidoctor use asciidoctor with the 'to'-commit
+asciidoctor use asciidoctor with both commits
+cut-header-footer cut away header and footer
"
SUBDIRECTORY_OK=1
. "$(git --exec-path)/git-sh-setup"
@@ -22,6 +29,9 @@
parallel=
force=
clean=
+from_program=
+to_program=
+cut_header_footer=
while test $# -gt 0
do
case "$1" in
@@ -31,6 +41,22 @@
clean=t ;;
-f)
force=t ;;
+ --from-asciidoctor)
+ from_program=-asciidoctor ;;
+ --to-asciidoctor)
+ to_program=-asciidoctor ;;
+ --asciidoctor)
+ from_program=-asciidoctor
+ to_program=-asciidoctor ;;
+ --from-asciidoc)
+ from_program=-asciidoc ;;
+ --to-asciidoc)
+ to_program=-asciidoc ;;
+ --asciidoc)
+ from_program=-asciidoc
+ to_program=-asciidoc ;;
+ --cut-header-footer)
+ cut_header_footer=-cut-header-footer ;;
--)
shift; break ;;
*)
@@ -79,6 +105,22 @@
ln -s "$dots/config.mak" "$tmp/worktree/config.mak"
fi
+construct_makemanflags () {
+ if test "$1" = "-asciidoc"
+ then
+ echo USE_ASCIIDOCTOR=
+ elif test "$1" = "-asciidoctor"
+ then
+ echo USE_ASCIIDOCTOR=YesPlease
+ fi
+}
+
+from_makemanflags=$(construct_makemanflags "$from_program") &&
+to_makemanflags=$(construct_makemanflags "$to_program") &&
+
+from_dir=$from_oid$from_program$cut_header_footer &&
+to_dir=$to_oid$to_program$cut_header_footer &&
+
# generate_render_makefile <srcdir> <dstdir>
generate_render_makefile () {
find "$1" -type f |
@@ -94,7 +136,7 @@
done
}
-# render_tree <committish_oid>
+# render_tree <committish_oid> <directory_name> <makemanflags>
render_tree () {
# Skip install-man entirely if we already have an installed directory.
# We can't rely on make here, since "install-man" unconditionally
@@ -102,28 +144,44 @@
# we then can't rely on during the render step). We use "mv" to make
# sure we don't get confused by a previous run that failed partway
# through.
- if ! test -d "$tmp/installed/$1"
+ oid=$1 &&
+ dname=$2 &&
+ makemanflags=$3 &&
+ if ! test -d "$tmp/installed/$dname"
then
- git -C "$tmp/worktree" checkout --detach "$1" &&
+ git -C "$tmp/worktree" checkout --detach "$oid" &&
make -j$parallel -C "$tmp/worktree" \
+ $makemanflags \
GIT_VERSION=omitted \
SOURCE_DATE_EPOCH=0 \
- DESTDIR="$tmp/installed/$1+" \
+ DESTDIR="$tmp/installed/$dname+" \
install-man &&
- mv "$tmp/installed/$1+" "$tmp/installed/$1"
+ mv "$tmp/installed/$dname+" "$tmp/installed/$dname"
fi &&
# As with "installed" above, we skip the render if it's already been
# done. So using make here is primarily just about running in
# parallel.
- if ! test -d "$tmp/rendered/$1"
+ if ! test -d "$tmp/rendered/$dname"
then
- generate_render_makefile "$tmp/installed/$1" "$tmp/rendered/$1+" |
+ generate_render_makefile "$tmp/installed/$dname" \
+ "$tmp/rendered/$dname+" |
make -j$parallel -f - &&
- mv "$tmp/rendered/$1+" "$tmp/rendered/$1"
+ mv "$tmp/rendered/$dname+" "$tmp/rendered/$dname"
+
+ if test "$cut_header_footer" = "-cut-header-footer"
+ then
+ for f in $(find "$tmp/rendered/$dname" -type f)
+ do
+ tail -n +3 "$f" | head -n -2 |
+ sed -e '1{/^$/d}' -e '${/^$/d}' >"$f+" &&
+ mv "$f+" "$f" ||
+ return 1
+ done
+ fi
fi
}
-render_tree $from_oid &&
-render_tree $to_oid &&
-git -C $tmp/rendered diff --no-index "$@" $from_oid $to_oid
+render_tree $from_oid $from_dir $from_makemanflags &&
+render_tree $to_oid $to_dir $to_makemanflags &&
+git -C $tmp/rendered diff --no-index "$@" $from_dir $to_dir
