Re: [PATCH 1/5] doc: git-add: remove options from SYNOPSIS

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

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Julia Evans <julia@jvns.ca>
>
> Motivations for this change:
>
> 1. Listing a huge number of options is visually overwhelming when
>    opening a man page for an unfamiliar command. It makes it harder
>    to understand the command's core syntax, like `git add <filename>`

For "git add", which has only one mode of operation, this may be
good.

Note that in general this is not necessarily a good idea, when a
command works in different modes (like "git branch" that can
list/enumerate or create/delete/manipulate), as not all the options
can be used in all the modes the command supports.  The "usage" part
of the output from "git branch -h" hits a good balance, and may want
to use as a model.

There is t0450 that aspires to ensure the short usage "git <cmd> -h"
matches the synopsis section of "git help <cmd>" for all <cmd>; right
now we have too many exceptions, and we should move towards making
these exceptions smaller.

> 2. For options which can be passed independently of any other options,
>    including them in the SYNOPSIS does not add any information which you
>    can't already get from reading the OPTIONS section.

Except that you have to scan a lot of text, which is quite
inefficient when you *know* the general idea behind the option you
want to use, and are only looking for the exact spelling of it (e.g.
"was it spelled --ignore-removed?")

> `git add` has
>    some mutually exclusive options, namely:
>    [--[no-]all | -A | --[no-]ignore-removal | [--update | -u]]
>    but personally I already find that line so hard to parse that
>    removing it doesn't remove a lot of information

It is a very good point why we may want to have these cues to
express "these go together" (my earlier example of "branch") and
"only one of these is used".  I tend to agree with you that these
are not necessarily very easy to read.

While it is important to make it easier for new readers to learn, we
should also keep in mind that nobody remains to be a newbie forever.

>  [synopsis]
> -git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p]
> -	[--edit | -e] [--[no-]all | -A | --[no-]ignore-removal | [--update | -u]] [--sparse]
> -	[--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] [--renormalize]
> -	[--chmod=(+|-)x] [--pathspec-from-file=<file> [--pathspec-file-nul]]
> -	[--] [<pathspec>...]

This being a long single line and with redundant "--long|-s" may be
making it unnecessarily ugly.  Have you considered folding lines and
simplifying "[--long | -s]" into "[-s]" and see if it makes easier
to follow?  Documentation/git-commit.adoc may serve as a better
model.

> +git add [<options>] [--] [<pathspec>...]
>  
>  DESCRIPTION
>  -----------