diff mbox series

[02/26] docs: i2c: summary: extend introduction

Message ID 20200105225012.11701-2-luca@lucaceresoli.net
State Changes Requested
Headers show
Series docs: i2c: rework I2C documentation, part I | expand

Commit Message

Luca Ceresoli Jan. 5, 2020, 10:49 p.m. UTC
- state the "official" name (I²C, not I2C, according to the spec) at
   the beginning but keep using the more practical I2C elsewhere
 - mention some known different names
 - add link to the specification document

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/i2c/summary.rst | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

Comments

Jean Delvare Jan. 20, 2020, 9:27 a.m. UTC | #1
On Sun,  5 Jan 2020 23:49:48 +0100, Luca Ceresoli wrote:
> - state the "official" name (I²C, not I2C, according to the spec) at
>    the beginning but keep using the more practical I2C elsewhere
>  - mention some known different names
>  - add link to the specification document

Indentation is inconsistent.

> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> ---
>  Documentation/i2c/summary.rst | 18 ++++++++++++------
>  1 file changed, 12 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst
> index 3a24eac17375..b7d3e620155b 100644
> --- a/Documentation/i2c/summary.rst
> +++ b/Documentation/i2c/summary.rst
> @@ -2,12 +2,18 @@
>  I2C and SMBus
>  =============
>  
> -I2C (pronounce: I squared C) is a protocol developed by Philips. It is a
> -slow two-wire protocol (variable speed, up to 400 kHz), with a high speed
> -extension (3.4 MHz).  It provides an inexpensive bus for connecting many
> -types of devices with infrequent or low bandwidth communications needs.
> -I2C is widely used with embedded systems.  Some systems use variants that
> -don't meet branding requirements, and so are not advertised as being I2C.
> +I²C (pronounce: I squared C and written I2C in the kernel documentation) is
> +a protocol developed by Philips. It is a slow two-wire protocol (variable
> +speed, up to 400 kHz), with a high speed extension (3.4 MHz).  It provides
> +an inexpensive bus for connecting many types of devices with infrequent or
> +low bandwidth communications needs.  I2C is widely used with embedded
> +systems.  Some systems use variants that don't meet branding requirements,
> +and so are not advertised as being I2C but with different names, e.g. TWI
> +(Two Wire Interface), IIC.

Maybe that's just me but "but with different names" sounds strange to
me in the sentence construct. Maybe "but come under different names"
instead?

> +
> +The official I2C specification is the `"I2C-bus specification and user
> +manual" (UM10204) <https://www.nxp.com/docs/en/user-guide/UM10204.pdf>`_
> +published by NXP Semiconductors.
>  
>  SMBus (System Management Bus) is based on the I2C protocol, and is mostly
>  a subset of I2C protocols and signaling.  Many I2C devices will work on an

Reviewed-by: Jean Delvare <jdelvare@suse.de>
Luca Ceresoli Jan. 20, 2020, 9:54 p.m. UTC | #2
Hi Jean,

On 20/01/20 10:27, Jean Delvare wrote:
> On Sun,  5 Jan 2020 23:49:48 +0100, Luca Ceresoli wrote:
>> - state the "official" name (I²C, not I2C, according to the spec) at
>>    the beginning but keep using the more practical I2C elsewhere
>>  - mention some known different names
>>  - add link to the specification document
> 
> Indentation is inconsistent.

Weird, this looks OK in my git log and my inbox, wrong on patchwork.
Perhaps starting an e-mail with a space breaks something? I'll try to
avoid that in the future.

>> diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst
>> index 3a24eac17375..b7d3e620155b 100644
>> --- a/Documentation/i2c/summary.rst
>> +++ b/Documentation/i2c/summary.rst
>> @@ -2,12 +2,18 @@
>>  I2C and SMBus
>>  =============
>>  
>> -I2C (pronounce: I squared C) is a protocol developed by Philips. It is a
>> -slow two-wire protocol (variable speed, up to 400 kHz), with a high speed
>> -extension (3.4 MHz).  It provides an inexpensive bus for connecting many
>> -types of devices with infrequent or low bandwidth communications needs.
>> -I2C is widely used with embedded systems.  Some systems use variants that
>> -don't meet branding requirements, and so are not advertised as being I2C.
>> +I²C (pronounce: I squared C and written I2C in the kernel documentation) is
>> +a protocol developed by Philips. It is a slow two-wire protocol (variable
>> +speed, up to 400 kHz), with a high speed extension (3.4 MHz).  It provides
>> +an inexpensive bus for connecting many types of devices with infrequent or
>> +low bandwidth communications needs.  I2C is widely used with embedded
>> +systems.  Some systems use variants that don't meet branding requirements,
>> +and so are not advertised as being I2C but with different names, e.g. TWI
>> +(Two Wire Interface), IIC.
> 
> Maybe that's just me but "but with different names" sounds strange to
> me in the sentence construct. Maybe "but come under different names"
> instead?

What I mean is "...are not advertised as being I2C but [are advertised]
with different names". Looks equally clear to me, but since it has to be
clear to readers, I'll take your suggestion for v2.

Thanks for all the review work. I'm not going to reply to each e-mail
individually, but each of your suggestions will be taken in v2 unless I
reply differently.
diff mbox series

Patch

diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst
index 3a24eac17375..b7d3e620155b 100644
--- a/Documentation/i2c/summary.rst
+++ b/Documentation/i2c/summary.rst
@@ -2,12 +2,18 @@ 
 I2C and SMBus
 =============
 
-I2C (pronounce: I squared C) is a protocol developed by Philips. It is a
-slow two-wire protocol (variable speed, up to 400 kHz), with a high speed
-extension (3.4 MHz).  It provides an inexpensive bus for connecting many
-types of devices with infrequent or low bandwidth communications needs.
-I2C is widely used with embedded systems.  Some systems use variants that
-don't meet branding requirements, and so are not advertised as being I2C.
+I²C (pronounce: I squared C and written I2C in the kernel documentation) is
+a protocol developed by Philips. It is a slow two-wire protocol (variable
+speed, up to 400 kHz), with a high speed extension (3.4 MHz).  It provides
+an inexpensive bus for connecting many types of devices with infrequent or
+low bandwidth communications needs.  I2C is widely used with embedded
+systems.  Some systems use variants that don't meet branding requirements,
+and so are not advertised as being I2C but with different names, e.g. TWI
+(Two Wire Interface), IIC.
+
+The official I2C specification is the `"I2C-bus specification and user
+manual" (UM10204) <https://www.nxp.com/docs/en/user-guide/UM10204.pdf>`_
+published by NXP Semiconductors.
 
 SMBus (System Management Bus) is based on the I2C protocol, and is mostly
 a subset of I2C protocols and signaling.  Many I2C devices will work on an