{"thread":{"id":"55750","subject":"[PATCH v3 0/5] doc: asciidoc cleanups","startedAt":"2021-05-21T22:29:45Z","lastAt":"2021-05-28T01:12:24Z","messageCount":21,"participants":["Felipe Contreras","Junio C Hamano","Jeff King"],"isPatch":true,"patchVersion":3,"patchTotal":5},"messages":[{"id":"425244","messageId":"20210521222941.525901-1-felipe.contreras@gmail.com","threadId":"55750","inReplyTo":null,"subject":"[PATCH v3 0/5] doc: asciidoc cleanups","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-21T22:29:36Z","receivedAt":"2021-05-21T22:29:45Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"This patch series is an attempt to cleanup the Makefile of the documentation.\n\nSince v2 only certain $(RM) commands are moved from one patch to another.\n\nFelipe Contreras (5):\n  doc: refactor common asciidoc dependencies\n  doc: improve asciidoc dependencies\n  doc: remove unnecessary rm instances\n  doc: simplify Makefile using .DELETE_ON_ERROR\n  doc: avoid using rm directly\n\n Documentation/Makefile | 77 ++++++++++++++++--------------------------\n 1 file changed, 29 insertions(+), 48 deletions(-)\n\nRange-diff against v2:\n1:  55b188c8ad = 1:  cbcaefed3e doc: refactor common asciidoc dependencies\n2:  e69d0a5b89 = 2:  1c8b0b9123 doc: improve asciidoc dependencies\n3:  4f18675ce9 < -:  ---------- doc: remove unnecessary rm instances\n-:  ---------- > 3:  3da461a55d doc: remove unnecessary rm instances\n4:  935675e070 ! 4:  a8c4c4ae26 doc: simplify Makefile using .DELETE_ON_ERROR\n    @@ Documentation/Makefile: docdep_prereqs = \\\n      \tcmd-list.made $(cmds_txt)\n      \n      doc.dep : $(docdep_prereqs) $(DOC_DEP_TXT) build-docdep.perl\n    --\t$(QUIET_GEN)$(RM) $@+ $@ && \\\n    --\t$(PERL_PATH) ./build-docdep.perl >$@+ $(QUIET_STDERR) && \\\n    +-\t$(QUIET_GEN)$(PERL_PATH) ./build-docdep.perl >$@+ $(QUIET_STDERR) && \\\n     -\tmv $@+ $@\n     +\t$(QUIET_GEN)$(PERL_PATH) ./build-docdep.perl >$@ $(QUIET_STDERR)\n      \n    @@ Documentation/Makefile: clean:\n      \t$(RM) GIT-ASCIIDOCFLAGS\n      \n      $(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)\n    --\t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n    --\t$(TXT_TO_HTML) -d manpage -o $@+ $< && \\\n    +-\t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -d manpage -o $@+ $< && \\\n     -\tmv $@+ $@\n     +\t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -d manpage -o $@ $<\n      \n      $(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS)\n    --\t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n    --\t$(TXT_TO_HTML) -o $@+ $< && \\\n    +-\t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@+ $< && \\\n     -\tmv $@+ $@\n     +\t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $<\n      \n    @@ Documentation/Makefile: manpage-base-url.xsl: manpage-base-url.xsl.in\n      \t$(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<\n      \n      %.xml : %.txt $(ASCIIDOC_DEPS)\n    --\t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n    --\t$(TXT_TO_XML) -d manpage -o $@+ $< && \\\n    +-\t$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@+ $< && \\\n     -\tmv $@+ $@\n     +\t$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<\n      \n      user-manual.xml: user-manual.txt user-manual.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n    --\t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n    --\t$(TXT_TO_XML) -d book -o $@+ $< && \\\n    +-\t$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d book -o $@+ $< && \\\n     -\tmv $@+ $@\n     +\t$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d book -o $@ $<\n      \n    @@ Documentation/Makefile: XSLTOPTS += --stringparam html.stylesheet docbook-xsl.cs\n      XSLTOPTS += --param generate.consistent.ids 1\n      \n      user-manual.html: user-manual.xml $(XSLT)\n    --\t$(QUIET_XSLTPROC)$(RM) $@+ $@ && \\\n    --\txsltproc $(XSLTOPTS) -o $@+ $(XSLT) $< && \\\n    +-\t$(QUIET_XSLTPROC)xsltproc $(XSLTOPTS) -o $@+ $(XSLT) $< && \\\n     -\tmv $@+ $@\n     +\t$(QUIET_XSLTPROC)xsltproc $(XSLTOPTS) -o $@ $(XSLT) $<\n      \n    @@ Documentation/Makefile: XSLTOPTS += --stringparam html.stylesheet docbook-xsl.cs\n      \t$(QUIET_MAKEINFO)$(MAKEINFO) --no-split -o $@ user-manual.texi\n      \n      user-manual.texi: user-manual.xml\n    --\t$(QUIET_DB2TEXI)$(RM) $@+ $@ && \\\n    --\t$(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout >$@++ && \\\n    +-\t$(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout >$@++ && \\\n     -\t$(PERL_PATH) fix-texi.perl <$@++ >$@+ && \\\n     -\trm $@++ && \\\n     -\tmv $@+ $@\n    @@ Documentation/Makefile: XSLTOPTS += --stringparam html.stylesheet docbook-xsl.cs\n     +\trm $@+\n      \n      user-manual.pdf: user-manual.xml\n    --\t$(QUIET_DBLATEX)$(RM) $@+ $@ && \\\n    --\t$(DBLATEX) -o $@+ $(DBLATEX_COMMON) $< && \\\n    +-\t$(QUIET_DBLATEX)$(DBLATEX) -o $@+ $(DBLATEX_COMMON) $< && \\\n     -\tmv $@+ $@\n     +\t$(QUIET_DBLATEX)$(DBLATEX) -o $@ $(DBLATEX_COMMON) $<\n      \n      gitman.texi: $(MAN_XML) cat-texi.perl texi.xsl\n    --\t$(QUIET_DB2TEXI)$(RM) $@+ $@ && \\\n    -+\t$(QUIET_DB2TEXI) \\\n    + \t$(QUIET_DB2TEXI) \\\n      \t($(foreach xml,$(sort $(MAN_XML)),xsltproc -o $(xml)+ texi.xsl $(xml) && \\\n      \t\t$(DOCBOOK2X_TEXI) --encoding=UTF-8 --to-stdout $(xml)+ && \\\n     -\t\trm $(xml)+ &&) true) > $@++ && \\\n    @@ Documentation/Makefile: XSLTOPTS += --stringparam html.stylesheet docbook-xsl.cs\n      \t$(QUIET_MAKEINFO)$(MAKEINFO) --no-split --no-validate $*.texi\n      \n      $(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml\n    --\t$(QUIET_DB2TEXI)$(RM) $@+ $@ && \\\n    --\t$(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@+ && \\\n    +-\t$(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@+ && \\\n     -\tmv $@+ $@\n     +\t$(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@\n      \n      howto-index.txt: howto-index.sh $(HOWTO_TXT)\n    --\t$(QUIET_GEN)$(RM) $@+ $@ && \\\n    --\t'$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(HOWTO_TXT)) >$@+ && \\\n    +-\t$(QUIET_GEN)'$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(HOWTO_TXT)) >$@+ && \\\n     -\tmv $@+ $@\n     +\t$(QUIET_GEN)'$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(HOWTO_TXT)) >$@\n      \n      $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt\n      \t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt\n    -@@ Documentation/Makefile: WEBDOC_DEST = /pub/software/scm/git/docs\n    - \n    - howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../\n    +@@ Documentation/Makefile: howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../\n      $(patsubst %.txt,%.html,$(HOWTO_TXT)): %.html : %.txt GIT-ASCIIDOCFLAGS\n    --\t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n    -+\t$(QUIET_ASCIIDOC) \\\n    + \t$(QUIET_ASCIIDOC) \\\n      \tsed -e '1,/^$$/d' $< | \\\n     -\t$(TXT_TO_HTML) - >$@+ && \\\n     -\tmv $@+ $@\n5:  b621f3b8e9 = 5:  2c330987b5 doc: avoid using rm directly\n-- \n2.32.0.rc0\n\n"},{"id":"425245","messageId":"20210521222941.525901-2-felipe.contreras@gmail.com","threadId":"55750","inReplyTo":"20210521222941.525901-1-felipe.contreras@gmail.com","subject":"[PATCH v3 1/5] doc: refactor common asciidoc dependencies","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-21T22:29:37Z","receivedAt":"2021-05-21T22:29:48Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>\n---\n Documentation/Makefile | 7 ++++---\n 1 file changed, 4 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 2aae4c9cbb..46d9b98dac 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -139,6 +139,7 @@ ASCIIDOC_CONF = -f asciidoc.conf\n ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \\\n \t\t-amanversion=$(GIT_VERSION) \\\n \t\t-amanmanual='Git Manual' -amansource='Git'\n+ASCIIDOC_DEPS = asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)\n TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK)\n MANPAGE_XSL = manpage-normal.xsl\n@@ -354,12 +355,12 @@ clean:\n \t$(RM) manpage-base-url.xsl\n \t$(RM) GIT-ASCIIDOCFLAGS\n \n-$(MAN_HTML): %.html : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n+$(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)\n \t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n \t$(TXT_TO_HTML) -d manpage -o $@+ $< && \\\n \tmv $@+ $@\n \n-$(OBSOLETE_HTML): %.html : %.txto asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n+$(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS)\n \t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n \t$(TXT_TO_HTML) -o $@+ $< && \\\n \tmv $@+ $@\n@@ -371,7 +372,7 @@ 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 asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n+%.xml : %.txt $(ASCIIDOC_DEPS)\n \t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n \t$(TXT_TO_XML) -d manpage -o $@+ $< && \\\n \tmv $@+ $@\n-- \n2.32.0.rc0\n\n"},{"id":"425246","messageId":"20210521222941.525901-3-felipe.contreras@gmail.com","threadId":"55750","inReplyTo":"20210521222941.525901-1-felipe.contreras@gmail.com","subject":"[PATCH v3 2/5] doc: improve asciidoc dependencies","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-21T22:29:38Z","receivedAt":"2021-05-21T22:29:49Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"asciidoc needs asciidoc.conf, asciidoctor asciidoctor-extensions.rb.\n\nNeither needs the other.\n\nSigned-off-by: Felipe Contreras <felipe.contreras@gmail.com>\n---\n Documentation/Makefile | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 46d9b98dac..0f59cc0853 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -139,7 +139,7 @@ ASCIIDOC_CONF = -f asciidoc.conf\n ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \\\n \t\t-amanversion=$(GIT_VERSION) \\\n \t\t-amanmanual='Git Manual' -amansource='Git'\n-ASCIIDOC_DEPS = asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n+ASCIIDOC_DEPS = asciidoc.conf GIT-ASCIIDOCFLAGS\n TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)\n TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK)\n MANPAGE_XSL = manpage-normal.xsl\n@@ -194,6 +194,7 @@ ASCIIDOC_DOCBOOK = docbook5\n ASCIIDOC_EXTRA += -acompat-mode -atabsize=8\n ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions\n ASCIIDOC_EXTRA += -alitdd='&\\#x2d;&\\#x2d;'\n+ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n DBLATEX_COMMON =\n XMLTO_EXTRA += --skip-validation\n XMLTO_EXTRA += -x manpage.xsl\n-- \n2.32.0.rc0\n\n"},{"id":"425247","messageId":"20210521222941.525901-4-felipe.contreras@gmail.com","threadId":"55750","inReplyTo":"20210521222941.525901-1-felipe.contreras@gmail.com","subject":"[PATCH v3 3/5] doc: remove unnecessary rm instances","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-21T22:29:39Z","receivedAt":"2021-05-21T22:29:51Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Commits 50cff52f1a (When generating manpages, delete outdated targets\nfirst., 2007-08-02) and f9286765b2 (Documentation/Makefile: remove\ncmd-list.made before redirecting to it., 2007-08-06) created these rm\ninstances for a very rare corner-case: building as root by mistake.\n\nIt's odd to have workarounds here, but nowhere else in the Makefile--\nwhich already fails in this stuation, starting from\nDocumentation/technical/.\n\nWe gain nothing but complexity, so let's remove them.\n\nComments-by: Jeff King <peff@peff.net>\nSigned-off-by: Felipe Contreras <felipe.contreras@gmail.com>\n---\n Documentation/Makefile | 42 +++++++++++++++---------------------------\n 1 file changed, 15 insertions(+), 27 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 0f59cc0853..73b88c3aad 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -296,8 +296,7 @@ docdep_prereqs = \\\n \tcmd-list.made $(cmds_txt)\n \n doc.dep : $(docdep_prereqs) $(DOC_DEP_TXT) build-docdep.perl\n-\t$(QUIET_GEN)$(RM) $@+ $@ && \\\n-\t$(PERL_PATH) ./build-docdep.perl >$@+ $(QUIET_STDERR) && \\\n+\t$(QUIET_GEN)$(PERL_PATH) ./build-docdep.perl >$@+ $(QUIET_STDERR) && \\\n \tmv $@+ $@\n \n ifneq ($(MAKECMDGOALS),clean)\n@@ -318,8 +317,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \\\n $(cmds_txt): cmd-list.made\n \n cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT)\n-\t$(QUIET_GEN)$(RM) $@ && \\\n-\t$(PERL_PATH) ./cmd-list.perl ../command-list.txt $(cmds_txt) $(QUIET_STDERR) && \\\n+\t$(QUIET_GEN)$(PERL_PATH) ./cmd-list.perl ../command-list.txt $(cmds_txt) $(QUIET_STDERR) && \\\n \tdate >$@\n \n mergetools_txt = mergetools-diff.txt mergetools-merge.txt\n@@ -327,7 +325,7 @@ mergetools_txt = mergetools-diff.txt mergetools-merge.txt\n $(mergetools_txt): mergetools-list.made\n \n mergetools-list.made: ../git-mergetool--lib.sh $(wildcard ../mergetools/*)\n-\t$(QUIET_GEN)$(RM) $@ && \\\n+\t$(QUIET_GEN) \\\n \t$(SHELL_PATH) -c 'MERGE_TOOLS_DIR=../mergetools && \\\n \t\t. ../git-mergetool--lib.sh && \\\n \t\tshow_tool_names can_diff \"* \" || :' >mergetools-diff.txt && \\\n@@ -357,30 +355,25 @@ clean:\n \t$(RM) GIT-ASCIIDOCFLAGS\n \n $(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)\n-\t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n-\t$(TXT_TO_HTML) -d manpage -o $@+ $< && \\\n+\t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -d manpage -o $@+ $< && \\\n \tmv $@+ $@\n \n $(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS)\n-\t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n-\t$(TXT_TO_HTML) -o $@+ $< && \\\n+\t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@+ $< && \\\n \tmv $@+ $@\n \n manpage-base-url.xsl: manpage-base-url.xsl.in\n \t$(QUIET_GEN)sed \"s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|\" $< > $@\n \n %.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)\n-\t$(QUIET_XMLTO)$(RM) $@ && \\\n-\t$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<\n+\t$(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<\n \n %.xml : %.txt $(ASCIIDOC_DEPS)\n-\t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n-\t$(TXT_TO_XML) -d manpage -o $@+ $< && \\\n+\t$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@+ $< && \\\n \tmv $@+ $@\n \n user-manual.xml: user-manual.txt user-manual.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n-\t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n-\t$(TXT_TO_XML) -d book -o $@+ $< && \\\n+\t$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d book -o $@+ $< && \\\n \tmv $@+ $@\n \n technical/api-index.txt: technical/api-index-skel.txt \\\n@@ -402,27 +395,24 @@ XSLTOPTS += --stringparam html.stylesheet docbook-xsl.css\n XSLTOPTS += --param generate.consistent.ids 1\n \n user-manual.html: user-manual.xml $(XSLT)\n-\t$(QUIET_XSLTPROC)$(RM) $@+ $@ && \\\n-\txsltproc $(XSLTOPTS) -o $@+ $(XSLT) $< && \\\n+\t$(QUIET_XSLTPROC)xsltproc $(XSLTOPTS) -o $@+ $(XSLT) $< && \\\n \tmv $@+ $@\n \n git.info: user-manual.texi\n \t$(QUIET_MAKEINFO)$(MAKEINFO) --no-split -o $@ user-manual.texi\n \n user-manual.texi: user-manual.xml\n-\t$(QUIET_DB2TEXI)$(RM) $@+ $@ && \\\n-\t$(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout >$@++ && \\\n+\t$(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout >$@++ && \\\n \t$(PERL_PATH) fix-texi.perl <$@++ >$@+ && \\\n \trm $@++ && \\\n \tmv $@+ $@\n \n user-manual.pdf: user-manual.xml\n-\t$(QUIET_DBLATEX)$(RM) $@+ $@ && \\\n-\t$(DBLATEX) -o $@+ $(DBLATEX_COMMON) $< && \\\n+\t$(QUIET_DBLATEX)$(DBLATEX) -o $@+ $(DBLATEX_COMMON) $< && \\\n \tmv $@+ $@\n \n gitman.texi: $(MAN_XML) cat-texi.perl texi.xsl\n-\t$(QUIET_DB2TEXI)$(RM) $@+ $@ && \\\n+\t$(QUIET_DB2TEXI) \\\n \t($(foreach xml,$(sort $(MAN_XML)),xsltproc -o $(xml)+ texi.xsl $(xml) && \\\n \t\t$(DOCBOOK2X_TEXI) --encoding=UTF-8 --to-stdout $(xml)+ && \\\n \t\trm $(xml)+ &&) true) > $@++ && \\\n@@ -434,13 +424,11 @@ gitman.info: gitman.texi\n \t$(QUIET_MAKEINFO)$(MAKEINFO) --no-split --no-validate $*.texi\n \n $(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml\n-\t$(QUIET_DB2TEXI)$(RM) $@+ $@ && \\\n-\t$(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@+ && \\\n+\t$(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@+ && \\\n \tmv $@+ $@\n \n howto-index.txt: howto-index.sh $(HOWTO_TXT)\n-\t$(QUIET_GEN)$(RM) $@+ $@ && \\\n-\t'$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(HOWTO_TXT)) >$@+ && \\\n+\t$(QUIET_GEN)'$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(HOWTO_TXT)) >$@+ && \\\n \tmv $@+ $@\n \n $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt\n@@ -450,7 +438,7 @@ WEBDOC_DEST = /pub/software/scm/git/docs\n \n howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../\n $(patsubst %.txt,%.html,$(HOWTO_TXT)): %.html : %.txt GIT-ASCIIDOCFLAGS\n-\t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n+\t$(QUIET_ASCIIDOC) \\\n \tsed -e '1,/^$$/d' $< | \\\n \t$(TXT_TO_HTML) - >$@+ && \\\n \tmv $@+ $@\n-- \n2.32.0.rc0\n\n"},{"id":"425248","messageId":"20210521222941.525901-5-felipe.contreras@gmail.com","threadId":"55750","inReplyTo":"20210521222941.525901-1-felipe.contreras@gmail.com","subject":"[PATCH v3 4/5] doc: simplify Makefile using .DELETE_ON_ERROR","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-21T22:29:40Z","receivedAt":"2021-05-21T22:29:56Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Currently GNU make already removes files when catching an interruption\nsignal, however, in order to deal with other kinds of errors a\nworkaround is in place to store target output to a temporary file, and\nonly move it to its right place on success.\n\nBy enabling the built-in .DELETE_ON_ERROR we let make do this task, so\nwe don't have to.\n\nThis way the rules can be simplified a lot.\n\nSuggested-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\nSigned-off-by: Felipe Contreras <felipe.contreras@gmail.com>\n---\n Documentation/Makefile | 47 +++++++++++++++++-------------------------\n 1 file changed, 19 insertions(+), 28 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 73b88c3aad..eaff97dcb8 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -296,8 +296,7 @@ docdep_prereqs = \\\n \tcmd-list.made $(cmds_txt)\n \n doc.dep : $(docdep_prereqs) $(DOC_DEP_TXT) build-docdep.perl\n-\t$(QUIET_GEN)$(PERL_PATH) ./build-docdep.perl >$@+ $(QUIET_STDERR) && \\\n-\tmv $@+ $@\n+\t$(QUIET_GEN)$(PERL_PATH) ./build-docdep.perl >$@ $(QUIET_STDERR)\n \n ifneq ($(MAKECMDGOALS),clean)\n -include doc.dep\n@@ -355,12 +354,10 @@ clean:\n \t$(RM) GIT-ASCIIDOCFLAGS\n \n $(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)\n-\t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -d manpage -o $@+ $< && \\\n-\tmv $@+ $@\n+\t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -d manpage -o $@ $<\n \n $(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS)\n-\t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@+ $< && \\\n-\tmv $@+ $@\n+\t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $<\n \n manpage-base-url.xsl: manpage-base-url.xsl.in\n \t$(QUIET_GEN)sed \"s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|\" $< > $@\n@@ -369,12 +366,10 @@ manpage-base-url.xsl: manpage-base-url.xsl.in\n \t$(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<\n \n %.xml : %.txt $(ASCIIDOC_DEPS)\n-\t$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@+ $< && \\\n-\tmv $@+ $@\n+\t$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<\n \n user-manual.xml: user-manual.txt user-manual.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n-\t$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d book -o $@+ $< && \\\n-\tmv $@+ $@\n+\t$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d book -o $@ $<\n \n technical/api-index.txt: technical/api-index-skel.txt \\\n \ttechnical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))\n@@ -395,41 +390,35 @@ XSLTOPTS += --stringparam html.stylesheet docbook-xsl.css\n XSLTOPTS += --param generate.consistent.ids 1\n \n user-manual.html: user-manual.xml $(XSLT)\n-\t$(QUIET_XSLTPROC)xsltproc $(XSLTOPTS) -o $@+ $(XSLT) $< && \\\n-\tmv $@+ $@\n+\t$(QUIET_XSLTPROC)xsltproc $(XSLTOPTS) -o $@ $(XSLT) $<\n \n git.info: user-manual.texi\n \t$(QUIET_MAKEINFO)$(MAKEINFO) --no-split -o $@ user-manual.texi\n \n user-manual.texi: user-manual.xml\n-\t$(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout >$@++ && \\\n-\t$(PERL_PATH) fix-texi.perl <$@++ >$@+ && \\\n-\trm $@++ && \\\n-\tmv $@+ $@\n+\t$(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout >$@+ && \\\n+\t$(PERL_PATH) fix-texi.perl <$@+ >$@ && \\\n+\trm $@+\n \n user-manual.pdf: user-manual.xml\n-\t$(QUIET_DBLATEX)$(DBLATEX) -o $@+ $(DBLATEX_COMMON) $< && \\\n-\tmv $@+ $@\n+\t$(QUIET_DBLATEX)$(DBLATEX) -o $@ $(DBLATEX_COMMON) $<\n \n gitman.texi: $(MAN_XML) cat-texi.perl texi.xsl\n \t$(QUIET_DB2TEXI) \\\n \t($(foreach xml,$(sort $(MAN_XML)),xsltproc -o $(xml)+ texi.xsl $(xml) && \\\n \t\t$(DOCBOOK2X_TEXI) --encoding=UTF-8 --to-stdout $(xml)+ && \\\n-\t\trm $(xml)+ &&) true) > $@++ && \\\n-\t$(PERL_PATH) cat-texi.perl $@ <$@++ >$@+ && \\\n-\trm $@++ && \\\n-\tmv $@+ $@\n+\t\trm $(xml)+ &&) true) > $@+ && \\\n+\t$(PERL_PATH) cat-texi.perl $@ <$@+ >$@ && \\\n+\trm $@+\n \n gitman.info: gitman.texi\n \t$(QUIET_MAKEINFO)$(MAKEINFO) --no-split --no-validate $*.texi\n \n $(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml\n-\t$(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@+ && \\\n-\tmv $@+ $@\n+\t$(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@\n \n howto-index.txt: howto-index.sh $(HOWTO_TXT)\n-\t$(QUIET_GEN)'$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(HOWTO_TXT)) >$@+ && \\\n-\tmv $@+ $@\n+\t$(QUIET_GEN)'$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(HOWTO_TXT)) >$@\n \n $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt\n \t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt\n@@ -440,8 +429,7 @@ howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../\n $(patsubst %.txt,%.html,$(HOWTO_TXT)): %.html : %.txt GIT-ASCIIDOCFLAGS\n \t$(QUIET_ASCIIDOC) \\\n \tsed -e '1,/^$$/d' $< | \\\n-\t$(TXT_TO_HTML) - >$@+ && \\\n-\tmv $@+ $@\n+\t$(TXT_TO_HTML) - >$@\n \n install-webdoc : html\n \t'$(SHELL_PATH_SQ)' ./install-webdoc.sh $(WEBDOC_DEST)\n@@ -482,4 +470,7 @@ doc-l10n install-l10n::\n \t$(MAKE) -C po $@\n endif\n \n+# Delete the target file on error\n+.DELETE_ON_ERROR:\n+\n .PHONY: FORCE\n-- \n2.32.0.rc0\n\n"},{"id":"425249","messageId":"20210521222941.525901-6-felipe.contreras@gmail.com","threadId":"55750","inReplyTo":"20210521222941.525901-1-felipe.contreras@gmail.com","subject":"[PATCH v3 5/5] doc: avoid using rm directly","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-21T22:29:41Z","receivedAt":"2021-05-21T22:29:58Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"That's what we have $(RM) for.\n\nSigned-off-by: Felipe Contreras <felipe.contreras@gmail.com>\n---\n Documentation/Makefile | 6 +++---\n 1 file changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex eaff97dcb8..f5605b7767 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -398,7 +398,7 @@ git.info: user-manual.texi\n user-manual.texi: user-manual.xml\n \t$(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout >$@+ && \\\n \t$(PERL_PATH) fix-texi.perl <$@+ >$@ && \\\n-\trm $@+\n+\t$(RM) $@+\n \n user-manual.pdf: user-manual.xml\n \t$(QUIET_DBLATEX)$(DBLATEX) -o $@ $(DBLATEX_COMMON) $<\n@@ -407,9 +407,9 @@ gitman.texi: $(MAN_XML) cat-texi.perl texi.xsl\n \t$(QUIET_DB2TEXI) \\\n \t($(foreach xml,$(sort $(MAN_XML)),xsltproc -o $(xml)+ texi.xsl $(xml) && \\\n \t\t$(DOCBOOK2X_TEXI) --encoding=UTF-8 --to-stdout $(xml)+ && \\\n-\t\trm $(xml)+ &&) true) > $@+ && \\\n+\t\t$(RM) $(xml)+ &&) true) > $@+ && \\\n \t$(PERL_PATH) cat-texi.perl $@ <$@+ >$@ && \\\n-\trm $@+\n+\t$(RM) $@+\n \n gitman.info: gitman.texi\n \t$(QUIET_MAKEINFO)$(MAKEINFO) --no-split --no-validate $*.texi\n-- \n2.32.0.rc0\n\n"},{"id":"425442","messageId":"xmqqcztgj9za.fsf@gitster.g","threadId":"55750","inReplyTo":"20210521222941.525901-4-felipe.contreras@gmail.com","subject":"Re: [PATCH v3 3/5] doc: remove unnecessary rm instances","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-05-24T17:51:53Z","receivedAt":"2021-05-24T17:51:57Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Felipe Contreras <felipe.contreras@gmail.com> writes:\n\n> Commits 50cff52f1a (When generating manpages, delete outdated targets\n> first., 2007-08-02) and f9286765b2 (Documentation/Makefile: remove\n> cmd-list.made before redirecting to it., 2007-08-06) created these rm\n> instances for a very rare corner-case: building as root by mistake.\n>\n> It's odd to have workarounds here, but nowhere else in the Makefile--\n> which already fails in this stuation, starting from\n> Documentation/technical/.\n>\n> We gain nothing but complexity, so let's remove them.\n>\n> Comments-by: Jeff King <peff@peff.net>\n\nThis is curious.  I understand what other kinds of trailers like\nHelped-by and Suggested-by people sometimes use mean, but this one\ndoes not tell anything other than that this person had some comments\non an earlier rounds, does not tell us what kind of comments they\nwere and if something was done to address those comments or the\ncomments were totally ignored or what.\n\nThe patch text itself, and the justification given in the second\nparagraph, both make perfect sense to me.\n\n> Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>\n> ---\n>  Documentation/Makefile | 42 +++++++++++++++---------------------------\n>  1 file changed, 15 insertions(+), 27 deletions(-)\n>\n> diff --git a/Documentation/Makefile b/Documentation/Makefile\n> index 0f59cc0853..73b88c3aad 100644\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -296,8 +296,7 @@ docdep_prereqs = \\\n>  \tcmd-list.made $(cmds_txt)\n>  \n>  doc.dep : $(docdep_prereqs) $(DOC_DEP_TXT) build-docdep.perl\n> -\t$(QUIET_GEN)$(RM) $@+ $@ && \\\n> -\t$(PERL_PATH) ./build-docdep.perl >$@+ $(QUIET_STDERR) && \\\n> +\t$(QUIET_GEN)$(PERL_PATH) ./build-docdep.perl >$@+ $(QUIET_STDERR) && \\\n>  \tmv $@+ $@\n>  \n>  ifneq ($(MAKECMDGOALS),clean)\n> @@ -318,8 +317,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \\\n>  $(cmds_txt): cmd-list.made\n>  \n>  cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT)\n> -\t$(QUIET_GEN)$(RM) $@ && \\\n> -\t$(PERL_PATH) ./cmd-list.perl ../command-list.txt $(cmds_txt) $(QUIET_STDERR) && \\\n> +\t$(QUIET_GEN)$(PERL_PATH) ./cmd-list.perl ../command-list.txt $(cmds_txt) $(QUIET_STDERR) && \\\n>  \tdate >$@\n>  \n>  mergetools_txt = mergetools-diff.txt mergetools-merge.txt\n> @@ -327,7 +325,7 @@ mergetools_txt = mergetools-diff.txt mergetools-merge.txt\n>  $(mergetools_txt): mergetools-list.made\n>  \n>  mergetools-list.made: ../git-mergetool--lib.sh $(wildcard ../mergetools/*)\n> -\t$(QUIET_GEN)$(RM) $@ && \\\n> +\t$(QUIET_GEN) \\\n>  \t$(SHELL_PATH) -c 'MERGE_TOOLS_DIR=../mergetools && \\\n>  \t\t. ../git-mergetool--lib.sh && \\\n>  \t\tshow_tool_names can_diff \"* \" || :' >mergetools-diff.txt && \\\n> @@ -357,30 +355,25 @@ clean:\n>  \t$(RM) GIT-ASCIIDOCFLAGS\n>  \n>  $(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)\n> -\t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n> -\t$(TXT_TO_HTML) -d manpage -o $@+ $< && \\\n> +\t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -d manpage -o $@+ $< && \\\n>  \tmv $@+ $@\n>  \n>  $(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS)\n> -\t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n> -\t$(TXT_TO_HTML) -o $@+ $< && \\\n> +\t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@+ $< && \\\n>  \tmv $@+ $@\n>  \n>  manpage-base-url.xsl: manpage-base-url.xsl.in\n>  \t$(QUIET_GEN)sed \"s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|\" $< > $@\n>  \n>  %.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)\n> -\t$(QUIET_XMLTO)$(RM) $@ && \\\n> -\t$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<\n> +\t$(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<\n>  \n>  %.xml : %.txt $(ASCIIDOC_DEPS)\n> -\t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n> -\t$(TXT_TO_XML) -d manpage -o $@+ $< && \\\n> +\t$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@+ $< && \\\n>  \tmv $@+ $@\n>  \n>  user-manual.xml: user-manual.txt user-manual.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n> -\t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n> -\t$(TXT_TO_XML) -d book -o $@+ $< && \\\n> +\t$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d book -o $@+ $< && \\\n>  \tmv $@+ $@\n>  \n>  technical/api-index.txt: technical/api-index-skel.txt \\\n> @@ -402,27 +395,24 @@ XSLTOPTS += --stringparam html.stylesheet docbook-xsl.css\n>  XSLTOPTS += --param generate.consistent.ids 1\n>  \n>  user-manual.html: user-manual.xml $(XSLT)\n> -\t$(QUIET_XSLTPROC)$(RM) $@+ $@ && \\\n> -\txsltproc $(XSLTOPTS) -o $@+ $(XSLT) $< && \\\n> +\t$(QUIET_XSLTPROC)xsltproc $(XSLTOPTS) -o $@+ $(XSLT) $< && \\\n>  \tmv $@+ $@\n>  \n>  git.info: user-manual.texi\n>  \t$(QUIET_MAKEINFO)$(MAKEINFO) --no-split -o $@ user-manual.texi\n>  \n>  user-manual.texi: user-manual.xml\n> -\t$(QUIET_DB2TEXI)$(RM) $@+ $@ && \\\n> -\t$(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout >$@++ && \\\n> +\t$(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout >$@++ && \\\n>  \t$(PERL_PATH) fix-texi.perl <$@++ >$@+ && \\\n>  \trm $@++ && \\\n>  \tmv $@+ $@\n>  \n>  user-manual.pdf: user-manual.xml\n> -\t$(QUIET_DBLATEX)$(RM) $@+ $@ && \\\n> -\t$(DBLATEX) -o $@+ $(DBLATEX_COMMON) $< && \\\n> +\t$(QUIET_DBLATEX)$(DBLATEX) -o $@+ $(DBLATEX_COMMON) $< && \\\n>  \tmv $@+ $@\n>  \n>  gitman.texi: $(MAN_XML) cat-texi.perl texi.xsl\n> -\t$(QUIET_DB2TEXI)$(RM) $@+ $@ && \\\n> +\t$(QUIET_DB2TEXI) \\\n>  \t($(foreach xml,$(sort $(MAN_XML)),xsltproc -o $(xml)+ texi.xsl $(xml) && \\\n>  \t\t$(DOCBOOK2X_TEXI) --encoding=UTF-8 --to-stdout $(xml)+ && \\\n>  \t\trm $(xml)+ &&) true) > $@++ && \\\n> @@ -434,13 +424,11 @@ gitman.info: gitman.texi\n>  \t$(QUIET_MAKEINFO)$(MAKEINFO) --no-split --no-validate $*.texi\n>  \n>  $(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml\n> -\t$(QUIET_DB2TEXI)$(RM) $@+ $@ && \\\n> -\t$(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@+ && \\\n> +\t$(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@+ && \\\n>  \tmv $@+ $@\n>  \n>  howto-index.txt: howto-index.sh $(HOWTO_TXT)\n> -\t$(QUIET_GEN)$(RM) $@+ $@ && \\\n> -\t'$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(HOWTO_TXT)) >$@+ && \\\n> +\t$(QUIET_GEN)'$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(HOWTO_TXT)) >$@+ && \\\n>  \tmv $@+ $@\n>  \n>  $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt\n> @@ -450,7 +438,7 @@ WEBDOC_DEST = /pub/software/scm/git/docs\n>  \n>  howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../\n>  $(patsubst %.txt,%.html,$(HOWTO_TXT)): %.html : %.txt GIT-ASCIIDOCFLAGS\n> -\t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n> +\t$(QUIET_ASCIIDOC) \\\n>  \tsed -e '1,/^$$/d' $< | \\\n>  \t$(TXT_TO_HTML) - >$@+ && \\\n>  \tmv $@+ $@\n"},{"id":"425443","messageId":"xmqq7djoj9z9.fsf@gitster.g","threadId":"55750","inReplyTo":"20210521222941.525901-1-felipe.contreras@gmail.com","subject":"Re: [PATCH v3 0/5] doc: asciidoc cleanups","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-05-24T17:51:54Z","receivedAt":"2021-05-24T17:52:01Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Felipe Contreras <felipe.contreras@gmail.com> writes:\n\n> This patch series is an attempt to cleanup the Makefile of the documentation.\n>\n> Since v2 only certain $(RM) commands are moved from one patch to another.\n\nThe above description is correct.  I can see that the end result is\nidentical to the previous one.\n\n>  Documentation/Makefile | 77 ++++++++++++++++--------------------------\n>  1 file changed, 29 insertions(+), 48 deletions(-)\n\nIs this satisfactory to everybody (I haven't taken a look beyond\ncomparing the end results)?\n\nIt does not seem to play well with what brian is already doing in\n'seen'; it overlaps with its changes in interesting ways.  Is this\nseries meant to be a superset of the topic and supersedes it?  How\nare you two coordinating to avoid duplicated work and stepping on\neach other's toes?\n\nThanks.\n\n\n"},{"id":"425448","messageId":"60abf32038579_1b209208d2@natae.notmuch","threadId":"55750","inReplyTo":"xmqqcztgj9za.fsf@gitster.g","subject":"Re: [PATCH v3 3/5] doc: remove unnecessary rm instances","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-24T18:40:32Z","receivedAt":"2021-05-24T18:40:36Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Junio C Hamano wrote:\n> Felipe Contreras <felipe.contreras@gmail.com> writes:\n> \n> > Commits 50cff52f1a (When generating manpages, delete outdated targets\n> > first., 2007-08-02) and f9286765b2 (Documentation/Makefile: remove\n> > cmd-list.made before redirecting to it., 2007-08-06) created these rm\n> > instances for a very rare corner-case: building as root by mistake.\n> >\n> > It's odd to have workarounds here, but nowhere else in the Makefile--\n> > which already fails in this stuation, starting from\n> > Documentation/technical/.\n> >\n> > We gain nothing but complexity, so let's remove them.\n> >\n> > Comments-by: Jeff King <peff@peff.net>\n> \n> This is curious.  I understand what other kinds of trailers like\n> Helped-by and Suggested-by people sometimes use mean, but this one\n> does not tell anything other than that this person had some comments\n> on an earlier rounds, does not tell us what kind of comments they\n> were and if something was done to address those comments or the\n> comments were totally ignored or what.\n\nIf they were ignored they would not be part of the commit. It is\nunderstood the comments were incorporated.\n\nWhen you see 'Tested-by' do you wonder what was the result of the test?\nI presume most people would understand that the test succeeded, and\nthat's why the trailer line was added.\n\nI happen to have at hand a script that ranks the most common trailer\nlines:\n\n * acked-by: 25% (1945)\n\nDoesn't apply.\n\n * reviewed-by: 22% (1729)\n\nThis does apply, but I'm not confident Jeff would like me to add that.\n\n * helped-by: 17% (1336)\n * reported-by: 12% (960)\n * mentored-by: 5% (379)\n * suggested-by: 4% (281)\n * cc: 3% (222)\n * noticed-by: 2% (165)\n * tested-by: 2% (153)\n * improved-by: 1% (88)\n * thanks-to: 1% (65)\n * signed-off-by: 1% (50)\n * based-on-patch-by: 1% (50)\n * contributions-by: 1% (43)\n * co-authored-by: 1% (41)\n\nI don't think any of these apply.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"425449","messageId":"60abf44d9057d_1b20920861@natae.notmuch","threadId":"55750","inReplyTo":"60abf32038579_1b209208d2@natae.notmuch","subject":"Re: [PATCH v3 3/5] doc: remove unnecessary rm instances","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-24T18:45:33Z","receivedAt":"2021-05-24T18:45:37Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Felipe Contreras wrote:\n> Junio C Hamano wrote:\n> > Felipe Contreras <felipe.contreras@gmail.com> writes:\n\n> > > Comments-by: Jeff King <peff@peff.net>\n> > \n> > This is curious.  I understand what other kinds of trailers like\n> > Helped-by and Suggested-by people sometimes use mean, but this one\n> > does not tell anything other than that this person had some comments\n> > on an earlier rounds, does not tell us what kind of comments they\n> > were and if something was done to address those comments or the\n> > comments were totally ignored or what.\n> \n> If they were ignored they would not be part of the commit. It is\n> understood the comments were incorporated.\n\nOh, and there are some instances already in the history:\n\n7a9b0b802e (git-clean: add colors to interactive git-clean, 2013-06-25)\n1b8fd46732 (git-clean: show items of del_list in columns, 2013-06-25)\n52fd972d59 (git-completion: fix regression in zsh support, 2011-05-10)\n\nAlthough one of those is mine.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"425480","messageId":"xmqqwnrnh626.fsf@gitster.g","threadId":"55750","inReplyTo":"60abf32038579_1b209208d2@natae.notmuch","subject":"Re: [PATCH v3 3/5] doc: remove unnecessary rm instances","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-05-25T02:59:29Z","receivedAt":"2021-05-25T02:59:34Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Felipe Contreras <felipe.contreras@gmail.com> writes:\n\n> I happen to have at hand a script that ranks the most common trailer\n> lines:\n>\n>  * acked-by: 25% (1945)\n>\n> Doesn't apply.\n>\n>  * reviewed-by: 22% (1729)\n>\n> This does apply, but I'm not confident Jeff would like me to add that.\n>\n>  * helped-by: 17% (1336)\n\nI actually think people use this one to say \"person X gave a\nvaluable input in the review discussion\", which is exactly the case\nhere, and that was why I wondered you needed to invent a completely\nnew one.\n\n"},{"id":"425493","messageId":"60ac9f332eeec_225d820832@natae.notmuch","threadId":"55750","inReplyTo":"xmqqwnrnh626.fsf@gitster.g","subject":"Re: [PATCH v3 3/5] doc: remove unnecessary rm instances","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-25T06:54:43Z","receivedAt":"2021-05-25T06:54:47Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Junio C Hamano wrote:\n> Felipe Contreras <felipe.contreras@gmail.com> writes:\n> \n> > I happen to have at hand a script that ranks the most common trailer\n> > lines:\n> >\n> >  * acked-by: 25% (1945)\n> >\n> > Doesn't apply.\n> >\n> >  * reviewed-by: 22% (1729)\n> >\n> > This does apply, but I'm not confident Jeff would like me to add that.\n> >\n> >  * helped-by: 17% (1336)\n> \n> I actually think people use this one to say \"person X gave a\n> valuable input in the review discussion\", which is exactly the case\n> here, and that was why I wondered you needed to invent a completely\n> new one.\n\nI think the opposite: \"helped-by\" encompasses virtually anything. A\nperson that reviews, reports, mentors, suggests, tests, provides a\npatch, contributes, and co-authors... is helping.\n\nThe question is *how* he helped in this particular patch... By providing\ncomments.\n\n-- \nFelipe Contreras\n"},{"id":"425529","messageId":"xmqqim36eo12.fsf@gitster.g","threadId":"55750","inReplyTo":"60ac9f332eeec_225d820832@natae.notmuch","subject":"Re: [PATCH v3 3/5] doc: remove unnecessary rm instances","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-05-25T17:11:53Z","receivedAt":"2021-05-25T17:11:58Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Felipe Contreras <felipe.contreras@gmail.com> writes:\n\n> Junio C Hamano wrote:\n>> Felipe Contreras <felipe.contreras@gmail.com> writes:\n>> >  * helped-by: 17% (1336)\n>> \n>> I actually think people use this one to say \"person X gave a\n>> valuable input in the review discussion\", which is exactly the case\n>> here, and that was why I wondered you needed to invent a completely\n>> new one.\n>\n> I think the opposite: \"helped-by\" encompasses virtually anything...\n\nBut your own stats disagrees with your opinion, so don't invent a\nnew thing, period.\n\n"},{"id":"425540","messageId":"60ad769938b70_294de208fc@natae.notmuch","threadId":"55750","inReplyTo":"xmqqim36eo12.fsf@gitster.g","subject":"Re: [PATCH v3 3/5] doc: remove unnecessary rm instances","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-25T22:13:45Z","receivedAt":"2021-05-25T22:13:50Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Junio C Hamano wrote:\n> Felipe Contreras <felipe.contreras@gmail.com> writes:\n> \n> > Junio C Hamano wrote:\n> >> Felipe Contreras <felipe.contreras@gmail.com> writes:\n> >> >  * helped-by: 17% (1336)\n> >> \n> >> I actually think people use this one to say \"person X gave a\n> >> valuable input in the review discussion\", which is exactly the case\n> >> here, and that was why I wondered you needed to invent a completely\n> >> new one.\n> >\n> > I think the opposite: \"helped-by\" encompasses virtually anything...\n> \n> But your own stats disagrees with your opinion, so don't invent a\n> new thing, period.\n\nStats don't have opinions.\n\nYou and I have had this discussion before, between the status quo:\n\n\tdie (\"could not find author in commit %s\",\n\t     oid_to_hex(&commit->object.oid));\n\nAnd:\n\n\tdie(\"could not find author in commit %s\",\n\t\toid_to_hex(&commit->object.oid));\n\nEventually you yourself updated the documentation to explicitly state\nthat it's fine to not align the subsequent lines to the opening\nparenthesis: f26443da04 (CodingGuidelines: on splitting a long line,\n2014-05-02).\n\nIt is wrong to demand something that is not in the guidelines,\nespecially if later on the guidelines might include the very thing\nsupposedly frowned upon [*].\n\n\nIn this particular case the guideline is not missing, it actually sides\nwith me:\n\n  You can also create your own tag or use one that's in common usage\n  such as \"Thanks-to:\", \"Based-on-patch-by:\", or \"Mentored-by:\".\n\nIf you want to forbid certain commit trailers--or limit the allowed\ntrailers to a sanctioned list--then update the guidelines first to\nreflect that.\n\n\nBut I don't think it makes sense to do that, because commit\ntrailers--just like words, and hundreds of other things--follow a Zipf's\nlaw, where the 10th most common word appears around 1/10th of the time.\n\nIf you graph the frequency of commit trailers vs. a Zipf distrubtion\nwith a 80:20 rule, it follows it almost perfectly [1]. That means 80% of the\ncommit trailers appear 20% of the time.\n\nMy script can calculate any quantile and for example found out that just\ntwo lines--Acked-by and Reviewed-by--acound for 47% of all the lines.\nThey are the top 1%.\n\nThe top 10% is constituted by 16 lines, and the top 25% are 33.\n\nThe median is 1 appearance. That means of the 155 unique lines, half of\nthem have just 1 appearance, in fact, more than half: 100 of them.\n\nFor more details see the mail I just sent [2].\n\nUnsurprisingly commit trailer lines follow the same pattern as income\ndistribution and musical bands popularity; the rich get richer.\n\nAs much as you might despise the poorest among commit trailers, they are\nthe majority, and they will keep being the majority.\n\nCheers.\n\n[1] https://i.imgur.com/1wQgSlP.png\n[2] https://lore.kernel.org/git/60ad75ac7ffca_2ae08208b@natae.notmuch/\n\n[Footnote]\n\n * Granted, my patch back then did not match the new guideline\n   perfectly, but also it wasn't wrong for reasons stated then.\n\n-- \nFelipe Contreras\n"},{"id":"425542","messageId":"60ad9552dd14c_2c31c2088a@natae.notmuch","threadId":"55750","inReplyTo":"60ad769938b70_294de208fc@natae.notmuch","subject":"Re: [PATCH v3 3/5] doc: remove unnecessary rm instances","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-26T00:24:50Z","receivedAt":"2021-05-26T00:24:55Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Felipe Contreras wrote:\n> Junio C Hamano wrote:\n> > Felipe Contreras <felipe.contreras@gmail.com> writes:\n> > \n> > > Junio C Hamano wrote:\n> > >> Felipe Contreras <felipe.contreras@gmail.com> writes:\n> > >> >  * helped-by: 17% (1336)\n> > >> \n> > >> I actually think people use this one to say \"person X gave a\n> > >> valuable input in the review discussion\", which is exactly the case\n> > >> here, and that was why I wondered you needed to invent a completely\n> > >> new one.\n> > >\n> > > I think the opposite: \"helped-by\" encompasses virtually anything...\n> > \n> > But your own stats disagrees with your opinion, so don't invent a\n> > new thing, period.\n> \n> Stats don't have opinions.\n\nPlus, here are some instances of commit trailer lines used only *once*\nby big names of git.git (they are the authors).\n\n2014-02-18: brought-to-attention-by: Junio C Hamano\n2012-03-16: discussion-triggered-by: Junio C Hamano\n2011-04-26: heavylifting-by: Junio C Hamano\n2010-06-23: initial-fix-by: Junio C Hamano\n2008-10-23: tested-on-freebsd-by: Junio C Hamano\n2008-10-23: tested-on-aix-by: Junio C Hamano\n2008-08-19: tested-on-mingw-by: Junio C Hamano\n2008-03-23: reference: Junio C Hamano\n\n2020-12-11: initial-patch-by: Johannes Schindelin\n2020-11-19: pointed-out-by: Johannes Schindelin\n2020-08-12: simplified-testcase-and-bisection-by: Elijah Newren\n2020-04-27: documentation-by: Elijah Newren\n2019-10-10: inspired-by-a-patch-by: Johannes Schindelin\n2018-07-16: explanation-by: Stefan Beller\n2018-01-04: also-reported-by: Johannes Schindelin\n2017-09-23: reported-at: Jeff King\n2017-01-06: test-provided-by: Stefan Beller\n2016-10-07: issue-found-by: Jakub Narębski\n2016-09-04: benchmarked-by: Christian Couder\n2016-05-11: initial-test-by: Johannes Schindelin\n2016-05-03: fix-proposed-by: Stefan Beller\n2016-01-13: assisted-by: Johannes Schindelin\n2016-01-12: derived-from-code-by: Johannes Schindelin\n2015-09-24: history-dug-by: Jeff King\n2015-09-09: reported-and-suggested-by: Johannes Schindelin\n2015-06-30: clever-idea-by: Jeff King\n2015-05-20: test-adapted-from: Jeff King\n2015-03-03: edited-by: Stefan Beller\n2014-12-12: tweaked-by: Michael Haggerty\n2014-12-08: analyzed-by: Nguyễn Thái Ngọc Duy\n2014-11-02: adapted-by: Nguyễn Thái Ngọc Duy\n2014-06-08: reminded-by: Nguyễn Thái Ngọc Duy\n2013-12-28: clarified-by: Jeff King\n2013-08-21: revised-by: Shawn O. Pearce\n2013-08-16: reported-and-analyzed-by: Nguyễn Thái Ngọc Duy\n2013-07-09: more-spots-found-by: Jeff King\n2013-02-23: brown-paper-bag-fixes-by: Jeff King\n2012-10-12: initial-work-by: Nguyễn Thái Ngọc Duy\n2012-07-22: reported-tested-and-explained-by: Jonathan Nieder\n2011-09-22: tracked-down-by: Nguyễn Thái Ngọc Duy\n2011-09-16: originally-by: Jakub Narębski\n2011-04-28: inspired-by-patch-by: Jakub Narębski\n2011-04-28: inspired-by-code-by: Jakub Narębski\n2011-04-28: based-on-code-by: Jakub Narębski\n2011-01-06: works-around: Jonathan Nieder\n2011-01-02: helpd-by: Jonathan Nieder\n2009-12-07: looks-fine-to-me-by: Jeff King\n2009-11-11: originally-submitted-by: Jonathan Nieder\n2009-05-15: looks-right-to-me-by: Johannes Schindelin\n2008-12-26: patch-by: Shawn O. Pearce\n2008-12-07: kind-of-noticed-by: Jakub Narębski\n2008-07-03: backtraced-by: Shawn O. Pearce\n2008-06-13: deemed-obviously-correct-by: Shawn O. Pearce\n2008-03-29: patch-submitted-by: Eric Wong\n2007-12-07: test-proposed-by: Jakub Narębski\n2007-11-17: completely-acked-by: Jeff King\n2007-09-12: proposed-by: Shawn O. Pearce\n2007-06-03: hopefully-signed-off-by: Johannes Schindelin\n2007-05-19: confirmed-by: Eric Wong\n\n-- \nFelipe Contreras"},{"id":"425679","messageId":"YK+texFSW6UurDui@coredump.intra.peff.net","threadId":"55750","inReplyTo":"xmqq7djoj9z9.fsf@gitster.g","subject":"Re: [PATCH v3 0/5] doc: asciidoc cleanups","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-05-27T14:32:27Z","receivedAt":"2021-05-27T14:32:31Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, May 25, 2021 at 02:51:54AM +0900, Junio C Hamano wrote:\n\n> >  Documentation/Makefile | 77 ++++++++++++++++--------------------------\n> >  1 file changed, 29 insertions(+), 48 deletions(-)\n> \n> Is this satisfactory to everybody (I haven't taken a look beyond\n> comparing the end results)?\n\nYes, all five patches look good to me.\n\nThe \"comments-by\" sub-thread looked unproductive to me, so I mostly\nskipped it. ;) But as the person whose name was in the trailer, I will\nsay that I do not care either way if it is included. It did not seem to\nadd anything to me. Some trailers are good for pointing later readers to\nfolks who may be able to help understand or debug an old commit. Some\nare good for just giving credit to people who helped. \"Comments-by\"\ndidn't really seem to do either to me (and I don't feel like I\ncontributed much worthy of credit anyway).\n\n-Peff\n"},{"id":"425692","messageId":"60afcfec2d93c_26530208ae@natae.notmuch","threadId":"55750","inReplyTo":"YK+texFSW6UurDui@coredump.intra.peff.net","subject":"Re: [PATCH v3 0/5] doc: asciidoc cleanups","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-27T16:59:24Z","receivedAt":"2021-05-27T16:59:33Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Jeff King wrote:\n> On Tue, May 25, 2021 at 02:51:54AM +0900, Junio C Hamano wrote:\n> \n> > >  Documentation/Makefile | 77 ++++++++++++++++--------------------------\n> > >  1 file changed, 29 insertions(+), 48 deletions(-)\n> > \n> > Is this satisfactory to everybody (I haven't taken a look beyond\n> > comparing the end results)?\n> \n> Yes, all five patches look good to me.\n\nSo... Acked-by?\n\n> The \"comments-by\" sub-thread looked unproductive to me, so I mostly\n> skipped it. ;) But as the person whose name was in the trailer, I will\n> say that I do not care either way if it is included. It did not seem to\n> add anything to me. Some trailers are good for pointing later readers to\n> folks who may be able to help understand or debug an old commit. Some\n> are good for just giving credit to people who helped. \"Comments-by\"\n> didn't really seem to do either to me (and I don't feel like I\n> contributed much worthy of credit anyway).\n\nBut you did provide comments, and those comments resulted in changes, so\nthe comments-by line is accurate. And for what it's worth that commit\ntrailer line has been used 3 times already, which places it in the 3rd\ntop decile.\n\nPerhaps some people would prefer feedback-by, but that that line has\nbeen used *zero* times. Even brown-paper-bag-fixes-by has been used more.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"425695","messageId":"YK/SZGTWd/tfSWeP@coredump.intra.peff.net","threadId":"55750","inReplyTo":"60afcfec2d93c_26530208ae@natae.notmuch","subject":"Re: [PATCH v3 0/5] doc: asciidoc cleanups","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-05-27T17:09:56Z","receivedAt":"2021-05-27T17:10:01Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, May 27, 2021 at 11:59:24AM -0500, Felipe Contreras wrote:\n\n> Jeff King wrote:\n> > On Tue, May 25, 2021 at 02:51:54AM +0900, Junio C Hamano wrote:\n> > \n> > > >  Documentation/Makefile | 77 ++++++++++++++++--------------------------\n> > > >  1 file changed, 29 insertions(+), 48 deletions(-)\n> > > \n> > > Is this satisfactory to everybody (I haven't taken a look beyond\n> > > comparing the end results)?\n> > \n> > Yes, all five patches look good to me.\n> \n> So... Acked-by?\n\nIf you want. I have never found that trailer to be particularly helpful.\n\n> > The \"comments-by\" sub-thread looked unproductive to me, so I mostly\n> > skipped it. ;) But as the person whose name was in the trailer, I will\n> > say that I do not care either way if it is included. It did not seem to\n> > add anything to me. Some trailers are good for pointing later readers to\n> > folks who may be able to help understand or debug an old commit. Some\n> > are good for just giving credit to people who helped. \"Comments-by\"\n> > didn't really seem to do either to me (and I don't feel like I\n> > contributed much worthy of credit anyway).\n> \n> But you did provide comments, and those comments resulted in changes, so\n> the comments-by line is accurate. And for what it's worth that commit\n> trailer line has been used 3 times already, which places it in the 3rd\n> top decile.\n\nI didn't say it was inaccurate. I just think it is not useful.\n\n-Peff\n"},{"id":"425698","messageId":"60afd868b68ae_2653020870@natae.notmuch","threadId":"55750","inReplyTo":"YK/SZGTWd/tfSWeP@coredump.intra.peff.net","subject":"Re: [PATCH v3 0/5] doc: asciidoc cleanups","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-27T17:35:36Z","receivedAt":"2021-05-27T17:35:40Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Jeff King wrote:\n> > > The \"comments-by\" sub-thread looked unproductive to me, so I mostly\n> > > skipped it. ;) But as the person whose name was in the trailer, I will\n> > > say that I do not care either way if it is included. It did not seem to\n> > > add anything to me. Some trailers are good for pointing later readers to\n> > > folks who may be able to help understand or debug an old commit. Some\n> > > are good for just giving credit to people who helped. \"Comments-by\"\n> > > didn't really seem to do either to me (and I don't feel like I\n> > > contributed much worthy of credit anyway).\n> > \n> > But you did provide comments, and those comments resulted in changes, so\n> > the comments-by line is accurate. And for what it's worth that commit\n> > trailer line has been used 3 times already, which places it in the 3rd\n> > top decile.\n> \n> I didn't say it was inaccurate. I just think it is not useful.\n\nI understood. I'm not saying the tag must be there because it's useful\n(I agree it's usefulness is marginal at best), I'm saying including it\ndoes not hurt.\n\n-- \nFelipe Contreras\n"},{"id":"425720","messageId":"xmqqmtsf9151.fsf@gitster.g","threadId":"55750","inReplyTo":"YK+texFSW6UurDui@coredump.intra.peff.net","subject":"Re: [PATCH v3 0/5] doc: asciidoc cleanups","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-05-28T00:02:02Z","receivedAt":"2021-05-28T00:02:09Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King <peff@peff.net> writes:\n\n> On Tue, May 25, 2021 at 02:51:54AM +0900, Junio C Hamano wrote:\n>\n>> >  Documentation/Makefile | 77 ++++++++++++++++--------------------------\n>> >  1 file changed, 29 insertions(+), 48 deletions(-)\n>> \n>> Is this satisfactory to everybody (I haven't taken a look beyond\n>> comparing the end results)?\n>\n> Yes, all five patches look good to me.\n\nThe issue that it interacts in a funny way with what brian already\nhas in 'seen' aside, the patches look good to me, too, so let's\nstart merging it down.\n\n> The \"comments-by\" sub-thread looked unproductive to me, so I mostly\n> skipped it. ;) But as the person whose name was in the trailer, I will\n> say that I do not care either way if it is included. It did not seem to\n> add anything to me. Some trailers are good for pointing later readers to\n> folks who may be able to help understand or debug an old commit. Some\n> are good for just giving credit to people who helped. \"Comments-by\"\n> didn't really seem to do either to me (and I don't feel like I\n> contributed much worthy of credit anyway).\n\nExactly the same feeling.  It didn't add any value that was why I\nsaw no point in using something almost nobody uses (instead of the\nmore commonly used Helped-by, for example).\n\nThanks.\n"},{"id":"425723","messageId":"60b0437310c0_405922085b@natae.notmuch","threadId":"55750","inReplyTo":"xmqqmtsf9151.fsf@gitster.g","subject":"Re: [PATCH v3 0/5] doc: asciidoc cleanups","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-28T01:12:19Z","receivedAt":"2021-05-28T01:12:24Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Junio C Hamano wrote:\n> Jeff King <peff@peff.net> writes:\n\n> > The \"comments-by\" sub-thread looked unproductive to me, so I mostly\n> > skipped it. ;) But as the person whose name was in the trailer, I will\n> > say that I do not care either way if it is included. It did not seem to\n> > add anything to me. Some trailers are good for pointing later readers to\n> > folks who may be able to help understand or debug an old commit. Some\n> > are good for just giving credit to people who helped. \"Comments-by\"\n> > didn't really seem to do either to me (and I don't feel like I\n> > contributed much worthy of credit anyway).\n> \n> Exactly the same feeling.  It didn't add any value that was why I\n> saw no point in using something almost nobody uses (instead of the\n> more commonly used Helped-by, for example).\n\nAs I demonstrated with probabilistic certainty; everyone uses uncommon\nlines (including you). The fact that a line is uncommon doesn't\nnecessarily mean it's bad, in fact, I do see value in going outside the\nbox (like one of my favorites: Brown-paper-bag-fixes-by [4981fe750b]).\n\nAnd of course if you find Comments-by so egregious, you can amend my\ncommit message (as you have done many times in the past). But this might\nbe a good opportunity to exercise the advice Jeff gave in another\nthread, and even if you are not 100% happy with something, let it slide.\n\nCheers.\n\n-- \nFelipe Contreras\n"}]}