doc: stash: split options from description (2)
authorAlexandr Miloslavskiy <alexandr.miloslavskiy@syntevo.com>
Mon, 17 Feb 2020 17:25:18 +0000 (17:25 +0000)
committerJunio C Hamano <gitster@pobox.com>
Wed, 19 Feb 2020 18:56:49 +0000 (10:56 -0800)
commit0093abc286fe3f195f702de28c6d9af009dda8e0
tree10285f625b46d407ababdb6be13e8c9ef0693528
parent2b7460d16719b751f025094ba9c8d10c81a6c4b1
doc: stash: split options from description (2)

Together with the previous patch, this brings docs for `git stash` to
the common layout used for most other commands (see for example docs
for `git add`, `git commit`, `git checkout`, `git reset`) where all
options are documented in a separate list.

After some thinking and having a look at docs for `git svn` and
`git `submodule`, I have arrived at following conclusions:
  * Options should be described in a list rather then text to
    facilitate lookup for user.
  * Single list is better then multiple lists because it avoids
    copy&pasting descriptions between subcommands (or, without
    copy&pasting, user will have to look up missing options in other
    subcommands).
  * As a consequence, commands section should only give brief info and
    list possible options. Since options have good enough names, user
will only need to look up the "interesting" options.
  * Every option should list which subcommands support it.

I have decided to use alphabetical sorting in the list of options to
facilitate lookup for user.

There is some text editing done to make old descriptions better fit
into the list-style format.

Signed-off-by: Alexandr Miloslavskiy <alexandr.miloslavskiy@syntevo.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Documentation/git-stash.txt