Re: [PATCH 12/53] docs: driver-api: avoid using UTF-8 chars

From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Andy Shevchenko <andy.shevchenko@gmail.com>
Cc: Linux Doc Mailing List <linux-doc@vger.kernel.org>,
	Jonathan Corbet <corbet@lwn.net>,
	Andy Shevchenko <andriy.shevchenko@linux.intel.com>,
	Dan Williams <dan.j.williams@intel.com>,
	Dave Ertman <david.m.ertman@intel.com>,
	Drew Fustini <drew@beagleboard.org>,
	Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
	Hans de Goede <hdegoede@redhat.com>,
	Heikki Krogerus <heikki.krogerus@linux.intel.com>,
	Jacob Keller <jacob.e.keller@intel.com>,
	Michael Walle <michael@walle.cc>,
	Philipp Zabel <p.zabel@pengutronix.de>,
	"linux-kernel@vger.kernel.org" <linux-kernel@vger.kernel.org>
Subject: Re: [PATCH 12/53] docs: driver-api: avoid using UTF-8 chars
Date: Wed, 12 May 2021 10:49:46 +0200	[thread overview]
Message-ID: <20210512104946.2fb26eeb@coco.lan> (raw)
In-Reply-To: <CAHp75Vegsb-+fVppv3C7Jp0a=mEGAh2pchX=Cr5ZvOMFt+G73Q@mail.gmail.com>

Em Mon, 10 May 2021 14:05:12 +0300
Andy Shevchenko <andy.shevchenko@gmail.com> escreveu:

> On Monday, May 10, 2021, Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> 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+00a0 (' '): NO-BREAK SPACE
> >         - U+2014 ('—'): EM DASH  
> 
> 
> Strictly speaking the EM Dash equivalent is ‘--‘.

Yes, EM DASH is equivalent to multiple '-'.

Sphinx (and other similar tools) use those rules:

	-- is equivalent to EN DASH;
	--- is equivalent to EM DASH

Anyway, I'll change this on a next spin.

> 
> 
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  Documentation/driver-api/index.rst | 2 +-
> >  Documentation/driver-api/ioctl.rst | 8 ++++----
> >  2 files changed, 5 insertions(+), 5 deletions(-)
> >
> > diff --git a/Documentation/driver-api/index.rst
> > b/Documentation/driver-api/index.rst
> > index f5a3207aa7fa..29eb9230b7a9 100644
> > --- a/Documentation/driver-api/index.rst
> > +++ b/Documentation/driver-api/index.rst
> > @@ -4,7 +4,7 @@ The Linux driver implementer's API guide
> >
> >  The kernel offers a wide variety of interfaces to support the development
> >  of device drivers.  This document is an only somewhat organized collection
> > -of some of those interfaces — it will hopefully get better over time!  The
> > +of some of those interfaces - it will hopefully get better over time!  The
> >  available subsections can be seen below.
> >
> >  .. class:: toc-title
> > diff --git a/Documentation/driver-api/ioctl.rst
> > b/Documentation/driver-api/ioctl.rst
> > index c455db0e1627..5b76e765827d 100644
> > --- a/Documentation/driver-api/ioctl.rst
> > +++ b/Documentation/driver-api/ioctl.rst
> > @@ -25,9 +25,9 @@ ioctl commands that follow modern conventions: ``_IO``,
> > ``_IOR``,
> >  with the correct parameters:
> >
> >  _IO/_IOR/_IOW/_IOWR
> > -   The macro name specifies how the argument will be used.  It may be a
> > +   The macro name specifies how the argument will be used.  It may be a
> >     pointer to data to be passed into the kernel (_IOW), out of the kernel
> > -   (_IOR), or both (_IOWR).  _IO can indicate either commands with no
> > +   (_IOR), or both (_IOWR).  _IO can indicate either commands with no
> >     argument or those passing an integer value instead of a pointer.
> >     It is recommended to only use _IO for commands without arguments,
> >     and use pointers for passing data.
> > @@ -200,10 +200,10 @@ cause an information leak, which can be used to
> > defeat kernel address
> >  space layout randomization (KASLR), helping in an attack.
> >
> >  For this reason (and for compat support) it is best to avoid any
> > -implicit padding in data structures.  Where there is implicit padding
> > +implicit padding in data structures.  Where there is implicit padding
> >  in an existing structure, kernel drivers must be careful to fully
> >  initialize an instance of the structure before copying it to user
> > -space.  This is usually done by calling memset() before assigning to
> > +space.  This is usually done by calling memset() before assigning to
> >  individual members.
> >
> >  Subsystem abstractions
> > --
> > 2.30.2
> >
> >  
> 

Thanks,
Mauro