Re: [RFC PATCH 1/1] Documentation/git-sparse-checkout.txt: add an OPTIONS section

[Derrick Stolee <derrickstolee@github.com>]

On 3/11/2022 8:21 AM, Shaoxuan Yuan wrote:
> Add an OPTIONS section to the manual and move the descriptions about
> these options from COMMANDS to the section.

This is a good goal.

> +OPTIONS
> +-------

However, there are a few issues with the current approach. First, I
believe it would be better to start with COMMANDS, then OPTIONS.

To be fair, we are not consistent here. These commands use OPTIONS
and then COMMANDS:

* git-commit-graph.txt
* git-remote.txt
* git-revert.txt

These use [SUB]COMMANDS and then OPTIONS:

* git-maintenance.txt
* git-notes.txt
* git-p4.txt
* git-stash.txt
* git-submodule.txt
* git-worktree.txt

My preference would be OPTIONS second (and we can clean up the
other docs as #leftoverbits). In particular, I noticed that
the SYNOPSIS for git-maintenance.txt is out of date.	

> +'--[no-]cone'::
> +	Use with ['set'|'reapply'].
> +	Specify using cone mode or not. The default is to use cone mode.
>  +
>  By default, the input list is considered a list of directories, matching
>  the output of `git ls-tree -d --name-only`.  This includes interpreting

The other issue is that this context is detailing information about
the 'set' command and the input it takes. You'll want to make sure
the information is properly grouped.

> @@ -78,6 +59,11 @@ with the `--sparse-index` option, and will likely be incompatible with
>  other new features as they are added.  See the "Non-cone Problems"
>  section below and the "Sparse Checkout" section of
>  linkgit:git-read-tree[1] for more details.
> +
> +'--[no-]sparse-index'::
> +	Use with ['set'|'reapply'].

I do like these clear indicators of which commands allow this
option. I wonder if it should instead be

	Use with the `set` and `reapply` commands.

Thanks,
-Stolee