This series follow up this past series:
https://lore.kernel.org/lkml/[email protected]/
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
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 <[email protected]>
---
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
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 <[email protected]>
---
.../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
Mauro Carvalho Chehab <[email protected]> writes:
> This series follow up this past series:
> https://lore.kernel.org/lkml/[email protected]/
>
> 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
> -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
Andrew Lunn <[email protected]> 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
On Tue, May 11, 2021 at 12:24:52PM -0600, Jonathan Corbet wrote:
> Andrew Lunn <[email protected]> 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!
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 <[email protected]>
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).
>
Em Tue, 11 May 2021 19:48:18 +0100
Matthew Wilcox <[email protected]> escreveu:
> On Tue, May 11, 2021 at 12:24:52PM -0600, Jonathan Corbet wrote:
> > Andrew Lunn <[email protected]> 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
Hi Guenter,
Em Tue, 11 May 2021 11:55:53 -0700
Guenter Roeck <[email protected]> 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 <[email protected]>
>
> 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/[email protected]/
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