Re: [PATCH 1/3] test-lib: Document short options in t/README

[Ilya Bobyr <ilya.bobyr@gmail.com>]

On 4/23/2014 11:24 AM, Junio C Hamano wrote:
> Ilya Bobyr <ilya.bobyr@gmail.com> writes:
>> Most arguments that could be provided to a test have short forms.
>> Unless documented, the only way to learn them is to read the code.
>>
>> Signed-off-by: Ilya Bobyr <ilya.bobyr@gmail.com>
>> ---
>>  t/README |    8 ++++----
>>  1 files changed, 4 insertions(+), 4 deletions(-)
>>
>> diff --git a/t/README b/t/README
>> index caeeb9d..6b93aca 100644
>> --- a/t/README
>> +++ b/t/README
>> @@ -71,7 +71,7 @@ You can pass --verbose (or -v), --debug (or -d), and --immediate
>>  (or -i) command line argument to the test, or by setting GIT_TEST_OPTS
>>  appropriately before running "make".
>>  
>> ---verbose::
>> +-v,--verbose::
>>  	This makes the test more verbose.  Specifically, the
>>  	command being run and their output if any are also
>>  	output.
> I was debating myself if the result should look more like this:
>
> 	-v::
> 	--verbose::
> 		This makes the test more verbose.  Specifically, the
> 		command being run and their output if any are also
> 		output.
>
> As a straight text file, your version is certainly a lot easier to
> read, but at the same time, the entire file is written in more or
> less AsciiDoc format (the list of prerequisites and the list of
> harness library functions need to be converted to the "item::" form
> for the text to format well, though) and I've seen some efforts by
> others to run text files in Documentation/ that were originally
> meant to be consumed as straight text thru AsciiDoc, so the latter
> form might be a small step for futureproofing.
>
> My conclusion at this point is that the original is good for the
> current need of the project; if somebody wants to include this file
> from somewhere in Documentation/technical, a conversion to use
> multiple "item1::<newline>item2::<newline>description" headers can
> be done by that person as part of the "make it fully AsciiDoc"
> effort.
>
> Thanks.

I've changed it.
It is a trivial change and it does not seem to be that bad in plain text
form either.

I do not know the AsciiDoc conventions as  have not read its spec.  If
there are any other conventions I am breaking - let me know.
I will read the spec if I will be contributing more to the documentation.

P.S.  Sorry it takes me this long to reply %)