From: Junio C Hamano <gitster@pobox.com>
To: Bagas Sanjaya <bagasdotme@gmail.com>
Cc: git@vger.kernel.org, Shaoxuan Yuan <shaoxuan.yuan02@gmail.com>,
Taylor Blau <me@ttaylorr.com>,
Derrick Stolee <derrickstolee@github.com>
Subject: Re: [PATCH] Documentation: simplify synopsis of git-repack(1)
Date: Sun, 13 Mar 2022 19:00:39 +0000 [thread overview]
Message-ID: <xmqqsfrlvfs8.fsf@gitster.g> (raw)
In-Reply-To: <20220312113136.26716-1-bagasdotme@gmail.com> (Bagas Sanjaya's message of "Sat, 12 Mar 2022 18:31:37 +0700")
Bagas Sanjaya <bagasdotme@gmail.com> writes:
> Simplify SYNOPSIS section to only mention [<options>...] placeholder.
> Redundant options list can now be avoided for aesthetic and clarity.
The "git cmd --help" output is meant to be readable and useful, so
clarity is good, but I do not know much about aesthetics.
More importantly, the above does not answer a lot more important
question. Is it just loss of duplicated information that this
commit brings in? Isn't the motivation that "not all options are
listed in SYNOPSIS section, and/or some options listed there are not
described in the body text and are not supported"? And instead of
trying to keep them in sync, the author chose to simplify SYNOPSIS
and have readers look options up in the body text, no? These two
would make a good pair of "what problem do we solve?" and "how we
choose to solve it?".
> [verse]
> -'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [-b] [-m] [--window=<n>] [--depth=<n>] [--threads=<n>] [--keep-pack=<pack-name>] [--write-midx]
> +'git repack' [<options>...]
Unlike commands with multiple "operation modes", "repack" does one
thing and only one thing, so a single-liner "git repack <options>"
may work well.
next prev parent reply other threads:[~2022-03-13 19:00 UTC|newest]
Thread overview: 5+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-03-12 11:31 [PATCH] Documentation: simplify synopsis of git-repack(1) Bagas Sanjaya
2022-03-13 19:00 ` Junio C Hamano [this message]
2022-03-22 7:11 ` Bagas Sanjaya
2022-03-22 9:16 ` Shaoxuan Yuan
2022-03-22 12:52 ` Ævar Arnfjörð Bjarmason
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=xmqqsfrlvfs8.fsf@gitster.g \
--to=gitster@pobox.com \
--cc=bagasdotme@gmail.com \
--cc=derrickstolee@github.com \
--cc=git@vger.kernel.org \
--cc=me@ttaylorr.com \
--cc=shaoxuan.yuan02@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).