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

From: Štěpán Němec <stepnem@gmail.com>
Date: Oct 8, 2010, 11:13 UTC
Message-ID: <87fwwhszsf.fsf@gmail.com>
In-Reply-To: <20101008074320.GB4671@burratino>

Jonathan Nieder <jrnieder@gmail.com> writes:

Show 8 quoted lines

> Š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.

Show 11 quoted lines

> 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.

Show 6 quoted lines

>> 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