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.

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