Re: [PATCH 8/8] Documentation/git-config: update to new-style syntax

[Eric Sunshine <sunshine@sunshineco.com>]

On Wed, Mar 6, 2024 at 6:32 AM Patrick Steinhardt <ps@pks.im> wrote:
> Update our documentation of git-config(1) to stop mentioning the old
> syntax while starting to mention the new syntax. Remove the help
> mismatch in t0450 so that we start to ensure that the manpage and
> builtin synopsis match.
> [...]
> Signed-off-by: Patrick Steinhardt <ps@pks.im>

I'd like to push back on the part of this patch which completely
eradicates mention of the old syntax. Doing so makes it difficult for
people to figure out the meaning of git-config commands which they run
across in blogs and existing tooling. For instance, the following
recommendation is commonly encountered in the wild:

    git config --global user.name "Your Name"
    git config --global user.email "youremail@yourdomain.com"

Typically, we instead retain the old syntax (or options or whatever)
in the documentation so that people who want to learn can learn, but
we rewrite it to make it clear that it is deprecated, and explicitly
point the reader at the modern replacement command or option (or
whatever).

So, perhaps you can have a SYNOPSIS section for the deprecated usage,
as well as a "DEPRECATED OPTIONS" section (or such), so that we don't
leave readers entirely in the dark.