[PATCH v4 0/9] Makefile & docs: document SHA-{1,256} behavior, fix bug

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

This is a documentation update to get to the eventual goal of making
DC_SHA1 the defaul on OSX. First we need to stop claiming that OpenSSL
is still our default everywhere, etc.

For v3 see:
https://lore.kernel.org/git/cover-v3-0.9-00000000000-20221020T223946Z-avarab@gmail.com/;
The updates here are all typos/grammar etc. issues spotted by Eric
Sunshine, thanks!

Junio: This v4 introduces a minor conflict with the subsequent DC_SHA1
topic[1], but you haven't picked that one up either, so I'm assuming
if you're interested in this at all it's better to cook this first.

In case you want both It's easily solved (just keep the other topic's
post-image). I.e. Eric pointed out a better wording for a paragraph,
but it's the one we're mostly removing/rewriting in [1].

1. https://lore.kernel.org/git/cover-v2-0.4-00000000000-20221019T010222Z-avarab@gmail.com/

Ævar Arnfjörð Bjarmason (9):
  Makefile: always (re)set DC_SHA1 on fallback
  INSTALL: remove discussion of SHA-1 backends
  Makefile: correct DC_SHA1 documentation
  Makefile: create and use sections for "define" flag listing
  Makefile: rephrase the discussion of *_SHA1 knobs
  Makefile: document default SHA-256 backend
  Makefile: document SHA-1 and SHA-256 default and selection order
  Makefile: document default SHA-1 backend on OSX
  Makefile: discuss SHAttered in *_SHA{1,256} discussion

 INSTALL  |   4 -
 Makefile | 259 +++++++++++++++++++++++++++++++++++--------------------
 2 files changed, 165 insertions(+), 98 deletions(-)

Range-diff against v3:
 1:  ef3c5be11e0 =  1:  11e92d15616 Makefile: always (re)set DC_SHA1 on fallback
 2:  017a0a9791c =  2:  abbe25f56b3 INSTALL: remove discussion of SHA-1 backends
 3:  62dd2d5708d =  3:  b0bd35987c0 Makefile: correct DC_SHA1 documentation
 4:  933bef576b3 =  4:  d0451d6c3a3 Makefile: create and use sections for "define" flag listing
 5:  5b18198c477 !  5:  b956d1c2640 Makefile: rephrase the discussion of *_SHA1 knobs
    @@ Makefile: include shared.mak
      #
     -# Define OPENSSL_SHA1 environment variable when running make to link
     -# with the SHA1 routine from openssl library.
    -+# Define OPENSSL_SHA1 to link to the the SHA-1 routines from
    -+# the OpenSSL library.
    ++# Define OPENSSL_SHA1 to link to the SHA-1 routines from the OpenSSL
    ++# library.
      #
      # === SHA-256 backend ===
      #
 6:  73685592aba =  6:  1e4695d0ba0 Makefile: document default SHA-256 backend
 7:  05edcfb9cd9 !  7:  847be3d32e2 Makefile: document SHA-1 and SHA-256 default and selection order
    @@ Commit message
         we'd error out if conflicting flags were provided, but per the
         discussion downhtread of[1] the consensus was to keep theses semantics.
     
    -    This behavior make it easier to e.g. integrate with autoconf-like
    +    This behavior makes it easier to e.g. integrate with autoconf-like
         systems, where the configuration can provide everything it can
         support, and Git is tasked with picking the first one it prefers.
     
    @@ Makefile: include shared.mak
      #
     +# ==== Default SHA-1 backend ====
     +#
    -+# If no *_SHA1 backend is picked we'll fall fall back on using the
    -+# default.
    ++# If no *_SHA1 backend is picked we'll fall back on using the default.
     +#
     +# Multiple *_SHA1 backends can be selected, the first supported one
     +# listed in "Other SHA-1 implementations" will be picked.
    @@ Makefile: include shared.mak
     -# Define BLK_SHA1 to make use of optimized C SHA-1 routines bundled
     -# with git (in the block-sha1/ directory).
     -#
    - # Define OPENSSL_SHA1 to link to the the SHA-1 routines from
    - # the OpenSSL library.
    + # Define OPENSSL_SHA1 to link to the SHA-1 routines from the OpenSSL
    + # library.
      #
     +# Define BLK_SHA1 to make use of optimized C SHA-1 routines bundled
     +# with git (in the block-sha1/ directory).
 8:  859e69fbe9f !  8:  0af3ea78eaf Makefile: document default SHA-1 backend on OSX
    @@ Makefile: include shared.mak
      #
     +# Define NO_APPLE_COMMON_CRYPTO on OSX to opt-out of using the
     +# "APPLE_COMMON_CRYPTO" backend for SHA-1, which is currently the
    -+# default on that OS. We'll define NO_APPLE_COMMON_CRYPTO on Mac OS
    -+# 10.4 or older ("Tiger", released in early 2005).
    ++# default on that OS. On macOS 01.4 (Tiger) or older,
    ++# NO_APPLE_COMMON_CRYPTO is defined by default.
     +#
      # === SHA-256 backend ===
      #
 9:  c1f27255d3e !  9:  9045ff9c4ed Makefile: discuss SHAttered in *_SHA{1,256} discussion
    @@ Makefile: include shared.mak
     +#
      # ==== Default SHA-1 backend ====
      #
    - # If no *_SHA1 backend is picked we'll fall fall back on using the
    + # If no *_SHA1 backend is picked we'll fall back on using the default.
     @@ Makefile: include shared.mak
      #
      # === SHA-256 backend ===
-- 
2.38.0.1251.g3eefdfb5e7a