# [PATCH 1/3] t/README: link to metacpan.org, not search.cpan.org

5 messages from 2017-03-22 to 2017-03-24. Participants: Ævar Arnfjörð Bjarmason, Junio C Hamano, Jonathan Nieder.
Thread: https://gitlist.dev/t/45471

## Ævar Arnfjörð Bjarmason, 2017-03-22 22:18

Subject: [PATCH 1/3] t/README: link to metacpan.org, not search.cpan.org
Message-ID: <20170322221854.10791-1-avarab@gmail.com>
URL: https://gitlist.dev/e/20170322221854.10791-1-avarab%40gmail.com

```
Change a link to the web version of the TAP::Parser::Grammar
documentation to link to metacpan.org instead of search.cpan.org.

This is something I added back in commit 20873f45e7 ("t/README:
Document the do's and don'ts of tests", 2010-07-02), at the time
search.cpan.org was the more actively maintained CPAN web-interface,
nowadays that's metacpan.org.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 t/README | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/t/README b/t/README
index 4982d1c521..a50290c789 100644
--- a/t/README
+++ b/t/README
@@ -471,7 +471,7 @@ Don't:
    their output.
 
    You can glean some further possible issues from the TAP grammar
-   (see http://search.cpan.org/perldoc?TAP::Parser::Grammar#TAP_Grammar)
+   (see https://metacpan.org/pod/TAP::Parser::Grammar#TAP-GRAMMAR)
    but the best indication is to just run the tests with prove(1),
    it'll complain if anything is amiss.
 
-- 
2.11.0


```

## Ævar Arnfjörð Bjarmason, 2017-03-22 22:18

Subject: [PATCH 3/3] t/README: clarify the test_have_prereq documentation
Message-ID: <20170322221854.10791-3-avarab@gmail.com>
URL: https://gitlist.dev/e/20170322221854.10791-3-avarab%40gmail.com
In-Reply-To: <20170322221854.10791-1-avarab@gmail.com>

```
Clarify the test_have_prereq documentation so that it's clear in the
reader's mind when the text says "most common use of this directly"
what the answer to "as opposed to what?" is.

Usually this function isn't used in lieu of using the prerequisite
support built into test_expect_*, mention that explicitly.

This changes documentation that I added in commit
9a897893a7 ("t/README: Document the prereq functions, and 3-arg
test_*", 2010-07-02).

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 t/README | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/t/README b/t/README
index 89512e23d4..36813cef94 100644
--- a/t/README
+++ b/t/README
@@ -612,8 +612,10 @@ library for your script to use.
  - test_have_prereq <prereq>
 
    Check if we have a prerequisite previously set with
-   test_set_prereq. The most common use of this directly is to skip
-   all the tests if we don't have some essential prerequisite:
+   test_set_prereq. The most common use-case for using this directly,
+   as opposed to as an argument to test_expect_*, is to skip all the
+   tests at the start of the test script if we don't have some
+   essential prerequisite:
 
 	if ! test_have_prereq PERL
 	then
-- 
2.11.0


```

## Ævar Arnfjörð Bjarmason, 2017-03-22 22:18

Subject: [PATCH 2/3] t/README: change "Inside <X> part" to "Inside the <X> part"
Message-ID: <20170322221854.10791-2-avarab@gmail.com>
URL: https://gitlist.dev/e/20170322221854.10791-2-avarab%40gmail.com
In-Reply-To: <20170322221854.10791-1-avarab@gmail.com>

```
Change the mention of "Inside the <script> part, the standard
output..." to use the definite article, which makes more sense in this
context.

This changes documentation I originally added back in commit
20873f45e7 ("t/README: Document the do's and don'ts of tests",
2010-07-02).

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 t/README | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/t/README b/t/README
index a50290c789..89512e23d4 100644
--- a/t/README
+++ b/t/README
@@ -477,7 +477,7 @@ Don't:
 
 Keep in mind:
 
- - Inside <script> part, the standard output and standard error
+ - Inside the <script> part, the standard output and standard error
    streams are discarded, and the test harness only reports "ok" or
    "not ok" to the end user running the tests. Under --verbose, they
    are shown to help debugging the tests.
-- 
2.11.0


```

## Junio C Hamano, 2017-03-22 22:34

Subject: Re: [PATCH 1/3] t/README: link to metacpan.org, not search.cpan.org
Message-ID: <xmqqpoh9gcur.fsf@gitster.mtv.corp.google.com>
URL: https://gitlist.dev/e/xmqqpoh9gcur.fsf%40gitster.mtv.corp.google.com
In-Reply-To: <20170322221854.10791-1-avarab@gmail.com>

```
Thanks.

```

## Jonathan Nieder, 2017-03-24 00:59

Subject: Re: [PATCH 3/3] t/README: clarify the test_have_prereq documentation
Message-ID: <20170324005932.GG20794@aiede.mtv.corp.google.com>
URL: https://gitlist.dev/e/20170324005932.GG20794%40aiede.mtv.corp.google.com
In-Reply-To: <20170322221854.10791-3-avarab@gmail.com>

```
Hi,

Ævar Arnfjörð Bjarmason wrote:

> --- a/t/README
> +++ b/t/README
> @@ -612,8 +612,10 @@ library for your script to use.
>   - test_have_prereq <prereq>
>  
>     Check if we have a prerequisite previously set with
> -   test_set_prereq. The most common use of this directly is to skip
> -   all the tests if we don't have some essential prerequisite:
> +   test_set_prereq. The most common use-case for using this directly,
> +   as opposed to as an argument to test_expect_*, is to skip all the
> +   tests at the start of the test script if we don't have some
> +   essential prerequisite:

Nit: the hyphenated word "use-case" feels jargon-ish.  I've seen it
more often as two separate words.  Better yet to clarify that we're
talking about idioms and not just goals:

                       The most common way to use this explicitly (as opposed
      to the implicit use when an argument is passed to test_expect_*) is to
      skip all the tests at the start of a test script if we don't have some
      essential prerequisite:

With or without such a change,
Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>

Thanks.

```