Re: [PATCH v2 4/9] git-sparse-checkout.txt: update docs for deprecation of 'init'

[Junio C Hamano <gitster@pobox.com>]

"Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com> writes:

> -When `--no-cone` is passed or `core.sparseCheckoutCone` is false,
> -the input list is considered a list of patterns.  This mode is harder
> -to use and less performant, and is thus not recommended.  See the
> -"Sparse Checkout" section of linkgit:git-read-tree[1] and the "Pattern
> -Set" sections below for more details.
> +When `--no-cone` is passed, the input list is considered a list of
> +patterns.  This mode is harder to use and less performant, and is thus

"less perfromant" can be quantified, but "harder to use" is probably
harder to defend.  Those on a project with need for more flexible
way to specify than "these are the directories I care about" would
not find it convincing.

> +not recommended.  See the "Sparse Checkout" section of
> +linkgit:git-read-tree[1]

The referenced section (I am reading "git read-tree --help" from
seen with these patches) may need updating.  It shows an example
of including everything except for unwanted, without mentioning
if that is for cone or non-cone.

> and the "Pattern Set" sections below for more
> +details.

Are we referring to "Internals - cone/full pattern set" sections?

This may be a topic of another step in this series, but the "core"
section starts by mentioning what characteristics the full pattern
set has and uses it to steer readers away from it, which I find it
less than ideal.  As we present "core" first (because it is the
default), we should present "core" by itself, without requiring to
know what the other thing is.  Perhaps replace the entire first
paragraph so that the section begins more like so:

	The "cone mode", which is the default, lets you specify only
	what directories to include and what directories to exclude.

	The accepted patterns in the cone pattern set are:...

Especially, the last sentence in the paragraph to be struck still
lives in the old world in which you needed to opt into the cone
mode.

Thanks.