{"thread":{"id":"50767","subject":"[PATCH 0/4] doc-diff: support diffing from/to AsciiDoc(tor)","startedAt":"2019-03-17T18:36:39Z","lastAt":"2019-03-20T20:12:08Z","messageCount":8,"participants":["Martin Ågren","Junio C Hamano","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":4},"messages":[{"id":"371741","messageId":"cover.1552838239.git.martin.agren@gmail.com","threadId":"50767","inReplyTo":null,"subject":"[PATCH 0/4] doc-diff: support diffing from/to AsciiDoc(tor)","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2019-03-17T18:35:59Z","receivedAt":"2019-03-17T18:36:39Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"I've taught `doc-diff` a few new knobs to support usage like\n\n $ ./doc-diff --from-asciidoc --to-asciidoctor HEAD HEAD\n\nand I don't think I've messed it up too badly in the process. I'm open\nto the idea that this might not be interesting to a whole lot of people.\nBut I have made some progress on fixing up Asciidoctor *and* AsciiDoc\nissues using this, and once the output of the above command is empty --\nwhich might not be too far off -- it could be interesting to try and\nkeep it that way using a bit of automation around these switches.\n\nWhile using/testing these patches, I've made some progress on the\nrendering of the headers and footers in Asciidoctor [1], so the\n`--cut-header-footer` switch that I'm adding in the final patch might\nhopefully not be necessary for too long. But we'd still need a\n`--cut-footer` switch -- at least I would, on my system [2]. If this\nseries is considered generally sane, I'd be happy to rework the final\npatch to `--cut-header` if that's preferred.\n\nPatch 1 has a minor purely-textual merge conflict with\nma/asciidoctor-fixes.\n\n[1] https://public-inbox.org/git/20190317144747.2418514-1-martin.agren@gmail.com/\n\n[2] After [1], the date in the footer is still formatted differently\n here. It might be a locale thing, and I tend to shy away from even\n trying to understand those. :-/\n\nMartin Ågren (4):\n Doc: auto-detect changed build flags\n doc-diff: let `render_tree()` take an explicit directory name\n doc-diff: support diffing from/to AsciiDoc(tor)\n doc-diff: add `--cut-header-footer`\n\n Documentation/.gitignore | 1 +\n Documentation/Makefile | 23 ++++++++---\n Documentation/doc-diff | 86 +++++++++++++++++++++++++++++++++-------\n 3 files changed, 90 insertions(+), 20 deletions(-)\n\n-- \n2.21.0\n\n"},{"id":"371742","messageId":"d35014bf3733b24f674510eaf428e05f74bf20be.1552838239.git.martin.agren@gmail.com","threadId":"50767","inReplyTo":"cover.1552838239.git.martin.agren@gmail.com","subject":"[PATCH 1/4] Doc: auto-detect changed build flags","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2019-03-17T18:36:00Z","receivedAt":"2019-03-17T18:36:57Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"If you build the documentation switching between different options,\ne.g., to build with both Asciidoc and Asciidoctor, you'll probably find\nyourself running `make -C Documentation clean` either too often (wasting\ntime) or too rarely (getting mixed builds).\n\nTrack the flags we're using in the documentation build, similar to how\nthe main Makefile tracks CFLAGS and prefix flags. Track ASCIIDOC_COMMON\ndirectly rather than its individual components -- that should make it\nharder to forget to update the tracking if/when we modify the build\ncommands.\n\nSigned-off-by: Martin Ågren \n---\n Documentation/.gitignore | 1 +\n Documentation/Makefile | 23 +++++++++++++++++------\n 2 files changed, 18 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/.gitignore b/Documentation/.gitignore\nindex 3ef54e0adb..bf2bf271b5 100644\n--- a/Documentation/.gitignore\n+++ b/Documentation/.gitignore\n@@ -13,3 +13,4 @@ mergetools-*.txt\n manpage-base-url.xsl\n SubmittingPatches.txt\n tmp-doc-diff/\n+GIT-ASCIIDOCFLAGS\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 26a2342bea..b534623012 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -331,6 +331,15 @@ mergetools-list.made: ../git-mergetool--lib.sh $(wildcard ../mergetools/*)\n \t\tshow_tool_names can_merge \"* \" || :' >mergetools-merge.txt && \\\n \tdate >$@\n \n+TRACK_ASCIIDOCFLAGS = $(subst ','\\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK))\n+\n+GIT-ASCIIDOCFLAGS: FORCE\n+\t@FLAGS='$(TRACK_ASCIIDOCFLAGS)'; \\\n+\t if test x\"$$FLAGS\" != x\"`cat GIT-ASCIIDOCFLAGS 2>/dev/null`\" ; then \\\n+\t\techo >&2 \" * new asciidoc flags\"; \\\n+\t\techo \"$$FLAGS\" >GIT-ASCIIDOCFLAGS; \\\n+ fi\n+\n clean:\n \t$(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7\n \t$(RM) *.texi *.texi+ *.texi++ git.info gitman.info\n@@ -340,13 +349,14 @@ clean:\n \t$(RM) SubmittingPatches.txt\n \t$(RM) $(cmds_txt) $(mergetools_txt) *.made\n \t$(RM) manpage-base-url.xsl\n+\t$(RM) GIT-ASCIIDOCFLAGS\n \n-$(MAN_HTML): %.html : %.txt asciidoc.conf\n+$(MAN_HTML): %.html : %.txt asciidoc.conf GIT-ASCIIDOCFLAGS\n \t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n \t$(TXT_TO_HTML) -d manpage -o $@+ $< && \\\n \tmv $@+ $@\n \n-$(OBSOLETE_HTML): %.html : %.txto asciidoc.conf\n+$(OBSOLETE_HTML): %.html : %.txto asciidoc.conf GIT-ASCIIDOCFLAGS\n \t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n \t$(TXT_TO_HTML) -o $@+ $< && \\\n \tmv $@+ $@\n@@ -358,12 +368,12 @@ manpage-base-url.xsl: manpage-base-url.xsl.in\n \t$(QUIET_XMLTO)$(RM) $@ && \\\n \t$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<\n \n-%.xml : %.txt asciidoc.conf\n+%.xml : %.txt asciidoc.conf GIT-ASCIIDOCFLAGS\n \t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n \t$(TXT_TO_XML) -d manpage -o $@+ $< && \\\n \tmv $@+ $@\n \n-user-manual.xml: user-manual.txt user-manual.conf\n+user-manual.xml: user-manual.txt user-manual.conf GIT-ASCIIDOCFLAGS\n \t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n \t$(TXT_TO_XML) -d book -o $@+ $< && \\\n \tmv $@+ $@\n@@ -373,7 +383,8 @@ technical/api-index.txt: technical/api-index-skel.txt \\\n \t$(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh\n \n technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../\n-$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt asciidoc.conf\n+$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt \\\n+\tasciidoc.conf GIT-ASCIIDOCFLAGS\n \t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt\n \n SubmittingPatches.txt: SubmittingPatches\n@@ -430,7 +441,7 @@ $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt\n WEBDOC_DEST = /pub/software/scm/git/docs\n \n howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../\n-$(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt\n+$(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt GIT-ASCIIDOCFLAGS\n \t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n \tsed -e '1,/^$$/d' $< | \\\n \t$(TXT_TO_HTML) - >$@+ && \\\n-- \n2.21.0\n\n"},{"id":"371743","messageId":"249372bed148417dcc77423f53e7f5f7d7a67757.1552838239.git.martin.agren@gmail.com","threadId":"50767","inReplyTo":"cover.1552838239.git.martin.agren@gmail.com","subject":"[PATCH 2/4] doc-diff: let `render_tree()` take an explicit directory name","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2019-03-17T18:36:01Z","receivedAt":"2019-03-17T18:37:01Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"In `render_tree()`, `$1` is documented to be the commit-ish/oid and we\nuse it as that with `git checkout`, but we mostly use it to form the\nname of various directories. To separate these concerns, and because we\nare about to construct the directory names a bit differently, take two\ndistinct arguments instead.\n\nSigned-off-by: Martin Ågren \n---\n Documentation/doc-diff | 28 +++++++++++++++++-----------\n 1 file changed, 17 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/doc-diff b/Documentation/doc-diff\nindex 32c83dd26f..3e975d3c5d 100755\n--- a/Documentation/doc-diff\n+++ b/Documentation/doc-diff\n@@ -79,6 +79,9 @@ then\n \tln -s \"$dots/config.mak\" \"$tmp/worktree/config.mak\"\n fi\n \n+from_dir=$from_oid &&\n+to_dir=$to_oid &&\n+\n # generate_render_makefile \n generate_render_makefile () {\n \tfind \"$1\" -type f |\n@@ -94,7 +97,7 @@ generate_render_makefile () {\n \tdone\n }\n \n-# render_tree \n+# render_tree \n render_tree () {\n \t# Skip install-man entirely if we already have an installed directory.\n \t# We can't rely on make here, since \"install-man\" unconditionally\n@@ -102,28 +105,31 @@ render_tree () {\n \t# we then can't rely on during the render step). We use \"mv\" to make\n \t# sure we don't get confused by a previous run that failed partway\n \t# through.\n-\tif ! test -d \"$tmp/installed/$1\"\n+\toid=$1 &&\n+\tdname=$2 &&\n+\tif ! test -d \"$tmp/installed/$dname\"\n \tthen\n-\t\tgit -C \"$tmp/worktree\" checkout --detach \"$1\" &&\n+\t\tgit -C \"$tmp/worktree\" checkout --detach \"$oid\" &&\n \t\tmake -j$parallel -C \"$tmp/worktree\" \\\n \t\t\tGIT_VERSION=omitted \\\n \t\t\tSOURCE_DATE_EPOCH=0 \\\n-\t\t\tDESTDIR=\"$tmp/installed/$1+\" \\\n+\t\t\tDESTDIR=\"$tmp/installed/$dname+\" \\\n \t\t\tinstall-man &&\n-\t\tmv \"$tmp/installed/$1+\" \"$tmp/installed/$1\"\n+\t\tmv \"$tmp/installed/$dname+\" \"$tmp/installed/$dname\"\n \tfi &&\n \n \t# As with \"installed\" above, we skip the render if it's already been\n \t# done. So using make here is primarily just about running in\n \t# parallel.\n-\tif ! test -d \"$tmp/rendered/$1\"\n+\tif ! test -d \"$tmp/rendered/$dname\"\n \tthen\n-\t\tgenerate_render_makefile \"$tmp/installed/$1\" \"$tmp/rendered/$1+\" |\n+\t\tgenerate_render_makefile \"$tmp/installed/$dname\" \\\n+\t\t\t\"$tmp/rendered/$dname+\" |\n \t\tmake -j$parallel -f - &&\n-\t\tmv \"$tmp/rendered/$1+\" \"$tmp/rendered/$1\"\n+\t\tmv \"$tmp/rendered/$dname+\" \"$tmp/rendered/$dname\"\n \tfi\n }\n \n-render_tree $from_oid &&\n-render_tree $to_oid &&\n-git -C $tmp/rendered diff --no-index \"$@\" $from_oid $to_oid\n+render_tree $from_oid $from_dir &&\n+render_tree $to_oid $to_dir &&\n+git -C $tmp/rendered diff --no-index \"$@\" $from_dir $to_dir\n-- \n2.21.0\n\n"},{"id":"371744","messageId":"e6c9f88e575e13a564d47a19050b65154dede7c6.1552838239.git.martin.agren@gmail.com","threadId":"50767","inReplyTo":"cover.1552838239.git.martin.agren@gmail.com","subject":"[PATCH 3/4] doc-diff: support diffing from/to AsciiDoc(tor)","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2019-03-17T18:36:02Z","receivedAt":"2019-03-17T18:37:04Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"Provide `--from-asciidoctor` and `--to-asciidoctor` to select that the\n\"from\" resp. \"to\" commit should be built with Asciidoctor, and provide\nan `--asciidoctor` shortcut for giving both. Similarly, provide\n--{from-,to-,}asciidoc for explicitly selecting AsciiDoc.\n\nImplement this using the USE_ASCIIDOCTOR flag. Let's not enforce a\ndefault here, but instead just let the Makefile fall back on whatever is\nin config.mak, so that `./doc-diff foo bar` without any of of these new\noptions behaves exactly like it did before this commit.\n\nEncode the choice into the directory names of our \"installed\" and\n\"rendered\" files, so that we can run `./doc-diff --from-asciidoc\n--to-asciidoctor HEAD HEAD` without our two runs stomping on each other.\n\nSigned-off-by: Martin Ågren \n---\n Documentation/doc-diff | 53 +++++++++++++++++++++++++++++++++++-------\n 1 file changed, 45 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/doc-diff b/Documentation/doc-diff\nindex 3e975d3c5d..36fc2307a7 100755\n--- a/Documentation/doc-diff\n+++ b/Documentation/doc-diff\n@@ -12,9 +12,15 @@ OPTIONS_SPEC=\"\\\n doc-diff [options] [-- ]\n doc-diff (-c|--clean)\n --\n-j=n\tparallel argument to pass to make\n-f\tforce rebuild; do not rely on cached results\n-c,clean\tcleanup temporary working files\n+j=n\t\t\tparallel argument to pass to make\n+f\t\t\tforce rebuild; do not rely on cached results\n+c,clean\t\t\tcleanup temporary working files\n+from-asciidoc\t\tuse asciidoc with the 'from'-commit\n+from-asciidoctor\tuse asciidoctor with the 'from'-commit\n+asciidoc\t\tuse asciidoc with both commits\n+to-asciidoc\t\tuse asciidoc with the 'to'-commit\n+to-asciidoctor\t\tuse asciidoctor with the 'to'-commit\n+asciidoctor\t\tuse asciidoctor with both commits\n \"\n SUBDIRECTORY_OK=1\n . \"$(git --exec-path)/git-sh-setup\"\n@@ -22,6 +28,8 @@ SUBDIRECTORY_OK=1\n parallel=\n force=\n clean=\n+from_program=\n+to_program=\n while test $# -gt 0\n do\n \tcase \"$1\" in\n@@ -31,6 +39,20 @@ do\n \t\tclean=t ;;\n \t-f)\n \t\tforce=t ;;\n+\t--from-asciidoctor)\n+\t\tfrom_program=-asciidoctor ;;\n+\t--to-asciidoctor)\n+\t\tto_program=-asciidoctor ;;\n+\t--asciidoctor)\n+\t\tfrom_program=-asciidoctor\n+\t\tto_program=-asciidoctor ;;\n+\t--from-asciidoc)\n+\t\tfrom_program=-asciidoc ;;\n+\t--to-asciidoc)\n+\t\tto_program=-asciidoc ;;\n+\t--asciidoc)\n+\t\tfrom_program=-asciidoc\n+\t\tto_program=-asciidoc ;;\n \t--)\n \t\tshift; break ;;\n \t*)\n@@ -79,8 +101,21 @@ then\n \tln -s \"$dots/config.mak\" \"$tmp/worktree/config.mak\"\n fi\n \n-from_dir=$from_oid &&\n-to_dir=$to_oid &&\n+construct_makemanflags () {\n+\tif test \"$1\" = \"-asciidoc\"\n+\tthen\n+\t\techo USE_ASCIIDOCTOR=\n+\telif test \"$1\" = \"-asciidoctor\"\n+\tthen\n+\t\techo USE_ASCIIDOCTOR=YesPlease\n+\tfi\n+}\n+\n+from_makemanflags=$(construct_makemanflags \"$from_program\") &&\n+to_makemanflags=$(construct_makemanflags \"$to_program\") &&\n+\n+from_dir=$from_oid$from_program &&\n+to_dir=$to_oid$to_program &&\n \n # generate_render_makefile \n generate_render_makefile () {\n@@ -97,7 +132,7 @@ generate_render_makefile () {\n \tdone\n }\n \n-# render_tree \n+# render_tree \n render_tree () {\n \t# Skip install-man entirely if we already have an installed directory.\n \t# We can't rely on make here, since \"install-man\" unconditionally\n@@ -107,10 +142,12 @@ render_tree () {\n \t# through.\n \toid=$1 &&\n \tdname=$2 &&\n+\tmakemanflags=$3 &&\n \tif ! test -d \"$tmp/installed/$dname\"\n \tthen\n \t\tgit -C \"$tmp/worktree\" checkout --detach \"$oid\" &&\n \t\tmake -j$parallel -C \"$tmp/worktree\" \\\n+\t\t\t$makemanflags \\\n \t\t\tGIT_VERSION=omitted \\\n \t\t\tSOURCE_DATE_EPOCH=0 \\\n \t\t\tDESTDIR=\"$tmp/installed/$dname+\" \\\n@@ -130,6 +167,6 @@ render_tree () {\n \tfi\n }\n \n-render_tree $from_oid $from_dir &&\n-render_tree $to_oid $to_dir &&\n+render_tree $from_oid $from_dir $from_makemanflags &&\n+render_tree $to_oid $to_dir $to_makemanflags &&\n git -C $tmp/rendered diff --no-index \"$@\" $from_dir $to_dir\n-- \n2.21.0\n\n"},{"id":"371745","messageId":"7ce7aa6f2f1ea40442c17c15fe8d7744b29d8650.1552838239.git.martin.agren@gmail.com","threadId":"50767","inReplyTo":"cover.1552838239.git.martin.agren@gmail.com","subject":"[PATCH 4/4] doc-diff: add `--cut-header-footer`","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2019-03-17T18:36:03Z","receivedAt":"2019-03-17T18:37:08Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"AsciiDoc and Asciidoctor do not agree on what to write in the header and\nfooter of each man-page, i.e., the very first and the very last line of\n*.[157]. Those differences can certainly be interesting in their own\nright, but they clutter the output of `./doc-diff --from-asciidoc\n--to-asciidoctor HEAD HEAD` quite a bit since the diff contains some\n10-15 lines of noise per file diffed.\n\nTeach doc-diff to cut away the first two and last two lines, i.e., the\nheader/footer and the empty line immediately following/preceding it.\nBecause Asciidoctor uses an extra empty line compared to AsciiDoc,\nremove one more line at each end of the file, but only if it's empty.\n\nAn alternative approach might be to pass down `--no-header-footer`,\nwhich both AsciiDoc and Asciidoctor understand, but it has some\ndrawbacks. First of all, the result doesn't build -- `xmlto` stumbles on\nthe resulting xml since it has multiple root elements. Second, it cuts\ntoo much -- dropping the header loses the synopsis, which would be\ninteresting to diff.\n\nLike in the previous commit, encode this option into the directory name\nof the \"installed\" and \"rendered\" files. Otherwise, we wouldn't be able\nto trust that what we use out of that cache actually corresponds to the\noptions given for this run. (We could optimize this caching a little\nsince this flag doesn't affect the contents of \"installed\" at all, but\nlet's punt on that.)\n\nSigned-off-by: Martin Ågren \n---\n Documentation/doc-diff | 19 +++++++++++++++++--\n 1 file changed, 17 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/doc-diff b/Documentation/doc-diff\nindex 36fc2307a7..3355be4798 100755\n--- a/Documentation/doc-diff\n+++ b/Documentation/doc-diff\n@@ -21,6 +21,7 @@ asciidoc\t\tuse asciidoc with both commits\n to-asciidoc\t\tuse asciidoc with the 'to'-commit\n to-asciidoctor\t\tuse asciidoctor with the 'to'-commit\n asciidoctor\t\tuse asciidoctor with both commits\n+cut-header-footer\tcut away header and footer\n \"\n SUBDIRECTORY_OK=1\n . \"$(git --exec-path)/git-sh-setup\"\n@@ -30,6 +31,7 @@ force=\n clean=\n from_program=\n to_program=\n+cut_header_footer=\n while test $# -gt 0\n do\n \tcase \"$1\" in\n@@ -53,6 +55,8 @@ do\n \t--asciidoc)\n \t\tfrom_program=-asciidoc\n \t\tto_program=-asciidoc ;;\n+\t--cut-header-footer)\n+\t\tcut_header_footer=-cut-header-footer ;;\n \t--)\n \t\tshift; break ;;\n \t*)\n@@ -114,8 +118,8 @@ construct_makemanflags () {\n from_makemanflags=$(construct_makemanflags \"$from_program\") &&\n to_makemanflags=$(construct_makemanflags \"$to_program\") &&\n \n-from_dir=$from_oid$from_program &&\n-to_dir=$to_oid$to_program &&\n+from_dir=$from_oid$from_program$cut_header_footer &&\n+to_dir=$to_oid$to_program$cut_header_footer &&\n \n # generate_render_makefile \n generate_render_makefile () {\n@@ -164,6 +168,17 @@ render_tree () {\n \t\t\t\"$tmp/rendered/$dname+\" |\n \t\tmake -j$parallel -f - &&\n \t\tmv \"$tmp/rendered/$dname+\" \"$tmp/rendered/$dname\"\n+\n+\t\tif test \"$cut_header_footer\" = \"-cut-header-footer\"\n+\t\tthen\n+\t\t\tfor f in $(find \"$tmp/rendered/$dname\" -type f)\n+\t\t\tdo\n+\t\t\t\ttail -n +3 \"$f\" | head -n -2 |\n+\t\t\t\tsed -e '1{/^$/d}' -e '${/^$/d}' >\"$f+\" &&\n+\t\t\t\tmv \"$f+\" \"$f\" ||\n+\t\t\t\treturn 1\n+\t\t\tdone\n+\t\tfi\n \tfi\n }\n \n-- \n2.21.0\n\n"},{"id":"371786","messageId":"xmqqsgvk1xmn.fsf@gitster-ct.c.googlers.com","threadId":"50767","inReplyTo":"cover.1552838239.git.martin.agren@gmail.com","subject":"Re: [PATCH 0/4] doc-diff: support diffing from/to AsciiDoc(tor)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-03-18T06:53:52Z","receivedAt":"2019-03-18T06:53:56Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin Ågren writes:\n\n> I've taught `doc-diff` a few new knobs to support usage like\n>\n> $ ./doc-diff --from-asciidoc --to-asciidoctor HEAD HEAD\n\nNice.\n\n> But I have made some progress on fixing up Asciidoctor *and* AsciiDoc\n> issues using this, and once the output of the above command is empty --\n> which might not be too far off -- it could be interesting to try and\n> keep it that way using a bit of automation around these switches.\n\nThat would be exciting.\n\n"},{"id":"371873","messageId":"20190319031412.GC6173@sigill.intra.peff.net","threadId":"50767","inReplyTo":"cover.1552838239.git.martin.agren@gmail.com","subject":"Re: [PATCH 0/4] doc-diff: support diffing from/to AsciiDoc(tor)","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2019-03-19T03:14:12Z","receivedAt":"2019-03-19T03:20:57Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sun, Mar 17, 2019 at 07:35:59PM +0100, Martin Ågren wrote:\n\n> I've taught `doc-diff` a few new knobs to support usage like\n> \n> $ ./doc-diff --from-asciidoc --to-asciidoctor HEAD HEAD\n> \n> and I don't think I've messed it up too badly in the process. I'm open\n> to the idea that this might not be interesting to a whole lot of people.\n> But I have made some progress on fixing up Asciidoctor *and* AsciiDoc\n> issues using this, and once the output of the above command is empty --\n> which might not be too far off -- it could be interesting to try and\n> keep it that way using a bit of automation around these switches.\n\nVery nice. All the patches look good to me.\n\nThe \"from\" and \"to\" variants of the options are a little awkward; these\nare really properties of the actual endpoints. It would be nice if we\nhad some fixed syntax that defined the whole state, like:\n\n ./doc-diff asciidoc:HEAD asciidoctor:HEAD^\n\nor something. But I think as you introduce new options (like the\nheader/footer cutting) that syntax would get pretty unwieldy. So\nprobably the separate options is the best way forward.\n\n> While using/testing these patches, I've made some progress on the\n> rendering of the headers and footers in Asciidoctor [1], so the\n> `--cut-header-footer` switch that I'm adding in the final patch might\n> hopefully not be necessary for too long. But we'd still need a\n> `--cut-footer` switch -- at least I would, on my system [2]. If this\n> series is considered generally sane, I'd be happy to rework the final\n> patch to `--cut-header` if that's preferred.\n\nI think what's here is fine for now. This is our own internal script, so\nif options become useless later on, we can always cull them.\n\n> [2] After [1], the date in the footer is still formatted differently\n> here. It might be a locale thing, and I tend to shy away from even\n> trying to understand those. :-/\n\nYeah, mine too.\n\n-Peff\n"},{"id":"372019","messageId":"CAN0heSr0vVYBL9=xG=sqHFvRGHWVRi+Uzn1kekb6w6ZP6FHdog@mail.gmail.com","threadId":"50767","inReplyTo":"20190319031412.GC6173@sigill.intra.peff.net","subject":"Re: [PATCH 0/4] doc-diff: support diffing from/to AsciiDoc(tor)","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2019-03-20T20:11:53Z","receivedAt":"2019-03-20T20:12:08Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Tue, 19 Mar 2019 at 04:14, Jeff King wrote:\n>\n> On Sun, Mar 17, 2019 at 07:35:59PM +0100, Martin Ågren wrote:\n>\n> > I've taught `doc-diff` a few new knobs to support usage like\n> >\n> > $ ./doc-diff --from-asciidoc --to-asciidoctor HEAD HEAD\n>\n> Very nice. All the patches look good to me.\n\nThank you.\n\n> The \"from\" and \"to\" variants of the options are a little awkward; these\n> are really properties of the actual endpoints. It would be nice if we\n> had some fixed syntax that defined the whole state, like:\n>\n> ./doc-diff asciidoc:HEAD asciidoctor:HEAD^\n\nRight. I wasn't terribly impressed by the look of the \"--from-foo\n--to-bar\" syntax, but at least I felt like I couldn't possibly mess up\nthe handling of it. As opposed to parsing substrings and whatnot.\n\n> or something. But I think as you introduce new options (like the\n> header/footer cutting) that syntax would get pretty unwieldy. So\n> probably the separate options is the best way forward.\n\nAnd this too. A few more orthogonal parameters on top and it would get\nhairy pretty quickly. (At least I got the feeling it would.)\n\nI think that at least --cut-header-footer is pretty useless to apply to\nonly one of the sides (you'd be asking for 4-6 lines to definitely\ndiffer, for each and every rendered file), so this particular parameter\nwould perhaps not be useful to bake into your alternative syntax.\n\n> > I'd be happy to rework the final\n> > patch to `--cut-header` if that's preferred.\n>\n> I think what's here is fine for now. This is our own internal script, so\n> if options become useless later on, we can always cull them.\n\nThat's true.\n\n> > [2] After [1], the date in the footer is still formatted differently\n> > here. It might be a locale thing, and I tend to shy away from even\n> > trying to understand those. :-/\n>\n> Yeah, mine too.\n\nThanks for a data point. So at least it's not just me.\n\n\nMartin\n"}]}