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 3ef54e0adbad5fbfd4468581037a2dcb9a9a4681..bf2bf271b5678895e94810dcbdca12b0dfb7de91 100644 (file)
--- a/Documentation/.gitignore
+++ b/Documentation/.gitignore
@@ -13,3 +13,4 @@ mergetools-*.txt
 manpage-base-url.xsl
 SubmittingPatches.txt
 tmp-doc-diff/
+GIT-ASCIIDOCFLAGS

diff --git a/Documentation/Makefile b/Documentation/Makefile
index ccac771d3fb5ecb863c64a782a947a76593df397..4e4dd7ecf14919fa3d5735daa6b87c8addcff1e8 100644 (file)
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -331,6 +331,15 @@ mergetools-list.made: ../git-mergetool--lib.sh $(wildcard ../mergetools/*)
                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 @@ clean:
        $(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 @@ manpage-base-url.xsl: manpage-base-url.xsl.in
        $(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 @@ technical/api-index.txt: technical/api-index-skel.txt \
        $(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 @@ $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt
 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 32c83dd26f4adf87fd9d6a3ebc6400f6bc108fc7..3355be479812375d8a01d316d26425c3d14be63d 100755 (executable)
--- a/Documentation/doc-diff
+++ b/Documentation/doc-diff
@@ -12,9 +12,16 @@ OPTIONS_SPEC="\
 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 @@ SUBDIRECTORY_OK=1
 parallel=
 force=
 clean=
+from_program=
+to_program=
+cut_header_footer=
 while test $# -gt 0
 do
        case "$1" in
@@ -31,6 +41,22 @@ do
                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 @@ then
        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 @@ generate_render_makefile () {
        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 @@ render_tree () {
        # 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