linux-kernel - Re: [PATCH v2 31/40] docs: PCI: acpi-info.rst: Use ASCII subset instead of UTF-8 alternate symbols

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Wed, 12 May 2021 16:29:38 -0500
From:   Bjorn Helgaas <helgaas@...nel.org>
To:     Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
Cc:     Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Jonathan Corbet <corbet@....net>,
        Bjorn Helgaas <bhelgaas@...gle.com>,
        linux-kernel@...r.kernel.org, linux-pci@...r.kernel.org,
        Krzysztof Wilczyński <kw@...ux.com>
Subject: Re: [PATCH v2 31/40] docs: PCI: acpi-info.rst: Use ASCII subset
 instead of UTF-8 alternate symbols

1) The subject line convention in Documentation/PCI has been
"Documentation: PCI: ...", but that is a little wordy, and if you want
to start a wider convention of "docs: PCI: ..." I'm OK with that.

2) IMO, including the filename ("acpi-info.rst") in the subject is not
really all that interesting.  In fact, I'd be fine with doing this
sort of mechanical conversion with a patch per directory or even a
single patch for *all* of Documentation/.

On Wed, May 12, 2021 at 02:50:35PM +0200, Mauro Carvalho Chehab wrote:
> The conversion tools used during DocBook/LaTeX/Markdown->ReST conversion
> and some automatic rules which exists on certain text editors like
> LibreOffice turned ASCII characters into some UTF-8 alternatives that
> are better displayed on html and PDF.
> 
> While it is OK to use UTF-8 characters in Linux, it is better to
> use the ASCII subset instead of using an UTF-8 equivalent character
> as it makes life easier for tools like grep, and are easier to edit
> with the some commonly used text/source code editors.
> 
> Also, Sphinx already do such conversion automatically outside literal blocks:
>    https://docutils.sourceforge.io/docs/user/smartquotes.html
> 
> So, replace the occurences of the following UTF-8 characters:
> 
> 	- U+00a0 (' '): NO-BREAK SPACE
> 	- U+2019 ('’'): RIGHT SINGLE QUOTATION MARK
> 
> Reviewed-by: Krzysztof Wilczyński <kw@...ux.com>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>

Yes, this is annoying.  Thanks for doing this.

I noticed a few other anomalies.  If you want to keep this series as
just a mechanical thing and leave the things below for later, I'm OK
with that, too.

Acked-by: Bjorn Helgaas <bhelgaas@...gle.com>

> ---
>  Documentation/PCI/acpi-info.rst | 22 +++++++++++-----------
>  1 file changed, 11 insertions(+), 11 deletions(-)
> 
> diff --git a/Documentation/PCI/acpi-info.rst b/Documentation/PCI/acpi-info.rst
> index 060217081c79..30d0fc85dd8e 100644
> --- a/Documentation/PCI/acpi-info.rst
> +++ b/Documentation/PCI/acpi-info.rst
> @@ -22,9 +22,9 @@ or if the device has INTx interrupts connected by platform interrupt
>  controllers and a _PRT is needed to describe those connections.
>  
>  ACPI resource description is done via _CRS objects of devices in the ACPI
> -namespace [2].   The _CRS is like a generalized PCI BAR: the OS can read
> +namespace [2].   The _CRS is like a generalized PCI BAR: the OS can read

s/   The _CRS/  The _CRS/

Remove one of the spaces at the end of this sentence.  One space is
OK, two is the convention in this file, and three is way too many :)

> @@ -66,7 +66,7 @@ the PNP0A03/PNP0A08 device itself.  The workaround was to describe the
>  bridge registers (including ECAM space) in PNP0C02 catch-all devices [6].
>  With the exception of ECAM, the bridge register space is device-specific
>  anyway, so the generic PNP0A03/PNP0A08 driver (pci_root.c) has no need to
> -know about it.  
> +know about it.  

Remove all the whitespace at the end of this line.

Bjorn