[PATCH i2c-tools] add BUGS section to manpages

[PATCH i2c-tools] add BUGS section to manpages

[Wolfram Sang]

For all manpages installed on my Debian system, add a BUGS section, so
people can easily find whom to contact.

Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
---
 eeprom/decode-dimms.1     | 3 +++
 eeprom/decode-vaio.1      | 3 +++
 stub/i2c-stub-from-dump.8 | 4 ++++
 tools/i2cdetect.8         | 4 ++++
 tools/i2cdump.8           | 4 ++++
 tools/i2cget.8            | 4 ++++
 tools/i2cset.8            | 4 ++++
 tools/i2ctransfer.8       | 4 ++++
 8 files changed, 30 insertions(+)

diff --git a/eeprom/decode-dimms.1 b/eeprom/decode-dimms.1
index 710d6bf..c684500 100644
--- a/eeprom/decode-dimms.1
+++ b/eeprom/decode-dimms.1
@@ -62,6 +62,9 @@ Same as -x except treat multibyte hex data as little endian
 .TP
 .B \-h, --help
 Display the usage summary
+.SH BUGS
+To report bugs or send fixes, please write to the Linux I2C mailing list
+<linux-i2c@vger.kernel.org>.
 .SH SEE ALSO
 .BR decode-vaio (1)
 .SH AUTHORS
diff --git a/eeprom/decode-vaio.1 b/eeprom/decode-vaio.1
index 125d597..9bdcacf 100644
--- a/eeprom/decode-vaio.1
+++ b/eeprom/decode-vaio.1
@@ -29,6 +29,9 @@ The purpose of the
 tool is to decode the information found in the Sony Vaio laptop
 identification EEPROMs.
 The tool requires the eeprom kernel module to be loaded.
+.SH BUGS
+To report bugs or send fixes, please write to the Linux I2C mailing list
+<linux-i2c@vger.kernel.org>.
 .SH SEE ALSO
 .BR decode-dimms (1)
 .SH AUTHOR
diff --git a/stub/i2c-stub-from-dump.8 b/stub/i2c-stub-from-dump.8
index b1550ed..3d55ac9 100644
--- a/stub/i2c-stub-from-dump.8
+++ b/stub/i2c-stub-from-dump.8
@@ -45,6 +45,10 @@ There are some limitations to the kind of devices that can be handled:
 .IP \(bu
 Device must not have banks (as most Winbond devices do).
 
+.SH BUGS
+To report bugs or send fixes, please write to the Linux I2C mailing list
+<linux-i2c@vger.kernel.org>.
+
 .SH SEE ALSO
 i2cdump(8), i2cdetect(8), i2cset(8)
 
diff --git a/tools/i2cdetect.8 b/tools/i2cdetect.8
index 14c1f18..9e9f7cc 100644
--- a/tools/i2cdetect.8
+++ b/tools/i2cdetect.8
@@ -113,6 +113,10 @@ using the "receive byte" method, after user confirmation:
 .RE
 .fi
 
+.SH BUGS
+To report bugs or send fixes, please write to the Linux I2C mailing list
+<linux-i2c@vger.kernel.org>.
+
 .SH SEE ALSO
 i2cdump(8), i2cget(8), i2cset(8), i2ctransfer(8), sensors-detect(8)
 
diff --git a/tools/i2cdump.8 b/tools/i2cdump.8
index 18bf600..6acfcc2 100644
--- a/tools/i2cdump.8
+++ b/tools/i2cdump.8
@@ -116,6 +116,10 @@ user confirmation:
 .RE
 .fi
 
+.SH BUGS
+To report bugs or send fixes, please write to the Linux I2C mailing list
+<linux-i2c@vger.kernel.org>.
+
 .SH SEE ALSO
 i2cdetect(8), i2cget(8), i2cset(8), i2ctransfer(8), isadump(8)
 
diff --git a/tools/i2cget.8 b/tools/i2cget.8
index 680279f..ac4024a 100644
--- a/tools/i2cget.8
+++ b/tools/i2cget.8
@@ -113,6 +113,10 @@ equivalent, so this is the only way to read data from a large EEPROM if your
 master isn't fully I2C capable. With a fully I2C capable master, you would
 use \fIi2ctransfer\fR to achieve the same in a safe and faster way.
 
+.SH BUGS
+To report bugs or send fixes, please write to the Linux I2C mailing list
+<linux-i2c@vger.kernel.org>.
+
 .SH SEE ALSO
 i2cdetect(8), i2cdump(8), i2cset(8), i2ctransfer(8)
 
diff --git a/tools/i2cset.8 b/tools/i2cset.8
index 8c73c60..138f545 100644
--- a/tools/i2cset.8
+++ b/tools/i2cset.8
@@ -125,6 +125,10 @@ address 0x48 on bus 1 (i2c-1), after user confirmation:
 Also see i2cget(8) for examples of combined usage of \fIi2cset\fR and
 \fIi2cget\fR.
 
+.SH BUGS
+To report bugs or send fixes, please write to the Linux I2C mailing list
+<linux-i2c@vger.kernel.org>.
+
 .SH SEE ALSO
 i2cdetect(8), i2cdump(8), i2cget(8), i2ctransfer(8), isaset(8)
 
diff --git a/tools/i2ctransfer.8 b/tools/i2ctransfer.8
index 152d20d..3b14375 100644
--- a/tools/i2ctransfer.8
+++ b/tools/i2ctransfer.8
@@ -152,6 +152,10 @@ It can confuse your I2C bus, cause data loss, or have more serious side effects.
 Writing to a serial EEPROM on a memory DIMM (chip addresses between 0x50 and 0x57) may DESTROY your memory, leaving your system unbootable!
 Be extremely careful using this program.
 
+.SH BUGS
+To report bugs or send fixes, please write to the Linux I2C mailing list
+<linux-i2c@vger.kernel.org>.
+
 .SH AUTHORS
 Wolfram Sang, based on
 .B i2cget
-- 
2.27.0

Re: [PATCH i2c-tools] add BUGS section to manpages

[Jean Delvare]

On Thu,  6 Aug 2020 16:54:21 +0200, Wolfram Sang wrote:
> For all manpages installed on my Debian system, add a BUGS section, so
> people can easily find whom to contact.
> 
> Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
> ---
>  eeprom/decode-dimms.1     | 3 +++
>  eeprom/decode-vaio.1      | 3 +++
>  stub/i2c-stub-from-dump.8 | 4 ++++
>  tools/i2cdetect.8         | 4 ++++
>  tools/i2cdump.8           | 4 ++++
>  tools/i2cget.8            | 4 ++++
>  tools/i2cset.8            | 4 ++++
>  tools/i2ctransfer.8       | 4 ++++
>  8 files changed, 30 insertions(+)
> (...)

Sure, can't hurt.

Reviewed-by: Jean Delvare <jdelvare@suse.de>

-- 
Jean Delvare
SUSE L3 Support

Re: [PATCH i2c-tools] add BUGS section to manpages

[Wolfram Sang]

[-- Attachment #1: Type: text/plain, Size: 274 bytes --]

On Thu, Aug 06, 2020 at 04:54:21PM +0200, Wolfram Sang wrote:
> For all manpages installed on my Debian system, add a BUGS section, so
> people can easily find whom to contact.
> 
> Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>

Applied to master.


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH i2c-tools] add BUGS section to manpages

[Jean Delvare]

Hi Wolfram,

On Thu,  6 Aug 2020 16:54:21 +0200, Wolfram Sang wrote:
> For all manpages installed on my Debian system, add a BUGS section, so
> people can easily find whom to contact.
> 
> Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
> (...)
> --- a/eeprom/decode-dimms.1
> +++ b/eeprom/decode-dimms.1
> @@ -62,6 +62,9 @@ Same as -x except treat multibyte hex data as little endian
>  .TP
>  .B \-h, --help
>  Display the usage summary
> +.SH BUGS
> +To report bugs or send fixes, please write to the Linux I2C mailing list
> +<linux-i2c@vger.kernel.org>.
>  .SH SEE ALSO
>  .BR decode-vaio (1)
>  .SH AUTHORS

On second thought... I see an issue with this.

So far, the contact information for reporting bugs was in the README
file:

Please post your questions and bug reports to the linux-i2c mailing list:
  linux-i2c@vger.kernel.org
with Cc to the current maintainer:
  Jean Delvare <jdelvare@suse.de>

Now the manual pages point to the mailing list only, which I am not
reading. It seems kind of wrong to tell users to report bugs on a list
which the current maintainer isn't reading.

I can see 3 solutions to that:

1a* I subscribe to linux-i2c again. I'm afraid this won't go well
though, as I unsubscribed for a reason - I no longer had time to read
that list and most of the traffic had no interest for me. These reasons
did not change. So even if I do subscribe, chances are that I won't
read the list and thus miss the relevant reports.

1b* Same as 1a but we explicitly ask people to add "i2c-tools" to the
subject, so that I can filter out everything else. That's not bullet
proof, and causes useless traffic to my mail box, but could work.

2* Add my address to the BUGS section of the manual pages, together
with the list's address. That should work for the time being, but I
don't feel too comfortable with my name being put forward that way,
plus this will require updating all files whenever the maintainer
changes (don't panic, I have no plan to leave, but no one can tell what
the future holds).

3* Create a separate list for linux-i2c tools. I think the VGER admins
are more open to creating additional lists than they were 13 years ago
when i2c-tools saw existence as a separate project. I would - obviously
- subscribe to that list. The advantage is that we then have a clear
separation between kernel-space topics and user-space topics, and
everyone can subscribe to either or both lists depending on their
needs, which is more flexible. The drawback is that people who are
interested in everything have twice as much work to subscribe, manage
their subscription and unsubscribe. Another issue is that it will take
some time before the information propagates and users start using the
new list for i2c-tools questions and bug reports.

And of course there's always the status quo option:

4* Do nothing. You get to let me know whenever something hits the list
that I should look into. That's fine with me, but this adds another
single point of failure on the path, and means extra work for you too.

What do you think?

Thanks,
-- 
Jean Delvare
SUSE L3 Support

Re: [PATCH i2c-tools] add BUGS section to manpages

[Wolfram Sang]

[-- Attachment #1: Type: text/plain, Size: 601 bytes --]


> 2* Add my address to the BUGS section of the manual pages, together
> with the list's address. That should work for the time being, but I
> don't feel too comfortable with my name being put forward that way,
> plus this will require updating all files whenever the maintainer
> changes (don't panic, I have no plan to leave, but no one can tell what
> the future holds).

I think let's go this way. For consistency, and because it is less work
for me and you. I don't have an issue with the maintainer being more
visible, and the changes (when they come) are just more work for sed,
not for us :)


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]