Re: [PATCH/RFC] Unify argument and option notation in the docs

["Štěpán Němec" <stepnem@gmail.com>]

Jonathan Nieder <jrnieder@gmail.com> writes:

> Štěpán Němec wrote:
>> [It is conceivable I could submit this as a series of smaller patches,
>> but the problems this is solving didn't seem diverse enough to me to
>> warrant that.
>
> Since the documentation processor is known to be, um, picky, could you
> do that?  That way after bisecting a formatting problem, one has a
> diff addressing a single issue to look at.

OK. Another reason I didn't do that is that my patch actually does not
introduce any mark-up not already present in the sources, so it
shouldn't introduce any new breakage AFAICT.

> On the other hand, I am happy enough to comment on a single, monolithic
> patch on list if you publish the smaller patches making it up in a git
> repository somewhere.
>
>> 1. Is `[--refs [--unpacked | --all]]' in `git-pack-object' documentation
>> correct? From my reading of builtin/pack-objects.c, `--unpacked' and
>> `--all' do the same thing and both imply --refs, so perhaps [--refs |
>> --unpacked | --all] would make more sense?
>
> Doesn't the OPTIONS section explain what --revs, --unpacked, and --all
> mean?

It does, but IMO it contradicts the synopsis. Doesn't the fact that
--unpacked and --all _imply_ --rev mean that you don't need to supply
the latter if you already gave one of the former two? That's also what I
understood from looking at pack-objects.c. So neither [--revs
[(--unpacked|--all)...]] nor [--revs [--unpacked|--all]] seem correct to
me.

I also don't see why you would want to supply --unpacked or --all
multiple times, so `...' would be definitely wrong, no?

>> (I also noticed that the
>> --reflog option is shown in the usage string but undocumented.)
>
> Looks like someone forgot to add it to the man page.

OK. I'll leave that to someone who knows what the option is supposed to
do; it's a matter for a separate patch anyway.

>> 2. I left in one special case, namely the GIT_* variables in `git(1)'
>> synopsis section as values for the `--exec-path' and other options.
>
> Hmm, --exec-path=GIT_EXEC_PATH currently serves as a reminder of the
> name of the corresponding environment variable, but I don't think
> that's very important.  --exec-path[=<path>] should be fine.

Yes, that's my opinion as well, thanks for confirmation. I'll include it
in the next round.

Štěpán