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

Luca Ceresoli
2020-01-20T21:54:11Z

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.

--
Luca