linux-wireless.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [PATCH 00/29] Standardize doc formats - part 3
@ 2017-05-19  1:25 Mauro Carvalho Chehab
  2017-05-19  1:25 ` [PATCH 08/29] rfkill.txt: standardize document format Mauro Carvalho Chehab
  0 siblings, 1 reply; 5+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19  1:25 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
	Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd,
	Alessandro Zummo, dri-devel, Bjorn Andersson, Alex Williamson,
	linux-pwm, linux-remoteproc, Thomas Gleixner, Ingo Molnar, kvm,
	Thierry Reding, Linus Walleij, kpreempt-tech, Darren Hart,
	rtc-linux, linux-gpio, Martin Mares, Robert Love, Kirti Wankhede,
	Gustavo Padovan, Peter Zijlstra, Alexandre Belloni,
	linux-wireless, Ohad Ben-Cohen, Johannes Berg, linux-video,
	Sumit Semwal

Each document under Documentation/*.txt has its own format.
Some follow markup notations, some don't even have a title!

In order to try to get some order on it, change the document
style to the standard we're adopting after the adoption of
ReStructured Text.

The documents touched on this series now build fine with
Sphinx, if renamed to *.rst extension.

The main goal with this is to teach people by example about
what format is expected on newer documents. It also helps
to add those files to Kernel books.

In order to make things more palatable, I'm spliting the
conversion into three parts.

This is	part 3.

Mauro Carvalho Chehab (29):
  pinctrl.txt: standardize document format
  pnp.txt: standardize document format
  preempt-locking.txt: standardize document format
  printk-formats.txt: standardize document format
  pwm.txt: standardize document format
  rbtree.txt: standardize document format
  remoteproc.txt: standardize document format
  rfkill.txt: standardize document format
  robust-futex-ABI.txt: standardize document format
  robust-futexes.txt: standardize document format
  rpmsg.txt: standardize document format
  rtc.txt: standardize document format
  SAK.txt: standardize document format
  sgi-ioc4.txt: standardize document format
  siphash.txt: standardize document format
  SM501.txt: standardize document format
  smsc_ece1099.txt: standardize document format
  static-keys.txt: standardize document format
  svga.txt: standardize document format
  sync_file.txt: standardize document format
  this_cpu_ops.txt: standardize document format
  unaligned-memory-access.txt: standardize document format
  vfio-mediated-device.txt: standardize document format
  vfio.txt: standardize document format
  video-output.txt: standardize document format
  xillybus.txt: standardize document format
  xz.txt: standardize document format
  zorro.txt: standardize document format
  dell_rbu.txt: standardize document format

 Documentation/SAK.txt                     |   65 +-
 Documentation/SM501.txt                   |    9 +-
 Documentation/dell_rbu.txt                |   81 ++-
 Documentation/pinctrl.txt                 | 1104 +++++++++++++++--------------
 Documentation/pnp.txt                     |  343 +++++----
 Documentation/preempt-locking.txt         |   40 +-
 Documentation/printk-formats.txt          |  416 ++++++-----
 Documentation/pwm.txt                     |   46 +-
 Documentation/rbtree.txt                  |   88 +--
 Documentation/remoteproc.txt              |  320 +++++----
 Documentation/rfkill.txt                  |   47 +-
 Documentation/robust-futex-ABI.txt        |   14 +-
 Documentation/robust-futexes.txt          |   12 +-
 Documentation/rpmsg.txt                   |  340 +++++----
 Documentation/rtc.txt                     |   44 +-
 Documentation/sgi-ioc4.txt                |    4 +
 Documentation/siphash.txt                 |  186 ++---
 Documentation/smsc_ece1099.txt            |    4 +
 Documentation/static-keys.txt             |  199 +++---
 Documentation/svga.txt                    |  146 ++--
 Documentation/sync_file.txt               |   23 +-
 Documentation/this_cpu_ops.txt            |   49 +-
 Documentation/unaligned-memory-access.txt |   57 +-
 Documentation/vfio-mediated-device.txt    |  252 +++----
 Documentation/vfio.txt                    |  261 +++----
 Documentation/video-output.txt            |   54 +-
 Documentation/xillybus.txt                |   29 +-
 Documentation/xz.txt                      |  182 ++---
 Documentation/zorro.txt                   |   59 +-
 29 files changed, 2437 insertions(+), 2037 deletions(-)

-- 
2.9.4

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

* [PATCH 08/29] rfkill.txt: standardize document format
  2017-05-19  1:25 [PATCH 00/29] Standardize doc formats - part 3 Mauro Carvalho Chehab
@ 2017-05-19  1:25 ` Mauro Carvalho Chehab
  2017-05-19 10:15   ` Johannes Berg
  0 siblings, 1 reply; 5+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19  1:25 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
	Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd,
	Johannes Berg, linux-wireless

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- mark titles;
- comment contents index;
- mark literal blocks;
- adjust identation.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/rfkill.txt | 47 ++++++++++++++++++++++++++++++-----------------
 1 file changed, 30 insertions(+), 17 deletions(-)

diff --git a/Documentation/rfkill.txt b/Documentation/rfkill.txt
index 8c174063b3f0..d22feccedbd1 100644
--- a/Documentation/rfkill.txt
+++ b/Documentation/rfkill.txt
@@ -1,13 +1,17 @@
+===============================
 rfkill - RF kill switch support
 ===============================
 
-1. Introduction
-2. Implementation details
-3. Kernel API
-4. Userspace support
+.. CONTENTS
 
+  1. Introduction
+  2. Implementation details
+  3. Kernel API
+  4. Userspace support
 
-1. Introduction
+
+Introduction
+============
 
 The rfkill subsystem provides a generic interface to disabling any radio
 transmitter in the system. When a transmitter is blocked, it shall not
@@ -21,17 +25,24 @@ aircraft.
 The rfkill subsystem has a concept of "hard" and "soft" block, which
 differ little in their meaning (block == transmitters off) but rather in
 whether they can be changed or not:
- - hard block: read-only radio block that cannot be overridden by software
- - soft block: writable radio block (need not be readable) that is set by
-               the system software.
+
+ - hard block
+	read-only radio block that cannot be overridden by software
+
+ - soft block
+	writable radio block (need not be readable) that is set by
+        the system software.
 
 The rfkill subsystem has two parameters, rfkill.default_state and
-rfkill.master_switch_mode, which are documented in admin-guide/kernel-parameters.rst.
+rfkill.master_switch_mode, which are documented in
+admin-guide/kernel-parameters.rst.
 
 
-2. Implementation details
+Implementation details
+======================
 
 The rfkill subsystem is composed of three main components:
+
  * the rfkill core,
  * the deprecated rfkill-input module (an input layer handler, being
    replaced by userspace policy code) and
@@ -55,7 +66,8 @@ use the return value of rfkill_set_hw_state() unless the hardware actually
 keeps track of soft and hard block separately.
 
 
-3. Kernel API
+Kernel API
+==========
 
 
 Drivers for radio transmitters normally implement an rfkill driver.
@@ -69,7 +81,7 @@ For some platforms, it is possible that the hardware state changes during
 suspend/hibernation, in which case it will be necessary to update the rfkill
 core with the current state is at resume time.
 
-To create an rfkill driver, driver's Kconfig needs to have
+To create an rfkill driver, driver's Kconfig needs to have::
 
 	depends on RFKILL || !RFKILL
 
@@ -87,7 +99,8 @@ RFKill provides per-switch LED triggers, which can be used to drive LEDs
 according to the switch state (LED_FULL when blocked, LED_OFF otherwise).
 
 
-5. Userspace support
+Userspace support
+=================
 
 The recommended userspace interface to use is /dev/rfkill, which is a misc
 character device that allows userspace to obtain and set the state of rfkill
@@ -112,11 +125,11 @@ rfkill core framework.
 Additionally, each rfkill device is registered in sysfs and emits uevents.
 
 rfkill devices issue uevents (with an action of "change"), with the following
-environment variables set:
+environment variables set::
 
-RFKILL_NAME
-RFKILL_STATE
-RFKILL_TYPE
+	RFKILL_NAME
+	RFKILL_STATE
+	RFKILL_TYPE
 
 The contents of these variables corresponds to the "name", "state" and
 "type" sysfs files explained above.
-- 
2.9.4

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

* Re: [PATCH 08/29] rfkill.txt: standardize document format
  2017-05-19  1:25 ` [PATCH 08/29] rfkill.txt: standardize document format Mauro Carvalho Chehab
@ 2017-05-19 10:15   ` Johannes Berg
  2017-05-19 11:11     ` Mauro Carvalho Chehab
  0 siblings, 1 reply; 5+ messages in thread
From: Johannes Berg @ 2017-05-19 10:15 UTC (permalink / raw)
  To: Mauro Carvalho Chehab, Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
	David Woodhouse, Brian Norris, Boris Brezillon, Marek Vasut,
	Richard Weinberger, Cyrille Pitchen, linux-mtd, linux-wireless

On Thu, 2017-05-18 at 22:25 -0300, Mauro Carvalho Chehab wrote:
> 
> +.. CONTENTS
>  
> +  1. Introduction
> +  2. Implementation details
> +  3. Kernel API
> +  4. Userspace support

Why not let this be auto-generated?

.. contents::
   :depth: 1

should work, no?

johannes

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

* Re: [PATCH 08/29] rfkill.txt: standardize document format
  2017-05-19 10:15   ` Johannes Berg
@ 2017-05-19 11:11     ` Mauro Carvalho Chehab
  2017-05-19 11:16       ` Johannes Berg
  0 siblings, 1 reply; 5+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 11:11 UTC (permalink / raw)
  To: Johannes Berg
  Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
	Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd,
	linux-wireless

Em Fri, 19 May 2017 12:15:01 +0200
Johannes Berg <johannes@sipsolutions.net> escreveu:

> On Thu, 2017-05-18 at 22:25 -0300, Mauro Carvalho Chehab wrote:
> > 
> > +.. CONTENTS
> >  
> > +  1. Introduction
> > +  2. Implementation details
> > +  3. Kernel API
> > +  4. Userspace support  
> 
> Why not let this be auto-generated?
> 
> .. contents::
>    :depth: 1
> 
> should work, no?

Yes, it should work. Actually, you would need to use :depth: 2 to
produce this output:


	Contents

	    . rfkill - RF kill switch support
	        . Introduction
	        . Implementation details
	        . Kernel API
	        . Userspace support

I opted to keep the contents as a comment just because, in the past, some
maintainers complained about TOC removal, arguing that it makes harder
for the ones that would be reading the file in ascii.

Thanks,
Mauro

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

* Re: [PATCH 08/29] rfkill.txt: standardize document format
  2017-05-19 11:11     ` Mauro Carvalho Chehab
@ 2017-05-19 11:16       ` Johannes Berg
  0 siblings, 0 replies; 5+ messages in thread
From: Johannes Berg @ 2017-05-19 11:16 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
	Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd,
	linux-wireless

On Fri, 2017-05-19 at 08:11 -0300, Mauro Carvalho Chehab wrote:
> 
> Yes, it should work. Actually, you would need to use :depth: 2 to
> produce this output:
> 
> 
> 	Contents
> 
> 	    . rfkill - RF kill switch support
> 	        . Introduction
> 	        . Implementation details
> 	        . Kernel API
> 	        . Userspace support

Sounds good to me.

> I opted to keep the contents as a comment just because, in the past,
> some maintainers complained about TOC removal, arguing that it makes
> harder for the ones that would be reading the file in ascii.

Ok. I don't really care much either way, I guess. The file is short
enough that the TOC isn't all that important to start with.

johannes

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

end of thread, other threads:[~2017-05-19 11:17 UTC | newest]

Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-05-19  1:25 [PATCH 00/29] Standardize doc formats - part 3 Mauro Carvalho Chehab
2017-05-19  1:25 ` [PATCH 08/29] rfkill.txt: standardize document format Mauro Carvalho Chehab
2017-05-19 10:15   ` Johannes Berg
2017-05-19 11:11     ` Mauro Carvalho Chehab
2017-05-19 11:16       ` Johannes Berg

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).