Linux-ACPI Archive on lore.kernel.org
 help / color / Atom feed
From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Richard Cochran <richardcochran@gmail.com>
Cc: "Linux Doc Mailing List" <linux-doc@vger.kernel.org>,
	"Greg Kroah-Hartman" <gregkh@linuxfoundation.org>,
	"Mauro Carvalho Chehab" <mchehab+samsung@kernel.org>,
	"Gautham R. Shenoy" <ego@linux.vnet.ibm.com>,
	"Jason A. Donenfeld" <Jason@zx2c4.com>,
	"Javier González" <javier@javigon.com>,
	"Jonathan Corbet" <corbet@lwn.net>,
	"Martin K. Petersen" <martin.petersen@oracle.com>,
	"Rafael J. Wysocki" <rjw@rjwysocki.net>,
	"Alexander Shishkin" <alexander.shishkin@linux.intel.com>,
	"Alexandre Belloni" <alexandre.belloni@bootlin.com>,
	"Alexandre Torgue" <alexandre.torgue@st.com>,
	"Andrew Donnellan" <ajd@linux.ibm.com>,
	"Andy Shevchenko" <andriy.shevchenko@linux.intel.com>,
	"Baolin Wang" <baolin.wang7@gmail.com>,
	"Benson Leung" <bleung@chromium.org>,
	"Boris Ostrovsky" <boris.ostrovsky@oracle.com>,
	"Bruno Meneguele" <bmeneg@redhat.com>,
	"Chunyan Zhang" <zhang.lyra@gmail.com>,
	"Dan Murphy" <dmurphy@ti.com>,
	"Dan Williams" <dan.j.williams@intel.com>,
	"Enric Balletbo i Serra" <enric.balletbo@collabora.com>,
	"Fabrice Gasnier" <fabrice.gasnier@st.com>,
	"Felipe Balbi" <balbi@kernel.org>,
	"Frederic Barrat" <fbarrat@linux.ibm.com>,
	"Guenter Roeck" <groeck@chromium.org>,
	"Hanjun Guo" <guohanjun@huawei.com>,
	"Heikki Krogerus" <heikki.krogerus@linux.intel.com>,
	"Jens Axboe" <axboe@kernel.dk>,
	"Johannes Thumshirn" <johannes.thumshirn@wdc.com>,
	"Jonathan Cameron" <jic23@kernel.org>,
	"Juergen Gross" <jgross@suse.com>,
	"Konstantin Khlebnikov" <koct9i@gmail.com>,
	"Kranthi Kuntala" <kranthi.kuntala@intel.com>,
	"Lakshmi Ramasubramanian" <nramas@linux.microsoft.com>,
	"Lars-Peter Clausen" <lars@metafoo.de>,
	"Len Brown" <lenb@kernel.org>,
	"Leonid Maksymchuk" <leonmaxx@gmail.com>,
	"Ludovic Desroches" <ludovic.desroches@microchip.com>,
	"Mario Limonciello" <mario.limonciello@dell.com>,
	"Maxime Coquelin" <mcoquelin.stm32@gmail.com>,
	"Michael Ellerman" <mpe@ellerman.id.au>,
	"Mika Westerberg" <mika.westerberg@linux.intel.com>,
	"Mike Kravetz" <mike.kravetz@oracle.com>,
	"Mimi Zohar" <zohar@linux.ibm.com>,
	"Nayna Jain" <nayna@linux.ibm.com>,
	"Nicolas Ferre" <nicolas.ferre@microchip.com>,
	"Niklas Cassel" <niklas.cassel@wdc.com>,
	"Oleh Kravchenko" <oleg@kaa.org.ua>,
	"Orson Zhai" <orsonzhai@gmail.com>, "Pavel Machek" <pavel@ucw.cz>,
	"Pawan Gupta" <pawan.kumar.gupta@linux.intel.com>,
	"Peter Meerwald-Stadler" <pmeerw@pmeerw.net>,
	"Peter Rosin" <peda@axentia.se>, "Petr Mladek" <pmladek@suse.com>,
	"Philippe Bergheaud" <felix@linux.ibm.com>,
	"Sebastian Reichel" <sre@kernel.org>,
	"Sergey Senozhatsky" <sergey.senozhatsky@gmail.com>,
	"Stefano Stabellini" <sstabellini@kernel.org>,
	"Thinh Nguyen" <Thinh.Nguyen@synopsys.com>,
	"Thomas Gleixner" <tglx@linutronix.de>,
	"Vineela Tummalapalli" <vineela.tummalapalli@intel.com>,
	"Vishal Verma" <vishal.l.verma@intel.com>,
	linux-acpi@vger.kernel.org, linux-arm-kernel@lists.infradead.org,
	linux-iio@vger.kernel.org, linux-kernel@vger.kernel.org,
	linux-mm@kvack.org, linux-pm@vger.kernel.org,
	linux-stm32@st-md-mailman.stormreply.com,
	linux-usb@vger.kernel.org, linuxppc-dev@lists.ozlabs.org,
	netdev@vger.kernel.org, xen-devel@lists.xenproject.org
Subject: Re: [PATCH 20/33] docs: ABI: testing: make the files compatible with ReST output
Date: Thu, 29 Oct 2020 08:21:00 +0100
Message-ID: <20201029082100.4820072c@coco.lan> (raw)
In-Reply-To: <20201028174427.GE9364@hoboy.vegasvil.org>

Hi Richard,

Em Wed, 28 Oct 2020 10:44:27 -0700
Richard Cochran <richardcochran@gmail.com> escreveu:

> On Wed, Oct 28, 2020 at 03:23:18PM +0100, Mauro Carvalho Chehab wrote:
> 
> > diff --git a/Documentation/ABI/testing/sysfs-uevent b/Documentation/ABI/testing/sysfs-uevent
> > index aa39f8d7bcdf..d0893dad3f38 100644
> > --- a/Documentation/ABI/testing/sysfs-uevent
> > +++ b/Documentation/ABI/testing/sysfs-uevent
> > @@ -19,7 +19,8 @@ Description:
> >                  a transaction identifier so it's possible to use the same UUID
> >                  value for one or more synthetic uevents in which case we
> >                  logically group these uevents together for any userspace
> > -                listeners. The UUID value appears in uevent as
> > +                listeners. The UUID value appears in uevent as:  
> 
> I know almost nothing about Sphinx, but why have one colon here ^^^ and ...

Good point. After re-reading the text, this ":" doesn't belong here.

> 
> > +
> >                  "SYNTH_UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" environment
> >                  variable.
> >  
> > @@ -30,18 +31,19 @@ Description:
> >                  It's possible to define zero or more pairs - each pair is then
> >                  delimited by a space character ' '. Each pair appears in
> >                  synthetic uevent as "SYNTH_ARG_KEY=VALUE". That means the KEY
> > -                name gains "SYNTH_ARG_" prefix to avoid possible collisions
> > +                name gains `SYNTH_ARG_` prefix to avoid possible collisions
> >                  with existing variables.
> >  
> > -                Example of valid sequence written to the uevent file:
> > +                Example of valid sequence written to the uevent file::  
> 
> ... two here?

The main issue that this patch wants to solve is here:

                This generates synthetic uevent including these variables::

                    ACTION=add
                    SYNTH_ARG_A=1
                    SYNTH_ARG_B=abc
                    SYNTH_UUID=fe4d7c9d-b8c6-4a70-9ef1-3d8a58d18eed

On Sphinx, consecutive lines with the same indent belongs to the same
paragraph. So, without "::", the above will be displayed on a single line,
which is undesired.

using "::" tells Sphinx to display as-is. It will also place it into a a 
box (colored for html output) and using a monospaced font.

The change at the "uevent file:" line was done just for coherency
purposes.

Yet, after re-reading the text, there are other things that are not
coherent. So, I guess the enclosed patch will work better for sys-uevent.

Thanks,
Mauro

docs: ABI: sysfs-uevent: make it compatible with ReST output

- Replace " by ``, in order to use monospaced fonts;
- mark literal blocks as such.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

diff --git a/Documentation/ABI/testing/sysfs-uevent b/Documentation/ABI/testing/sysfs-uevent
index aa39f8d7bcdf..0b6227706b35 100644
--- a/Documentation/ABI/testing/sysfs-uevent
+++ b/Documentation/ABI/testing/sysfs-uevent
@@ -6,42 +6,46 @@ Description:
                 Enable passing additional variables for synthetic uevents that
                 are generated by writing /sys/.../uevent file.
 
-                Recognized extended format is ACTION [UUID [KEY=VALUE ...].
+                Recognized extended format is::
 
-                The ACTION is compulsory - it is the name of the uevent action
-                ("add", "change", "remove"). There is no change compared to
-                previous functionality here. The rest of the extended format
-                is optional.
+			ACTION [UUID [KEY=VALUE ...]
+
+                The ACTION is compulsory - it is the name of the uevent
+                action (``add``, ``change``, ``remove``). There is no change
+                compared to previous functionality here. The rest of the
+                extended format is optional.
 
                 You need to pass UUID first before any KEY=VALUE pairs.
-                The UUID must be in "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+                The UUID must be in ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx``
                 format where 'x' is a hex digit. The UUID is considered to be
                 a transaction identifier so it's possible to use the same UUID
                 value for one or more synthetic uevents in which case we
                 logically group these uevents together for any userspace
                 listeners. The UUID value appears in uevent as
-                "SYNTH_UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" environment
+                ``SYNTH_UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`` environment
                 variable.
 
                 If UUID is not passed in, the generated synthetic uevent gains
-                "SYNTH_UUID=0" environment variable automatically.
+                ``SYNTH_UUID=0`` environment variable automatically.
 
                 The KEY=VALUE pairs can contain alphanumeric characters only.
+
                 It's possible to define zero or more pairs - each pair is then
                 delimited by a space character ' '. Each pair appears in
-                synthetic uevent as "SYNTH_ARG_KEY=VALUE". That means the KEY
-                name gains "SYNTH_ARG_" prefix to avoid possible collisions
+                synthetic uevent as ``SYNTH_ARG_KEY=VALUE``. That means the KEY
+                name gains ``SYNTH_ARG_`` prefix to avoid possible collisions
                 with existing variables.
 
-                Example of valid sequence written to the uevent file:
+                Example of valid sequence written to the uevent file::
 
                     add fe4d7c9d-b8c6-4a70-9ef1-3d8a58d18eed A=1 B=abc
 
-                This generates synthetic uevent including these variables:
+                This generates synthetic uevent including these variables::
 
                     ACTION=add
                     SYNTH_ARG_A=1
                     SYNTH_ARG_B=abc
                     SYNTH_UUID=fe4d7c9d-b8c6-4a70-9ef1-3d8a58d18eed
+
 Users:
                 udev, userspace tools generating synthetic uevents

  reply index

Thread overview: 8+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
     [not found] <cover.1603893146.git.mchehab+huawei@kernel.org>
2020-10-28 14:23 ` [PATCH 26/33] docs: ABI: convert testing/configfs-acpi to ReST Mauro Carvalho Chehab
     [not found] ` <4ebaaa0320101479e392ce2db4b62e24fdf15ef1.1603893146.git.mchehab+huawei@kernel.org>
2020-10-28 17:44   ` [PATCH 20/33] docs: ABI: testing: make the files compatible with ReST output Richard Cochran
2020-10-29  7:21     ` Mauro Carvalho Chehab [this message]
2020-10-29 14:49   ` Jonathan Cameron
2020-10-30  7:11     ` Mauro Carvalho Chehab
2020-11-02 15:06   ` Gautham R Shenoy
     [not found] ` <95ef2cf3a58f4e50f17d9e58e0d9440ad14d0427.1603893146.git.mchehab+huawei@kernel.org>
2020-10-30  6:33   ` [PATCH 30/33] docs: ABI: cleanup several ABI documents Vaibhav Jain
2020-11-03 15:24   ` Bjorn Andersson

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20201029082100.4820072c@coco.lan \
    --to=mchehab+huawei@kernel.org \
    --cc=Jason@zx2c4.com \
    --cc=Thinh.Nguyen@synopsys.com \
    --cc=ajd@linux.ibm.com \
    --cc=alexander.shishkin@linux.intel.com \
    --cc=alexandre.belloni@bootlin.com \
    --cc=alexandre.torgue@st.com \
    --cc=andriy.shevchenko@linux.intel.com \
    --cc=axboe@kernel.dk \
    --cc=balbi@kernel.org \
    --cc=baolin.wang7@gmail.com \
    --cc=bleung@chromium.org \
    --cc=bmeneg@redhat.com \
    --cc=boris.ostrovsky@oracle.com \
    --cc=corbet@lwn.net \
    --cc=dan.j.williams@intel.com \
    --cc=dmurphy@ti.com \
    --cc=ego@linux.vnet.ibm.com \
    --cc=enric.balletbo@collabora.com \
    --cc=fabrice.gasnier@st.com \
    --cc=fbarrat@linux.ibm.com \
    --cc=felix@linux.ibm.com \
    --cc=gregkh@linuxfoundation.org \
    --cc=groeck@chromium.org \
    --cc=guohanjun@huawei.com \
    --cc=heikki.krogerus@linux.intel.com \
    --cc=javier@javigon.com \
    --cc=jgross@suse.com \
    --cc=jic23@kernel.org \
    --cc=johannes.thumshirn@wdc.com \
    --cc=koct9i@gmail.com \
    --cc=kranthi.kuntala@intel.com \
    --cc=lars@metafoo.de \
    --cc=lenb@kernel.org \
    --cc=leonmaxx@gmail.com \
    --cc=linux-acpi@vger.kernel.org \
    --cc=linux-arm-kernel@lists.infradead.org \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-iio@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-mm@kvack.org \
    --cc=linux-pm@vger.kernel.org \
    --cc=linux-stm32@st-md-mailman.stormreply.com \
    --cc=linux-usb@vger.kernel.org \
    --cc=linuxppc-dev@lists.ozlabs.org \
    --cc=ludovic.desroches@microchip.com \
    --cc=mario.limonciello@dell.com \
    --cc=martin.petersen@oracle.com \
    --cc=mchehab+samsung@kernel.org \
    --cc=mcoquelin.stm32@gmail.com \
    --cc=mika.westerberg@linux.intel.com \
    --cc=mike.kravetz@oracle.com \
    --cc=mpe@ellerman.id.au \
    --cc=nayna@linux.ibm.com \
    --cc=netdev@vger.kernel.org \
    --cc=nicolas.ferre@microchip.com \
    --cc=niklas.cassel@wdc.com \
    --cc=nramas@linux.microsoft.com \
    --cc=oleg@kaa.org.ua \
    --cc=orsonzhai@gmail.com \
    --cc=pavel@ucw.cz \
    --cc=pawan.kumar.gupta@linux.intel.com \
    --cc=peda@axentia.se \
    --cc=pmeerw@pmeerw.net \
    --cc=pmladek@suse.com \
    --cc=richardcochran@gmail.com \
    --cc=rjw@rjwysocki.net \
    --cc=sergey.senozhatsky@gmail.com \
    --cc=sre@kernel.org \
    --cc=sstabellini@kernel.org \
    --cc=tglx@linutronix.de \
    --cc=vineela.tummalapalli@intel.com \
    --cc=vishal.l.verma@intel.com \
    --cc=xen-devel@lists.xenproject.org \
    --cc=zhang.lyra@gmail.com \
    --cc=zohar@linux.ibm.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Linux-ACPI Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-acpi/0 linux-acpi/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-acpi linux-acpi/ https://lore.kernel.org/linux-acpi \
		linux-acpi@vger.kernel.org
	public-inbox-index linux-acpi

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.linux-acpi


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git