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

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 23, 2014, 18:24 UTC
Message-ID: <xmqqr44nzyx6.fsf@gitster.dls.corp.google.com>
In-Reply-To: <1398154767-1276-2-git-send-email-ilya.bobyr@gmail.com>

Ilya Bobyr <ilya.bobyr@gmail.com> writes:

Show 21 quoted lines

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