Re: [PATCH v2] name-rev: make --stdin hidden

From: Eric Sunshine <sunshine@sunshineco.com>
Date: May 5, 2023, 19:31 UTC
Message-ID: <CAPig+cRRyMBQCiS7v0B1J+PSJFVVR++oOssrW7M3xwXS-2_jwQ@mail.gmail.com>
In-Reply-To: <pull.1225.v2.git.git.1683314270964.gitgitgadget@gmail.com>

On Fri, May 5, 2023 at 3:19 PM John Cai via GitGitGadget <gitgitgadget@gmail.com> wrote:

Show 7 quoted lines

> In 34ae3b70 (name-rev: deprecate --stdin in favor of --annotate-stdin),
> we renamed --stdin to --annotate-stdin for the sake of a clearer name
> for the option, and added text that indicates --stdin is deprecated. The
> next step is to hide --stdin completely.
>
> Make the option hidden. Also, update documentation to remove all
> mentions of --stdin.

Eradicating all mention of --stdin from the documentation makes it more hostile for end-users, doesn't it? If someone runs across --stdin in a blog post or in some in-the-wild script, then this makes it more difficult to learn what the option does. In other such cases, rather than purging all mention from documentation, we've instead mentioned the deprecated option only as a minor aside of the option which replaces it. For instance:

    --annotate-stdin::
        Transform stdin by ... omitting $hex altogether.
        `--stdin` is a deprecated synonym.

> Signed-off-by: "John Cai" <johncai86@gmail.com>