From: "Ævar Arnfjörð Bjarmason" <firstname.lastname@example.org> To: Jeff King <email@example.com> Cc: Taylor Blau <firstname.lastname@example.org>, Junio C Hamano <email@example.com>, firstname.lastname@example.org, Kyle Meyer <email@example.com>, Eric Sunshine <firstname.lastname@example.org> Subject: Re: [PATCH v2] rev-list --disk-usage Date: Thu, 11 Feb 2021 13:04:26 +0100 [thread overview] Message-ID: <email@example.com> (raw) In-Reply-To: <YCUOSmnsJ4LLPFgK@coredump.intra.peff.net> On Thu, Feb 11 2021, Jeff King wrote: > On Wed, Feb 10, 2021 at 06:15:16PM -0500, Taylor Blau wrote: > >> > > I kind of feel sad to have a nice write-up like this only in the >> > > list archive. Is there a section in our documentation set to keep >> > > collection of such a real-life use cases? Perhaps the examples >> > > section of manpages is the closest thing, but it looks a bit too >> > > narrowly scoped for the example section of "rev-list" manpage. >> > >> > Agreed on both counts. If this gets put into a release, I suspect Taylor >> > would cover it in a release blog post. That is not quite the same thing >> > as having it in the documentation, but it may provide more search engine >> > boost than the list archive. I dunno. >> >> Yeah, this is the perfect sort of thing for those blog posts. >> >> But it makes sense to include some of these examples in our own >> documentation here, too. git-rev-list(1) doesn't have an EXAMPLES >> section, but maybe it should. > > I think this is the "narrowly scoped" bit from Junio's response above. > It would be a bit weird to have an examples section for rev-list that > only mentions this rather obscure feature. I don't think the lack of an EXAMPLES section or the relative obscurity of the switch should preclude us from adding useful documentation. Yes it would feel a bit out of place, but we can always have a sub-section of EXAMPLES, and we've got to start somewhere. In this case I don't see why it couldn't be added to OPTIONS, we've got some very long discussion there already, and as long as there's a clear separation in prose from an initial brief discussion of the switch and further prose it won't be confusing for readers, they can just page past the details.
next prev parent reply other threads:[~2021-02-11 12:08 UTC|newest] Thread overview: 30+ messages / expand[flat|nested] mbox.gz Atom feed top 2021-01-27 22:11 [PATCH 0/2] " Jeff King 2021-01-27 22:12 ` [PATCH 1/2] t: add --no-tag option to test_commit Jeff King 2021-01-27 22:48 ` Taylor Blau 2021-01-27 22:17 ` [PATCH 2/2] rev-list: add --disk-usage option for calculating disk usage Jeff King 2021-01-27 22:57 ` Taylor Blau 2021-01-27 23:34 ` Jeff King 2021-01-27 23:01 ` Kyle Meyer 2021-01-27 23:36 ` Jeff King 2021-01-27 23:07 ` Eric Sunshine 2021-01-27 23:39 ` Jeff King 2021-01-27 22:46 ` [PATCH 0/2] rev-list --disk-usage Taylor Blau 2021-02-09 10:52 ` [PATCH v2] " Jeff King 2021-02-09 10:52 ` [PATCH v2 1/2] t: add --no-tag option to test_commit Jeff King 2021-02-09 10:53 ` [PATCH v2 2/2] rev-list: add --disk-usage option for calculating disk usage Jeff King 2021-02-09 11:09 ` [PATCH v2] rev-list --disk-usage Jeff King 2021-02-09 21:14 ` Junio C Hamano 2021-02-10 9:38 ` Jeff King 2021-02-10 0:44 ` Junio C Hamano 2021-02-10 1:49 ` Taylor Blau 2021-02-10 10:01 ` Jeff King 2021-02-10 16:31 ` Junio C Hamano 2021-02-10 20:38 ` Jeff King 2021-02-10 23:15 ` Taylor Blau 2021-02-11 11:00 ` Jeff King 2021-02-11 12:04 ` Ævar Arnfjörð Bjarmason [this message] 2021-02-11 17:57 ` Junio C Hamano 2021-02-17 23:31 ` [PATCH 0/2] rev-list --disk-usage example docs Jeff King 2021-02-17 23:34 ` [PATCH 1/2] docs/rev-list: add an examples section Jeff King 2021-02-17 23:35 ` [PATCH 2/2] docs/rev-list: add some examples of --disk-usage Jeff King 2021-02-17 23:44 ` [PATCH 0/2] rev-list --disk-usage example docs Taylor Blau
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 \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --subject='Re: [PATCH v2] rev-list --disk-usage' \ /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
This is a public inbox, see mirroring instructions on how to clone and mirror all data and code used for this inbox