[PATCH 1/5] docs: networking: nfc: change headlines to sphinx syntax

[PATCH 1/5] docs: networking: nfc: change headlines to sphinx syntax

[Robert Schwebel]

The headlines in this file do are not in the standard kernel docu-
mentation headline format. Change it, so this file can be switched to
rst in the future.

Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
---
 Documentation/networking/nfc.txt | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/networking/nfc.txt b/Documentation/networking/nfc.txt
index b24c29bdae27..c053610bfadc 100644
--- a/Documentation/networking/nfc.txt
+++ b/Documentation/networking/nfc.txt
@@ -1,3 +1,4 @@
+===================
 Linux NFC subsystem
 ===================
 
@@ -8,7 +9,7 @@ This document covers the architecture overview, the device driver interface
 description and the userspace interface description.
 
 Architecture overview
----------------------
+=====================
 
 The NFC subsystem is responsible for:
       - NFC adapters management;
@@ -51,7 +52,7 @@ PF_NFC. The NFC_SOCKPROTO_RAW performs raw communication with NFC targets.
                                     +-----------+
 
 Device Driver Interface
------------------------
+=======================
 
 When registering on the NFC subsystem, the device driver must inform the core
 of the set of supported NFC protocols and the set of ops callbacks. The ops
@@ -64,7 +65,7 @@ callbacks that must be implemented are the following:
 * data_exchange - send data and receive the response (transceive operation)
 
 Userspace interface
---------------------
+===================
 
 The userspace interface is divided in control operations and low-level data
 exchange operation.
-- 
2.24.0

[PATCH 2/5] docs: networking: nfc: change block diagram to sphinx syntax

[Robert Schwebel]

Change the block diagram to match the sphinx syntax. This will make it
possible to switch this file to rst in the future.

Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
---
 Documentation/networking/nfc.txt | 49 ++++++++++++++++----------------
 1 file changed, 25 insertions(+), 24 deletions(-)

diff --git a/Documentation/networking/nfc.txt b/Documentation/networking/nfc.txt
index c053610bfadc..b6056e597e20 100644
--- a/Documentation/networking/nfc.txt
+++ b/Documentation/networking/nfc.txt
@@ -26,30 +26,31 @@ The control operations are available to userspace via generic netlink.
 The low-level data exchange interface is provided by the new socket family
 PF_NFC. The NFC_SOCKPROTO_RAW performs raw communication with NFC targets.
 
-
-             +--------------------------------------+
-             |              USER SPACE              |
-             +--------------------------------------+
-                 ^                       ^
-                 | low-level             | control
-                 | data exchange         | operations
-                 |                       |
-                 |                       v
-                 |                  +-----------+
-                 | AF_NFC           |  netlink  |
-                 | socket           +-----------+
-                 | raw                   ^
-                 |                       |
-                 v                       v
-             +---------+            +-----------+
-             | rawsock | <--------> |   core    |
-             +---------+            +-----------+
-                                         ^
-                                         |
-                                         v
-                                    +-----------+
-                                    |  driver   |
-                                    +-----------+
+.. code-block:: none
+
+        +--------------------------------------+
+        |              USER SPACE              |
+        +--------------------------------------+
+            ^                       ^
+            | low-level             | control
+            | data exchange         | operations
+            |                       |
+            |                       v
+            |                  +-----------+
+            | AF_NFC           |  netlink  |
+            | socket           +-----------+
+            | raw                   ^
+            |                       |
+            v                       v
+        +---------+            +-----------+
+        | rawsock | <--------> |   core    |
+        +---------+            +-----------+
+                                    ^
+                                    |
+                                    v
+                               +-----------+
+                               |  driver   |
+                               +-----------+
 
 Device Driver Interface
 =======================
-- 
2.24.0

[PATCH 3/5] docs: networking: nfc: fix bullet list syntax

[Robert Schwebel]

Fix this warning:

Documentation/networking/nfc.rst:87: WARNING: Bullet list ends without
a blank line; unexpected unindent.

Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
---
 Documentation/networking/nfc.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/networking/nfc.txt b/Documentation/networking/nfc.txt
index b6056e597e20..af69b3a90eaa 100644
--- a/Documentation/networking/nfc.txt
+++ b/Documentation/networking/nfc.txt
@@ -84,7 +84,7 @@ The operations are composed by commands and events, all listed below:
 * NFC_EVENT_DEVICE_ADDED - reports an NFC device addition
 * NFC_EVENT_DEVICE_REMOVED - reports an NFC device removal
 * NFC_EVENT_TARGETS_FOUND - reports START_POLL results when 1 or more targets
-are found
+  are found
 
 The user must call START_POLL to poll for NFC targets, passing the desired NFC
 protocols through NFC_ATTR_PROTOCOLS attribute. The device remains in polling
-- 
2.24.0

[PATCH 4/5] docs: networking: nfc: fix code block syntax

[Robert Schwebel]

Silence this warning:

Documentation/networking/nfc.rst:113: WARNING: Definition list ends without
a blank line; unexpected unindent.

Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
---
 Documentation/networking/nfc.txt | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/Documentation/networking/nfc.txt b/Documentation/networking/nfc.txt
index af69b3a90eaa..63e483f6afb4 100644
--- a/Documentation/networking/nfc.txt
+++ b/Documentation/networking/nfc.txt
@@ -105,12 +105,14 @@ LOW-LEVEL DATA EXCHANGE:
 The userspace must use PF_NFC sockets to perform any data communication with
 targets. All NFC sockets use AF_NFC:
 
-struct sockaddr_nfc {
-       sa_family_t sa_family;
-       __u32 dev_idx;
-       __u32 target_idx;
-       __u32 nfc_protocol;
-};
+.. code-block:: none
+
+        struct sockaddr_nfc {
+               sa_family_t sa_family;
+               __u32 dev_idx;
+               __u32 target_idx;
+               __u32 nfc_protocol;
+        };
 
 To establish a connection with one target, the user must create an
 NFC_SOCKPROTO_RAW socket and call the 'connect' syscall with the sockaddr_nfc
-- 
2.24.0

Re: [PATCH 4/5] docs: networking: nfc: fix code block syntax

[Jonathan Corbet]

On Thu, 21 Nov 2019 16:55:02 +0100
Robert Schwebel <r.schwebel@pengutronix.de> wrote:

> Silence this warning:
> 
> Documentation/networking/nfc.rst:113: WARNING: Definition list ends without
> a blank line; unexpected unindent.
> 
> Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
> ---
>  Documentation/networking/nfc.txt | 14 ++++++++------
>  1 file changed, 8 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/networking/nfc.txt b/Documentation/networking/nfc.txt
> index af69b3a90eaa..63e483f6afb4 100644
> --- a/Documentation/networking/nfc.txt
> +++ b/Documentation/networking/nfc.txt
> @@ -105,12 +105,14 @@ LOW-LEVEL DATA EXCHANGE:
>  The userspace must use PF_NFC sockets to perform any data communication with
>  targets. All NFC sockets use AF_NFC:
>  
> -struct sockaddr_nfc {
> -       sa_family_t sa_family;
> -       __u32 dev_idx;
> -       __u32 target_idx;
> -       __u32 nfc_protocol;
> -};
> +.. code-block:: none
> +
> +        struct sockaddr_nfc {
> +               sa_family_t sa_family;
> +               __u32 dev_idx;
> +               __u32 target_idx;
> +               __u32 nfc_protocol;
> +        };

Rather than cluttering the text with ".. code-block::", you can just use
the literal-block shortcut:

	targets. All NFC sockets use AF_NFC::

	    struct sockaddr_nfc {

Thanks,

jon

>  
>  To establish a connection with one target, the user must create an
>  NFC_SOCKPROTO_RAW socket and call the 'connect' syscall with the sockaddr_nfc

Re: [PATCH 4/5] docs: networking: nfc: fix code block syntax

[Robert Schwebel]

On Thu, Nov 21, 2019 at 10:09:19AM -0700, Jonathan Corbet wrote:
> > +.. code-block:: none
> > +
> > +        struct sockaddr_nfc {
> > +               sa_family_t sa_family;
> > +               __u32 dev_idx;
> > +               __u32 target_idx;
> > +               __u32 nfc_protocol;
> > +        };
> 
> Rather than cluttering the text with ".. code-block::", you can just use
> the literal-block shortcut:
> 
> 	targets. All NFC sockets use AF_NFC::
> 
> 	    struct sockaddr_nfc {
> 

Thanks, will do in v2.

rsc
-- 
Pengutronix e.K.                           | Dipl.-Ing. Robert Schwebel  |
Steuerwalder Str. 21                       | https://www.pengutronix.de/ |
31137 Hildesheim, Germany                  | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |

[PATCH 5/5] docs: networking: nfc: change to rst format

[Robert Schwebel]

Now that the sphinx syntax has been fixed, change the document from txt
to rst and add it to the index.

Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
---
 Documentation/networking/{nfc.txt => nfc.rst} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename Documentation/networking/{nfc.txt => nfc.rst} (100%)

diff --git a/Documentation/networking/nfc.txt b/Documentation/networking/nfc.rst
similarity index 100%
rename from Documentation/networking/nfc.txt
rename to Documentation/networking/nfc.rst
-- 
2.24.0

Re: [PATCH 5/5] docs: networking: nfc: change to rst format

[Jonathan Corbet]

On Thu, 21 Nov 2019 16:55:03 +0100
Robert Schwebel <r.schwebel@pengutronix.de> wrote:

> Now that the sphinx syntax has been fixed, change the document from txt
> to rst and add it to the index.
> 
> Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
> ---
>  Documentation/networking/{nfc.txt => nfc.rst} | 0
>  1 file changed, 0 insertions(+), 0 deletions(-)
>  rename Documentation/networking/{nfc.txt => nfc.rst} (100%)
> 
> diff --git a/Documentation/networking/nfc.txt b/Documentation/networking/nfc.rst
> similarity index 100%
> rename from Documentation/networking/nfc.txt
> rename to Documentation/networking/nfc.rst

It looks like you didn't actually add it to index.rst?

In general the changes look good.  I'd do it all in one patch, but that's
up to Dave (who I assume will pick this up).

Thanks,

jon

Re: [PATCH 5/5] docs: networking: nfc: change to rst format

[Robert Schwebel]

On Thu, Nov 21, 2019 at 10:10:27AM -0700, Jonathan Corbet wrote:
> > Now that the sphinx syntax has been fixed, change the document from txt
> > to rst and add it to the index.
> >
> > [...]
> >
> > diff --git a/Documentation/networking/nfc.txt b/Documentation/networking/nfc.rst
> > similarity index 100%
> > rename from Documentation/networking/nfc.txt
> > rename to Documentation/networking/nfc.rst
> 
> It looks like you didn't actually add it to index.rst?

Whoops, that got lost, will change.

rsc
-- 
Pengutronix e.K.                           | Dipl.-Ing. Robert Schwebel  |
Steuerwalder Str. 21                       | https://www.pengutronix.de/ |
31137 Hildesheim, Germany                  | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |

Re: [PATCH 5/5] docs: networking: nfc: change to rst format

[David Miller]

From: Robert Schwebel <r.schwebel@pengutronix.de>
Date: Thu, 21 Nov 2019 16:55:03 +0100

> Now that the sphinx syntax has been fixed, change the document from txt
> to rst and add it to the index.
> 
> Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>

As Jon mentioned, you aren't actually adding it to the index in this
patch yet the commit message says that you did.

Please fix that, repsin this series, and provide a proper "[PATCH 0/5]
..."  cover letter this time.

Thank you.

Re: [PATCH 5/5] docs: networking: nfc: change to rst format

[Robert Schwebel]

On Thu, Nov 21, 2019 at 03:06:07PM -0800, David Miller wrote:
> From: Robert Schwebel <r.schwebel@pengutronix.de>
> Date: Thu, 21 Nov 2019 16:55:03 +0100
> 
> > Now that the sphinx syntax has been fixed, change the document from txt
> > to rst and add it to the index.
> > 
> > Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
> 
> As Jon mentioned, you aren't actually adding it to the index in this
> patch yet the commit message says that you did.

The index doesn't seem to be particularly ordered, so I'll just add it
to the end, ok?

> Please fix that, repsin this series, and provide a proper "[PATCH 0/5]
> ..."  cover letter this time.

Will do, thanks.

rsc
-- 
Pengutronix e.K.                           | Dipl.-Ing. Robert Schwebel  |
Steuerwalder Str. 21                       | https://www.pengutronix.de/ |
31137 Hildesheim, Germany                  | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |