linux-doc.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [PATCH 0/5] Fix some UTF-8 bad usages
@ 2021-05-11 15:01 Mauro Carvalho Chehab
  2021-05-11 15:01 ` [PATCH 1/5] docs: cdrom-standard.rst: get rid of uneeded UTF-8 chars Mauro Carvalho Chehab
                   ` (5 more replies)
  0 siblings, 6 replies; 14+ messages in thread
From: Mauro Carvalho Chehab @ 2021-05-11 15:01 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
	David S. Miller, Guenter Roeck, Jakub Kicinski, Jean Delvare,
	Jens Axboe, intel-wired-lan, linux-hwmon, netdev

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=UTF-8, Size: 1720 bytes --]

This series follow up this past series:
	https://lore.kernel.org/lkml/cover.1620641727.git.mchehab+huawei@kernel.org/

Containing just the manual fixes from it. I'll respin the remaining
patches on a separate series.

Please note that patches 1 to 3 are identical to the ones posted
on the original series.

Patch 1 is special: it fixes some left-overs from a convertion
from cdrom-standard.tex: there, some characters that are
valid in C were converted to some visually similar UTF-8 by LaTeX.

Patch 2 remove U+00ac ('¬'): NOT SIGN characters at the end of
the first line of two files. No idea why those ended being there :-p

Patch 3 replaces:
	KernelVersion:»·3.3
by:
	KernelVersion:	3.3

which is the expected format for the KernelVersion field;

Patches 4 and 5 fix some bad usages of EM DASH/EN DASH on
places that it should be, instead, a normal hyphen. I suspect
that they ended being there due to the usage of some conversion
toolset.

Mauro Carvalho Chehab (5):
  docs: cdrom-standard.rst: get rid of uneeded UTF-8 chars
  docs: ABI: remove a meaningless UTF-8 character
  docs: ABI: remove some spurious characters
  docs: hwmon: tmp103.rst: fix bad usage of UTF-8 chars
  docs: networking: device_drivers: fix bad usage of UTF-8 chars

 .../obsolete/sysfs-kernel-fadump_registered   |  2 +-
 .../obsolete/sysfs-kernel-fadump_release_mem  |  2 +-
 Documentation/ABI/testing/sysfs-module        |  4 +--
 Documentation/cdrom/cdrom-standard.rst        | 30 +++++++++----------
 Documentation/hwmon/tmp103.rst                |  4 +--
 .../device_drivers/ethernet/intel/i40e.rst    |  4 +--
 .../device_drivers/ethernet/intel/iavf.rst    |  2 +-
 7 files changed, 24 insertions(+), 24 deletions(-)

-- 
2.30.2



^ permalink raw reply	[flat|nested] 14+ messages in thread

* [PATCH 1/5] docs: cdrom-standard.rst: get rid of uneeded UTF-8 chars
  2021-05-11 15:01 [PATCH 0/5] Fix some UTF-8 bad usages Mauro Carvalho Chehab
@ 2021-05-11 15:01 ` Mauro Carvalho Chehab
  2021-05-11 15:21   ` Jens Axboe
  2021-05-11 15:01 ` [PATCH 2/5] docs: ABI: remove a meaningless UTF-8 character Mauro Carvalho Chehab
                   ` (4 subsequent siblings)
  5 siblings, 1 reply; 14+ messages in thread
From: Mauro Carvalho Chehab @ 2021-05-11 15:01 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Jens Axboe, linux-kernel

This file was converted from a LaTeX one. The conversion used
some UTF-8 characters at the literal blocks. Replace them
by normal ASCII characters.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/cdrom/cdrom-standard.rst | 30 +++++++++++++-------------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/Documentation/cdrom/cdrom-standard.rst b/Documentation/cdrom/cdrom-standard.rst
index 70500b189cc8..5845960ca382 100644
--- a/Documentation/cdrom/cdrom-standard.rst
+++ b/Documentation/cdrom/cdrom-standard.rst
@@ -146,18 +146,18 @@ with the kernel as a block device by registering the following general
 *struct file_operations*::
 
 	struct file_operations cdrom_fops = {
-		NULL,			/∗ lseek ∗/
-		block _read ,		/∗ read—general block-dev read ∗/
-		block _write,		/∗ write—general block-dev write ∗/
-		NULL,			/∗ readdir ∗/
-		NULL,			/∗ select ∗/
-		cdrom_ioctl,		/∗ ioctl ∗/
-		NULL,			/∗ mmap ∗/
-		cdrom_open,		/∗ open ∗/
-		cdrom_release,		/∗ release ∗/
-		NULL,			/∗ fsync ∗/
-		NULL,			/∗ fasync ∗/
-		NULL			/∗ revalidate ∗/
+		NULL,			/* lseek */
+		block _read ,		/* read--general block-dev read */
+		block _write,		/* write--general block-dev write */
+		NULL,			/* readdir */
+		NULL,			/* select */
+		cdrom_ioctl,		/* ioctl */
+		NULL,			/* mmap */
+		cdrom_open,		/* open */
+		cdrom_release,		/* release */
+		NULL,			/* fsync */
+		NULL,			/* fasync */
+		NULL			/* revalidate */
 	};
 
 Every active CD-ROM device shares this *struct*. The routines
@@ -250,12 +250,12 @@ The drive-specific, minor-like information that is registered with
 `cdrom.c`, currently contains the following fields::
 
   struct cdrom_device_info {
-	const struct cdrom_device_ops * ops; 	/* device operations for this major */
+	const struct cdrom_device_ops * ops;	/* device operations for this major */
 	struct list_head list;			/* linked list of all device_info */
 	struct gendisk * disk;			/* matching block layer disk */
 	void *  handle;				/* driver-dependent data */
 
-	int mask; 				/* mask of capability: disables them */
+	int mask;				/* mask of capability: disables them */
 	int speed;				/* maximum speed for reading data */
 	int capacity;				/* number of discs in a jukebox */
 
@@ -569,7 +569,7 @@ the *CDC_CLOSE_TRAY* bit in *mask*.
 
 In the file `cdrom.c` you will encounter many constructions of the type::
 
-	if (cdo->capability & ∼cdi->mask & CDC _⟨capability⟩) ...
+	if (cdo->capability & ~cdi->mask & CDC _<capability>) ...
 
 There is no *ioctl* to set the mask... The reason is that
 I think it is better to control the **behavior** rather than the
-- 
2.30.2


^ permalink raw reply	[flat|nested] 14+ messages in thread

* [PATCH 2/5] docs: ABI: remove a meaningless UTF-8 character
  2021-05-11 15:01 [PATCH 0/5] Fix some UTF-8 bad usages Mauro Carvalho Chehab
  2021-05-11 15:01 ` [PATCH 1/5] docs: cdrom-standard.rst: get rid of uneeded UTF-8 chars Mauro Carvalho Chehab
@ 2021-05-11 15:01 ` Mauro Carvalho Chehab
  2021-05-11 15:01 ` [PATCH 3/5] docs: ABI: remove some spurious characters Mauro Carvalho Chehab
                   ` (3 subsequent siblings)
  5 siblings, 0 replies; 14+ messages in thread
From: Mauro Carvalho Chehab @ 2021-05-11 15:01 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, linux-kernel

Those two files have this character:
	- U+00ac ('¬'): NOT SIGN

at the end of the first line, apparently for no reason. Drop them.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/ABI/obsolete/sysfs-kernel-fadump_registered  | 2 +-
 Documentation/ABI/obsolete/sysfs-kernel-fadump_release_mem | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/ABI/obsolete/sysfs-kernel-fadump_registered b/Documentation/ABI/obsolete/sysfs-kernel-fadump_registered
index 0360be39c98e..dae880b1a5d5 100644
--- a/Documentation/ABI/obsolete/sysfs-kernel-fadump_registered
+++ b/Documentation/ABI/obsolete/sysfs-kernel-fadump_registered
@@ -1,4 +1,4 @@
-This ABI is renamed and moved to a new location /sys/kernel/fadump/registered.¬
+This ABI is renamed and moved to a new location /sys/kernel/fadump/registered.
 
 What:		/sys/kernel/fadump_registered
 Date:		Feb 2012
diff --git a/Documentation/ABI/obsolete/sysfs-kernel-fadump_release_mem b/Documentation/ABI/obsolete/sysfs-kernel-fadump_release_mem
index 6ce0b129ab12..ca2396edb5f1 100644
--- a/Documentation/ABI/obsolete/sysfs-kernel-fadump_release_mem
+++ b/Documentation/ABI/obsolete/sysfs-kernel-fadump_release_mem
@@ -1,4 +1,4 @@
-This ABI is renamed and moved to a new location /sys/kernel/fadump/release_mem.¬
+This ABI is renamed and moved to a new location /sys/kernel/fadump/release_mem.
 
 What:		/sys/kernel/fadump_release_mem
 Date:		Feb 2012
-- 
2.30.2


^ permalink raw reply	[flat|nested] 14+ messages in thread

* [PATCH 3/5] docs: ABI: remove some spurious characters
  2021-05-11 15:01 [PATCH 0/5] Fix some UTF-8 bad usages Mauro Carvalho Chehab
  2021-05-11 15:01 ` [PATCH 1/5] docs: cdrom-standard.rst: get rid of uneeded UTF-8 chars Mauro Carvalho Chehab
  2021-05-11 15:01 ` [PATCH 2/5] docs: ABI: remove a meaningless UTF-8 character Mauro Carvalho Chehab
@ 2021-05-11 15:01 ` Mauro Carvalho Chehab
  2021-05-11 15:01 ` [PATCH 4/5] docs: hwmon: tmp103.rst: fix bad usage of UTF-8 chars Mauro Carvalho Chehab
                   ` (2 subsequent siblings)
  5 siblings, 0 replies; 14+ messages in thread
From: Mauro Carvalho Chehab @ 2021-05-11 15:01 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Cezary Rojewski,
	Geert Uytterhoeven, Oded Gabbay, Tom Rix, linux-kernel

The KernelVersion tag contains some spurious UTF-8 characters
for no reason. Drop them.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/ABI/testing/sysfs-module | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-module b/Documentation/ABI/testing/sysfs-module
index a485434d2a0f..88bddf192ceb 100644
--- a/Documentation/ABI/testing/sysfs-module
+++ b/Documentation/ABI/testing/sysfs-module
@@ -37,13 +37,13 @@ Description:	Maximum time allowed for periodic transfers per microframe (μs)
 
 What:		/sys/module/*/{coresize,initsize}
 Date:		Jan 2012
-KernelVersion:»·3.3
+KernelVersion:	3.3
 Contact:	Kay Sievers <kay.sievers@vrfy.org>
 Description:	Module size in bytes.
 
 What:		/sys/module/*/taint
 Date:		Jan 2012
-KernelVersion:»·3.3
+KernelVersion:	3.3
 Contact:	Kay Sievers <kay.sievers@vrfy.org>
 Description:	Module taint flags:
 			==  =====================
-- 
2.30.2


^ permalink raw reply	[flat|nested] 14+ messages in thread

* [PATCH 4/5] docs: hwmon: tmp103.rst: fix bad usage of UTF-8 chars
  2021-05-11 15:01 [PATCH 0/5] Fix some UTF-8 bad usages Mauro Carvalho Chehab
                   ` (2 preceding siblings ...)
  2021-05-11 15:01 ` [PATCH 3/5] docs: ABI: remove some spurious characters Mauro Carvalho Chehab
@ 2021-05-11 15:01 ` Mauro Carvalho Chehab
  2021-05-11 18:55   ` Guenter Roeck
  2021-05-11 15:01 ` [PATCH 5/5] docs: networking: device_drivers: " Mauro Carvalho Chehab
  2021-05-11 17:01 ` [PATCH 0/5] Fix some UTF-8 bad usages Jonathan Corbet
  5 siblings, 1 reply; 14+ messages in thread
From: Mauro Carvalho Chehab @ 2021-05-11 15:01 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Guenter Roeck,
	Jean Delvare, linux-hwmon, linux-kernel

While UTF-8 characters can be used at the Linux documentation,
the best is to use them only when ASCII doesn't offer a good replacement.
So, replace the occurences of the following UTF-8 characters:

	- U+2013 ('–'): EN DASH

In this specific case, EN DASH was used instead of a minus
sign. So, replace it by a single hyphen.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/hwmon/tmp103.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/hwmon/tmp103.rst b/Documentation/hwmon/tmp103.rst
index e195a7d14309..b3ef81475cf8 100644
--- a/Documentation/hwmon/tmp103.rst
+++ b/Documentation/hwmon/tmp103.rst
@@ -21,10 +21,10 @@ Description
 The TMP103 is a digital output temperature sensor in a four-ball
 wafer chip-scale package (WCSP). The TMP103 is capable of reading
 temperatures to a resolution of 1°C. The TMP103 is specified for
-operation over a temperature range of –40°C to +125°C.
+operation over a temperature range of -40°C to +125°C.
 
 Resolution: 8 Bits
-Accuracy: ±1°C Typ (–10°C to +100°C)
+Accuracy: ±1°C Typ (-10°C to +100°C)
 
 The driver provides the common sysfs-interface for temperatures (see
 Documentation/hwmon/sysfs-interface.rst under Temperatures).
-- 
2.30.2


^ permalink raw reply	[flat|nested] 14+ messages in thread

* [PATCH 5/5] docs: networking: device_drivers: fix bad usage of UTF-8 chars
  2021-05-11 15:01 [PATCH 0/5] Fix some UTF-8 bad usages Mauro Carvalho Chehab
                   ` (3 preceding siblings ...)
  2021-05-11 15:01 ` [PATCH 4/5] docs: hwmon: tmp103.rst: fix bad usage of UTF-8 chars Mauro Carvalho Chehab
@ 2021-05-11 15:01 ` Mauro Carvalho Chehab
  2021-05-11 17:22   ` Andrew Lunn
  2021-05-11 17:01 ` [PATCH 0/5] Fix some UTF-8 bad usages Jonathan Corbet
  5 siblings, 1 reply; 14+ messages in thread
From: Mauro Carvalho Chehab @ 2021-05-11 15:01 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, David S. Miller, Jonathan Corbet,
	Jakub Kicinski, Jesse Brandeburg, Tony Nguyen, intel-wired-lan,
	linux-kernel, netdev

Probably because the original file was pre-processed by some
tool, both i40e.rst and iavf.rst files are using this character:

	- U+2013 ('–'): EN DASH

meaning an hyphen when calling a command line application, which
is obviously wrong. So, replace them by an hyphen, ensuring
that it will be properly displayed as literals when building
the documentation.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 .../networking/device_drivers/ethernet/intel/i40e.rst         | 4 ++--
 .../networking/device_drivers/ethernet/intel/iavf.rst         | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/networking/device_drivers/ethernet/intel/i40e.rst b/Documentation/networking/device_drivers/ethernet/intel/i40e.rst
index 8a9b18573688..2d3f6bd969a2 100644
--- a/Documentation/networking/device_drivers/ethernet/intel/i40e.rst
+++ b/Documentation/networking/device_drivers/ethernet/intel/i40e.rst
@@ -173,7 +173,7 @@ Director rule is added from ethtool (Sideband filter), ATR is turned off by the
 driver. To re-enable ATR, the sideband can be disabled with the ethtool -K
 option. For example::
 
-  ethtool –K [adapter] ntuple [off|on]
+  ethtool -K [adapter] ntuple [off|on]
 
 If sideband is re-enabled after ATR is re-enabled, ATR remains enabled until a
 TCP-IP flow is added. When all TCP-IP sideband rules are deleted, ATR is
@@ -688,7 +688,7 @@ shaper bw_rlimit: for each tc, sets minimum and maximum bandwidth rates.
 Totals must be equal or less than port speed.
 
 For example: min_rate 1Gbit 3Gbit: Verify bandwidth limit using network
-monitoring tools such as ifstat or sar –n DEV [interval] [number of samples]
+monitoring tools such as `ifstat` or `sar -n DEV [interval] [number of samples]`
 
 2. Enable HW TC offload on interface::
 
diff --git a/Documentation/networking/device_drivers/ethernet/intel/iavf.rst b/Documentation/networking/device_drivers/ethernet/intel/iavf.rst
index 52e037b11c97..25330b7b5168 100644
--- a/Documentation/networking/device_drivers/ethernet/intel/iavf.rst
+++ b/Documentation/networking/device_drivers/ethernet/intel/iavf.rst
@@ -179,7 +179,7 @@ shaper bw_rlimit: for each tc, sets minimum and maximum bandwidth rates.
 Totals must be equal or less than port speed.
 
 For example: min_rate 1Gbit 3Gbit: Verify bandwidth limit using network
-monitoring tools such as ifstat or sar –n DEV [interval] [number of samples]
+monitoring tools such as ``ifstat`` or ``sar -n DEV [interval] [number of samples]``
 
 NOTE:
   Setting up channels via ethtool (ethtool -L) is not supported when the
-- 
2.30.2


^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [PATCH 1/5] docs: cdrom-standard.rst: get rid of uneeded UTF-8 chars
  2021-05-11 15:01 ` [PATCH 1/5] docs: cdrom-standard.rst: get rid of uneeded UTF-8 chars Mauro Carvalho Chehab
@ 2021-05-11 15:21   ` Jens Axboe
  0 siblings, 0 replies; 14+ messages in thread
From: Jens Axboe @ 2021-05-11 15:21 UTC (permalink / raw)
  To: Mauro Carvalho Chehab, Linux Doc Mailing List
  Cc: Jonathan Corbet, linux-kernel

On 5/11/21 9:01 AM, Mauro Carvalho Chehab wrote:
> This file was converted from a LaTeX one. The conversion used
> some UTF-8 characters at the literal blocks. Replace them
> by normal ASCII characters.

Acked-by: Jens Axboe <axboe@kernel.dk>

-- 
Jens Axboe


^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [PATCH 0/5] Fix some UTF-8 bad usages
  2021-05-11 15:01 [PATCH 0/5] Fix some UTF-8 bad usages Mauro Carvalho Chehab
                   ` (4 preceding siblings ...)
  2021-05-11 15:01 ` [PATCH 5/5] docs: networking: device_drivers: " Mauro Carvalho Chehab
@ 2021-05-11 17:01 ` Jonathan Corbet
  5 siblings, 0 replies; 14+ messages in thread
From: Jonathan Corbet @ 2021-05-11 17:01 UTC (permalink / raw)
  To: Mauro Carvalho Chehab, Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, linux-kernel, David S. Miller,
	Guenter Roeck, Jakub Kicinski, Jean Delvare, Jens Axboe,
	intel-wired-lan, linux-hwmon, netdev

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

> This series follow up this past series:
> 	https://lore.kernel.org/lkml/cover.1620641727.git.mchehab+huawei@kernel.org/
>
> Containing just the manual fixes from it. I'll respin the remaining
> patches on a separate series.
>
> Please note that patches 1 to 3 are identical to the ones posted
> on the original series.
>
> Patch 1 is special: it fixes some left-overs from a convertion
> from cdrom-standard.tex: there, some characters that are
> valid in C were converted to some visually similar UTF-8 by LaTeX.
>
> Patch 2 remove U+00ac (''): NOT SIGN characters at the end of
> the first line of two files. No idea why those ended being there :-p
>
> Patch 3 replaces:
> 	KernelVersion:3.3
> by:
> 	KernelVersion:	3.3
>
> which is the expected format for the KernelVersion field;
>
> Patches 4 and 5 fix some bad usages of EM DASH/EN DASH on
> places that it should be, instead, a normal hyphen. I suspect
> that they ended being there due to the usage of some conversion
> toolset.
>
> Mauro Carvalho Chehab (5):
>   docs: cdrom-standard.rst: get rid of uneeded UTF-8 chars
>   docs: ABI: remove a meaningless UTF-8 character
>   docs: ABI: remove some spurious characters
>   docs: hwmon: tmp103.rst: fix bad usage of UTF-8 chars
>   docs: networking: device_drivers: fix bad usage of UTF-8 chars
>
>  .../obsolete/sysfs-kernel-fadump_registered   |  2 +-
>  .../obsolete/sysfs-kernel-fadump_release_mem  |  2 +-
>  Documentation/ABI/testing/sysfs-module        |  4 +--
>  Documentation/cdrom/cdrom-standard.rst        | 30 +++++++++----------
>  Documentation/hwmon/tmp103.rst                |  4 +--
>  .../device_drivers/ethernet/intel/i40e.rst    |  4 +--
>  .../device_drivers/ethernet/intel/iavf.rst    |  2 +-
>  7 files changed, 24 insertions(+), 24 deletions(-)

These seem pretty straightforward; I've applied the set, thanks.

jon

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [PATCH 5/5] docs: networking: device_drivers: fix bad usage of UTF-8 chars
  2021-05-11 15:01 ` [PATCH 5/5] docs: networking: device_drivers: " Mauro Carvalho Chehab
@ 2021-05-11 17:22   ` Andrew Lunn
  2021-05-11 18:24     ` Jonathan Corbet
  0 siblings, 1 reply; 14+ messages in thread
From: Andrew Lunn @ 2021-05-11 17:22 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Linux Doc Mailing List, David S. Miller, Jonathan Corbet,
	Jakub Kicinski, Jesse Brandeburg, Tony Nguyen, intel-wired-lan,
	linux-kernel, netdev

> -monitoring tools such as ifstat or sar –n DEV [interval] [number of samples]
> +monitoring tools such as `ifstat` or `sar -n DEV [interval] [number of samples]`

...

>  For example: min_rate 1Gbit 3Gbit: Verify bandwidth limit using network
> -monitoring tools such as ifstat or sar –n DEV [interval] [number of samples]
> +monitoring tools such as ``ifstat`` or ``sar -n DEV [interval] [number of samples]``

Is there a difference between ` and `` ? Does it make sense to be
consistent?

	Andrew

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [PATCH 5/5] docs: networking: device_drivers: fix bad usage of UTF-8 chars
  2021-05-11 17:22   ` Andrew Lunn
@ 2021-05-11 18:24     ` Jonathan Corbet
  2021-05-11 18:48       ` Matthew Wilcox
  0 siblings, 1 reply; 14+ messages in thread
From: Jonathan Corbet @ 2021-05-11 18:24 UTC (permalink / raw)
  To: Andrew Lunn, Mauro Carvalho Chehab
  Cc: Linux Doc Mailing List, David S. Miller, Jakub Kicinski,
	Jesse Brandeburg, Tony Nguyen, intel-wired-lan, linux-kernel,
	netdev

Andrew Lunn <andrew@lunn.ch> writes:

>> -monitoring tools such as ifstat or sar –n DEV [interval] [number of samples]
>> +monitoring tools such as `ifstat` or `sar -n DEV [interval] [number of samples]`
>
> ...
>
>>  For example: min_rate 1Gbit 3Gbit: Verify bandwidth limit using network
>> -monitoring tools such as ifstat or sar –n DEV [interval] [number of samples]
>> +monitoring tools such as ``ifstat`` or ``sar -n DEV [interval] [number of samples]``
>
> Is there a difference between ` and `` ? Does it make sense to be
> consistent?

This is `just weird quotes`
This is ``literal text`` set in monospace in processed output.

There is a certain tension between those who want to see liberal use of
literal-text markup, and those who would rather have less markup in the
text overall; certainly, it's better not to go totally nuts with it.

jon

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [PATCH 5/5] docs: networking: device_drivers: fix bad usage of UTF-8 chars
  2021-05-11 18:24     ` Jonathan Corbet
@ 2021-05-11 18:48       ` Matthew Wilcox
  2021-05-11 19:10         ` Mauro Carvalho Chehab
  0 siblings, 1 reply; 14+ messages in thread
From: Matthew Wilcox @ 2021-05-11 18:48 UTC (permalink / raw)
  To: Jonathan Corbet
  Cc: Andrew Lunn, Mauro Carvalho Chehab, Linux Doc Mailing List,
	David S. Miller, Jakub Kicinski, Jesse Brandeburg, Tony Nguyen,
	intel-wired-lan, linux-kernel, netdev

On Tue, May 11, 2021 at 12:24:52PM -0600, Jonathan Corbet wrote:
> Andrew Lunn <andrew@lunn.ch> writes:
> 
> >> -monitoring tools such as ifstat or sar –n DEV [interval] [number of samples]
> >> +monitoring tools such as `ifstat` or `sar -n DEV [interval] [number of samples]`
> >
> > ...
> >
> >>  For example: min_rate 1Gbit 3Gbit: Verify bandwidth limit using network
> >> -monitoring tools such as ifstat or sar –n DEV [interval] [number of samples]
> >> +monitoring tools such as ``ifstat`` or ``sar -n DEV [interval] [number of samples]``
> >
> > Is there a difference between ` and `` ? Does it make sense to be
> > consistent?
> 
> This is `just weird quotes`

umm ... `this` is supposed to be "interpreted text"
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#inline-markup

Maybe we don't actually interpret it.

> This is ``literal text`` set in monospace in processed output.
> 
> There is a certain tension between those who want to see liberal use of
> literal-text markup, and those who would rather have less markup in the
> text overall; certainly, it's better not to go totally nuts with it.

I really appreciate the work you did to reduce the amount of
markup that's needed!

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [PATCH 4/5] docs: hwmon: tmp103.rst: fix bad usage of UTF-8 chars
  2021-05-11 15:01 ` [PATCH 4/5] docs: hwmon: tmp103.rst: fix bad usage of UTF-8 chars Mauro Carvalho Chehab
@ 2021-05-11 18:55   ` Guenter Roeck
  2021-05-12  5:33     ` Mauro Carvalho Chehab
  0 siblings, 1 reply; 14+ messages in thread
From: Guenter Roeck @ 2021-05-11 18:55 UTC (permalink / raw)
  To: Mauro Carvalho Chehab, Linux Doc Mailing List
  Cc: Jonathan Corbet, Jean Delvare, linux-hwmon, linux-kernel

On 5/11/21 8:01 AM, Mauro Carvalho Chehab wrote:
> While UTF-8 characters can be used at the Linux documentation,
> the best is to use them only when ASCII doesn't offer a good replacement.
> So, replace the occurences of the following UTF-8 characters:
> 
> 	- U+2013 ('–'): EN DASH
> 
> In this specific case, EN DASH was used instead of a minus
> sign. So, replace it by a single hyphen.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Confused. Is that supposed to replace the earlier patch (docs: hwmon:
avoid using UTF-8 chars) ? I thought that was more comprehensive
and just as valid. Anyway, should I drop that patch ?

Guenter

> ---
>   Documentation/hwmon/tmp103.rst | 4 ++--
>   1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/hwmon/tmp103.rst b/Documentation/hwmon/tmp103.rst
> index e195a7d14309..b3ef81475cf8 100644
> --- a/Documentation/hwmon/tmp103.rst
> +++ b/Documentation/hwmon/tmp103.rst
> @@ -21,10 +21,10 @@ Description
>   The TMP103 is a digital output temperature sensor in a four-ball
>   wafer chip-scale package (WCSP). The TMP103 is capable of reading
>   temperatures to a resolution of 1°C. The TMP103 is specified for
> -operation over a temperature range of –40°C to +125°C.
> +operation over a temperature range of -40°C to +125°C.
>   
>   Resolution: 8 Bits
> -Accuracy: ±1°C Typ (–10°C to +100°C)
> +Accuracy: ±1°C Typ (-10°C to +100°C)
>   
>   The driver provides the common sysfs-interface for temperatures (see
>   Documentation/hwmon/sysfs-interface.rst under Temperatures).
> 


^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [PATCH 5/5] docs: networking: device_drivers: fix bad usage of UTF-8 chars
  2021-05-11 18:48       ` Matthew Wilcox
@ 2021-05-11 19:10         ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 14+ messages in thread
From: Mauro Carvalho Chehab @ 2021-05-11 19:10 UTC (permalink / raw)
  To: Matthew Wilcox
  Cc: Jonathan Corbet, Andrew Lunn, Linux Doc Mailing List,
	David S. Miller, Jakub Kicinski, Jesse Brandeburg, Tony Nguyen,
	intel-wired-lan, linux-kernel, netdev

Em Tue, 11 May 2021 19:48:18 +0100
Matthew Wilcox <willy@infradead.org> escreveu:

> On Tue, May 11, 2021 at 12:24:52PM -0600, Jonathan Corbet wrote:
> > Andrew Lunn <andrew@lunn.ch> writes:
> >   
> > >> -monitoring tools such as ifstat or sar –n DEV [interval] [number of samples]
> > >> +monitoring tools such as `ifstat` or `sar -n DEV [interval] [number of samples]`  
> > >
> > > ...
> > >  
> > >>  For example: min_rate 1Gbit 3Gbit: Verify bandwidth limit using network
> > >> -monitoring tools such as ifstat or sar –n DEV [interval] [number of samples]
> > >> +monitoring tools such as ``ifstat`` or ``sar -n DEV [interval] [number of samples]``  
> > >
> > > Is there a difference between ` and `` ? Does it make sense to be
> > > consistent?  
> > 
> > This is `just weird quotes`  

Gah, sorry for that! I sent a wrong version of this patch...
i40e.rst should also be using:

	monitoring tools such as ``ifstat`` or ``sar -n DEV [interval] [number of samples]`` 

I'll fix it on the next spin.

> 
> umm ... `this` is supposed to be "interpreted text"
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#inline-markup
> 
> Maybe we don't actually interpret it.

Well, if we use it as something like :ref:`foo`, it is then interpreted ;-)

using `foo` on Sphinx produces, in practice, the same effect as
``foo`` (at least on the initial versions): it also sets the font to
monospace and stops parsing other markups inside the `interpreted text`
string. 

I remember that, at the very beginning, I did some ReST conversions
using `foo`. Then, I realized that this actually wrong, from the
definition PoV, and started using ``foo``.

> 
> > This is ``literal text`` set in monospace in processed output.
> > 
> > There is a certain tension between those who want to see liberal use of
> > literal-text markup, and those who would rather have less markup in the
> > text overall; certainly, it's better not to go totally nuts with it.  
> 
> I really appreciate the work you did to reduce the amount of
> markup that's needed!

In the specific case of using things like: ``command -n``, I would
put it on a literal block, either like the proposed path, or as:

	monitoring tools such as::

		ifstat

	or::
		sar -n DEV [interval] [number of samples]

ifstat is there using the same monospaced font just for
consistency purposes.

See, if you use just: sar -n

The Sphinx output could convert the hyphen to a dash.

Btw, if there was two hyphens, like: "ifstat --help"

This would be converted into "ifstat –help", using the EN DASH UTF-8
character.

So, I strongly recommend that programs (specially when followed
by arguments) to always use a literal block markup.


Thanks,
Mauro

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: [PATCH 4/5] docs: hwmon: tmp103.rst: fix bad usage of UTF-8 chars
  2021-05-11 18:55   ` Guenter Roeck
@ 2021-05-12  5:33     ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 14+ messages in thread
From: Mauro Carvalho Chehab @ 2021-05-12  5:33 UTC (permalink / raw)
  To: Guenter Roeck
  Cc: Linux Doc Mailing List, Jonathan Corbet, Jean Delvare,
	linux-hwmon, linux-kernel

Hi Guenter,

Em Tue, 11 May 2021 11:55:53 -0700
Guenter Roeck <linux@roeck-us.net> escreveu:

> On 5/11/21 8:01 AM, Mauro Carvalho Chehab wrote:
> > While UTF-8 characters can be used at the Linux documentation,
> > the best is to use them only when ASCII doesn't offer a good replacement.
> > So, replace the occurences of the following UTF-8 characters:
> > 
> > 	- U+2013 ('–'): EN DASH
> > 
> > In this specific case, EN DASH was used instead of a minus
> > sign. So, replace it by a single hyphen.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>  
> 
> Confused. Is that supposed to replace the earlier patch (docs: hwmon:
> avoid using UTF-8 chars) ? I thought that was more comprehensive
> and just as valid. Anyway, should I drop that patch ?

If you applied already the previous patch, that's OK. Just ignore this
one.

It is just that, after some discussions around EM/EN DASH on
patch 00/53[1], I opted to split the changes on three parts:

	- UTF-8 fixes;
	- non DASH UTF-8 replacements;
	- EM/EN DASH.

in order to make easier for reviewers to discuss EM/EN DASH if needed.

-

[1] You can see the full thread at:

	https://lore.kernel.org/lkml/cover.1620641727.git.mchehab+huawei@kernel.org/

    In summary, my original patchset were replacing both
    EM/EN DASH to a single hyphen.

    Yet, several maintainers seem to prefer using "--" for EN DASH
    and either "--" or "---" for EM DASH.

    Neither -- nor --- would make any sense on tmp103.rst, as here it
    means a minus sign.
    

> 
> Guenter
> 
> > ---
> >   Documentation/hwmon/tmp103.rst | 4 ++--
> >   1 file changed, 2 insertions(+), 2 deletions(-)
> > 
> > diff --git a/Documentation/hwmon/tmp103.rst b/Documentation/hwmon/tmp103.rst
> > index e195a7d14309..b3ef81475cf8 100644
> > --- a/Documentation/hwmon/tmp103.rst
> > +++ b/Documentation/hwmon/tmp103.rst
> > @@ -21,10 +21,10 @@ Description
> >   The TMP103 is a digital output temperature sensor in a four-ball
> >   wafer chip-scale package (WCSP). The TMP103 is capable of reading
> >   temperatures to a resolution of 1°C. The TMP103 is specified for
> > -operation over a temperature range of –40°C to +125°C.
> > +operation over a temperature range of -40°C to +125°C.
> >   
> >   Resolution: 8 Bits
> > -Accuracy: ±1°C Typ (–10°C to +100°C)
> > +Accuracy: ±1°C Typ (-10°C to +100°C)
> >   
> >   The driver provides the common sysfs-interface for temperatures (see
> >   Documentation/hwmon/sysfs-interface.rst under Temperatures).
> >   
> 



Thanks,
Mauro

^ permalink raw reply	[flat|nested] 14+ messages in thread

end of thread, other threads:[~2021-05-12  5:33 UTC | newest]

Thread overview: 14+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-05-11 15:01 [PATCH 0/5] Fix some UTF-8 bad usages Mauro Carvalho Chehab
2021-05-11 15:01 ` [PATCH 1/5] docs: cdrom-standard.rst: get rid of uneeded UTF-8 chars Mauro Carvalho Chehab
2021-05-11 15:21   ` Jens Axboe
2021-05-11 15:01 ` [PATCH 2/5] docs: ABI: remove a meaningless UTF-8 character Mauro Carvalho Chehab
2021-05-11 15:01 ` [PATCH 3/5] docs: ABI: remove some spurious characters Mauro Carvalho Chehab
2021-05-11 15:01 ` [PATCH 4/5] docs: hwmon: tmp103.rst: fix bad usage of UTF-8 chars Mauro Carvalho Chehab
2021-05-11 18:55   ` Guenter Roeck
2021-05-12  5:33     ` Mauro Carvalho Chehab
2021-05-11 15:01 ` [PATCH 5/5] docs: networking: device_drivers: " Mauro Carvalho Chehab
2021-05-11 17:22   ` Andrew Lunn
2021-05-11 18:24     ` Jonathan Corbet
2021-05-11 18:48       ` Matthew Wilcox
2021-05-11 19:10         ` Mauro Carvalho Chehab
2021-05-11 17:01 ` [PATCH 0/5] Fix some UTF-8 bad usages Jonathan Corbet

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).