[PATCH 00/30] Standardize doc formats - part 2

[PATCH 00/30] Standardize doc formats - part 2

[Mauro Carvalho Chehab]

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

Mauro Carvalho Chehab (30):
  iostats.txt: update it to cover recent Kernels
  IPMI.txt: standardize document format
  IRQ-affinity.txt: standardize document format
  IRQ-domain.txt: standardize document format
  irqflags-tracing.txt: standardize document format
  IRQ.txt: add a markup for its title
  isapnp.txt: promote title level
  isa.txt: standardize document format
  kernel-per-CPU-kthreads.txt: standardize document format
  kobject.txt: standardize document format
  kprobes.txt: standardize document format
  kref.txt: standardize document format
  kselftest.txt: standardize document format
  ldm.txt: standardize document format
  lockup-watchdogs.txt: standardize document format
  lzo.txt: standardize document format
  mailbox.txt: standardize document format
  memory-barriers.txt: standardize document format
  memory-barriers.txt: use literals for variables
  memory-hotplug.txt: standardize document format
  men-chameleon-bus.txt: standardize document format
  nommu-mmap.txt: standardize document format
  nommu-mmap.txt: don't use all upper case on titles
  ntb.txt: standardize document format
  numastat.txt: standardize document format
  padata.txt: standardize document format
  parport-lowlevel.txt: standardize document format
  percpu-rw-semaphore.txt: standardize document format
  phy.txt: standardize document format
  pi-futex.txt: standardize document format

 Documentation/IPMI.txt                    |   76 +-
 Documentation/IRQ-affinity.txt            |   77 +-
 Documentation/IRQ-domain.txt              |   69 +-
 Documentation/IRQ.txt                     |    2 +
 Documentation/iostats.txt                 |   44 +-
 Documentation/irqflags-tracing.txt        |   10 +-
 Documentation/isa.txt                     |   53 +-
 Documentation/isapnp.txt                  |    1 +
 Documentation/kernel-per-CPU-kthreads.txt |  156 +++-
 Documentation/kobject.txt                 |   69 +-
 Documentation/kprobes.txt                 |  450 ++++++----
 Documentation/kref.txt                    |  285 ++++---
 Documentation/kselftest.txt               |   37 +-
 Documentation/ldm.txt                     |   54 +-
 Documentation/lockup-watchdogs.txt        |    3 +-
 Documentation/lzo.txt                     |   27 +-
 Documentation/mailbox.txt                 |  181 ++--
 Documentation/memory-barriers.txt         |  794 +++++++++---------
 Documentation/memory-hotplug.txt          |  357 ++++----
 Documentation/men-chameleon-bus.txt       |  298 +++----
 Documentation/nommu-mmap.txt              |   68 +-
 Documentation/ntb.txt                     |   55 +-
 Documentation/numastat.txt                |    5 +-
 Documentation/padata.txt                  |   27 +-
 Documentation/parport-lowlevel.txt        | 1303 ++++++++++++++++++-----------
 Documentation/percpu-rw-semaphore.txt     |    3 +-
 Documentation/phy.txt                     |  106 ++-
 Documentation/pi-futex.txt                |   15 +-
 28 files changed, 2683 insertions(+), 1942 deletions(-)

-- 
2.9.4



------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot

[PATCH 26/30] padata.txt: standardize document format

[Mauro Carvalho Chehab]

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 document title;
- mark literal blocks.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/padata.txt | 27 +++++++++++++++------------
 1 file changed, 15 insertions(+), 12 deletions(-)

diff --git a/Documentation/padata.txt b/Documentation/padata.txt
index 7ddfe216a0aa..b103d0c82000 100644
--- a/Documentation/padata.txt
+++ b/Documentation/padata.txt
@@ -1,5 +1,8 @@
+=======================================
 The padata parallel execution mechanism
-Last updated for 2.6.36
+=======================================
+
+:Last updated: for 2.6.36
 
 Padata is a mechanism by which the kernel can farm work out to be done in
 parallel on multiple CPUs while retaining the ordering of tasks.  It was
@@ -9,7 +12,7 @@ those packets.  The crypto developers made a point of writing padata in a
 sufficiently general fashion that it could be put to other uses as well.
 
 The first step in using padata is to set up a padata_instance structure for
-overall control of how tasks are to be run:
+overall control of how tasks are to be run::
 
     #include <linux/padata.h>
 
@@ -24,7 +27,7 @@ The workqueue wq is where the work will actually be done; it should be
 a multithreaded queue, naturally.
 
 To allocate a padata instance with the cpu_possible_mask for both
-cpumasks this helper function can be used:
+cpumasks this helper function can be used::
 
     struct padata_instance *padata_alloc_possible(struct workqueue_struct *wq);
 
@@ -36,7 +39,7 @@ it is legal to supply a cpumask to padata that contains offline CPUs.
 Once an offline CPU in the user supplied cpumask comes online, padata
 is going to use it.
 
-There are functions for enabling and disabling the instance:
+There are functions for enabling and disabling the instance::
 
     int padata_start(struct padata_instance *pinst);
     void padata_stop(struct padata_instance *pinst);
@@ -48,7 +51,7 @@ padata cpumask contains no active CPU (flag not set).
 padata_stop clears the flag and blocks until the padata instance
 is unused.
 
-The list of CPUs to be used can be adjusted with these functions:
+The list of CPUs to be used can be adjusted with these functions::
 
     int padata_set_cpumasks(struct padata_instance *pinst,
 			    cpumask_var_t pcpumask,
@@ -71,12 +74,12 @@ padata_add_cpu/padata_remove_cpu are used. cpu specifies the CPU to add or
 remove and mask is one of PADATA_CPU_SERIAL, PADATA_CPU_PARALLEL.
 
 If a user is interested in padata cpumask changes, he can register to
-the padata cpumask change notifier:
+the padata cpumask change notifier::
 
     int padata_register_cpumask_notifier(struct padata_instance *pinst,
 					 struct notifier_block *nblock);
 
-To unregister from that notifier:
+To unregister from that notifier::
 
     int padata_unregister_cpumask_notifier(struct padata_instance *pinst,
 					   struct notifier_block *nblock);
@@ -84,7 +87,7 @@ To unregister from that notifier:
 The padata cpumask change notifier notifies about changes of the usable
 cpumasks, i.e. the subset of active CPUs in the user supplied cpumask.
 
-Padata calls the notifier chain with:
+Padata calls the notifier chain with::
 
     blocking_notifier_call_chain(&pinst->cpumask_change_notifier,
 				 notification_mask,
@@ -95,7 +98,7 @@ is one of PADATA_CPU_SERIAL, PADATA_CPU_PARALLEL and cpumask is a pointer
 to a struct padata_cpumask that contains the new cpumask information.
 
 Actually submitting work to the padata instance requires the creation of a
-padata_priv structure:
+padata_priv structure::
 
     struct padata_priv {
         /* Other stuff here... */
@@ -110,7 +113,7 @@ parallel() and serial() functions should be provided.  Those functions will
 be called in the process of getting the work done as we will see
 momentarily.
 
-The submission of work is done with:
+The submission of work is done with::
 
     int padata_do_parallel(struct padata_instance *pinst,
 		           struct padata_priv *padata, int cb_cpu);
@@ -138,7 +141,7 @@ need not be completed during this call, but, if parallel() leaves work
 outstanding, it should be prepared to be called again with a new job before
 the previous one completes.  When a task does complete, parallel() (or
 whatever function actually finishes the job) should inform padata of the
-fact with a call to:
+fact with a call to::
 
     void padata_do_serial(struct padata_priv *padata);
 
@@ -151,7 +154,7 @@ pains to ensure that tasks are completed in the order in which they were
 submitted.
 
 The one remaining function in the padata API should be called to clean up
-when a padata instance is no longer needed:
+when a padata instance is no longer needed::
 
     void padata_free(struct padata_instance *pinst);
 
-- 
2.9.4