diff mbox series

[v4,2/2] Documentation: dev-tools: fix KTAP specification build warnings

Message ID 20220210023519.3221051-3-frowand.list@gmail.com (mailing list archive)
State New
Headers show
Series Documentation: dev-tools: clarify KTAP specification wording | expand

Commit Message

Frank Rowand Feb. 10, 2022, 2:35 a.m. UTC 
From: Frank Rowand <frank.rowand@sony.com>

Convert "Major differences between TAP and KTAP" from a bullet list
to a table.  The bullet list was being formatted as a single
paragraph.

Add missing required argument in code-block directives.

---

Table conversion suggested by Shuah.

Patch 2/2 not previously reviewed, so Reviewed-by tags not provided.

Changes since version 3
  - Add this commit (patch 2/2) to the series

Signed-off-by: Frank Rowand <frank.rowand@sony.com>
---
 Documentation/dev-tools/ktap.rst | 33 +++++++++++++++++---------------
 1 file changed, 18 insertions(+), 15 deletions(-)

Comments

David Gow Feb. 10, 2022, 7:44 a.m. UTC | #1 
On Thu, Feb 10, 2022 at 10:35 AM <frowand.list@gmail.com> wrote:
>
> From: Frank Rowand <frank.rowand@sony.com>
>
> Convert "Major differences between TAP and KTAP" from a bullet list
> to a table.  The bullet list was being formatted as a single
> paragraph.
>
> Add missing required argument in code-block directives.
>
> ---
>
> Table conversion suggested by Shuah.
>
> Patch 2/2 not previously reviewed, so Reviewed-by tags not provided.
>
> Changes since version 3
>   - Add this commit (patch 2/2) to the series
>
> Signed-off-by: Frank Rowand <frank.rowand@sony.com>
> ---

The table looks good to me, the "none" argument in code-block
directives is already fixed in another patch.

The table bits are:

Reviewed-by: David Gow <davidgow@google.com>

Cheers,
-- David

>  Documentation/dev-tools/ktap.rst | 33 +++++++++++++++++---------------
>  1 file changed, 18 insertions(+), 15 deletions(-)
>
> diff --git a/Documentation/dev-tools/ktap.rst b/Documentation/dev-tools/ktap.rst
> index dfb3f10a8b2d..5ee735c6687f 100644
> --- a/Documentation/dev-tools/ktap.rst
> +++ b/Documentation/dev-tools/ktap.rst
> @@ -68,7 +68,7 @@ Test case result lines
>  Test case result lines indicate the final status of a test.
>  They are required and must have the format:
>
> -.. code-block::
> +.. code-block:: none

These code-block changes were already submitted in:
https://lore.kernel.org/lkml/20220131003637.14274-1-rdunlap@infradead.org/T/


>
>         <result> <number> [<description>][ # [<directive>] [<diagnostic data>]]
>
> @@ -117,32 +117,32 @@ separator.
>
>  Example result lines include:
>
> -.. code-block::
> +.. code-block:: none
>
>         ok 1 test_case_name
>
>  The test "test_case_name" passed.
>
> -.. code-block::
> +.. code-block:: none
>
>         not ok 1 test_case_name
>
>  The test "test_case_name" failed.
>
> -.. code-block::
> +.. code-block:: none
>
>         ok 1 test # SKIP necessary dependency unavailable
>
>  The test "test" was SKIPPED with the diagnostic message "necessary dependency
>  unavailable".
>
> -.. code-block::
> +.. code-block:: none
>
>         not ok 1 test # TIMEOUT 30 seconds
>
>  The test "test" timed out, with diagnostic data "30 seconds".
>
> -.. code-block::
> +.. code-block:: none
>
>         ok 5 check return code # rcode=0
>
> @@ -202,7 +202,7 @@ allowed to be either indented or not indented.
>
>  An example of a test with two nested subtests:
>
> -.. code-block::
> +.. code-block:: none
>
>         KTAP version 1
>         1..1
> @@ -215,7 +215,7 @@ An example of a test with two nested subtests:
>
>  An example format with multiple levels of nested testing:
>
> -.. code-block::
> +.. code-block:: none
>
>         KTAP version 1
>         1..2
> @@ -234,12 +234,15 @@ An example format with multiple levels of nested testing:
>  Major differences between TAP and KTAP
>  --------------------------------------
>
> -Note the major differences between the TAP and KTAP specification:
> -- yaml and json are not recommended in KTAP diagnostic messages
> -- TODO directive not recognized in KTAP
> -- KTAP allows for an arbitrary number of tests to be nested
> -- TAP includes "Unknown lines" in the category of "Anything else"
> -- TAP says "Unknown lines" are "incorrect"; KTAP allows "Unknown lines"
> +==================================================   =========  ===============
> +Feature                                              TAP        KTAP
> +==================================================   =========  ===============
> +yaml and json in diagnosic message                   ok         not recommended
> +TODO directive                                       ok         not recognized
> +allows an arbitrary number of tests to be nested     no         yes
> +"Unknown lines" are in category of "Anything else"   yes        no
> +"Unknown lines" are                                  incorrect  allowed
> +==================================================   =========  ===============

This looks good to me, thanks!

>
>  The TAP14 specification does permit nested tests, but instead of using another
>  nested version line, uses a line of the form
> @@ -247,7 +250,7 @@ nested version line, uses a line of the form
>
>  Example KTAP output
>  --------------------
> -.. code-block::
> +.. code-block:: none
>
>         KTAP version 1
>         1..1
> --
> Frank Rowand <frank.rowand@sony.com>
>
Shuah Khan Feb. 10, 2022, 5:25 p.m. UTC | #2 
On 2/9/22 7:35 PM, frowand.list@gmail.com wrote:
> From: Frank Rowand <frank.rowand@sony.com>
> 
> Convert "Major differences between TAP and KTAP" from a bullet list
> to a table.  The bullet list was being formatted as a single
> paragraph.
> 
> Add missing required argument in code-block directives.
> 
> ---
> 
> Table conversion suggested by Shuah.
> 
> Patch 2/2 not previously reviewed, so Reviewed-by tags not provided.
> 
> Changes since version 3
>    - Add this commit (patch 2/2) to the series
> 
> Signed-off-by: Frank Rowand <frank.rowand@sony.com>
> ---
>   Documentation/dev-tools/ktap.rst | 33 +++++++++++++++++---------------
>   1 file changed, 18 insertions(+), 15 deletions(-)
> 
> diff --git a/Documentation/dev-tools/ktap.rst b/Documentation/dev-tools/ktap.rst
> index dfb3f10a8b2d..5ee735c6687f 100644
> --- a/Documentation/dev-tools/ktap.rst
> +++ b/Documentation/dev-tools/ktap.rst
> @@ -68,7 +68,7 @@ Test case result lines
>   Test case result lines indicate the final status of a test.
>   They are required and must have the format:
>   
> -.. code-block::
> +.. code-block:: none
>   
>   	<result> <number> [<description>][ # [<directive>] [<diagnostic data>]]
>   
> @@ -117,32 +117,32 @@ separator.
>   
>   Example result lines include:
>   
> -.. code-block::
> +.. code-block:: none
>   
>   	ok 1 test_case_name
>   
>   The test "test_case_name" passed.
>   
> -.. code-block::
> +.. code-block:: none
>   
>   	not ok 1 test_case_name
>   
>   The test "test_case_name" failed.
>   
> -.. code-block::
> +.. code-block:: none
>   
>   	ok 1 test # SKIP necessary dependency unavailable
>   
>   The test "test" was SKIPPED with the diagnostic message "necessary dependency
>   unavailable".
>   
> -.. code-block::
> +.. code-block:: none
>   
>   	not ok 1 test # TIMEOUT 30 seconds
>   
>   The test "test" timed out, with diagnostic data "30 seconds".
>   
> -.. code-block::
> +.. code-block:: none
>   
>   	ok 5 check return code # rcode=0
>   
> @@ -202,7 +202,7 @@ allowed to be either indented or not indented.
>   
>   An example of a test with two nested subtests:
>   
> -.. code-block::
> +.. code-block:: none
>   
>   	KTAP version 1
>   	1..1
> @@ -215,7 +215,7 @@ An example of a test with two nested subtests:
>   
>   An example format with multiple levels of nested testing:
>   
> -.. code-block::
> +.. code-block:: none
>   
>   	KTAP version 1
>   	1..2
> @@ -234,12 +234,15 @@ An example format with multiple levels of nested testing:
>   Major differences between TAP and KTAP
>   --------------------------------------
>   
> -Note the major differences between the TAP and KTAP specification:
> -- yaml and json are not recommended in KTAP diagnostic messages
> -- TODO directive not recognized in KTAP
> -- KTAP allows for an arbitrary number of tests to be nested
> -- TAP includes "Unknown lines" in the category of "Anything else"
> -- TAP says "Unknown lines" are "incorrect"; KTAP allows "Unknown lines"
> +==================================================   =========  ===============
> +Feature                                              TAP        KTAP
> +==================================================   =========  ===============
> +yaml and json in diagnosic message                   ok         not recommended
> +TODO directive                                       ok         not recognized
> +allows an arbitrary number of tests to be nested     no         yes
> +"Unknown lines" are in category of "Anything else"   yes        no
> +"Unknown lines" are                                  incorrect  allowed
> +==================================================   =========  ===============
>   
>   The TAP14 specification does permit nested tests, but instead of using another
>   nested version line, uses a line of the form
> @@ -247,7 +250,7 @@ nested version line, uses a line of the form
>   
>   Example KTAP output
>   --------------------
> -.. code-block::
> +.. code-block:: none
>   
>   	KTAP version 1
>   	1..1
> 

Table looks good. Thanks for adding it. The two patches could be
collapsed into one perhaps? Either way:

Reviewed-by: Shuah Khan <skhan@linuxfoundation.org>

thanks,
-- Shuah
Kees Cook Feb. 10, 2022, 5:43 p.m. UTC | #3 
On Wed, Feb 09, 2022 at 08:35:19PM -0600, frowand.list@gmail.com wrote:
> From: Frank Rowand <frank.rowand@sony.com>
> 
> Convert "Major differences between TAP and KTAP" from a bullet list
> to a table.  The bullet list was being formatted as a single
> paragraph.
> 
> Add missing required argument in code-block directives.
> 
> ---
> 
> Table conversion suggested by Shuah.
> 
> Patch 2/2 not previously reviewed, so Reviewed-by tags not provided.
> 
> Changes since version 3
>   - Add this commit (patch 2/2) to the series
> 
> Signed-off-by: Frank Rowand <frank.rowand@sony.com>

Reviewed-by: Kees Cook <keescook@chromium.org>
diff mbox series

Patch

diff --git a/Documentation/dev-tools/ktap.rst b/Documentation/dev-tools/ktap.rst
index dfb3f10a8b2d..5ee735c6687f 100644
--- a/Documentation/dev-tools/ktap.rst
+++ b/Documentation/dev-tools/ktap.rst
@@ -68,7 +68,7 @@  Test case result lines
 Test case result lines indicate the final status of a test.
 They are required and must have the format:
 
-.. code-block::
+.. code-block:: none
 
 	<result> <number> [<description>][ # [<directive>] [<diagnostic data>]]
 
@@ -117,32 +117,32 @@  separator.
 
 Example result lines include:
 
-.. code-block::
+.. code-block:: none
 
 	ok 1 test_case_name
 
 The test "test_case_name" passed.
 
-.. code-block::
+.. code-block:: none
 
 	not ok 1 test_case_name
 
 The test "test_case_name" failed.
 
-.. code-block::
+.. code-block:: none
 
 	ok 1 test # SKIP necessary dependency unavailable
 
 The test "test" was SKIPPED with the diagnostic message "necessary dependency
 unavailable".
 
-.. code-block::
+.. code-block:: none
 
 	not ok 1 test # TIMEOUT 30 seconds
 
 The test "test" timed out, with diagnostic data "30 seconds".
 
-.. code-block::
+.. code-block:: none
 
 	ok 5 check return code # rcode=0
 
@@ -202,7 +202,7 @@  allowed to be either indented or not indented.
 
 An example of a test with two nested subtests:
 
-.. code-block::
+.. code-block:: none
 
 	KTAP version 1
 	1..1
@@ -215,7 +215,7 @@  An example of a test with two nested subtests:
 
 An example format with multiple levels of nested testing:
 
-.. code-block::
+.. code-block:: none
 
 	KTAP version 1
 	1..2
@@ -234,12 +234,15 @@  An example format with multiple levels of nested testing:
 Major differences between TAP and KTAP
 --------------------------------------
 
-Note the major differences between the TAP and KTAP specification:
-- yaml and json are not recommended in KTAP diagnostic messages
-- TODO directive not recognized in KTAP
-- KTAP allows for an arbitrary number of tests to be nested
-- TAP includes "Unknown lines" in the category of "Anything else"
-- TAP says "Unknown lines" are "incorrect"; KTAP allows "Unknown lines"
+==================================================   =========  ===============
+Feature                                              TAP        KTAP
+==================================================   =========  ===============
+yaml and json in diagnosic message                   ok         not recommended
+TODO directive                                       ok         not recognized
+allows an arbitrary number of tests to be nested     no         yes
+"Unknown lines" are in category of "Anything else"   yes        no
+"Unknown lines" are                                  incorrect  allowed
+==================================================   =========  ===============
 
 The TAP14 specification does permit nested tests, but instead of using another
 nested version line, uses a line of the form
@@ -247,7 +250,7 @@  nested version line, uses a line of the form
 
 Example KTAP output
 --------------------
-.. code-block::
+.. code-block:: none
 
 	KTAP version 1
 	1..1