Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1645034 > unrolled thread

[PATCH 08/29] rfkill.txt: standardize document format

Back to article view | Back to linux.kernel

This discussion starts older than the indexed window; earlier articles aren't shown. The article labeled Started by below is the oldest one visible, not the original post.

Contents

  [PATCH 08/29] rfkill.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:30 +0200
    Re: [PATCH 08/29] rfkill.txt: standardize document format Johannes Berg <johannes@sipsolutions.net> - 2017-05-19 12:20 +0200
      Re: [PATCH 08/29] rfkill.txt: standardize document format Johannes Berg <johannes@sipsolutions.net> - 2017-05-19 13:20 +0200
      Re: [PATCH 08/29] rfkill.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 13:20 +0200

#1645034 — [PATCH 08/29] rfkill.txt: standardize document format

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

[toc] | [next] | [standalone]

#1645492

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

[toc] | [prev] | [next] | [standalone]

#1645521

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

[toc] | [prev] | [next] | [standalone]

#1645526

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

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web