From: Bert Wesarg <bert.wesarg@googlemail.com>
Date: Thu, 07 Oct 2010 18:52:47 GMT
Subject: Re: [PATCH] Documentation: update-index: -z applies also to --index-info
Message-ID: <AANLkTimsJ+uG7KhiBMii8szFYmbXo5OjAkYgs99_Hjzr@mail.gmail.com>
In-Reply-To: <87wrptua21.fsf@gmail.com>

On Thu, Oct 7, 2010 at 20:33, Štěpán Němec <stepnem@gmail.com> wrote:
> Bert Wesarg <bert.wesarg@googlemail.com> writes:
>
>> Also mention, that --stdin and --index-info needs to be the last
>> option supplied and indicate this in the usage string.
>>
>> Signed-off-by: Bert Wesarg <bert.wesarg@googlemail.com>
>>
>> ---
>>
>> We may like the usage string like this:
>>
>> [[-z] --stdin | --index-info]
>
> Yeah, that'd be definitely better IMO.

Will do.

>
> Also the usage string in builtin/update-index.c should be updated to the
> same effect.
>
> There is actually at least one more problem with the current SYNOPSIS of
> `update-index'. Obviously the `*' on the third line of the Asciidoc
> source makes the whole `--cacheinfo' line disappear and the rest bold
> (cf. e.g. the result at
> <http://www.kernel.org/pub/software/scm/git/docs/git-update-index.html>).
>
> I guess using `...' instead of the asterisks (also on the last line,
> i.e. [<file>...], not [<file>]*) would both fix the problem and at the
> same time make it more consistent with other man pages.

I wont change it in this patch, because I can't build the html docs right now.

>
>> to make it also clear, that -z applies only to --stdin or --index-only.
>> ---
>>  Documentation/git-update-index.txt |   14 ++++++++------
>>  1 files changed, 8 insertions(+), 6 deletions(-)
>>
>> diff --git a/Documentation/git-update-index.txt
>> b/Documentation/git-update-index.txt
>> index 74d1d49..4441d7c 100644 Documentation/git-update-index.txt
>> --- a/Documentation/git-update-index.txt
>> +++ b/Documentation/git-update-index.txt
>> @@ -18,8 +18,9 @@ SYNOPSIS
>>            [--skip-worktree | --no-skip-worktree]
>>            [--ignore-submodules]
>>            [--really-refresh] [--unresolve] [--again | -g]
>> -          [--info-only] [--index-info]
>> -          [-z] [--stdin]
>> +          [--info-only]
>> +          [-z]
>> +          [--stdin] [--index-info]
>>            [--verbose]
>>            [--] [<file>]*
>
> Shouldn't `--verbose' be also moved before the must-be-last options?

Sure. I noticed this myself, but the patch was already in the wire.

>
>> @@ -72,7 +73,7 @@ OPTIONS
>>       Directly insert the specified info into the index.
>>
>>  --index-info::
>> -        Read index information from stdin.
>> +        Read index information from stdin (Must be last option).
>
> I'm not a native speaker myself, but I suspect "must be THE last option"
> is more correct (including the lower-case `m' :-)).

Maybe this should be in its own sentence, like the '(Implies
--remove.)' in --force-remove.

>
>>  --chmod=(+|-)x::
>>          Set the execute permissions on the updated files.
>> @@ -138,14 +139,15 @@ you will need to handle the situation manually.
>>  --stdin::
>>       Instead of taking list of paths from the command line,
>>       read list of paths from the standard input.  Paths are
>> -     separated by LF (i.e. one path per line) by default.
>> +     separated by LF (i.e. one path per line) by default
>> +     (Must be last option).
>
> (same here)
>
>>
>>  --verbose::
>>          Report what is being added and removed from index.
>>
>>  -z::
>> -     Only meaningful with `--stdin`; paths are separated with
>> -     NUL character instead of LF.
>> +     Only meaningful with `--stdin` or `--index-info`; paths are
>> +     separated with NUL character instead of LF.
>>
>>  \--::
>>       Do not interpret any more arguments as options.
>
> Thanks,

Thank you.

Bert

>
> Štěpán
>