doc-diff: add `--cut-header-footer`

AsciiDoc and Asciidoctor do not agree on what to write in the header and
footer of each man-page, i.e., the very first and the very last line of
*.[157]. Those differences can certainly be interesting in their own
right, but they clutter the output of `./doc-diff --from-asciidoc
--to-asciidoctor HEAD HEAD` quite a bit since the diff contains some
10-15 lines of noise per file diffed.

Teach doc-diff to cut away the first two and last two lines, i.e., the
header/footer and the empty line immediately following/preceding it.
Because Asciidoctor uses an extra empty line compared to AsciiDoc,
remove one more line at each end of the file, but only if it's empty.

An alternative approach might be to pass down `--no-header-footer`,
which both AsciiDoc and Asciidoctor understand, but it has some
drawbacks. First of all, the result doesn't build -- `xmlto` stumbles on
the resulting xml since it has multiple root elements. Second, it cuts
too much -- dropping the header loses the synopsis, which would be
interesting to diff.

Like in the previous commit, encode this option into the directory name
of the "installed" and "rendered" files. Otherwise, we wouldn't be able
to trust that what we use out of that cache actually corresponds to the
options given for this run. (We could optimize this caching a little
since this flag doesn't affect the contents of "installed" at all, but
let's punt on that.)

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/doc-diff b/Documentation/doc-diff
index 36fc2307a795ccac4f107fe3fb556ade1af9e2fa..3355be479812375d8a01d316d26425c3d14be63d 100755 (executable)
--- a/Documentation/doc-diff
+++ b/Documentation/doc-diff
@@ -21,6 +21,7 @@ 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"
@@ -30,6 +31,7 @@ force=
 clean=
 from_program=
 to_program=
+cut_header_footer=
 while test $# -gt 0
 do
        case "$1" in
@@ -53,6 +55,8 @@ do
        --asciidoc)
                from_program=-asciidoc
                to_program=-asciidoc ;;
+       --cut-header-footer)
+               cut_header_footer=-cut-header-footer ;;
        --)
                shift; break ;;
        *)
@@ -114,8 +118,8 @@ construct_makemanflags () {
 from_makemanflags=$(construct_makemanflags "$from_program") &&
 to_makemanflags=$(construct_makemanflags "$to_program") &&
 
-from_dir=$from_oid$from_program &&
-to_dir=$to_oid$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 () {
@@ -164,6 +168,17 @@ render_tree () {
                        "$tmp/rendered/$dname+" |
                make -j$parallel -f - &&
                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
 }