Re: [PATCH 1/4] docs: update git hash algorithm for breaking changes mode

[Junio C Hamano <gitster@pobox.com>]

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

> +ifndef::with-breaking-changes[]
> +	The default is "sha1".
> +endif::with-breaking-changes[]
> +ifdef::with-breaking-changes[]
> +	The default is "sha256".
> +endif::with-breaking-changes[]
>  	See `--object-format` in linkgit:git-init[1].
>  
>  `GIT_DEFAULT_REF_FORMAT`::

I wonder if we can have a macro definition at a central location, so
that we can refer to the text without "ifdef" everywhere?

Caution: this illustration of the idea seems to work with AsciiDoc
but it was typed in an airline lounge with rum-and-coke in my left
hand and haven't been tested with Asciidoctor at all.  I do not even
understand why many other [attributes] entries like {asterisk} can
successfully be grokked by Asciidoctor, but we seem to do -alitdd=<>
in the Makefile for Asciidoctor, so I mimicked it without fully
understanding what is going on.

But the patch should be good enough to illustrate the idea.

 Documentation/Makefile         | 5 +++++
 Documentation/asciidoc.conf.in | 6 ++++++
 Documentation/git.adoc         | 2 +-
 3 files changed, 12 insertions(+), 1 deletion(-)

diff --git c/Documentation/Makefile w/Documentation/Makefile
index 04e9e10b27..88b8ed55a2 100644
--- c/Documentation/Makefile
+++ w/Documentation/Makefile
@@ -222,6 +222,11 @@ ASCIIDOC_DOCBOOK = docbook5
 ASCIIDOC_EXTRA += -acompat-mode -atabsize=8
 ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions
 ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
+ifdef WITH_BREAKING_CHANGES
+ASCIIDOC_EXTRA += -adefaulthash=sha256
+else
+ASCIIDOC_EXTRA += -adefaulthash=sha1
+endif
 ASCIIDOC_EXTRA += -adocinfo=shared
 ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
 DBLATEX_COMMON =
diff --git c/Documentation/asciidoc.conf.in w/Documentation/asciidoc.conf.in
index ff9ea0a294..2de6b80197 100644
--- c/Documentation/asciidoc.conf.in
+++ w/Documentation/asciidoc.conf.in
@@ -24,6 +24,12 @@ litdd=&#45;&#45;
 manmanual=Git Manual
 mansource=Git @GIT_VERSION@
 revdate=@GIT_DATE@
+ifdef::with-breaking-changes[]
+defaulthash=sha256
+endif::with-breaking-changes[]
+ifndef::with-breaking-changes[]
+defaulthash=sha1
+endif::with-breaking-changes[]
 
 ifdef::doctype-book[]
 [titles]
diff --git c/Documentation/git.adoc w/Documentation/git.adoc
index 8c6a3f6042..f21dbba5a1 100644
--- c/Documentation/git.adoc
+++ w/Documentation/git.adoc
@@ -576,7 +576,7 @@ double-quotes and respecting backslash escapes. E.g., the value
 	If this variable is set, the default hash algorithm for new
 	repositories will be set to this value. This value is
 	ignored when cloning and the setting of the remote repository
-	is always used. The default is "sha1".
+	is always used. The default is "{defaulthash}".
 	See `--object-format` in linkgit:git-init[1].
 
 `GIT_DEFAULT_REF_FORMAT`::