[PATCH v2 00/20] Create a book for Kernel development

[PATCH v2 00/20] Create a book for Kernel development

[Mauro Carvalho Chehab]

There are several documents related to Kernel development, where the
HOWTO working like an index to most of them. There are also a series
of files describing the development process.

Convert the documents mentioned at the HOWTO (including it) and the
development-process/ documents to ReST and add them at the Sphinx build.

NOTE: HOWTO also mentions the /README document on it. While IMHO it 
makes sense to convert it to ReST, moving it out of the main directory 
didn't sound a good idea. So, I'm leaving this one untouched.

PS.: I decided to do such conversion because today I received yet 
another email from one developer wanted to submit drivers, but not being 
aware of the right proceures. As usual, I pointed him to the Kernel 
sources, but there are a way too much documentation there with a mix of 
procedures and API docs inside.

It would be a way easier to point to a single URL where the submission 
procedures would be altoghether. Hopefully, this will have a lot of time 
in the future. My evil plan is to put this doc somewhere at LinuxTV and 
have a standard e-mail prepared for such next requests :-D

The produced output, in HTML, is at:
	https://mchehab.fedorapeople.org/development-process/

The LaTeX version at:
	https://mchehab.fedorapeople.org/development-process/latex/development-process.tex

And the PDF version at:
	https://mchehab.fedorapeople.org/development-process/latex/development-process.pdf


--

Version 2 changes:

- On version 1, I forgot to c/c LKML;
- Per Jonathan Corbet's suggestion, this version is placing all documents at
  the already existing developing-process/ directory, instead of creating a
  new dir;
- Also per Jon's suggestion, it also converts the development-process files
  to rst.
- Replaced all occurrences of the renamed files at the Kernel Documentation dir;
- Added conf.py and the need logic to produce both LaTeX and PDF output;

Mauro Carvalho Chehab (20):
  docs-rst: move HOWTO and mentioned documents to a separate dir
  docs-rst: HOWTO.rst: convert to ReST notation
  docs-rst: applying-patches.rst: convert it to ReST markup
  docs-rst: Changes.rst: convert it to ReST markup
  docs-rst: CodingStyle.rst: Convert to ReST markup
  CodingStyle.rst: use the proper tag for verbatim font
  CodingStyle.rst: replace underline markups
  CodingStyle.rst: use the .. note:: markup where needed
  kernel-docs.rst: convert it to ReST markup
  ManagementStyle.rst: convert it to ReST markup
  SecurityBugs.rst: convert it to ReST markup
  stable_api_nonsense.rst: convert it to ReST markup
  stable_kernel_rules.rst: convert it to ReST markup
  SubmittingDrivers.rst: convert it to ReST markup
  SubmittingPatches.rst: convert it to ReST markup
  HOWTO.rst: add cross-references to other documents
  doc: development-process: rename files to rst
  doc: development-process: convert it to ReST markup
  doc: adjust references to development-process
  doc: Add the development-process to Sphinx build

 Documentation/ABI/README                           |   2 +-
 Documentation/BUG-HUNTING                          |   2 +-
 Documentation/DocBook/kernel-hacking.tmpl          |   4 +-
 Documentation/SubmitChecklist                      |   4 +-
 Documentation/adding-syscalls.txt                  |   2 +-
 Documentation/conf.py                              |   2 +
 .../development-process/{1.Intro => 1.Intro.rst}   |  68 +-
 .../{2.Process => 2.Process.rst}                   |  41 +-
 .../{3.Early-stage => 3.Early-stage.rst}           |  22 +-
 .../development-process/{4.Coding => 4.Coding.rst} |  48 +-
 .../{5.Posting => 5.Posting.rst}                   |  30 +-
 .../{6.Followthrough => 6.Followthrough.rst}       |  14 +-
 .../{7.AdvancedTopics => 7.AdvancedTopics.rst}     |  13 +-
 .../{8.Conclusion => 8.Conclusion.rst}             |   8 +-
 .../{Changes => development-process/Changes.rst}   | 226 +++---
 .../CodingStyle.rst}                               | 384 ++++++----
 .../{HOWTO => development-process/HOWTO.rst}       |  73 +-
 .../ManagementStyle.rst}                           | 152 ++--
 .../SecurityBugs.rst}                              |  14 +-
 .../SubmittingDrivers.rst}                         |  51 +-
 .../SubmittingPatches.rst}                         | 244 ++++---
 .../applying-patches.rst}                          | 312 ++++----
 Documentation/development-process/conf.py          |  10 +
 .../development-process/development-process.rst    |  27 +
 Documentation/development-process/index.rst        |  31 +
 Documentation/development-process/kernel-docs.rst  | 791 +++++++++++++++++++++
 .../stable_api_nonsense.rst}                       |  35 +-
 .../stable_kernel_rules.rst}                       | 107 ++-
 .../devicetree/bindings/submitting-patches.txt     |   2 +-
 Documentation/filesystems/locks.txt                |   2 +-
 Documentation/hwmon/submitting-patches             |   6 +-
 Documentation/index.rst                            |   1 +
 Documentation/isdn/README                          |   2 +-
 Documentation/ja_JP/HOWTO                          |  28 +-
 Documentation/ja_JP/SubmitChecklist                |   2 +-
 Documentation/ja_JP/SubmittingPatches              |  14 +-
 Documentation/ja_JP/stable_api_nonsense.txt        |   4 +-
 Documentation/ja_JP/stable_kernel_rules.txt        |   6 +-
 Documentation/kernel-docs.txt                      | 731 -------------------
 Documentation/ko_KR/HOWTO                          |  28 +-
 Documentation/ko_KR/stable_api_nonsense.txt        |   4 +-
 Documentation/networking/PLIP.txt                  |   2 +-
 Documentation/networking/netdev-FAQ.txt            |   8 +-
 Documentation/scsi/scsi_mid_low_api.txt            |   2 +-
 Documentation/virtual/kvm/review-checklist.txt     |   4 +-
 .../watchdog/convert_drivers_to_kernel_api.txt     |   2 +-
 Documentation/zh_CN/CodingStyle                    |   4 +-
 Documentation/zh_CN/HOWTO                          |  28 +-
 Documentation/zh_CN/SecurityBugs                   |   4 +-
 Documentation/zh_CN/SubmittingDrivers              |   8 +-
 Documentation/zh_CN/SubmittingPatches              |  10 +-
 Documentation/zh_CN/stable_api_nonsense.txt        |   4 +-
 Documentation/zh_CN/stable_kernel_rules.txt        |   6 +-
 MAINTAINERS                                        |   2 +-
 README                                             |   4 +-
 REPORTING-BUGS                                     |   2 +-
 drivers/net/ppp/Kconfig                            |   2 +-
 drivers/pcmcia/Kconfig                             |   2 +-
 fs/Kconfig.binfmt                                  |   2 +-
 fs/fuse/Kconfig                                    |   2 +-
 net/Kconfig                                        |   4 +-
 scripts/ver_linux                                  |   2 +-
 tools/testing/selftests/futex/README               |   2 +-
 63 files changed, 2129 insertions(+), 1524 deletions(-)
 rename Documentation/development-process/{1.Intro => 1.Intro.rst} (87%)
 rename Documentation/development-process/{2.Process => 2.Process.rst} (96%)
 rename Documentation/development-process/{3.Early-stage => 3.Early-stage.rst} (97%)
 rename Documentation/development-process/{4.Coding => 4.Coding.rst} (97%)
 rename Documentation/development-process/{5.Posting => 5.Posting.rst} (96%)
 rename Documentation/development-process/{6.Followthrough => 6.Followthrough.rst} (98%)
 rename Documentation/development-process/{7.AdvancedTopics => 7.AdvancedTopics.rst} (98%)
 rename Documentation/development-process/{8.Conclusion => 8.Conclusion.rst} (96%)
 rename Documentation/{Changes => development-process/Changes.rst} (56%)
 rename Documentation/{CodingStyle => development-process/CodingStyle.rst} (78%)
 rename Documentation/{HOWTO => development-process/HOWTO.rst} (96%)
 rename Documentation/{ManagementStyle => development-process/ManagementStyle.rst} (76%)
 rename Documentation/{SecurityBugs => development-process/SecurityBugs.rst} (92%)
 rename Documentation/{SubmittingDrivers => development-process/SubmittingDrivers.rst} (83%)
 rename Documentation/{SubmittingPatches => development-process/SubmittingPatches.rst} (85%)
 rename Documentation/{applying-patches.txt => development-process/applying-patches.rst} (68%)
 create mode 100644 Documentation/development-process/conf.py
 create mode 100644 Documentation/development-process/development-process.rst
 create mode 100644 Documentation/development-process/index.rst
 create mode 100644 Documentation/development-process/kernel-docs.rst
 rename Documentation/{stable_api_nonsense.txt => development-process/stable_api_nonsense.rst} (92%)
 rename Documentation/{stable_kernel_rules.txt => development-process/stable_kernel_rules.rst} (65%)
 delete mode 100644 Documentation/kernel-docs.txt

-- 
2.7.4

[PATCH v2 01/20] docs-rst: move HOWTO and mentioned documents to a separate dir

[Mauro Carvalho Chehab]

In preparation to convert the Kernel development documentation
to ReST, move them to a separate dir and rename their extension
to RST.

Please notice that the main README file was not moved. It
probably makes sense to move it too as well, in order to be
able to parse it via Sphinx, but this could be counter-intuitive.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/{Changes => development-process/Changes.rst}                | 0
 Documentation/{CodingStyle => development-process/CodingStyle.rst}        | 0
 Documentation/{HOWTO => development-process/HOWTO.rst}                    | 0
 .../{ManagementStyle => development-process/ManagementStyle.rst}          | 0
 Documentation/{SecurityBugs => development-process/SecurityBugs.rst}      | 0
 .../{SubmittingDrivers => development-process/SubmittingDrivers.rst}      | 0
 .../{SubmittingPatches => development-process/SubmittingPatches.rst}      | 0
 .../{applying-patches.txt => development-process/applying-patches.rst}    | 0
 Documentation/{kernel-docs.txt => development-process/kernel-docs.rst}    | 0
 .../stable_api_nonsense.rst}                                              | 0
 .../stable_kernel_rules.rst}                                              | 0
 11 files changed, 0 insertions(+), 0 deletions(-)
 rename Documentation/{Changes => development-process/Changes.rst} (100%)
 rename Documentation/{CodingStyle => development-process/CodingStyle.rst} (100%)
 rename Documentation/{HOWTO => development-process/HOWTO.rst} (100%)
 rename Documentation/{ManagementStyle => development-process/ManagementStyle.rst} (100%)
 rename Documentation/{SecurityBugs => development-process/SecurityBugs.rst} (100%)
 rename Documentation/{SubmittingDrivers => development-process/SubmittingDrivers.rst} (100%)
 rename Documentation/{SubmittingPatches => development-process/SubmittingPatches.rst} (100%)
 rename Documentation/{applying-patches.txt => development-process/applying-patches.rst} (100%)
 rename Documentation/{kernel-docs.txt => development-process/kernel-docs.rst} (100%)
 rename Documentation/{stable_api_nonsense.txt => development-process/stable_api_nonsense.rst} (100%)
 rename Documentation/{stable_kernel_rules.txt => development-process/stable_kernel_rules.rst} (100%)

diff --git a/Documentation/Changes b/Documentation/development-process/Changes.rst
similarity index 100%
rename from Documentation/Changes
rename to Documentation/development-process/Changes.rst
diff --git a/Documentation/CodingStyle b/Documentation/development-process/CodingStyle.rst
similarity index 100%
rename from Documentation/CodingStyle
rename to Documentation/development-process/CodingStyle.rst
diff --git a/Documentation/HOWTO b/Documentation/development-process/HOWTO.rst
similarity index 100%
rename from Documentation/HOWTO
rename to Documentation/development-process/HOWTO.rst
diff --git a/Documentation/ManagementStyle b/Documentation/development-process/ManagementStyle.rst
similarity index 100%
rename from Documentation/ManagementStyle
rename to Documentation/development-process/ManagementStyle.rst
diff --git a/Documentation/SecurityBugs b/Documentation/development-process/SecurityBugs.rst
similarity index 100%
rename from Documentation/SecurityBugs
rename to Documentation/development-process/SecurityBugs.rst
diff --git a/Documentation/SubmittingDrivers b/Documentation/development-process/SubmittingDrivers.rst
similarity index 100%
rename from Documentation/SubmittingDrivers
rename to Documentation/development-process/SubmittingDrivers.rst
diff --git a/Documentation/SubmittingPatches b/Documentation/development-process/SubmittingPatches.rst
similarity index 100%
rename from Documentation/SubmittingPatches
rename to Documentation/development-process/SubmittingPatches.rst
diff --git a/Documentation/applying-patches.txt b/Documentation/development-process/applying-patches.rst
similarity index 100%
rename from Documentation/applying-patches.txt
rename to Documentation/development-process/applying-patches.rst
diff --git a/Documentation/kernel-docs.txt b/Documentation/development-process/kernel-docs.rst
similarity index 100%
rename from Documentation/kernel-docs.txt
rename to Documentation/development-process/kernel-docs.rst
diff --git a/Documentation/stable_api_nonsense.txt b/Documentation/development-process/stable_api_nonsense.rst
similarity index 100%
rename from Documentation/stable_api_nonsense.txt
rename to Documentation/development-process/stable_api_nonsense.rst
diff --git a/Documentation/stable_kernel_rules.txt b/Documentation/development-process/stable_kernel_rules.rst
similarity index 100%
rename from Documentation/stable_kernel_rules.txt
rename to Documentation/development-process/stable_kernel_rules.rst
-- 
2.7.4

[PATCH v2 02/20] docs-rst: HOWTO.rst: convert to ReST notation

[Mauro Carvalho Chehab]

This document is almost compiant with ReST notation, but some
small adjustments are needed to make it parse properly by
Sphinx (mostly, add blank lines where needed).

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/development-process/HOWTO.rst | 53 ++++++++++++++++++++++++++---
 1 file changed, 49 insertions(+), 4 deletions(-)

diff --git a/Documentation/development-process/HOWTO.rst b/Documentation/development-process/HOWTO.rst
index 1f345da28ec5..5a85e3a8112b 100644
--- a/Documentation/development-process/HOWTO.rst
+++ b/Documentation/development-process/HOWTO.rst
@@ -1,5 +1,5 @@
 HOWTO do Linux kernel development
----------------------------------
+=================================
 
 This is the be-all, end-all document on this topic.  It contains
 instructions on how to become a Linux kernel developer and how to learn
@@ -28,6 +28,7 @@ kernel development.  Assembly (any architecture) is not required unless
 you plan to do low-level development for that architecture.  Though they
 are not a good substitute for a solid C education and/or years of
 experience, the following books are good for, if anything, reference:
+
  - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall]
  - "Practical C Programming" by Steve Oualline [O'Reilly]
  - "C:  A Reference Manual" by Harbison and Steele [Prentice Hall]
@@ -64,6 +65,7 @@ people on the mailing lists are not lawyers, and you should not rely on
 their statements on legal matters.
 
 For common questions and answers about the GPL, please see:
+
 	http://www.gnu.org/licenses/gpl-faq.html
 
 
@@ -82,6 +84,7 @@ linux-api@vger.kernel.org.
 
 Here is a list of files that are in the kernel source tree that are
 required reading:
+
   README
     This file gives a short background on the Linux kernel and describes
     what is necessary to do to configure and build the kernel.  People
@@ -99,30 +102,37 @@ required reading:
     patches if these rules are followed, and many people will only
     review code if it is in the proper style.
 
-  Documentation/SubmittingPatches
-  Documentation/SubmittingDrivers
+  Documentation/SubmittingPatches and Documentation/SubmittingDrivers
     These files describe in explicit detail how to successfully create
     and send a patch, including (but not limited to):
+
        - Email contents
        - Email format
        - Who to send it to
+
     Following these rules will not guarantee success (as all patches are
     subject to scrutiny for content and style), but not following them
     will almost always prevent it.
 
     Other excellent descriptions of how to create patches properly are:
+
 	"The Perfect Patch"
+
 		http://www.ozlabs.org/~akpm/stuff/tpp.txt
+
 	"Linux kernel patch submission format"
+
 		http://linux.yyz.us/patch-format.html
 
   Documentation/stable_api_nonsense.txt
     This file describes the rationale behind the conscious decision to
     not have a stable API within the kernel, including things like:
+
       - Subsystem shim-layers (for compatibility?)
       - Driver portability between Operating Systems.
       - Mitigating rapid change within the kernel source tree (or
 	preventing rapid change)
+
     This document is crucial for understanding the Linux development
     philosophy and is very important for people moving to Linux from
     development on other Operating Systems.
@@ -159,10 +169,14 @@ full description of the in-kernel API, and rules on how to handle
 locking properly.  The documents will be created in the
 Documentation/DocBook/ directory and can be generated as PDF,
 Postscript, HTML, and man pages by running:
+
+::
+
 	make pdfdocs
 	make psdocs
 	make htmldocs
 	make mandocs
+
 respectively from the main kernel source directory.
 
 
@@ -171,7 +185,9 @@ Becoming A Kernel Developer
 
 If you do not know anything about Linux kernel development, you should
 look at the Linux KernelNewbies project:
+
 	http://kernelnewbies.org
+
 It consists of a helpful mailing list where you can ask almost any type
 of basic kernel development question (make sure to search the archives
 first, before asking something that has already been answered in the
@@ -187,7 +203,9 @@ apply a patch.
 If you do not know where you want to start, but you want to look for
 some task to start doing to join into the kernel development community,
 go to the Linux Kernel Janitor's project:
+
 	http://kernelnewbies.org/KernelJanitors
+
 It is a great place to start.  It describes a list of relatively simple
 problems that need to be cleaned up and fixed within the Linux kernel
 source tree.  Working with the developers in charge of this project, you
@@ -199,6 +217,7 @@ If you already have a chunk of code that you want to put into the kernel
 tree, but need some help getting it in the proper form, the
 kernel-mentors project was created to help you out with this.  It is a
 mailing list, and can be found at:
+
 	http://selenic.com/mailman/listinfo/kernel-mentors
 
 Before making any actual modifications to the Linux kernel code, it is
@@ -209,6 +228,7 @@ tools.  One such tool that is particularly recommended is the Linux
 Cross-Reference project, which is able to present source code in a
 self-referential, indexed webpage format. An excellent up-to-date
 repository of the kernel code may be found at:
+
 	http://lxr.free-electrons.com/
 
 
@@ -218,6 +238,7 @@ The development process
 Linux kernel development process currently consists of a few different
 main kernel "branches" and lots of different subsystem-specific kernel
 branches.  These different branches are:
+
   - main 4.x kernel tree
   - 4.x.y -stable kernel tree
   - 4.x -git kernel patches
@@ -229,6 +250,7 @@ branches.  These different branches are:
 4.x kernels are maintained by Linus Torvalds, and can be found on
 kernel.org in the pub/linux/kernel/v4.x/ directory.  Its development
 process is as follows:
+
   - As soon as a new kernel is released a two weeks window is open,
     during this period of time maintainers can submit big diffs to
     Linus, usually the patches that have already been included in the
@@ -253,6 +275,9 @@ process is as follows:
 
 It is worth mentioning what Andrew Morton wrote on the linux-kernel
 mailing list about kernel releases:
+
+::
+
 	"Nobody knows when a kernel will be released, because it's
 	released according to perceived bug status, not according to a
 	preconceived timeline."
@@ -318,6 +343,7 @@ Before updates from subsystem trees are merged into the mainline 4.x
 tree, they need to be integration-tested.  For this purpose, a special
 testing repository exists into which virtually all subsystem trees are
 pulled on an almost daily basis:
+
 	http://git.kernel.org/?p=linux/kernel/git/next/linux-next.git
 
 This way, the -next kernel gives a summary outlook onto what will be
@@ -331,6 +357,7 @@ Bug Reporting
 bugzilla.kernel.org is where the Linux kernel developers track kernel
 bugs.  Users are encouraged to report all bugs that they find in this
 tool.  For details on how to use the kernel bugzilla, please see:
+
 	http://bugzilla.kernel.org/page.cgi?id=faq.html
 
 The file REPORTING-BUGS in the main kernel source directory has a good
@@ -365,10 +392,14 @@ Mailing lists
 As some of the above documents describe, the majority of the core kernel
 developers participate on the Linux Kernel Mailing list.  Details on how
 to subscribe and unsubscribe from the list can be found at:
+
 	http://vger.kernel.org/vger-lists.html#linux-kernel
+
 There are archives of the mailing list on the web in many different
 places.  Use a search engine to find these archives.  For example:
+
 	http://dir.gmane.org/gmane.linux.kernel
+
 It is highly recommended that you search the archives about the topic
 you want to bring up, before you post it to the list. A lot of things
 already discussed in detail are only recorded at the mailing list
@@ -381,11 +412,13 @@ groups.
 
 Many of the lists are hosted on kernel.org. Information on them can be
 found at:
+
 	http://vger.kernel.org/vger-lists.html
 
 Please remember to follow good behavioral habits when using the lists.
 Though a bit cheesy, the following URL has some simple guidelines for
 interacting with the list (or any list):
+
 	http://www.albion.com/netiquette/
 
 If multiple people respond to your mail, the CC: list of recipients may
@@ -418,6 +451,7 @@ The goal of the kernel community is to provide the best possible kernel
 there is.  When you submit a patch for acceptance, it will be reviewed
 on its technical merits and those alone.  So, what should you be
 expecting?
+
   - criticism
   - comments
   - requests for change
@@ -432,6 +466,7 @@ If there are no responses to your posting, wait a few days and try
 again, sometimes things get lost in the huge volume.
 
 What should you not do?
+
   - expect your patch to be accepted without question
   - become defensive
   - ignore comments
@@ -457,7 +492,9 @@ Differences between the kernel community and corporate structures
 The kernel community works differently than most traditional corporate
 development environments.  Here are a list of things that you can try to
 do to avoid problems:
+
   Good things to say regarding your proposed changes:
+
     - "This solves multiple problems."
     - "This deletes 2000 lines of code."
     - "Here is a patch that explains what I am trying to describe."
@@ -466,6 +503,7 @@ do to avoid problems:
     - "This increases performance on typical machines..."
 
   Bad things you should avoid saying:
+
     - "We did it this way in AIX/ptx/Solaris, so therefore it must be
       good..."
     - "I've being doing this for 20 years, so..."
@@ -527,12 +565,15 @@ The reasons for breaking things up are the following:
    and simplify (or simply re-order) patches before submitting them.
 
 Here is an analogy from kernel developer Al Viro:
+
+::
+
 	"Think of a teacher grading homework from a math student.  The
 	teacher does not want to see the student's trials and errors
 	before they came up with the solution. They want to see the
 	cleanest, most elegant answer.  A good student knows this, and
 	would never submit her intermediate work before the final
-	solution."
+	solution.
 
 	The same is true of kernel development. The maintainers and
 	reviewers do not want to see the thought process behind the
@@ -565,6 +606,7 @@ When sending in your patches, pay special attention to what you say in
 the text in your email.  This information will become the ChangeLog
 information for the patch, and will be preserved for everyone to see for
 all time.  It should describe the patch completely, containing:
+
   - why the change is necessary
   - the overall design approach in the patch
   - implementation details
@@ -572,7 +614,9 @@ all time.  It should describe the patch completely, containing:
 
 For more details on what this should all look like, please see the
 ChangeLog section of the document:
+
   "The Perfect Patch"
+
       http://www.ozlabs.org/~akpm/stuff/tpp.txt
 
 
@@ -588,6 +632,7 @@ start exactly where you are now.
 
 
 ----------
+
 Thanks to Paolo Ciarrocchi who allowed the "Development Process"
 (http://lwn.net/Articles/94386/) section
 to be based on text he had written, and to Randy Dunlap and Gerrit
-- 
2.7.4

[PATCH v2 03/20] docs-rst: applying-patches.rst: convert it to ReST markup

[Mauro Carvalho Chehab]

- use the correct markup to identify each section;

- Add some blank lines for Sphinx to properly interpret
  the markups;

- Remove a blank space on some paragraphs;

- Fix the verbatim and bold markups;

- Cleanup the remaining errors to make Sphinx happy.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 .../development-process/applying-patches.rst       | 311 +++++++++++++--------
 1 file changed, 189 insertions(+), 122 deletions(-)

diff --git a/Documentation/development-process/applying-patches.rst b/Documentation/development-process/applying-patches.rst
index 77df55b0225a..573eb3bee19e 100644
--- a/Documentation/development-process/applying-patches.rst
+++ b/Documentation/development-process/applying-patches.rst
@@ -1,9 +1,12 @@
 
-	Applying Patches To The Linux Kernel
-	------------------------------------
+Applying Patches To The Linux Kernel
+++++++++++++++++++++++++++++++++++++
 
-	Original by: Jesper Juhl, August 2005
-	Last update: 2006-01-05
+Original by:
+	Jesper Juhl, August 2005
+
+Last update:
+	2006-01-05
 
 
 A frequently asked question on the Linux Kernel Mailing List is how to apply
@@ -17,10 +20,12 @@ their specific patches) is also provided.
 
 
 What is a patch?
----
- A patch is a small text document containing a delta of changes between two
-different versions of a source tree. Patches are created with the `diff'
+================
+
+A patch is a small text document containing a delta of changes between two
+different versions of a source tree. Patches are created with the ``diff``
 program.
+
 To correctly apply a patch you need to know what base it was generated from
 and what new version the patch will change the source tree into. These
 should both be present in the patch file metadata or be possible to deduce
@@ -28,8 +33,9 @@ from the filename.
 
 
 How do I apply or revert a patch?
----
- You apply a patch with the `patch' program. The patch program reads a diff
+=================================
+
+You apply a patch with the ``patch`` program. The patch program reads a diff
 (or patch) file and makes the changes to the source tree described in it.
 
 Patches for the Linux kernel are generated relative to the parent directory
@@ -38,26 +44,39 @@ holding the kernel source dir.
 This means that paths to files inside the patch file contain the name of the
 kernel source directories it was generated against (or some other directory
 names like "a/" and "b/").
+
 Since this is unlikely to match the name of the kernel source dir on your
 local machine (but is often useful info to see what version an otherwise
 unlabeled patch was generated against) you should change into your kernel
 source directory and then strip the first element of the path from filenames
-in the patch file when applying it (the -p1 argument to `patch' does this).
+in the patch file when applying it (the ``-p1`` argument to ``patch`` does
+this).
 
 To revert a previously applied patch, use the -R argument to patch.
 So, if you applied a patch like this:
+
+::
+
 	patch -p1 < ../patch-x.y.z
 
 You can revert (undo) it like this:
+
+::
+
 	patch -R -p1 < ../patch-x.y.z
 
 
-How do I feed a patch/diff file to `patch'?
----
- This (as usual with Linux and other UNIX like operating systems) can be
+How do I feed a patch/diff file to ``patch``?
+=============================================
+
+This (as usual with Linux and other UNIX like operating systems) can be
 done in several different ways.
+
 In all the examples below I feed the file (in uncompressed form) to patch
 via stdin using the following syntax:
+
+::
+
 	patch -p1 < path/to/patch-x.y.z
 
 If you just want to be able to follow the examples below and don't want to
@@ -66,34 +85,45 @@ section here.
 
 Patch can also get the name of the file to use via the -i argument, like
 this:
+
+::
+
 	patch -p1 -i path/to/patch-x.y.z
 
 If your patch file is compressed with gzip or bzip2 and you don't want to
 uncompress it before applying it, then you can feed it to patch like this
 instead:
+
+::
+
 	zcat path/to/patch-x.y.z.gz | patch -p1
 	bzcat path/to/patch-x.y.z.bz2 | patch -p1
 
 If you wish to uncompress the patch file by hand first before applying it
 (what I assume you've done in the examples below), then you simply run
 gunzip or bunzip2 on the file -- like this:
+
+::
+
 	gunzip patch-x.y.z.gz
 	bunzip2 patch-x.y.z.bz2
 
 Which will leave you with a plain text patch-x.y.z file that you can feed to
-patch via stdin or the -i argument, as you prefer.
+patch via stdin or the ``-i`` argument, as you prefer.
 
-A few other nice arguments for patch are -s which causes patch to be silent
+A few other nice arguments for patch are ``-s`` which causes patch to be silent
 except for errors which is nice to prevent errors from scrolling out of the
-screen too fast, and --dry-run which causes patch to just print a listing of
-what would happen, but doesn't actually make any changes. Finally --verbose
+screen too fast, and ``--dry-run`` which causes patch to just print a listing of
+what would happen, but doesn't actually make any changes. Finally ``--verbose``
 tells patch to print more information about the work being done.
 
 
 Common errors when patching
----
- When patch applies a patch file it attempts to verify the sanity of the
+===========================
+
+When patch applies a patch file it attempts to verify the sanity of the
 file in different ways.
+
 Checking that the file looks like a valid patch file and checking the code
 around the bits being modified matches the context provided in the patch are
 just two of the basic sanity checks patch does.
@@ -111,13 +141,13 @@ everything looks good it has just moved up or down a bit, and patch will
 usually adjust the line numbers and apply the patch.
 
 Whenever patch applies a patch that it had to modify a bit to make it fit
-it'll tell you about it by saying the patch applied with 'fuzz'.
+it'll tell you about it by saying the patch applied with **fuzz**.
 You should be wary of such changes since even though patch probably got it
 right it doesn't /always/ get it right, and the result will sometimes be
 wrong.
 
 When patch encounters a change that it can't fix up with fuzz it rejects it
-outright and leaves a file with a .rej extension (a reject file). You can
+outright and leaves a file with a ``.rej`` extension (a reject file). You can
 read this file to see exactly what change couldn't be applied, so you can
 go fix it up by hand if you wish.
 
@@ -132,43 +162,47 @@ to start with a fresh tree downloaded in full from kernel.org.
 
 Let's look a bit more at some of the messages patch can produce.
 
-If patch stops and presents a "File to patch:" prompt, then patch could not
+If patch stops and presents a ``File to patch:`` prompt, then patch could not
 find a file to be patched. Most likely you forgot to specify -p1 or you are
 in the wrong directory. Less often, you'll find patches that need to be
-applied with -p0 instead of -p1 (reading the patch file should reveal if
+applied with ``-p0`` instead of ``-p1`` (reading the patch file should reveal if
 this is the case -- if so, then this is an error by the person who created
 the patch but is not fatal).
 
-If you get "Hunk #2 succeeded at 1887 with fuzz 2 (offset 7 lines)." or a
+If you get ``Hunk #2 succeeded at 1887 with fuzz 2 (offset 7 lines).`` or a
 message similar to that, then it means that patch had to adjust the location
 of the change (in this example it needed to move 7 lines from where it
 expected to make the change to make it fit).
+
 The resulting file may or may not be OK, depending on the reason the file
 was different than expected.
+
 This often happens if you try to apply a patch that was generated against a
 different kernel version than the one you are trying to patch.
 
-If you get a message like "Hunk #3 FAILED at 2387.", then it means that the
+If you get a message like ``Hunk #3 FAILED at 2387.``, then it means that the
 patch could not be applied correctly and the patch program was unable to
-fuzz its way through. This will generate a .rej file with the change that
-caused the patch to fail and also a .orig file showing you the original
+fuzz its way through. This will generate a ``.rej`` file with the change that
+caused the patch to fail and also a ``.orig`` file showing you the original
 content that couldn't be changed.
 
-If you get "Reversed (or previously applied) patch detected!  Assume -R? [n]"
+If you get ``Reversed (or previously applied) patch detected!  Assume -R? [n]``
 then patch detected that the change contained in the patch seems to have
 already been made.
+
 If you actually did apply this patch previously and you just re-applied it
 in error, then just say [n]o and abort this patch. If you applied this patch
 previously and actually intended to revert it, but forgot to specify -R,
-then you can say [y]es here to make patch revert it for you.
+then you can say [**y**]es here to make patch revert it for you.
+
 This can also happen if the creator of the patch reversed the source and
 destination directories when creating the patch, and in that case reverting
 the patch will in fact apply it.
 
-A message similar to "patch: **** unexpected end of file in patch" or "patch
-unexpectedly ends in middle of line" means that patch could make no sense of
-the file you fed to it. Either your download is broken, you tried to feed
-patch a compressed patch file without uncompressing it first, or the patch
+A message similar to ``patch: **** unexpected end of file in patch`` or
+``patch unexpectedly ends in middle of line`` means that patch could make no
+sense of the file you fed to it. Either your download is broken, you tried to
+feed patch a compressed patch file without uncompressing it first, or the patch
 file that you are using has been mangled by a mail client or mail transfer
 agent along the way somewhere, e.g., by splitting a long line into two lines.
 Often these warnings can easily be fixed by joining (concatenating) the
@@ -182,28 +216,34 @@ to start over with a fresh download of a full kernel tree and the patch you
 wish to apply.
 
 
-Are there any alternatives to `patch'?
----
- Yes there are alternatives.
+Are there any alternatives to ``patch``?
+========================================
 
- You can use the `interdiff' program (http://cyberelk.net/tim/patchutils/) to
+
+Yes there are alternatives.
+
+You can use the ``interdiff`` program (http://cyberelk.net/tim/patchutils/) to
 generate a patch representing the differences between two patches and then
 apply the result.
+
 This will let you move from something like 2.6.12.2 to 2.6.12.3 in a single
 step. The -z flag to interdiff will even let you feed it patches in gzip or
 bzip2 compressed form directly without the use of zcat or bzcat or manual
 decompression.
 
 Here's how you'd go from 2.6.12.2 to 2.6.12.3 in a single step:
+
+::
+
 	interdiff -z ../patch-2.6.12.2.bz2 ../patch-2.6.12.3.gz | patch -p1
 
 Although interdiff may save you a step or two you are generally advised to
 do the additional steps since interdiff can get things wrong in some cases.
 
- Another alternative is `ketchup', which is a python script for automatic
+Another alternative is ``ketchup``, which is a python script for automatic
 downloading and applying of patches (http://www.selenic.com/ketchup/).
 
- Other nice tools are diffstat, which shows a summary of changes made by a
+Other nice tools are diffstat, which shows a summary of changes made by a
 patch; lsdiff, which displays a short listing of affected files in a patch
 file, along with (optionally) the line numbers of the start of each patch;
 and grepdiff, which displays a list of the files modified by a patch where
@@ -211,24 +251,29 @@ the patch contains a given regular expression.
 
 
 Where can I download the patches?
----
- The patches are available at http://kernel.org/
+=================================
+
+The patches are available at http://kernel.org/
 Most recent patches are linked from the front page, but they also have
 specific homes.
 
 The 2.6.x.y (-stable) and 2.6.x patches live at
- ftp://ftp.kernel.org/pub/linux/kernel/v2.6/
+
+	ftp://ftp.kernel.org/pub/linux/kernel/v2.6/
 
 The -rc patches live at
- ftp://ftp.kernel.org/pub/linux/kernel/v2.6/testing/
+
+	ftp://ftp.kernel.org/pub/linux/kernel/v2.6/testing/
 
 The -git patches live at
- ftp://ftp.kernel.org/pub/linux/kernel/v2.6/snapshots/
+
+	ftp://ftp.kernel.org/pub/linux/kernel/v2.6/snapshots/
 
 The -mm kernels live at
- ftp://ftp.kernel.org/pub/linux/kernel/people/akpm/patches/2.6/
 
-In place of ftp.kernel.org you can use ftp.cc.kernel.org, where cc is a
+	ftp://ftp.kernel.org/pub/linux/kernel/people/akpm/patches/2.6/
+
+In place of ``ftp.kernel.org`` you can use ``ftp.cc.kernel.org``, where cc is a
 country code. This way you'll be downloading from a mirror site that's most
 likely geographically closer to you, resulting in faster downloads for you,
 less bandwidth used globally and less load on the main kernel.org servers --
@@ -236,8 +281,9 @@ these are good things, so do use mirrors when possible.
 
 
 The 2.6.x kernels
----
- These are the base stable releases released by Linus. The highest numbered
+=================
+
+These are the base stable releases released by Linus. The highest numbered
 release is the most recent.
 
 If regressions or other serious flaws are found, then a -stable fix patch
@@ -246,30 +292,33 @@ kernel is released, a patch is made available that is a delta between the
 previous 2.6.x kernel and the new one.
 
 To apply a patch moving from 2.6.11 to 2.6.12, you'd do the following (note
-that such patches do *NOT* apply on top of 2.6.x.y kernels but on top of the
+that such patches do **NOT** apply on top of 2.6.x.y kernels but on top of the
 base 2.6.x kernel -- if you need to move from 2.6.x.y to 2.6.x+1 you need to
 first revert the 2.6.x.y patch).
 
 Here are some examples:
 
-# moving from 2.6.11 to 2.6.12
-$ cd ~/linux-2.6.11			# change to kernel source dir
-$ patch -p1 < ../patch-2.6.12		# apply the 2.6.12 patch
-$ cd ..
-$ mv linux-2.6.11 linux-2.6.12		# rename source dir
+::
 
-# moving from 2.6.11.1 to 2.6.12
-$ cd ~/linux-2.6.11.1			# change to kernel source dir
-$ patch -p1 -R < ../patch-2.6.11.1	# revert the 2.6.11.1 patch
-					# source dir is now 2.6.11
-$ patch -p1 < ../patch-2.6.12		# apply new 2.6.12 patch
-$ cd ..
-$ mv linux-2.6.11.1 linux-2.6.12		# rename source dir
+	# moving from 2.6.11 to 2.6.12
+	$ cd ~/linux-2.6.11			# change to kernel source dir
+	$ patch -p1 < ../patch-2.6.12		# apply the 2.6.12 patch
+	$ cd ..
+	$ mv linux-2.6.11 linux-2.6.12		# rename source dir
+
+	# moving from 2.6.11.1 to 2.6.12
+	$ cd ~/linux-2.6.11.1			# change to kernel source dir
+	$ patch -p1 -R < ../patch-2.6.11.1	# revert the 2.6.11.1 patch
+						# source dir is now 2.6.11
+	$ patch -p1 < ../patch-2.6.12		# apply new 2.6.12 patch
+	$ cd ..
+	$ mv linux-2.6.11.1 linux-2.6.12	# rename source dir
 
 
 The 2.6.x.y kernels
----
- Kernels with 4-digit versions are -stable kernels. They contain small(ish)
+===================
+
+Kernels with 4-digit versions are -stable kernels. They contain small(ish)
 critical fixes for security problems or significant regressions discovered
 in a given 2.6.x kernel.
 
@@ -280,30 +329,35 @@ versions.
 If no 2.6.x.y kernel is available, then the highest numbered 2.6.x kernel is
 the current stable kernel.
 
- note: the -stable team usually do make incremental patches available as well
+.. note::
+
+ The -stable team usually do make incremental patches available as well
  as patches against the latest mainline release, but I only cover the
  non-incremental ones below. The incremental ones can be found at
  ftp://ftp.kernel.org/pub/linux/kernel/v2.6/incr/
 
 These patches are not incremental, meaning that for example the 2.6.12.3
 patch does not apply on top of the 2.6.12.2 kernel source, but rather on top
-of the base 2.6.12 kernel source .
+of the base 2.6.12 kernel source.
+
 So, in order to apply the 2.6.12.3 patch to your existing 2.6.12.2 kernel
 source you have to first back out the 2.6.12.2 patch (so you are left with a
 base 2.6.12 kernel source) and then apply the new 2.6.12.3 patch.
 
 Here's a small example:
 
-$ cd ~/linux-2.6.12.2			# change into the kernel source dir
-$ patch -p1 -R < ../patch-2.6.12.2	# revert the 2.6.12.2 patch
-$ patch -p1 < ../patch-2.6.12.3		# apply the new 2.6.12.3 patch
-$ cd ..
-$ mv linux-2.6.12.2 linux-2.6.12.3	# rename the kernel source dir
+::
 
+	$ cd ~/linux-2.6.12.2			# change to the kernel source dir
+	$ patch -p1 -R < ../patch-2.6.12.2	# revert the 2.6.12.2 patch
+	$ patch -p1 < ../patch-2.6.12.3		# apply the new 2.6.12.3 patch
+	$ cd ..
+	$ mv linux-2.6.12.2 linux-2.6.12.3	# rename the kernel source dir
 
 The -rc kernels
----
- These are release-candidate kernels. These are development kernels released
+===============
+
+These are release-candidate kernels. These are development kernels released
 by Linus whenever he deems the current git (the kernel's source management
 tool) tree to be in a reasonably sane state adequate for testing.
 
@@ -321,35 +375,39 @@ The -rc patches are not incremental, they apply to a base 2.6.x kernel, just
 like the 2.6.x.y patches described above. The kernel version before the -rcN
 suffix denotes the version of the kernel that this -rc kernel will eventually
 turn into.
+
 So, 2.6.13-rc5 means that this is the fifth release candidate for the 2.6.13
 kernel and the patch should be applied on top of the 2.6.12 kernel source.
 
 Here are 3 examples of how to apply these patches:
 
-# first an example of moving from 2.6.12 to 2.6.13-rc3
-$ cd ~/linux-2.6.12			# change into the 2.6.12 source dir
-$ patch -p1 < ../patch-2.6.13-rc3	# apply the 2.6.13-rc3 patch
-$ cd ..
-$ mv linux-2.6.12 linux-2.6.13-rc3	# rename the source dir
+::
 
-# now let's move from 2.6.13-rc3 to 2.6.13-rc5
-$ cd ~/linux-2.6.13-rc3			# change into the 2.6.13-rc3 dir
-$ patch -p1 -R < ../patch-2.6.13-rc3	# revert the 2.6.13-rc3 patch
-$ patch -p1 < ../patch-2.6.13-rc5	# apply the new 2.6.13-rc5 patch
-$ cd ..
-$ mv linux-2.6.13-rc3 linux-2.6.13-rc5	# rename the source dir
+	# first an example of moving from 2.6.12 to 2.6.13-rc3
+	$ cd ~/linux-2.6.12			# change to the 2.6.12 source dir
+	$ patch -p1 < ../patch-2.6.13-rc3	# apply the 2.6.13-rc3 patch
+	$ cd ..
+	$ mv linux-2.6.12 linux-2.6.13-rc3	# rename the source dir
 
-# finally let's try and move from 2.6.12.3 to 2.6.13-rc5
-$ cd ~/linux-2.6.12.3			# change to the kernel source dir
-$ patch -p1 -R < ../patch-2.6.12.3	# revert the 2.6.12.3 patch
-$ patch -p1 < ../patch-2.6.13-rc5	# apply new 2.6.13-rc5 patch
-$ cd ..
-$ mv linux-2.6.12.3 linux-2.6.13-rc5	# rename the kernel source dir
+	# now let's move from 2.6.13-rc3 to 2.6.13-rc5
+	$ cd ~/linux-2.6.13-rc3			# change to the 2.6.13-rc3 dir
+	$ patch -p1 -R < ../patch-2.6.13-rc3	# revert the 2.6.13-rc3 patch
+	$ patch -p1 < ../patch-2.6.13-rc5	# apply the new 2.6.13-rc5 patch
+	$ cd ..
+	$ mv linux-2.6.13-rc3 linux-2.6.13-rc5	# rename the source dir
+
+	# finally let's try and move from 2.6.12.3 to 2.6.13-rc5
+	$ cd ~/linux-2.6.12.3			# change to the kernel source dir
+	$ patch -p1 -R < ../patch-2.6.12.3	# revert the 2.6.12.3 patch
+	$ patch -p1 < ../patch-2.6.13-rc5	# apply new 2.6.13-rc5 patch
+	$ cd ..
+	$ mv linux-2.6.12.3 linux-2.6.13-rc5	# rename the kernel source dir
 
 
 The -git kernels
----
- These are daily snapshots of Linus' kernel tree (managed in a git
+================
+
+These are daily snapshots of Linus' kernel tree (managed in a git
 repository, hence the name).
 
 These patches are usually released daily and represent the current state of
@@ -364,35 +422,40 @@ named 2.6.13-rc3-git2 applies to the source of the 2.6.13-rc3 kernel.
 
 Here are some examples of how to apply these patches:
 
-# moving from 2.6.12 to 2.6.12-git1
-$ cd ~/linux-2.6.12			# change to the kernel source dir
-$ patch -p1 < ../patch-2.6.12-git1	# apply the 2.6.12-git1 patch
-$ cd ..
-$ mv linux-2.6.12 linux-2.6.12-git1	# rename the kernel source dir
+::
 
-# moving from 2.6.12-git1 to 2.6.13-rc2-git3
-$ cd ~/linux-2.6.12-git1		# change to the kernel source dir
-$ patch -p1 -R < ../patch-2.6.12-git1	# revert the 2.6.12-git1 patch
-					# we now have a 2.6.12 kernel
-$ patch -p1 < ../patch-2.6.13-rc2	# apply the 2.6.13-rc2 patch
-					# the kernel is now 2.6.13-rc2
-$ patch -p1 < ../patch-2.6.13-rc2-git3	# apply the 2.6.13-rc2-git3 patch
-					# the kernel is now 2.6.13-rc2-git3
-$ cd ..
-$ mv linux-2.6.12-git1 linux-2.6.13-rc2-git3	# rename source dir
+	# moving from 2.6.12 to 2.6.12-git1
+	$ cd ~/linux-2.6.12			# change to the kernel source dir
+	$ patch -p1 < ../patch-2.6.12-git1	# apply the 2.6.12-git1 patch
+	$ cd ..
+	$ mv linux-2.6.12 linux-2.6.12-git1	# rename the kernel source dir
+
+	# moving from 2.6.12-git1 to 2.6.13-rc2-git3
+	$ cd ~/linux-2.6.12-git1		# change to the kernel source dir
+	$ patch -p1 -R < ../patch-2.6.12-git1	# revert the 2.6.12-git1 patch
+						# we now have a 2.6.12 kernel
+	$ patch -p1 < ../patch-2.6.13-rc2	# apply the 2.6.13-rc2 patch
+						# the kernel is now 2.6.13-rc2
+	$ patch -p1 < ../patch-2.6.13-rc2-git3	# apply the 2.6.13-rc2-git3 patch
+						# the kernel is now 2.6.13-rc2-git3
+	$ cd ..
+	$ mv linux-2.6.12-git1 linux-2.6.13-rc2-git3	# rename source dir
 
 
 The -mm kernels
----
- These are experimental kernels released by Andrew Morton.
+===============
+
+These are experimental kernels released by Andrew Morton.
 
 The -mm tree serves as a sort of proving ground for new features and other
 experimental patches.
+
 Once a patch has proved its worth in -mm for a while Andrew pushes it on to
 Linus for inclusion in mainline.
 
 Although it's encouraged that patches flow to Linus via the -mm tree, this
 is not always enforced.
+
 Subsystem maintainers (or individuals) sometimes push their patches directly
 to Linus, even though (or after) they have been merged and tested in -mm (or
 sometimes even without prior testing in -mm).
@@ -417,31 +480,35 @@ Testing of -mm kernels is greatly appreciated since the whole point of the
 tree is to weed out regressions, crashes, data corruption bugs, build
 breakage (and any other bug in general) before changes are merged into the
 more stable mainline Linus tree.
+
 But testers of -mm should be aware that breakage in this tree is more common
 than in any other tree.
 
 The -mm kernels are not released on a fixed schedule, but usually a few -mm
 kernels are released in between each -rc kernel (1 to 3 is common).
+
 The -mm kernels apply to either a base 2.6.x kernel (when no -rc kernels
 have been released yet) or to a Linus -rc kernel.
 
 Here are some examples of applying the -mm patches:
 
-# moving from 2.6.12 to 2.6.12-mm1
-$ cd ~/linux-2.6.12			# change to the 2.6.12 source dir
-$ patch -p1 < ../2.6.12-mm1		# apply the 2.6.12-mm1 patch
-$ cd ..
-$ mv linux-2.6.12 linux-2.6.12-mm1	# rename the source appropriately
+::
 
-# moving from 2.6.12-mm1 to 2.6.13-rc3-mm3
-$ cd ~/linux-2.6.12-mm1
-$ patch -p1 -R < ../2.6.12-mm1		# revert the 2.6.12-mm1 patch
-					# we now have a 2.6.12 source
-$ patch -p1 < ../patch-2.6.13-rc3	# apply the 2.6.13-rc3 patch
-					# we now have a 2.6.13-rc3 source
-$ patch -p1 < ../2.6.13-rc3-mm3		# apply the 2.6.13-rc3-mm3 patch
-$ cd ..
-$ mv linux-2.6.12-mm1 linux-2.6.13-rc3-mm3	# rename the source dir
+	# moving from 2.6.12 to 2.6.12-mm1
+	$ cd ~/linux-2.6.12			# change to the 2.6.12 source dir
+	$ patch -p1 < ../2.6.12-mm1		# apply the 2.6.12-mm1 patch
+	$ cd ..
+	$ mv linux-2.6.12 linux-2.6.12-mm1	# rename the source appropriately
+
+	# moving from 2.6.12-mm1 to 2.6.13-rc3-mm3
+	$ cd ~/linux-2.6.12-mm1
+	$ patch -p1 -R < ../2.6.12-mm1		# revert the 2.6.12-mm1 patch
+						# we now have a 2.6.12 source
+	$ patch -p1 < ../patch-2.6.13-rc3	# apply the 2.6.13-rc3 patch
+						# we now have a 2.6.13-rc3 source
+	$ patch -p1 < ../2.6.13-rc3-mm3		# apply the 2.6.13-rc3-mm3 patch
+	$ cd ..
+	$ mv linux-2.6.12-mm1 linux-2.6.13-rc3-mm3	# rename the source dir
 
 
 This concludes this list of explanations of the various kernel trees.
-- 
2.7.4

[PATCH v2 04/20] docs-rst: Changes.rst: convert it to ReST markup

[Mauro Carvalho Chehab]

- Fix chapter identation inconsistencies;
- Convert table to ReST format;
- use the right tag for bullets;
- Fix bold emphasis;
- mark blocks with :: tags;
- use verbatim font for files;
- make Sphinx happy

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/development-process/Changes.rst | 224 +++++++++++++++-----------
 1 file changed, 134 insertions(+), 90 deletions(-)

diff --git a/Documentation/development-process/Changes.rst b/Documentation/development-process/Changes.rst
index ec97b77c8b00..a9f365d864c7 100644
--- a/Documentation/development-process/Changes.rst
+++ b/Documentation/development-process/Changes.rst
@@ -1,3 +1,6 @@
+Minimal requerements to compile the Kernel
+++++++++++++++++++++++++++++++++++++++++++
+
 Intro
 =====
 
@@ -10,9 +13,9 @@ Axel Boldt, Alessandro Sigala, and countless other users all over the
 'net).
 
 Current Minimal Requirements
-============================
+****************************
 
-Upgrade to at *least* these software revisions before thinking you've
+Upgrade to at **least** these software revisions before thinking you've
 encountered a bug!  If you're unsure what version you're currently
 running, the suggested command should tell you.
 
@@ -21,34 +24,38 @@ running a Linux kernel.  Also, not all tools are necessary on all
 systems; obviously, if you don't have any ISDN hardware, for example,
 you probably needn't concern yourself with isdn4k-utils.
 
-o  GNU C                  3.2                     # gcc --version
-o  GNU make               3.80                    # make --version
-o  binutils               2.12                    # ld -v
-o  util-linux             2.10o                   # fdformat --version
-o  module-init-tools      0.9.10                  # depmod -V
-o  e2fsprogs              1.41.4                  # e2fsck -V
-o  jfsutils               1.1.3                   # fsck.jfs -V
-o  reiserfsprogs          3.6.3                   # reiserfsck -V
-o  xfsprogs               2.6.0                   # xfs_db -V
-o  squashfs-tools         4.0                     # mksquashfs -version
-o  btrfs-progs            0.18                    # btrfsck
-o  pcmciautils            004                     # pccardctl -V
-o  quota-tools            3.09                    # quota -V
-o  PPP                    2.4.0                   # pppd --version
-o  isdn4k-utils           3.1pre1                 # isdnctrl 2>&1|grep version
-o  nfs-utils              1.0.5                   # showmount --version
-o  procps                 3.2.0                   # ps --version
-o  oprofile               0.9                     # oprofiled --version
-o  udev                   081                     # udevd --version
-o  grub                   0.93                    # grub --version || grub-install --version
-o  mcelog                 0.6                     # mcelog --version
-o  iptables               1.4.2                   # iptables -V
-o  openssl & libcrypto    1.0.0                   # openssl version
-o  bc                     1.06.95                 # bc --version
+====================== ===============  ========================================
+        Program        Minimal version       Command to check the version
+====================== ===============  ========================================
+GNU C                  3.2              gcc --version
+GNU make               3.80             make --version
+binutils               2.12             ld -v
+util-linux             2.10o            fdformat --version
+module-init-tools      0.9.10           depmod -V
+e2fsprogs              1.41.4           e2fsck -V
+jfsutils               1.1.3            fsck.jfs -V
+reiserfsprogs          3.6.3            reiserfsck -V
+xfsprogs               2.6.0            xfs_db -V
+squashfs-tools         4.0              mksquashfs -version
+btrfs-progs            0.18             btrfsck
+pcmciautils            004              pccardctl -V
+quota-tools            3.09             quota -V
+PPP                    2.4.0            pppd --version
+isdn4k-utils           3.1pre1          isdnctrl 2>&1|grep version
+nfs-utils              1.0.5            showmount --version
+procps                 3.2.0            ps --version
+oprofile               0.9              oprofiled --version
+udev                   081              udevd --version
+grub                   0.93             grub --version || grub-install --version
+mcelog                 0.6              mcelog --version
+iptables               1.4.2            iptables -V
+openssl & libcrypto    1.0.0            openssl version
+bc                     1.06.95          bc --version
+====================== ===============  ========================================
 
 
 Kernel compilation
-==================
+******************
 
 GCC
 ---
@@ -64,16 +71,16 @@ You will need GNU make 3.80 or later to build the kernel.
 Binutils
 --------
 
-Linux on IA-32 has recently switched from using as86 to using gas for
-assembling the 16-bit boot code, removing the need for as86 to compile
+Linux on IA-32 has recently switched from using ``as86`` to using ``gas`` for
+assembling the 16-bit boot code, removing the need for ``as86`` to compile
 your kernel.  This change does, however, mean that you need a recent
 release of binutils.
 
 Perl
 ----
 
-You will need perl 5 and the following modules: Getopt::Long, Getopt::Std,
-File::Basename, and File::Find to build the kernel.
+You will need perl 5 and the following modules: ``Getopt::Long``,
+``Getopt::Std``, ``File::Basename``, and ``File::Find`` to build the kernel.
 
 BC
 --
@@ -93,7 +100,7 @@ and higher.
 
 
 System utilities
-================
+****************
 
 Architectural changes
 ---------------------
@@ -115,7 +122,7 @@ well as the desired DocBook stylesheets.
 Util-linux
 ----------
 
-New versions of util-linux provide *fdisk support for larger disks,
+New versions of util-linux provide ``fdisk`` support for larger disks,
 support new options to mount, recognize more supported partition
 types, have a fdformat which works with 2.4 kernels, and similar goodies.
 You'll probably want to upgrade.
@@ -125,54 +132,57 @@ Ksymoops
 
 If the unthinkable happens and your kernel oopses, you may need the
 ksymoops tool to decode it, but in most cases you don't.
-It is generally preferred to build the kernel with CONFIG_KALLSYMS so
+It is generally preferred to build the kernel with ``CONFIG_KALLSYMS`` so
 that it produces readable dumps that can be used as-is (this also
 produces better output than ksymoops).  If for some reason your kernel
-is not build with CONFIG_KALLSYMS and you have no way to rebuild and
+is not build with ``CONFIG_KALLSYMS`` and you have no way to rebuild and
 reproduce the Oops with that option, then you can still decode that Oops
 with ksymoops.
 
 Module-Init-Tools
 -----------------
 
-A new module loader is now in the kernel that requires module-init-tools
+A new module loader is now in the kernel that requires ``module-init-tools``
 to use.  It is backward compatible with the 2.4.x series kernels.
 
 Mkinitrd
 --------
 
-These changes to the /lib/modules file tree layout also require that
+These changes to the ``/lib/modules`` file tree layout also require that
 mkinitrd be upgraded.
 
 E2fsprogs
 ---------
 
-The latest version of e2fsprogs fixes several bugs in fsck and
+The latest version of ``e2fsprogs`` fixes several bugs in fsck and
 debugfs.  Obviously, it's a good idea to upgrade.
 
 JFSutils
 --------
 
-The jfsutils package contains the utilities for the file system.
+The ``jfsutils`` package contains the utilities for the file system.
 The following utilities are available:
-o fsck.jfs - initiate replay of the transaction log, and check
+
+- ``fsck.jfs`` - initiate replay of the transaction log, and check
   and repair a JFS formatted partition.
-o mkfs.jfs - create a JFS formatted partition.
-o other file system utilities are also available in this package.
+
+- ``mkfs.jfs`` - create a JFS formatted partition.
+
+- other file system utilities are also available in this package.
 
 Reiserfsprogs
 -------------
 
 The reiserfsprogs package should be used for reiserfs-3.6.x
 (Linux kernels 2.4.x). It is a combined package and contains working
-versions of mkreiserfs, resize_reiserfs, debugreiserfs and
-reiserfsck. These utils work on both i386 and alpha platforms.
+versions of ``mkreiserfs``, ``resize_reiserfs``, ``debugreiserfs`` and
+``reiserfsck``. These utils work on both i386 and alpha platforms.
 
 Xfsprogs
 --------
 
-The latest version of xfsprogs contains mkfs.xfs, xfs_db, and the
-xfs_repair utilities, among others, for the XFS filesystem.  It is
+The latest version of ``xfsprogs`` contains ``mkfs.xfs``, ``xfs_db``, and the
+``xfs_repair`` utilities, among others, for the XFS filesystem.  It is
 architecture independent and any version from 2.0.0 onward should
 work correctly with this version of the XFS kernel code (2.6.0 or
 later is recommended, due to some significant improvements).
@@ -180,7 +190,7 @@ later is recommended, due to some significant improvements).
 PCMCIAutils
 -----------
 
-PCMCIAutils replaces pcmcia-cs. It properly sets up
+PCMCIAutils replaces ``pcmcia-cs``. It properly sets up
 PCMCIA sockets at system startup and loads the appropriate modules
 for 16-bit PCMCIA devices if the kernel is modularized and the hotplug
 subsystem is used.
@@ -200,17 +210,20 @@ A driver has been added to allow updating of Intel IA32 microcode,
 accessible as a normal (misc) character device.  If you are not using
 udev you may need to:
 
-mkdir /dev/cpu
-mknod /dev/cpu/microcode c 10 184
-chmod 0644 /dev/cpu/microcode
+::
+
+  mkdir /dev/cpu
+  mknod /dev/cpu/microcode c 10 184
+  chmod 0644 /dev/cpu/microcode
 
 as root before you can use this.  You'll probably also want to
 get the user-space microcode_ctl utility to use with this.
 
 udev
 ----
-udev is a userspace application for populating /dev dynamically with
-only entries for devices actually present.  udev replaces the basic
+
+``udev`` is a userspace application for populating ``/dev`` dynamically with
+only entries for devices actually present. ``udev`` replaces the basic
 functionality of devfs, while allowing persistent device naming for
 devices.
 
@@ -218,10 +231,10 @@ FUSE
 ----
 
 Needs libfuse 2.4.0 or later.  Absolute minimum is 2.3.0 but mount
-options 'direct_io' and 'kernel_cache' won't work.
+options ``direct_io`` and ``kernel_cache`` won't work.
 
 Networking
-==========
+**********
 
 General changes
 ---------------
@@ -245,7 +258,9 @@ upgrade pppd to at least 2.4.0.
 If you are not using udev, you must have the device file /dev/ppp
 which can be made by:
 
-mknod /dev/ppp c 108 0
+::
+
+  mknod /dev/ppp c 108 0
 
 as root.
 
@@ -260,23 +275,25 @@ NFS-utils
 
 In ancient (2.4 and earlier) kernels, the nfs server needed to know
 about any client that expected to be able to access files via NFS.  This
-information would be given to the kernel by "mountd" when the client
-mounted the filesystem, or by "exportfs" at system startup.  exportfs
-would take information about active clients from /var/lib/nfs/rmtab.
+information would be given to the kernel by ``mountd`` when the client
+mounted the filesystem, or by ``exportfs`` at system startup.  exportfs
+would take information about active clients from ``/var/lib/nfs/rmtab``.
 
 This approach is quite fragile as it depends on rmtab being correct
 which is not always easy, particularly when trying to implement
-fail-over.  Even when the system is working well, rmtab suffers from
+fail-over.  Even when the system is working well, ``rmtab`` suffers from
 getting lots of old entries that never get removed.
 
 With modern kernels we have the option of having the kernel tell mountd
 when it gets a request from an unknown host, and mountd can give
 appropriate export information to the kernel.  This removes the
-dependency on rmtab and means that the kernel only needs to know about
+dependency on ``rmtab`` and means that the kernel only needs to know about
 currently active clients.
 
 To enable this new functionality, you need to:
 
+::
+
   mount -t nfsd nfsd /proc/fs/nfsd
 
 before running exportfs or mountd.  It is recommended that all NFS
@@ -287,8 +304,8 @@ mcelog
 ------
 
 On x86 kernels the mcelog utility is needed to process and log machine check
-events when CONFIG_X86_MCE is enabled. Machine check events are errors reported
-by the CPU. Processing them is strongly encouraged.
+events when ``CONFIG_X86_MCE`` is enabled. Machine check events are errors
+reported by the CPU. Processing them is strongly encouraged.
 
 Getting updated software
 ========================
@@ -298,114 +315,141 @@ Kernel compilation
 
 gcc
 ---
-o  <ftp://ftp.gnu.org/gnu/gcc/>
+
+- <ftp://ftp.gnu.org/gnu/gcc/>
 
 Make
 ----
-o  <ftp://ftp.gnu.org/gnu/make/>
+
+- <ftp://ftp.gnu.org/gnu/make/>
 
 Binutils
 --------
-o  <ftp://ftp.kernel.org/pub/linux/devel/binutils/>
+
+- <ftp://ftp.kernel.org/pub/linux/devel/binutils/>
 
 OpenSSL
 -------
-o  <https://www.openssl.org/>
+
+- <https://www.openssl.org/>
 
 System utilities
 ****************
 
 Util-linux
 ----------
-o  <ftp://ftp.kernel.org/pub/linux/utils/util-linux/>
+
+- <ftp://ftp.kernel.org/pub/linux/utils/util-linux/>
 
 Ksymoops
 --------
-o  <ftp://ftp.kernel.org/pub/linux/utils/kernel/ksymoops/v2.4/>
+
+- <ftp://ftp.kernel.org/pub/linux/utils/kernel/ksymoops/v2.4/>
 
 Module-Init-Tools
 -----------------
-o  <ftp://ftp.kernel.org/pub/linux/kernel/people/rusty/modules/>
+
+- <ftp://ftp.kernel.org/pub/linux/kernel/people/rusty/modules/>
 
 Mkinitrd
 --------
-o  <https://code.launchpad.net/initrd-tools/main>
+
+- <https://code.launchpad.net/initrd-tools/main>
 
 E2fsprogs
 ---------
-o  <http://prdownloads.sourceforge.net/e2fsprogs/e2fsprogs-1.29.tar.gz>
+
+- <http://prdownloads.sourceforge.net/e2fsprogs/e2fsprogs-1.29.tar.gz>
 
 JFSutils
 --------
-o  <http://jfs.sourceforge.net/>
+
+- <http://jfs.sourceforge.net/>
 
 Reiserfsprogs
 -------------
-o  <http://www.kernel.org/pub/linux/utils/fs/reiserfs/>
+
+- <http://www.kernel.org/pub/linux/utils/fs/reiserfs/>
 
 Xfsprogs
 --------
-o  <ftp://oss.sgi.com/projects/xfs/>
+
+- <ftp://oss.sgi.com/projects/xfs/>
 
 Pcmciautils
 -----------
-o  <ftp://ftp.kernel.org/pub/linux/utils/kernel/pcmcia/>
+
+- <ftp://ftp.kernel.org/pub/linux/utils/kernel/pcmcia/>
 
 Quota-tools
-----------
-o  <http://sourceforge.net/projects/linuxquota/>
+-----------
+
+- <http://sourceforge.net/projects/linuxquota/>
 
 DocBook Stylesheets
 -------------------
-o  <http://sourceforge.net/projects/docbook/files/docbook-dsssl/>
+
+- <http://sourceforge.net/projects/docbook/files/docbook-dsssl/>
 
 XMLTO XSLT Frontend
 -------------------
-o  <http://cyberelk.net/tim/xmlto/>
+
+- <http://cyberelk.net/tim/xmlto/>
 
 Intel P6 microcode
 ------------------
-o  <https://downloadcenter.intel.com/>
+
+- <https://downloadcenter.intel.com/>
 
 udev
 ----
-o <http://www.freedesktop.org/software/systemd/man/udev.html>
+
+- <http://www.freedesktop.org/software/systemd/man/udev.html>
 
 FUSE
 ----
-o <http://sourceforge.net/projects/fuse>
+
+- <http://sourceforge.net/projects/fuse>
 
 mcelog
 ------
-o <http://www.mcelog.org/>
+
+- <http://www.mcelog.org/>
 
 Networking
 **********
 
 PPP
 ---
-o  <ftp://ftp.samba.org/pub/ppp/>
+
+- <ftp://ftp.samba.org/pub/ppp/>
 
 Isdn4k-utils
 ------------
-o  <ftp://ftp.isdn4linux.de/pub/isdn4linux/utils/>
+
+- <ftp://ftp.isdn4linux.de/pub/isdn4linux/utils/>
 
 NFS-utils
 ---------
-o  <http://sourceforge.net/project/showfiles.php?group_id=14>
+
+- <http://sourceforge.net/project/showfiles.php?group_id=14>
 
 Iptables
 --------
-o  <http://www.iptables.org/downloads.html>
+
+- <http://www.iptables.org/downloads.html>
 
 Ip-route2
 ---------
-o  <https://www.kernel.org/pub/linux/utils/net/iproute2/>
+
+- <https://www.kernel.org/pub/linux/utils/net/iproute2/>
 
 OProfile
 --------
-o  <http://oprofile.sf.net/download/>
+
+- <http://oprofile.sf.net/download/>
 
 NFS-Utils
 ---------
-o  <http://nfs.sourceforge.net/>
+
+- <http://nfs.sourceforge.net/>
-- 
2.7.4

[PATCH v2 05/20] docs-rst: CodingStyle.rst: Convert to ReST markup

[Mauro Carvalho Chehab]

- Fix all chapter identation;
- add c blocks where needed;

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/development-process/CodingStyle.rst | 253 ++++++++++++++++------
 1 file changed, 187 insertions(+), 66 deletions(-)

diff --git a/Documentation/development-process/CodingStyle.rst b/Documentation/development-process/CodingStyle.rst
index 0f1dbd87eb48..3bc022b43ed8 100644
--- a/Documentation/development-process/CodingStyle.rst
+++ b/Documentation/development-process/CodingStyle.rst
@@ -1,5 +1,6 @@
 
-		Linux kernel coding style
+Linux kernel coding style
+=========================
 
 This is a short document describing the preferred coding style for the
 linux kernel.  Coding style is very personal, and I won't _force_ my
@@ -13,7 +14,8 @@ and NOT read it.  Burn them, it's a great symbolic gesture.
 Anyway, here goes:
 
 
-		Chapter 1: Indentation
+Indentation
+-----------
 
 Tabs are 8 characters, and thus indentations are also 8 characters.
 There are heretic movements that try to make indentations 4 (or even 2!)
@@ -39,6 +41,8 @@ The preferred way to ease multiple indentation levels in a switch statement is
 to align the "switch" and its subordinate "case" labels in the same column
 instead of "double-indenting" the "case" labels.  E.g.:
 
+.. code-block:: c
+
 	switch (suffix) {
 	case 'G':
 	case 'g':
@@ -59,6 +63,8 @@ instead of "double-indenting" the "case" labels.  E.g.:
 Don't put multiple statements on a single line unless you have
 something to hide:
 
+.. code-block:: c
+
 	if (condition) do_this;
 	  do_something_everytime;
 
@@ -71,7 +77,8 @@ used for indentation, and the above example is deliberately broken.
 Get a decent editor and don't leave whitespace at the end of lines.
 
 
-		Chapter 2: Breaking long lines and strings
+Breaking long lines and strings
+-------------------------------
 
 Coding style is all about readability and maintainability using commonly
 available tools.
@@ -87,7 +94,8 @@ with a long argument list. However, never break user-visible strings such as
 printk messages, because that breaks the ability to grep for them.
 
 
-		Chapter 3: Placing Braces and Spaces
+Placing Braces and Spaces
+-------------------------
 
 The other issue that always comes up in C styling is the placement of
 braces.  Unlike the indent size, there are few technical reasons to
@@ -95,6 +103,8 @@ choose one placement strategy over the other, but the preferred way, as
 shown to us by the prophets Kernighan and Ritchie, is to put the opening
 brace last on the line, and put the closing brace first, thusly:
 
+.. code-block:: c
+
 	if (x is true) {
 		we do y
 	}
@@ -102,6 +112,8 @@ brace last on the line, and put the closing brace first, thusly:
 This applies to all non-function statement blocks (if, switch, for,
 while, do).  E.g.:
 
+.. code-block:: c
+
 	switch (action) {
 	case KOBJ_ADD:
 		return "add";
@@ -116,6 +128,8 @@ while, do).  E.g.:
 However, there is one special case, namely functions: they have the
 opening brace at the beginning of the next line, thus:
 
+.. code-block:: c
+
 	int function(int x)
 	{
 		body of function
@@ -131,12 +145,16 @@ the cases where it is followed by a continuation of the same statement,
 ie a "while" in a do-statement or an "else" in an if-statement, like
 this:
 
+.. code-block:: c
+
 	do {
 		body of do-loop
 	} while (condition);
 
 and
 
+.. code-block:: c
+
 	if (x == y) {
 		..
 	} else if (x > y) {
@@ -155,11 +173,15 @@ comments on.
 
 Do not unnecessarily use braces where a single statement will do.
 
+.. code-block:: c
+
 	if (condition)
 		action();
 
 and
 
+.. code-block:: c
+
 	if (condition)
 		do_this();
 	else
@@ -168,6 +190,8 @@ and
 This does not apply if only one branch of a conditional statement is a single
 statement; in the latter case use braces in both branches:
 
+.. code-block:: c
+
 	if (condition) {
 		do_this();
 		do_that();
@@ -175,32 +199,44 @@ statement; in the latter case use braces in both branches:
 		otherwise();
 	}
 
-		3.1:  Spaces
+Spaces
+******
 
 Linux kernel style for use of spaces depends (mostly) on
 function-versus-keyword usage.  Use a space after (most) keywords.  The
 notable exceptions are sizeof, typeof, alignof, and __attribute__, which look
 somewhat like functions (and are usually used with parentheses in Linux,
-although they are not required in the language, as in: "sizeof info" after
-"struct fileinfo info;" is declared).
+although they are not required in the language, as in: ``sizeof info`` after
+``struct fileinfo info;`` is declared).
 
 So use a space after these keywords:
 
+::
+
 	if, switch, case, for, do, while
 
 but not with sizeof, typeof, alignof, or __attribute__.  E.g.,
 
+.. code-block:: c
+
+
 	s = sizeof(struct file);
 
 Do not add spaces around (inside) parenthesized expressions.  This example is
-*bad*:
+**bad**:
+
+.. code-block:: c
+
 
 	s = sizeof( struct file );
 
 When declaring pointer data or a function that returns a pointer type, the
-preferred use of '*' is adjacent to the data name or function name and not
+preferred use of '\*' is adjacent to the data name or function name and not
 adjacent to the type name.  Examples:
 
+.. code-block:: c
+
+
 	char *linux_banner;
 	unsigned long long memparse(char *ptr, char **retptr);
 	char *match_strdup(substring_t *s);
@@ -208,18 +244,26 @@ adjacent to the type name.  Examples:
 Use one space around (on each side of) most binary and ternary operators,
 such as any of these:
 
+::
+
 	=  +  -  <  >  *  /  %  |  &  ^  <=  >=  ==  !=  ?  :
 
 but no space after unary operators:
 
+::
+
 	&  *  +  -  ~  !  sizeof  typeof  alignof  __attribute__  defined
 
 no space before the postfix increment & decrement unary operators:
 
+::
+
 	++  --
 
 no space after the prefix increment & decrement unary operators:
 
+::
+
 	++  --
 
 and no space around the '.' and "->" structure member operators.
@@ -237,7 +281,8 @@ of patches, this may make later patches in the series fail by changing their
 context lines.
 
 
-		Chapter 4: Naming
+Naming
+------
 
 C is a Spartan language, and so should your naming be.  Unlike Modula-2
 and Pascal programmers, C programmers do not use cute names like
@@ -270,16 +315,22 @@ problem, which is called the function-growth-hormone-imbalance syndrome.
 See chapter 6 (Functions).
 
 
-		Chapter 5: Typedefs
+Typedefs
+--------
 
 Please don't use things like "vps_t".
 It's a _mistake_ to use typedef for structures and pointers. When you see a
 
+.. code-block:: c
+
+
 	vps_t a;
 
 in the source, what does it mean?
 In contrast, if it says
 
+.. code-block:: c
+
 	struct virtual_container *a;
 
 you can actually tell what "a" is.
@@ -344,7 +395,8 @@ In general, a pointer, or a struct that has elements that can reasonably
 be directly accessed should _never_ be a typedef.
 
 
-		Chapter 6: Functions
+Functions
+---------
 
 Functions should be short and sweet, and do just one thing.  They should
 fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
@@ -372,8 +424,10 @@ and it gets confused.  You know you're brilliant, but maybe you'd like
 to understand what you did 2 weeks from now.
 
 In source files, separate functions with one blank line.  If the function is
-exported, the EXPORT* macro for it should follow immediately after the closing
-function brace line.  E.g.:
+exported, the **EXPORT** macro for it should follow immediately after the
+closing function brace line.  E.g.:
+
+.. code-block:: c
 
 	int system_is_up(void)
 	{
@@ -386,7 +440,8 @@ Although this is not required by the C language, it is preferred in Linux
 because it is a simple way to add valuable information for the reader.
 
 
-		Chapter 7: Centralized exiting of functions
+Centralized exiting of functions
+--------------------------------
 
 Albeit deprecated by some people, the equivalent of the goto statement is
 used frequently by compilers in form of the unconditional jump instruction.
@@ -409,9 +464,11 @@ The rationale for using gotos is:
 - unconditional statements are easier to understand and follow
 - nesting is reduced
 - errors by not updating individual exit points when making
-    modifications are prevented
+  modifications are prevented
 - saves the compiler work to optimize redundant code away ;)
 
+.. code-block:: c
+
 	int fun(int a)
 	{
 		int result = 0;
@@ -436,6 +493,8 @@ The rationale for using gotos is:
 
 A common type of bug to be aware of is "one err bugs" which look like this:
 
+.. code-block:: c
+
 	 err:
 		kfree(foo->bar);
 		kfree(foo);
@@ -445,6 +504,8 @@ The bug in this code is that on some exit paths "foo" is NULL.  Normally the
 fix for this is to split it up into two error labels "err_free_bar:" and
 "err_free_foo:":
 
+.. code-block:: c
+
 	 err_free_bar:
 		kfree(foo->bar);
 	 err_free_foo:
@@ -454,7 +515,8 @@ fix for this is to split it up into two error labels "err_free_bar:" and
 Ideally you should simulate errors to test all exit paths.
 
 
-		Chapter 8: Commenting
+Commenting
+----------
 
 Comments are good, but there is also a danger of over-commenting.  NEVER
 try to explain HOW your code works in a comment: it's much better to
@@ -476,6 +538,8 @@ for details.
 
 The preferred style for long (multi-line) comments is:
 
+.. code-block:: c
+
 	/*
 	 * This is the preferred style for multi-line
 	 * comments in the Linux kernel source code.
@@ -488,6 +552,8 @@ The preferred style for long (multi-line) comments is:
 For files in net/ and drivers/net/ the preferred style for long (multi-line)
 comments is a little different.
 
+.. code-block:: c
+
 	/* The preferred comment style for files in net/ and drivers/net
 	 * looks like this.
 	 *
@@ -501,7 +567,8 @@ multiple data declarations).  This leaves you room for a small comment on each
 item, explaining its use.
 
 
-		Chapter 9: You've made a mess of it
+You've made a mess of it
+------------------------
 
 That's OK, we all do.  You've probably been told by your long-time Unix
 user helper that "GNU emacs" automatically formats the C sources for
@@ -513,38 +580,40 @@ make a good program).
 So, you can either get rid of GNU emacs, or change it to use saner
 values.  To do the latter, you can stick the following in your .emacs file:
 
-(defun c-lineup-arglist-tabs-only (ignored)
-  "Line up argument lists by tabs, not spaces"
-  (let* ((anchor (c-langelem-pos c-syntactic-element))
-         (column (c-langelem-2nd-pos c-syntactic-element))
-         (offset (- (1+ column) anchor))
-         (steps (floor offset c-basic-offset)))
-    (* (max steps 1)
-       c-basic-offset)))
+.. code-block:: none
 
-(add-hook 'c-mode-common-hook
-          (lambda ()
-            ;; Add kernel style
-            (c-add-style
-             "linux-tabs-only"
-             '("linux" (c-offsets-alist
-                        (arglist-cont-nonempty
-                         c-lineup-gcc-asm-reg
-                         c-lineup-arglist-tabs-only))))))
+  (defun c-lineup-arglist-tabs-only (ignored)
+    "Line up argument lists by tabs, not spaces"
+    (let* ((anchor (c-langelem-pos c-syntactic-element))
+           (column (c-langelem-2nd-pos c-syntactic-element))
+           (offset (- (1+ column) anchor))
+           (steps (floor offset c-basic-offset)))
+      (* (max steps 1)
+         c-basic-offset)))
 
-(add-hook 'c-mode-hook
-          (lambda ()
-            (let ((filename (buffer-file-name)))
-              ;; Enable kernel mode for the appropriate files
-              (when (and filename
-                         (string-match (expand-file-name "~/src/linux-trees")
-                                       filename))
-                (setq indent-tabs-mode t)
-                (setq show-trailing-whitespace t)
-                (c-set-style "linux-tabs-only")))))
+  (add-hook 'c-mode-common-hook
+            (lambda ()
+              ;; Add kernel style
+              (c-add-style
+               "linux-tabs-only"
+               '("linux" (c-offsets-alist
+                          (arglist-cont-nonempty
+                           c-lineup-gcc-asm-reg
+                           c-lineup-arglist-tabs-only))))))
+
+  (add-hook 'c-mode-hook
+            (lambda ()
+              (let ((filename (buffer-file-name)))
+                ;; Enable kernel mode for the appropriate files
+                (when (and filename
+                           (string-match (expand-file-name "~/src/linux-trees")
+                                         filename))
+                  (setq indent-tabs-mode t)
+                  (setq show-trailing-whitespace t)
+                  (c-set-style "linux-tabs-only")))))
 
 This will make emacs go better with the kernel coding style for C
-files below ~/src/linux-trees.
+files below ``~/src/linux-trees``.
 
 But even if you fail in getting emacs to do sane formatting, not
 everything is lost: use "indent".
@@ -562,14 +631,17 @@ re-formatting you may want to take a look at the man page.  But
 remember: "indent" is not a fix for bad programming.
 
 
-		Chapter 10: Kconfig configuration files
+Kconfig configuration files
+---------------------------
 
 For all of the Kconfig* configuration files throughout the source tree,
 the indentation is somewhat different.  Lines under a "config" definition
 are indented with one tab, while help text is indented an additional two
 spaces.  Example:
 
-config AUDIT
+::
+
+  config AUDIT
 	bool "Auditing support"
 	depends on NET
 	help
@@ -581,7 +653,9 @@ config AUDIT
 Seriously dangerous features (such as write support for certain
 filesystems) should advertise this prominently in their prompt string:
 
-config ADFS_FS_RW
+::
+
+  config ADFS_FS_RW
 	bool "ADFS write support (DANGEROUS)"
 	depends on ADFS_FS
 	...
@@ -590,7 +664,8 @@ For full documentation on the configuration files, see the file
 Documentation/kbuild/kconfig-language.txt.
 
 
-		Chapter 11: Data structures
+Data structures
+---------------
 
 Data structures that have visibility outside the single-threaded
 environment they are created and destroyed in should always have
@@ -621,10 +696,13 @@ Remember: if another thread can find your data structure, and you don't
 have a reference count on it, you almost certainly have a bug.
 
 
-		Chapter 12: Macros, Enums and RTL
+Macros, Enums and RTL
+---------------------
 
 Names of macros defining constants and labels in enums are capitalized.
 
+.. code-block:: c
+
 	#define CONSTANT 0x12345
 
 Enums are preferred when defining several related constants.
@@ -636,6 +714,8 @@ Generally, inline functions are preferable to macros resembling functions.
 
 Macros with multiple statements should be enclosed in a do - while block:
 
+.. code-block:: c
+
 	#define macrofun(a, b, c) 			\
 		do {					\
 			if (a == 5)			\
@@ -646,6 +726,8 @@ Things to avoid when using macros:
 
 1) macros that affect control flow:
 
+.. code-block:: c
+
 	#define FOO(x)					\
 		do {					\
 			if (blah(x) < 0)		\
@@ -657,6 +739,8 @@ function; don't break the internal parsers of those who will read the code.
 
 2) macros that depend on having a local variable with a magic name:
 
+.. code-block:: c
+
 	#define FOO(val) bar(index, val)
 
 might look like a good thing, but it's confusing as hell when one reads the
@@ -669,18 +753,22 @@ bite you if somebody e.g. turns FOO into an inline function.
 must enclose the expression in parentheses. Beware of similar issues with
 macros using parameters.
 
+.. code-block:: c
+
 	#define CONSTANT 0x4000
 	#define CONSTEXP (CONSTANT | 3)
 
 5) namespace collisions when defining local variables in macros resembling
 functions:
 
-#define FOO(x)				\
-({					\
-	typeof(x) ret;			\
-	ret = calc_ret(x);		\
-	(ret);				\
-})
+.. code-block:: c
+
+	#define FOO(x)				\
+	({					\
+		typeof(x) ret;			\
+		ret = calc_ret(x);		\
+		(ret);				\
+	})
 
 ret is a common name for a local variable - __foo_ret is less likely
 to collide with an existing variable.
@@ -689,7 +777,8 @@ The cpp manual deals with macros exhaustively. The gcc internals manual also
 covers RTL which is used frequently with assembly language in the kernel.
 
 
-		Chapter 13: Printing kernel messages
+Printing kernel messages
+------------------------
 
 Kernel developers like to be seen as literate. Do mind the spelling
 of kernel messages to make a good impression. Do not use crippled
@@ -723,7 +812,8 @@ already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be
 used.
 
 
-		Chapter 14: Allocating memory
+Allocating memory
+------------------
 
 The kernel provides the following general purpose memory allocators:
 kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and
@@ -732,6 +822,8 @@ about them.
 
 The preferred form for passing a size of a struct is the following:
 
+.. code-block:: c
+
 	p = kmalloc(sizeof(*p), ...);
 
 The alternative form where struct name is spelled out hurts readability and
@@ -744,17 +836,22 @@ language.
 
 The preferred form for allocating an array is the following:
 
+.. code-block:: c
+
 	p = kmalloc_array(n, sizeof(...), ...);
 
 The preferred form for allocating a zeroed array is the following:
 
+.. code-block:: c
+
 	p = kcalloc(n, sizeof(...), ...);
 
 Both forms check for overflow on the allocation size n * sizeof(...),
 and return NULL if that occurred.
 
 
-		Chapter 15: The inline disease
+The inline disease
+------------------
 
 There appears to be a common misperception that gcc has a magic "make me
 faster" speedup option called "inline". While the use of inlines can be
@@ -781,7 +878,8 @@ appears outweighs the potential value of the hint that tells gcc to do
 something it would have done anyway.
 
 
-		Chapter 16: Function return values and names
+Function return values and names
+--------------------------------
 
 Functions can return values of many different kinds, and one of the
 most common is a value indicating whether the function succeeded or
@@ -795,6 +893,8 @@ between integers and booleans then the compiler would find these mistakes
 for us... but it doesn't.  To help prevent such bugs, always follow this
 convention:
 
+::
+
 	If the name of a function is an action or an imperative command,
 	the function should return an error-code integer.  If the name
 	is a predicate, the function should return a "succeeded" boolean.
@@ -815,17 +915,22 @@ result.  Typical examples would be functions that return pointers; they use
 NULL or the ERR_PTR mechanism to report failure.
 
 
-		Chapter 17:  Don't re-invent the kernel macros
+Don't re-invent the kernel macros
+---------------------------------
 
 The header file include/linux/kernel.h contains a number of macros that
 you should use, rather than explicitly coding some variant of them yourself.
 For example, if you need to calculate the length of an array, take advantage
 of the macro
 
+.. code-block:: c
+
 	#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
 
 Similarly, if you need to calculate the size of some structure member, use
 
+.. code-block:: c
+
 	#define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f))
 
 There are also min() and max() macros that do strict type checking if you
@@ -833,16 +938,21 @@ need them.  Feel free to peruse that header file to see what else is already
 defined that you shouldn't reproduce in your code.
 
 
-		Chapter 18:  Editor modelines and other cruft
+Editor modelines and other cruft
+--------------------------------
 
 Some editors can interpret configuration information embedded in source files,
 indicated with special markers.  For example, emacs interprets lines marked
 like this:
 
+.. code-block:: c
+
 	-*- mode: c -*-
 
 Or like this:
 
+.. code-block:: c
+
 	/*
 	Local Variables:
 	compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
@@ -851,6 +961,8 @@ Or like this:
 
 Vim interprets markers that look like this:
 
+.. code-block:: c
+
 	/* vim:set sw=8 noet */
 
 Do not include any of these in source files.  People have their own personal
@@ -860,7 +972,8 @@ own custom mode, or may have some other magic method for making indentation
 work correctly.
 
 
-		Chapter 19:  Inline assembly
+Inline assembly
+---------------
 
 In architecture-specific code, you may need to use inline assembly to interface
 with CPU or platform functionality.  Don't hesitate to do so when necessary.
@@ -884,12 +997,15 @@ instructions, put each instruction on a separate line in a separate quoted
 string, and end each string except the last with \n\t to properly indent the
 next instruction in the assembly output:
 
+.. code-block:: c
+
 	asm ("magic %reg1, #42\n\t"
 	     "more_magic %reg2, %reg3"
 	     : /* outputs */ : /* inputs */ : /* clobbers */);
 
 
-		Chapter 20: Conditional Compilation
+Conditional Compilation
+-----------------------
 
 Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c
 files; doing so makes code harder to read and logic harder to follow.  Instead,
@@ -913,6 +1029,8 @@ unused, delete it.)
 Within code, where possible, use the IS_ENABLED macro to convert a Kconfig
 symbol into a C boolean expression, and use it in a normal C conditional:
 
+.. code-block:: c
+
 	if (IS_ENABLED(CONFIG_SOMETHING)) {
 		...
 	}
@@ -928,12 +1046,15 @@ At the end of any non-trivial #if or #ifdef block (more than a few lines),
 place a comment after the #endif on the same line, noting the conditional
 expression used.  For instance:
 
+.. code-block:: c
+
 	#ifdef CONFIG_SOMETHING
 	...
 	#endif /* CONFIG_SOMETHING */
 
 
-		Appendix I: References
+Appendix I: References
+----------------------
 
 The C Programming Language, Second Edition
 by Brian W. Kernighan and Dennis M. Ritchie.
-- 
2.7.4

Re: [PATCH v2 05/20] docs-rst: CodingStyle.rst: Convert to ReST markup

[Joe Perches]

On Mon, 2016-09-12 at 23:17 -0300, Mauro Carvalho Chehab wrote:
> - Fix all chapter identation;
> - add c blocks where needed;

Assuming this is really useful and people agree with simple
conversions of .txt to .rst (and it does have some use),
there are a couple funky conversions

	if (condition)
		do_this();
	else
		do_that();

do_that() is oddly displayed in the code_block

and in the "Spaces" section, the pointer description is wrong

"\* is adjacent"

other than that, looks good to me.
> 

Re: [PATCH v2 05/20] docs-rst: CodingStyle.rst: Convert to ReST markup

[Mauro Carvalho Chehab]

Em Mon, 12 Sep 2016 19:59:00 -0700
Joe Perches <joe@perches.com> escreveu:

> On Mon, 2016-09-12 at 23:17 -0300, Mauro Carvalho Chehab wrote:
> > - Fix all chapter identation;
> > - add c blocks where needed;  
> 
> Assuming this is really useful and people agree with simple
> conversions of .txt to .rst (and it does have some use),
> there are a couple funky conversions
> 
> 	if (condition)
> 		do_this();
> 	else
> 		do_that();
> 
> do_that() is oddly displayed in the code_block

Yeah, Sphinx uses pygments to colorize C blocks, with seems to be buggy.

We could use a block of type none, forcing it to not using pygments.
The question is: should we do it for just this block, for the entire
file or for all ReST files?

> 
> and in the "Spaces" section, the pointer description is wrong
> 
> "\* is adjacent"
> 
> other than that, looks good to me.

Thanks for review!

The following fixup patch should address the two pointed issues. I took
the shortest path: I just avoided highlights at the if/else block that
looked odd.

If you agree that this is the best solution, I'll fold it with the original
patch on a next version of this patchset.

Regards,
Mauro


diff --git a/Documentation/development-process/CodingStyle.rst b/Documentation/development-process/CodingStyle.rst
index 510063361b04..56f4a42922ab 100644
--- a/Documentation/development-process/CodingStyle.rst
+++ b/Documentation/development-process/CodingStyle.rst
@@ -181,7 +181,7 @@ Do not unnecessarily use braces where a single statement will do.
 
 and
 
-.. code-block:: c
+.. code-block:: none
 
 	if (condition)
 		do_this();
@@ -232,7 +232,7 @@ Do not add spaces around (inside) parenthesized expressions.  This example is
 	s = sizeof( struct file );
 
 When declaring pointer data or a function that returns a pointer type, the
-preferred use of ``\*`` is adjacent to the data name or function name and not
+preferred use of ``*`` is adjacent to the data name or function name and not
 adjacent to the type name.  Examples:
 
 .. code-block:: c

Thanks,
Mauro

[PATCH v2 06/20] CodingStyle.rst: use the proper tag for verbatim font

[Mauro Carvalho Chehab]

Instead of using "foo", use ``foo`` for the names that are
literal.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/development-process/CodingStyle.rst | 98 +++++++++++------------
 1 file changed, 49 insertions(+), 49 deletions(-)

diff --git a/Documentation/development-process/CodingStyle.rst b/Documentation/development-process/CodingStyle.rst
index 3bc022b43ed8..4b2ba1008b11 100644
--- a/Documentation/development-process/CodingStyle.rst
+++ b/Documentation/development-process/CodingStyle.rst
@@ -38,8 +38,8 @@ benefit of warning you when you're nesting your functions too deep.
 Heed that warning.
 
 The preferred way to ease multiple indentation levels in a switch statement is
-to align the "switch" and its subordinate "case" labels in the same column
-instead of "double-indenting" the "case" labels.  E.g.:
+to align the ``switch`` and its subordinate ``case`` labels in the same column
+instead of ``double-indenting`` the ``case`` labels.  E.g.:
 
 .. code-block:: c
 
@@ -142,7 +142,7 @@ special anyway (you can't nest them in C).
 
 Note that the closing brace is empty on a line of its own, _except_ in
 the cases where it is followed by a continuation of the same statement,
-ie a "while" in a do-statement or an "else" in an if-statement, like
+ie a ``while`` in a do-statement or an ``else`` in an if-statement, like
 this:
 
 .. code-block:: c
@@ -231,7 +231,7 @@ Do not add spaces around (inside) parenthesized expressions.  This example is
 	s = sizeof( struct file );
 
 When declaring pointer data or a function that returns a pointer type, the
-preferred use of '\*' is adjacent to the data name or function name and not
+preferred use of ``\*`` is adjacent to the data name or function name and not
 adjacent to the type name.  Examples:
 
 .. code-block:: c
@@ -266,10 +266,10 @@ no space after the prefix increment & decrement unary operators:
 
 	++  --
 
-and no space around the '.' and "->" structure member operators.
+and no space around the ``.`` and ``->`` structure member operators.
 
 Do not leave trailing whitespace at the ends of lines.  Some editors with
-"smart" indentation will insert whitespace at the beginning of new lines as
+``smart`` indentation will insert whitespace at the beginning of new lines as
 appropriate, so you can start typing the next line of code right away.
 However, some such editors do not remove the whitespace if you end up not
 putting a line of code there, such as if you leave a blank line.  As a result,
@@ -287,17 +287,17 @@ Naming
 C is a Spartan language, and so should your naming be.  Unlike Modula-2
 and Pascal programmers, C programmers do not use cute names like
 ThisVariableIsATemporaryCounter.  A C programmer would call that
-variable "tmp", which is much easier to write, and not the least more
+variable ``tmp``, which is much easier to write, and not the least more
 difficult to understand.
 
 HOWEVER, while mixed-case names are frowned upon, descriptive names for
-global variables are a must.  To call a global function "foo" is a
+global variables are a must.  To call a global function ``foo`` is a
 shooting offense.
 
 GLOBAL variables (to be used only if you _really_ need them) need to
 have descriptive names, as do global functions.  If you have a function
 that counts the number of active users, you should call that
-"count_active_users()" or similar, you should _not_ call it "cntusr()".
+``count_active_users()`` or similar, you should _not_ call it ``cntusr()``.
 
 Encoding the type of a function into the name (so-called Hungarian
 notation) is brain damaged - the compiler knows the types anyway and can
@@ -305,9 +305,9 @@ check those, and it only confuses the programmer.  No wonder MicroSoft
 makes buggy programs.
 
 LOCAL variable names should be short, and to the point.  If you have
-some random integer loop counter, it should probably be called "i".
-Calling it "loop_counter" is non-productive, if there is no chance of it
-being mis-understood.  Similarly, "tmp" can be just about any type of
+some random integer loop counter, it should probably be called ``i``.
+Calling it ``loop_counter`` is non-productive, if there is no chance of it
+being mis-understood.  Similarly, ``tmp`` can be just about any type of
 variable that is used to hold a temporary value.
 
 If you are afraid to mix up your local variable names, you have another
@@ -318,7 +318,7 @@ See chapter 6 (Functions).
 Typedefs
 --------
 
-Please don't use things like "vps_t".
+Please don't use things like ``vps_t``.
 It's a _mistake_ to use typedef for structures and pointers. When you see a
 
 .. code-block:: c
@@ -333,35 +333,35 @@ In contrast, if it says
 
 	struct virtual_container *a;
 
-you can actually tell what "a" is.
+you can actually tell what ``a`` is.
 
-Lots of people think that typedefs "help readability". Not so. They are
+Lots of people think that typedefs ``help readability``. Not so. They are
 useful only for:
 
  (a) totally opaque objects (where the typedef is actively used to _hide_
      what the object is).
 
-     Example: "pte_t" etc. opaque objects that you can only access using
+     Example: ``pte_t`` etc. opaque objects that you can only access using
      the proper accessor functions.
 
-     NOTE! Opaqueness and "accessor functions" are not good in themselves.
+     NOTE! Opaqueness and ``accessor functions`` are not good in themselves.
      The reason we have them for things like pte_t etc. is that there
      really is absolutely _zero_ portably accessible information there.
 
  (b) Clear integer types, where the abstraction _helps_ avoid confusion
-     whether it is "int" or "long".
+     whether it is ``int`` or ``long``.
 
      u8/u16/u32 are perfectly fine typedefs, although they fit into
      category (d) better than here.
 
      NOTE! Again - there needs to be a _reason_ for this. If something is
-     "unsigned long", then there's no reason to do
+     ``unsigned long``, then there's no reason to do
 
 	typedef unsigned long myflags_t;
 
      but if there is a clear reason for why it under certain circumstances
-     might be an "unsigned int" and under other configurations might be
-     "unsigned long", then by all means go ahead and use a typedef.
+     might be an ``unsigned int`` and under other configurations might be
+     ``unsigned long``, then by all means go ahead and use a typedef.
 
  (c) when you use sparse to literally create a _new_ type for
      type-checking.
@@ -370,10 +370,10 @@ useful only for:
      exceptional circumstances.
 
      Although it would only take a short amount of time for the eyes and
-     brain to become accustomed to the standard types like 'uint32_t',
+     brain to become accustomed to the standard types like ``uint32_t``,
      some people object to their use anyway.
 
-     Therefore, the Linux-specific 'u8/u16/u32/u64' types and their
+     Therefore, the Linux-specific ``u8/u16/u32/u64`` types and their
      signed equivalents which are identical to standard types are
      permitted -- although they are not mandatory in new code of your
      own.
@@ -384,7 +384,7 @@ useful only for:
  (e) Types safe for use in userspace.
 
      In certain structures which are visible to userspace, we cannot
-     require C99 types and cannot use the 'u32' form above. Thus, we
+     require C99 types and cannot use the ``u32`` form above. Thus, we
      use __u32 and similar types in all structures which are shared
      with userspace.
 
@@ -451,13 +451,13 @@ locations and some common work such as cleanup has to be done.  If there is no
 cleanup needed then just return directly.
 
 Choose label names which say what the goto does or why the goto exists.  An
-example of a good name could be "out_free_buffer:" if the goto frees "buffer".
-Avoid using GW-BASIC names like "err1:" and "err2:", as you would have to
+example of a good name could be ``out_free_buffer:`` if the goto frees ``buffer``.
+Avoid using GW-BASIC names like ``err1:`` and ``err2:``, as you would have to
 renumber them if you ever add or remove exit paths, and they make correctness
 difficult to verify anyway.
 
 It is advised to indent labels with a single space (not tab), so that
-"diff -p" does not confuse labels with functions.
+``diff -p`` does not confuse labels with functions.
 
 The rationale for using gotos is:
 
@@ -491,7 +491,7 @@ The rationale for using gotos is:
 		return result;
 	}
 
-A common type of bug to be aware of is "one err bugs" which look like this:
+A common type of bug to be aware of is ``one err bugs`` which look like this:
 
 .. code-block:: c
 
@@ -500,9 +500,9 @@ A common type of bug to be aware of is "one err bugs" which look like this:
 		kfree(foo);
 		return ret;
 
-The bug in this code is that on some exit paths "foo" is NULL.  Normally the
-fix for this is to split it up into two error labels "err_free_bar:" and
-"err_free_foo:":
+The bug in this code is that on some exit paths ``foo`` is NULL.  Normally the
+fix for this is to split it up into two error labels ``err_free_bar:`` and
+``err_free_foo:``:
 
 .. code-block:: c
 
@@ -571,7 +571,7 @@ You've made a mess of it
 ------------------------
 
 That's OK, we all do.  You've probably been told by your long-time Unix
-user helper that "GNU emacs" automatically formats the C sources for
+user helper that ``GNU emacs`` automatically formats the C sources for
 you, and you've noticed that yes, it does do that, but the defaults it
 uses are less than desirable (in fact, they are worse than random
 typing - an infinite number of monkeys typing into GNU emacs would never
@@ -616,26 +616,26 @@ This will make emacs go better with the kernel coding style for C
 files below ``~/src/linux-trees``.
 
 But even if you fail in getting emacs to do sane formatting, not
-everything is lost: use "indent".
+everything is lost: use ``indent``.
 
 Now, again, GNU indent has the same brain-dead settings that GNU emacs
 has, which is why you need to give it a few command line options.
 However, that's not too bad, because even the makers of GNU indent
 recognize the authority of K&R (the GNU people aren't evil, they are
 just severely misguided in this matter), so you just give indent the
-options "-kr -i8" (stands for "K&R, 8 character indents"), or use
-"scripts/Lindent", which indents in the latest style.
+options ``-kr -i8`` (stands for ``K&R, 8 character indents``), or use
+``scripts/Lindent``, which indents in the latest style.
 
-"indent" has a lot of options, and especially when it comes to comment
+``indent`` has a lot of options, and especially when it comes to comment
 re-formatting you may want to take a look at the man page.  But
-remember: "indent" is not a fix for bad programming.
+remember: ``indent`` is not a fix for bad programming.
 
 
 Kconfig configuration files
 ---------------------------
 
 For all of the Kconfig* configuration files throughout the source tree,
-the indentation is somewhat different.  Lines under a "config" definition
+the indentation is somewhat different.  Lines under a ``config`` definition
 are indented with one tab, while help text is indented an additional two
 spaces.  Example:
 
@@ -684,13 +684,13 @@ counting is a memory management technique.  Usually both are needed, and
 they are not to be confused with each other.
 
 Many data structures can indeed have two levels of reference counting,
-when there are users of different "classes".  The subclass count counts
+when there are users of different ``classes``.  The subclass count counts
 the number of subclass users, and decrements the global count just once
 when the subclass count goes to zero.
 
-Examples of this kind of "multi-level-reference-counting" can be found in
-memory management ("struct mm_struct": mm_users and mm_count), and in
-filesystem code ("struct super_block": s_count and s_active).
+Examples of this kind of ``multi-level-reference-counting`` can be found in
+memory management (``struct mm_struct``: mm_users and mm_count), and in
+filesystem code (``struct super_block``: s_count and s_active).
 
 Remember: if another thread can find your data structure, and you don't
 have a reference count on it, you almost certainly have a bug.
@@ -734,7 +734,7 @@ Things to avoid when using macros:
 				return -EBUGGERED;	\
 		} while (0)
 
-is a _very_ bad idea.  It looks like a function call but exits the "calling"
+is a _very_ bad idea.  It looks like a function call but exits the ``calling``
 function; don't break the internal parsers of those who will read the code.
 
 2) macros that depend on having a local variable with a magic name:
@@ -782,7 +782,7 @@ Printing kernel messages
 
 Kernel developers like to be seen as literate. Do mind the spelling
 of kernel messages to make a good impression. Do not use crippled
-words like "dont"; use "do not" or "don't" instead.  Make the messages
+words like ``dont``; use ``do not`` or ``don't`` instead.  Make the messages
 concise, clear, and unambiguous.
 
 Kernel messages do not have to be terminated with a period.
@@ -854,7 +854,7 @@ The inline disease
 ------------------
 
 There appears to be a common misperception that gcc has a magic "make me
-faster" speedup option called "inline". While the use of inlines can be
+faster" speedup option called ``inline``. While the use of inlines can be
 appropriate (for example as a means of replacing macros, see Chapter 12), it
 very often is not. Abundant use of the inline keyword leads to a much bigger
 kernel, which in turn slows the system as a whole down, due to a bigger
@@ -884,7 +884,7 @@ Function return values and names
 Functions can return values of many different kinds, and one of the
 most common is a value indicating whether the function succeeded or
 failed.  Such a value can be represented as an error-code integer
-(-Exxx = failure, 0 = success) or a "succeeded" boolean (0 = failure,
+(-Exxx = failure, 0 = success) or a ``succeeded`` boolean (0 = failure,
 non-zero = success).
 
 Mixing up these two sorts of representations is a fertile source of
@@ -899,8 +899,8 @@ convention:
 	the function should return an error-code integer.  If the name
 	is a predicate, the function should return a "succeeded" boolean.
 
-For example, "add work" is a command, and the add_work() function returns 0
-for success or -EBUSY for failure.  In the same way, "PCI device present" is
+For example, ``add work`` is a command, and the add_work() function returns 0
+for success or -EBUSY for failure.  In the same way, ``PCI device present`` is
 a predicate, and the pci_dev_present() function returns 1 if it succeeds in
 finding a matching device or 0 if it doesn't.
 
@@ -986,7 +986,7 @@ that inline assembly can use C parameters.
 
 Large, non-trivial assembly functions should go in .S files, with corresponding
 C prototypes defined in C header files.  The C prototypes for assembly
-functions should use "asmlinkage".
+functions should use ``asmlinkage``.
 
 You may need to mark your asm statement as volatile, to prevent GCC from
 removing it if GCC doesn't notice any side effects.  You don't always need to
-- 
2.7.4

[PATCH v2 07/20] CodingStyle.rst: replace underline markups

[Mauro Carvalho Chehab]

Sphinx doesn't accept underline markups by purpose. While we might
hack it via CSS, this won't be portable with non-html outputs.

So, let's replace those by bold.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/development-process/CodingStyle.rst | 32 +++++++++++------------
 1 file changed, 16 insertions(+), 16 deletions(-)

diff --git a/Documentation/development-process/CodingStyle.rst b/Documentation/development-process/CodingStyle.rst
index 4b2ba1008b11..1829b1ad7ef8 100644
--- a/Documentation/development-process/CodingStyle.rst
+++ b/Documentation/development-process/CodingStyle.rst
@@ -3,7 +3,7 @@ Linux kernel coding style
 =========================
 
 This is a short document describing the preferred coding style for the
-linux kernel.  Coding style is very personal, and I won't _force_ my
+linux kernel.  Coding style is very personal, and I won't **force** my
 views on anybody, but this is what goes for anything that I have to be
 able to maintain, and I'd prefer it for most other things too.  Please
 at least consider the points made here.
@@ -137,10 +137,10 @@ opening brace at the beginning of the next line, thus:
 
 Heretic people all over the world have claimed that this inconsistency
 is ...  well ...  inconsistent, but all right-thinking people know that
-(a) K&R are _right_ and (b) K&R are right.  Besides, functions are
+(a) K&R are **right** and (b) K&R are right.  Besides, functions are
 special anyway (you can't nest them in C).
 
-Note that the closing brace is empty on a line of its own, _except_ in
+Note that the closing brace is empty on a line of its own, **except** in
 the cases where it is followed by a continuation of the same statement,
 ie a ``while`` in a do-statement or an ``else`` in an if-statement, like
 this:
@@ -294,10 +294,10 @@ HOWEVER, while mixed-case names are frowned upon, descriptive names for
 global variables are a must.  To call a global function ``foo`` is a
 shooting offense.
 
-GLOBAL variables (to be used only if you _really_ need them) need to
+GLOBAL variables (to be used only if you **really** need them) need to
 have descriptive names, as do global functions.  If you have a function
 that counts the number of active users, you should call that
-``count_active_users()`` or similar, you should _not_ call it ``cntusr()``.
+``count_active_users()`` or similar, you should **not** call it ``cntusr()``.
 
 Encoding the type of a function into the name (so-called Hungarian
 notation) is brain damaged - the compiler knows the types anyway and can
@@ -319,7 +319,7 @@ Typedefs
 --------
 
 Please don't use things like ``vps_t``.
-It's a _mistake_ to use typedef for structures and pointers. When you see a
+It's a **mistake** to use typedef for structures and pointers. When you see a
 
 .. code-block:: c
 
@@ -338,7 +338,7 @@ you can actually tell what ``a`` is.
 Lots of people think that typedefs ``help readability``. Not so. They are
 useful only for:
 
- (a) totally opaque objects (where the typedef is actively used to _hide_
+ (a) totally opaque objects (where the typedef is actively used to **hide**
      what the object is).
 
      Example: ``pte_t`` etc. opaque objects that you can only access using
@@ -346,15 +346,15 @@ useful only for:
 
      NOTE! Opaqueness and ``accessor functions`` are not good in themselves.
      The reason we have them for things like pte_t etc. is that there
-     really is absolutely _zero_ portably accessible information there.
+     really is absolutely **zero** portably accessible information there.
 
- (b) Clear integer types, where the abstraction _helps_ avoid confusion
+ (b) Clear integer types, where the abstraction **helps** avoid confusion
      whether it is ``int`` or ``long``.
 
      u8/u16/u32 are perfectly fine typedefs, although they fit into
      category (d) better than here.
 
-     NOTE! Again - there needs to be a _reason_ for this. If something is
+     NOTE! Again - there needs to be a **reason** for this. If something is
      ``unsigned long``, then there's no reason to do
 
 	typedef unsigned long myflags_t;
@@ -363,7 +363,7 @@ useful only for:
      might be an ``unsigned int`` and under other configurations might be
      ``unsigned long``, then by all means go ahead and use a typedef.
 
- (c) when you use sparse to literally create a _new_ type for
+ (c) when you use sparse to literally create a **new** type for
      type-checking.
 
  (d) New types which are identical to standard C99 types, in certain
@@ -392,7 +392,7 @@ Maybe there are other cases too, but the rule should basically be to NEVER
 EVER use a typedef unless you can clearly match one of those rules.
 
 In general, a pointer, or a struct that has elements that can reasonably
-be directly accessed should _never_ be a typedef.
+be directly accessed should **never** be a typedef.
 
 
 Functions
@@ -520,7 +520,7 @@ Commenting
 
 Comments are good, but there is also a danger of over-commenting.  NEVER
 try to explain HOW your code works in a comment: it's much better to
-write the code so that the _working_ is obvious, and it's a waste of
+write the code so that the **working** is obvious, and it's a waste of
 time to explain badly written code.
 
 Generally, you want your comments to tell WHAT your code does, not HOW.
@@ -671,14 +671,14 @@ Data structures that have visibility outside the single-threaded
 environment they are created and destroyed in should always have
 reference counts.  In the kernel, garbage collection doesn't exist (and
 outside the kernel garbage collection is slow and inefficient), which
-means that you absolutely _have_ to reference count all your uses.
+means that you absolutely **have** to reference count all your uses.
 
 Reference counting means that you can avoid locking, and allows multiple
 users to have access to the data structure in parallel - and not having
 to worry about the structure suddenly going away from under them just
 because they slept or did something else for a while.
 
-Note that locking is _not_ a replacement for reference counting.
+Note that locking is **not** a replacement for reference counting.
 Locking is used to keep data structures coherent, while reference
 counting is a memory management technique.  Usually both are needed, and
 they are not to be confused with each other.
@@ -734,7 +734,7 @@ Things to avoid when using macros:
 				return -EBUGGERED;	\
 		} while (0)
 
-is a _very_ bad idea.  It looks like a function call but exits the ``calling``
+is a **very** bad idea.  It looks like a function call but exits the ``calling``
 function; don't break the internal parsers of those who will read the code.
 
 2) macros that depend on having a local variable with a magic name:
-- 
2.7.4

[PATCH v2 08/20] CodingStyle.rst: use the .. note:: markup where needed

[Mauro Carvalho Chehab]

There are two places there where there are notes that should
be bold. So, use the right markup for that.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/development-process/CodingStyle.rst | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/Documentation/development-process/CodingStyle.rst b/Documentation/development-process/CodingStyle.rst
index 1829b1ad7ef8..d9debafbd2eb 100644
--- a/Documentation/development-process/CodingStyle.rst
+++ b/Documentation/development-process/CodingStyle.rst
@@ -344,9 +344,11 @@ useful only for:
      Example: ``pte_t`` etc. opaque objects that you can only access using
      the proper accessor functions.
 
-     NOTE! Opaqueness and ``accessor functions`` are not good in themselves.
-     The reason we have them for things like pte_t etc. is that there
-     really is absolutely **zero** portably accessible information there.
+     .. note::
+
+       Opaqueness and ``accessor functions`` are not good in themselves.
+       The reason we have them for things like pte_t etc. is that there
+       really is absolutely **zero** portably accessible information there.
 
  (b) Clear integer types, where the abstraction **helps** avoid confusion
      whether it is ``int`` or ``long``.
@@ -354,8 +356,10 @@ useful only for:
      u8/u16/u32 are perfectly fine typedefs, although they fit into
      category (d) better than here.
 
-     NOTE! Again - there needs to be a **reason** for this. If something is
-     ``unsigned long``, then there's no reason to do
+     .. note::
+
+       Again - there needs to be a **reason** for this. If something is
+       ``unsigned long``, then there's no reason to do
 
 	typedef unsigned long myflags_t;
 
-- 
2.7.4

[PATCH v2 09/20] kernel-docs.rst: convert it to ReST markup

[Mauro Carvalho Chehab]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=true, Size: 70755 bytes --]

This one required lots of manual work, for it to be properly
displayed.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/development-process/kernel-docs.rst | 1514 +++++++++++----------
 1 file changed, 786 insertions(+), 728 deletions(-)

diff --git a/Documentation/development-process/kernel-docs.rst b/Documentation/development-process/kernel-docs.rst
index 1dafc52167b0..7ca806184426 100644
--- a/Documentation/development-process/kernel-docs.rst
+++ b/Documentation/development-process/kernel-docs.rst
@@ -1,731 +1,789 @@
-
-    Index of Documentation for People Interested in Writing and/or
-
-                   Understanding the Linux Kernel.
+Index of Documentation for People Interested in Writing and/or Understanding the Linux Kernel
+=============================================================================================
 
           Juan-Mariano de Goyeneche <jmseyas@dit.upm.es>
 
-/*
- * The latest version of this document may be found at:
- *   http://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html
- */
-
-   The need for a document like this one became apparent in the
-   linux-kernel mailing list as the same questions, asking for pointers
-   to information, appeared again and again.
-   
-   Fortunately, as more and more people get to GNU/Linux, more and more
-   get interested in the Kernel. But reading the sources is not always
-   enough. It is easy to understand the code, but miss the concepts, the
-   philosophy and design decisions behind this code.
-   
-   Unfortunately, not many documents are available for beginners to
-   start. And, even if they exist, there was no "well-known" place which
-   kept track of them. These lines try to cover this lack. All documents
-   available on line known by the author are listed, while some reference
-   books are also mentioned.
-   
-   PLEASE, if you know any paper not listed here or write a new document,
-   send me an e-mail, and I'll include a reference to it here. Any
-   corrections, ideas or comments are also welcomed.
-   
-   The papers that follow are listed in no particular order. All are
-   cataloged with the following fields: the document's "Title", the
-   "Author"/s, the "URL" where they can be found, some "Keywords" helpful
-   when searching for specific topics, and a brief "Description" of the
-   Document.
-   
-   Enjoy!
-   
-     ON-LINE DOCS:
-       
-     * Title: "Linux Device Drivers, Third Edition"
-       Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman
-       URL: http://lwn.net/Kernel/LDD3/
-       Description: A 600-page book covering the (2.6.10) driver
-       programming API and kernel hacking in general.  Available under the
-       Creative Commons Attribution-ShareAlike 2.0 license.
-
-     * Title: "The Linux Kernel"
-       Author: David A. Rusling.
-       URL: http://www.tldp.org/LDP/tlk/tlk.html
-       Keywords: everything!, book.
-       Description: On line, 200 pages book describing most aspects of
-       the Linux Kernel. Probably, the first reference for beginners.
-       Lots of illustrations explaining data structures use and
-       relationships in the purest Richard W. Stevens' style. Contents:
-       "1.-Hardware Basics, 2.-Software Basics, 3.-Memory Management,
-       4.-Processes, 5.-Interprocess Communication Mechanisms, 6.-PCI,
-       7.-Interrupts and Interrupt Handling, 8.-Device Drivers, 9.-The
-       File system, 10.-Networks, 11.-Kernel Mechanisms, 12.-Modules,
-       13.-The Linux Kernel Sources, A.-Linux Data Structures, B.-The
-       Alpha AXP Processor, C.-Useful Web and FTP Sites, D.-The GNU
-       General Public License, Glossary". In short: a must have.
-
-     * Title: "Linux Device Drivers, 2nd Edition"
-       Author: Alessandro Rubini and Jonathan Corbet.
-       URL: http://www.xml.com/ldd/chapter/book/index.html
-       Keywords: device drivers, modules, debugging, memory, hardware,
-       interrupt handling, char drivers, block drivers, kmod, mmap, DMA,
-       buses.
-       Description: O'Reilly's popular book, now also on-line under the
-       GNU Free Documentation License.
-       Notes: You can also buy it in paper-form from O'Reilly. See below
-       under BOOKS (Not on-line).
-
-     * Title: "Conceptual Architecture of the Linux Kernel"
-       Author: Ivan T. Bowman.
-       URL: http://plg.uwaterloo.ca/
-       Keywords: conceptual software architecture, extracted design,
-       reverse engineering, system structure.
-       Description: Conceptual software architecture of the Linux kernel,
-       automatically extracted from the source code. Very detailed. Good
-       figures. Gives good overall kernel understanding.
-
-     * Title: "Concrete Architecture of the Linux Kernel"
-       Author: Ivan T. Bowman, Saheem Siddiqi, and Meyer C. Tanuan.
-       URL: http://plg.uwaterloo.ca/
-       Keywords: concrete architecture, extracted design, reverse
-       engineering, system structure, dependencies.
-       Description: Concrete architecture of the Linux kernel,
-       automatically extracted from the source code. Very detailed. Good
-       figures. Gives good overall kernel understanding. This papers
-       focus on lower details than its predecessor (files, variables...).
-
-     * Title: "Linux as a Case Study: Its Extracted Software
-       Architecture"
-       Author: Ivan T. Bowman, Richard C. Holt and Neil V. Brewster.
-       URL: http://plg.uwaterloo.ca/
-       Keywords: software architecture, architecture recovery,
-       redocumentation.
-       Description: Paper appeared at ICSE'99, Los Angeles, May 16-22,
-       1999. A mixture of the previous two documents from the same
-       author.
-
-     * Title: "Overview of the Virtual File System"
-       Author: Richard Gooch.
-       URL: http://www.mjmwired.net/kernel/Documentation/filesystems/vfs.txt
-       Keywords: VFS, File System, mounting filesystems, opening files,
-       dentries, dcache.
-       Description: Brief introduction to the Linux Virtual File System.
-       What is it, how it works, operations taken when opening a file or
-       mounting a file system and description of important data
-       structures explaining the purpose of each of their entries.
-
-     * Title: "The Linux RAID-1, 4, 5 Code"
-       Author: Ingo Molnar, Gadi Oxman and Miguel de Icaza.
-       URL: http://www.linuxjournal.com/article.php?sid=2391
-       Keywords: RAID, MD driver.
-       Description: Linux Journal Kernel Korner article. Here is its
-       abstract: "A description of the implementation of the RAID-1,
-       RAID-4 and RAID-5 personalities of the MD device driver in the
-       Linux kernel, providing users with high performance and reliable,
-       secondary-storage capability using software".
-
-     * Title: "Dynamic Kernels: Modularized Device Drivers"
-       Author: Alessandro Rubini.
-       URL: http://www.linuxjournal.com/article.php?sid=1219
-       Keywords: device driver, module, loading/unloading modules,
-       allocating resources.
-       Description: Linux Journal Kernel Korner article. Here is its
-       abstract: "This is the first of a series of four articles
-       co-authored by Alessandro Rubini and Georg Zezchwitz which present
-       a practical approach to writing Linux device drivers as kernel
-       loadable modules. This installment presents an introduction to the
-       topic, preparing the reader to understand next month's
-       installment".
-
-     * Title: "Dynamic Kernels: Discovery"
-       Author: Alessandro Rubini.
-       URL: http://www.linuxjournal.com/article.php?sid=1220
-       Keywords: character driver, init_module, clean_up module,
-       autodetection, mayor number, minor number, file operations,
-       open(), close().
-       Description: Linux Journal Kernel Korner article. Here is its
-       abstract: "This article, the second of four, introduces part of
-       the actual code to create custom module implementing a character
-       device driver. It describes the code for module initialization and
-       cleanup, as well as the open() and close() system calls".
-
-     * Title: "The Devil's in the Details"
-       Author: Georg v. Zezschwitz and Alessandro Rubini.
-       URL: http://www.linuxjournal.com/article.php?sid=1221
-       Keywords: read(), write(), select(), ioctl(), blocking/non
-       blocking mode, interrupt handler.
-       Description: Linux Journal Kernel Korner article. Here is its
-       abstract: "This article, the third of four on writing character
-       device drivers, introduces concepts of reading, writing, and using
-       ioctl-calls".
-
-     * Title: "Dissecting Interrupts and Browsing DMA"
-       Author: Alessandro Rubini and Georg v. Zezschwitz.
-       URL: http://www.linuxjournal.com/article.php?sid=1222
-       Keywords: interrupts, irqs, DMA, bottom halves, task queues.
-       Description: Linux Journal Kernel Korner article. Here is its
-       abstract: "This is the fourth in a series of articles about
-       writing character device drivers as loadable kernel modules. This
-       month, we further investigate the field of interrupt handling.
-       Though it is conceptually simple, practical limitations and
-       constraints make this an ``interesting'' part of device driver
-       writing, and several different facilities have been provided for
-       different situations. We also investigate the complex topic of
-       DMA".
-
-     * Title: "Device Drivers Concluded"
-       Author: Georg v. Zezschwitz.
-       URL: http://www.linuxjournal.com/article.php?sid=1287
-       Keywords: address spaces, pages, pagination, page management,
-       demand loading, swapping, memory protection, memory mapping, mmap,
-       virtual memory areas (VMAs), vremap, PCI.
-       Description: Finally, the above turned out into a five articles
-       series. This latest one's introduction reads: "This is the last of
-       five articles about character device drivers. In this final
-       section, Georg deals with memory mapping devices, beginning with
-       an overall description of the Linux memory management concepts".
-
-     * Title: "Network Buffers And Memory Management"
-       Author: Alan Cox.
-       URL: http://www.linuxjournal.com/article.php?sid=1312
-       Keywords: sk_buffs, network devices, protocol/link layer
-       variables, network devices flags, transmit, receive,
-       configuration, multicast.
-       Description: Linux Journal Kernel Korner. Here is the abstract:
-       "Writing a network device driver for Linux is fundamentally
-       simple---most of the complexity (other than talking to the
-       hardware) involves managing network packets in memory".
-       
-     * Title: "Linux Kernel Hackers' Guide"
-       Author: Michael K. Johnson.
-       URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html
-       Keywords: device drivers, files, VFS, kernel interface, character vs
-       block devices, hardware interrupts, scsi, DMA, access to user memory,
-       memory allocation, timers.
-       Description: A guide designed to help you get up to speed on the
-       concepts that are not intuitevly obvious, and to document the internal
-       structures of Linux.
-       
-     * Title: "The Venus kernel interface"
-       Author: Peter J. Braam.
-       URL:
-       http://www.coda.cs.cmu.edu/doc/html/kernel-venus-protocol.html
-       Keywords: coda, filesystem, venus, cache manager.
-       Description: "This document describes the communication between
-       Venus and kernel level file system code needed for the operation
-       of the Coda filesystem. This version document is meant to describe
-       the current interface (version 1.0) as well as improvements we
-       envisage".
-
-     * Title: "Programming PCI-Devices under Linux"
-       Author: Claus Schroeter.
-       URL:
-       ftp://ftp.llp.fu-berlin.de/pub/linux/LINUX-LAB/whitepapers/pcip.ps.gz
-       Keywords: PCI, device, busmastering.
-       Description: 6 pages tutorial on PCI programming under Linux.
-       Gives the basic concepts on the architecture of the PCI subsystem,
-       as long as basic functions and macros to read/write the devices
-       and perform busmastering.
-
-     * Title: "Writing Character Device Driver for Linux"
-       Author: R. Baruch and C. Schroeter.
-       URL:
-       ftp://ftp.llp.fu-berlin.de/pub/linux/LINUX-LAB/whitepapers/drivers.ps.gz
-       Keywords: character device drivers, I/O, signals, DMA, accessing
-       ports in user space, kernel environment.
-       Description: 68 pages paper on writing character drivers. A little
-       bit old (1.993, 1.994) although still useful.
-
-     * Title: "Design and Implementation of the Second Extended
-       Filesystem"
-       Author: Rémy Card, Theodore Ts'o, Stephen Tweedie.
-       URL: http://web.mit.edu/tytso/www/linux/ext2intro.html
-       Keywords: ext2, linux fs history, inode, directory, link, devices,
-       VFS, physical structure, performance, benchmarks, ext2fs library,
-       ext2fs tools, e2fsck.
-       Description: Paper written by three of the top ext2 hackers.
-       Covers Linux filesystems history, ext2 motivation, ext2 features,
-       design, physical structure on disk, performance, benchmarks,
-       e2fsck's passes description... A must read!
-       Notes: This paper was first published in the Proceedings of the
-       First Dutch International Symposium on Linux, ISBN 90-367-0385-9.
-
-     * Title: "Analysis of the Ext2fs structure"
-       Author: Louis-Dominique Dubeau.
-       URL: http://teaching.csse.uwa.edu.au/units/CITS2002/fs-ext2/
-       Keywords: ext2, filesystem, ext2fs.
-       Description: Description of ext2's blocks, directories, inodes,
-       bitmaps, invariants...
-
-     * Title: "Journaling the Linux ext2fs Filesystem"
-       Author: Stephen C. Tweedie.
-       URL:
-       ftp://ftp.uk.linux.org/pub/linux/sct/fs/jfs/journal-design.ps.gz
-       Keywords: ext3, journaling.
-       Description: Excellent 8-pages paper explaining the journaling
-       capabilities added to ext2 by the author, showing different
-       problems faced and the alternatives chosen.
-
-     * Title: "Kernel API changes from 2.0 to 2.2"
-       Author: Richard Gooch.
-       URL: http://www.safe-mbox.com/~rgooch/linux/docs/porting-to-2.2.html
-       Keywords: 2.2, changes.
-       Description: Kernel functions/structures/variables which changed
-       from 2.0.x to 2.2.x.
-
-     * Title: "Kernel API changes from 2.2 to 2.4"
-       Author: Richard Gooch.
-       URL: http://www.safe-mbox.com/~rgooch/linux/docs/porting-to-2.4.html
-       Keywords: 2.4, changes.
-       Description: Kernel functions/structures/variables which changed
-       from 2.2.x to 2.4.x.
-       
-     * Title: "Linux Kernel Module Programming Guide"
-       Author: Ori Pomerantz.
-       URL: http://tldp.org/LDP/lkmpg/2.6/html/index.html
-       Keywords: modules, GPL book, /proc, ioctls, system calls,
-       interrupt handlers .
-       Description: Very nice 92 pages GPL book on the topic of modules
-       programming. Lots of examples.
-       
-     * Title: "I/O Event Handling Under Linux"
-       Author: Richard Gooch.
-       Keywords: IO, I/O, select(2), poll(2), FDs, aio_read(2), readiness
-       event queues.
-       Description: From the Introduction: "I/O Event handling is about
-       how your Operating System allows you to manage a large number of
-       open files (file descriptors in UNIX/POSIX, or FDs) in your
-       application. You want the OS to notify you when FDs become active
-       (have data ready to be read or are ready for writing). Ideally you
-       want a mechanism that is scalable. This means a large number of
-       inactive FDs cost very little in memory and CPU time to manage".
-       
-     * Title: "The Kernel Hacking HOWTO"
-       Author: Various Talented People, and Rusty.
-       Location: in kernel tree, Documentation/DocBook/kernel-hacking.tmpl
-       (must be built as "make {htmldocs | psdocs | pdfdocs})
-       Keywords: HOWTO, kernel contexts, deadlock, locking, modules,
-       symbols, return conventions.
-       Description: From the Introduction: "Please understand that I
-       never wanted to write this document, being grossly underqualified,
-       but I always wanted to read it, and this was the only way. I
-       simply explain some best practices, and give reading entry-points
-       into the kernel sources. I avoid implementation details: that's
-       what the code is for, and I ignore whole tracts of useful
-       routines. This document assumes familiarity with C, and an
-       understanding of what the kernel is, and how it is used. It was
-       originally written for the 2.3 kernels, but nearly all of it
-       applies to 2.2 too; 2.0 is slightly different".
-       
-     * Title: "Writing an ALSA Driver"
-       Author: Takashi Iwai <tiwai@suse.de>
-       URL: http://www.alsa-project.org/~iwai/writing-an-alsa-driver/index.html
-       Keywords: ALSA, sound, soundcard, driver, lowlevel, hardware.
-       Description: Advanced Linux Sound Architecture for developers,
-       both at kernel and user-level sides. ALSA is the Linux kernel
-       sound architecture in the 2.6 kernel version.
-       
-     * Title: "Programming Guide for Linux USB Device Drivers"
-       Author: Detlef Fliegl.
-       URL: http://usb.in.tum.de/usbdoc/
-       Keywords: USB, universal serial bus.
-       Description: A must-read. From the Preface: "This document should
-       give detailed information about the current state of the USB
-       subsystem and its API for USB device drivers. The first section
-       will deal with the basics of USB devices. You will learn about
-       different types of devices and their properties. Going into detail
-       you will see how USB devices communicate on the bus. The second
-       section gives an overview of the Linux USB subsystem [2] and the
-       device driver framework. Then the API and its data structures will
-       be explained step by step. The last section of this document
-       contains a reference of all API calls and their return codes".
-       Notes: Beware: the main page states: "This document may not be
-       published, printed or used in excerpts without explicit permission
-       of the author". Fortunately, it may still be read...
-
-     * Title: "Linux Kernel Mailing List Glossary"
-       Author: various
-       URL: http://kernelnewbies.org/glossary/
-       Keywords: glossary, terms, linux-kernel.
-       Description: From the introduction: "This glossary is intended as
-       a brief description of some of the acronyms and terms you may hear
-       during discussion of the Linux kernel".
-       
-     * Title: "Linux Kernel Locking HOWTO"
-       Author: Various Talented People, and Rusty.
-       Location: in kernel tree, Documentation/DocBook/kernel-locking.tmpl
-       (must be built as "make {htmldocs | psdocs | pdfdocs})
-       Keywords: locks, locking, spinlock, semaphore, atomic, race
-       condition, bottom halves, tasklets, softirqs.
-       Description: The title says it all: document describing the
-       locking system in the Linux Kernel either in uniprocessor or SMP
-       systems.
-       Notes: "It was originally written for the later (>2.3.47) 2.3
-       kernels, but most of it applies to 2.2 too; 2.0 is slightly
-       different". Freely redistributable under the conditions of the GNU
-       General Public License.
-
-     * Title: "Global spinlock list and usage"
-       Author: Rick Lindsley.
-       URL: http://lse.sourceforge.net/lockhier/global-spin-lock
-       Keywords: spinlock.
-       Description: This is an attempt to document both the existence and
-       usage of the spinlocks in the Linux 2.4.5 kernel. Comprehensive
-       list of spinlocks showing when they are used, which functions
-       access them, how each lock is acquired, under what conditions it
-       is held, whether interrupts can occur or not while it is held...
-
-     * Title: "Porting Linux 2.0 Drivers To Linux 2.2: Changes and New
-       Features "
-       Author: Alan Cox.
-       URL: http://www.linux-mag.com/1999-05/gear_01.html
-       Keywords: ports, porting.
-       Description: Article from Linux Magazine on porting from 2.0 to
-       2.2 kernels.
-
-     * Title: "Porting Device Drivers To Linux 2.2: part II"
-       Author: Alan Cox.
-       URL: http://www.linux-mag.com/id/238 
-       Keywords: ports, porting.
-       Description: Second part on porting from 2.0 to 2.2 kernels.
-
-     * Title: "How To Make Sure Your Driver Will Work On The Power
-       Macintosh"
-       Author: Paul Mackerras.
-       URL: http://www.linux-mag.com/id/261
-       Keywords: Mac, Power Macintosh, porting, drivers, compatibility.
-       Description: The title says it all.
-
-     * Title: "An Introduction to SCSI Drivers"
-       Author: Alan Cox.
-       URL: http://www.linux-mag.com/id/284
-       Keywords: SCSI, device, driver.
-       Description: The title says it all.
-
-     * Title: "Advanced SCSI Drivers And Other Tales"
-       Author: Alan Cox.
-       URL: http://www.linux-mag.com/id/307
-       Keywords: SCSI, device, driver, advanced.
-       Description: The title says it all.
-
-     * Title: "Writing Linux Mouse Drivers"
-       Author: Alan Cox.
-       URL: http://www.linux-mag.com/id/330
-       Keywords: mouse, driver, gpm.
-       Description: The title says it all.
-
-     * Title: "More on Mouse Drivers"
-       Author: Alan Cox.
-       URL: http://www.linux-mag.com/id/356
-       Keywords: mouse, driver, gpm, races, asynchronous I/O.
-       Description: The title still says it all.
-
-     * Title: "Writing Video4linux Radio Driver"
-       Author: Alan Cox.
-       URL: http://www.linux-mag.com/id/381
-       Keywords: video4linux, driver, radio, radio devices.
-       Description: The title says it all.
-
-     * Title: "Video4linux Drivers, Part 1: Video-Capture Device"
-       Author: Alan Cox.
-       URL: http://www.linux-mag.com/id/406
-       Keywords: video4linux, driver, video capture, capture devices,
-       camera driver.
-       Description: The title says it all.
-
-     * Title: "Video4linux Drivers, Part 2: Video-capture Devices"
-       Author: Alan Cox.
-       URL: http://www.linux-mag.com/id/429
-       Keywords: video4linux, driver, video capture, capture devices,
-       camera driver, control, query capabilities, capability, facility.
-       Description: The title says it all.
-
-     * Title: "PCI Management in Linux 2.2"
-       Author: Alan Cox.
-       URL: http://www.linux-mag.com/id/452
-       Keywords: PCI, bus, bus-mastering.
-       Description: The title says it all.
-
-     * Title: "Linux 2.4 Kernel Internals"
-       Author: Tigran Aivazian and Christoph Hellwig.
-       URL: http://www.moses.uklinux.net/patches/lki.html
-       Keywords: Linux, kernel, booting, SMB boot, VFS, page cache.
-       Description: A little book used for a short training course.
-       Covers building the kernel image, booting (including SMP bootup),
-       process management, VFS and more.
-
-     * Title: "Linux IP Networking. A Guide to the Implementation and
-       Modification of the Linux Protocol Stack."
-       Author: Glenn Herrin.
-       URL: http://www.cs.unh.edu/cnrg/gherrin
-       Keywords: network, networking, protocol, IP, UDP, TCP, connection,
-       socket, receiving, transmitting, forwarding, routing, packets,
-       modules, /proc, sk_buff, FIB, tags.
-       Description: Excellent paper devoted to the Linux IP Networking,
-       explaining anything from the kernel's to the user space
-       configuration tools' code. Very good to get a general overview of
-       the kernel networking implementation and understand all steps
-       packets follow from the time they are received at the network
-       device till they are delivered to applications. The studied kernel
-       code is from 2.2.14 version. Provides code for a working packet
-       dropper example.
-       
-     * Title: "Get those boards talking under Linux."
-       Author: Alex Ivchenko.
-       URL: http://www.edn.com/article/CA46968.html
-       Keywords: data-acquisition boards, drivers, modules, interrupts,
-       memory allocation.
-       Description: Article written for people wishing to make their data
-       acquisition boards work on their GNU/Linux machines. Gives a basic
-       overview on writing drivers, from the naming of functions to
-       interrupt handling.
-       Notes: Two-parts article. Part II is at
-       URL: http://www.edn.com/article/CA46998.html
-       
-     * Title: "Linux PCMCIA Programmer's Guide"
-       Author: David Hinds.
-       URL: http://pcmcia-cs.sourceforge.net/ftp/doc/PCMCIA-PROG.html
-       Keywords: PCMCIA.
-       Description: "This document describes how to write kernel device
-       drivers for the Linux PCMCIA Card Services interface. It also
-       describes how to write user-mode utilities for communicating with
-       Card Services.
-
-     * Title: "The Linux Kernel NFSD Implementation"
-       Author: Neil Brown.
-       URL:
-       http://www.cse.unsw.edu.au/~neilb/oss/linux-commentary/nfsd.html
-       Keywords: knfsd, nfsd, NFS, RPC, lockd, mountd, statd.
-       Description: The title says it all.
-       Notes: Covers knfsd's version 1.4.7 (patch against 2.2.7 kernel).
-       
-     * Title: "A Linux vm README"
-       Author: Kanoj Sarcar.
-       URL: http://kos.enix.org/pub/linux-vmm.html
-       Keywords: virtual memory, mm, pgd, vma, page, page flags, page
-       cache, swap cache, kswapd.
-       Description: Telegraphic, short descriptions and definitions
-       relating the Linux virtual memory implementation.
-       
-     * Title: "(nearly) Complete Linux Loadable Kernel Modules. The
-       definitive guide for hackers, virus coders and system
-       administrators."
-       Author: pragmatic/THC.
-       URL: http://packetstormsecurity.org/docs/hack/LKM_HACKING.html
-       Keywords: syscalls, intercept, hide, abuse, symbol table.
-       Description: Interesting paper on how to abuse the Linux kernel in
-       order to intercept and modify syscalls, make
-       files/directories/processes invisible, become root, hijack ttys,
-       write kernel modules based virus... and solutions for admins to
-       avoid all those abuses.
-       Notes: For 2.0.x kernels. Gives guidances to port it to 2.2.x
-       kernels.
-       
-     BOOKS: (Not on-line)
-   
-     * Title: "Linux Device Drivers"
-       Author: Alessandro Rubini.
-       Publisher: O'Reilly & Associates.
-       Date: 1998.
-       Pages: 439.
-       ISBN: 1-56592-292-1
-       
-     * Title: "Linux Device Drivers, 2nd Edition"
-       Author: Alessandro Rubini and Jonathan Corbet.
-       Publisher: O'Reilly & Associates.
-       Date: 2001.
-       Pages: 586.
-       ISBN: 0-59600-008-1
-       Notes: Further information in
-       http://www.oreilly.com/catalog/linuxdrive2/
-
-     * Title: "Linux Device Drivers, 3rd Edition"
-       Authors: Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman
-       Publisher: O'Reilly & Associates.
-       Date: 2005.
-       Pages: 636.
-       ISBN: 0-596-00590-3
-       Notes: Further information in
-       http://www.oreilly.com/catalog/linuxdrive3/
-       PDF format, URL: http://lwn.net/Kernel/LDD3/
-
-     * Title: "Linux Kernel Internals"
-       Author: Michael Beck.
-       Publisher: Addison-Wesley.
-       Date: 1997.
-       ISBN: 0-201-33143-8 (second edition)
-       
-     * Title: "The Design of the UNIX Operating System"
-       Author: Maurice J. Bach.
-       Publisher: Prentice Hall.
-       Date: 1986.
-       Pages: 471.
-       ISBN: 0-13-201757-1
-       
-     * Title: "The Design and Implementation of the 4.3 BSD UNIX
-       Operating System"
-       Author: Samuel J. Leffler, Marshall Kirk McKusick, Michael J.
-       Karels, John S. Quarterman.
-       Publisher: Addison-Wesley.
-       Date: 1989 (reprinted with corrections on October, 1990).
-       ISBN: 0-201-06196-1
-       
-     * Title: "The Design and Implementation of the 4.4 BSD UNIX
-       Operating System"
-       Author: Marshall Kirk McKusick, Keith Bostic, Michael J. Karels,
-       John S. Quarterman.
-       Publisher: Addison-Wesley.
-       Date: 1996.
-       ISBN: 0-201-54979-4
-       
-     * Title: "Programmation Linux 2.0 API systeme et fonctionnement du
-       noyau"
-       Author: Remy Card, Eric Dumas, Franck Mevel.
-       Publisher: Eyrolles.
-       Date: 1997.
-       Pages: 520.
-       ISBN: 2-212-08932-5
-       Notes: French.
-
-     * Title: "Unix internals -- the new frontiers"
-       Author: Uresh Vahalia.
-       Publisher: Prentice Hall.
-       Date: 1996.
-       Pages: 600.
-       ISBN: 0-13-101908-2
-
-     * Title: "Programming for the real world - POSIX.4"
-       Author: Bill O. Gallmeister.
-       Publisher: O'Reilly & Associates, Inc..
-       Date: 1995.
-       Pages: ???.
-       ISBN: I-56592-074-0
-       Notes: Though not being directly about Linux, Linux aims to be
-       POSIX. Good reference.
-
-     * Title:  "UNIX  Systems  for  Modern Architectures: Symmetric
-       Multiprocessing and Caching for Kernel Programmers"
-       Author: Curt Schimmel.
-       Publisher: Addison Wesley.
-       Date: June, 1994.
-       Pages: 432.
-       ISBN: 0-201-63338-8
-
-     * Title: "Linux Kernel Development, 3rd Edition"
-       Author: Robert Love
-       Publisher: Addison-Wesley.
-       Date: July, 2010
-       Pages: 440
-       ISBN: 978-0672329463
-
-     MISCELLANEOUS:
-
-     * Name: linux/Documentation
-       Author: Many.
-       URL: Just look inside your kernel sources.
-       Keywords: anything, DocBook.
-       Description: Documentation that comes with the kernel sources,
-       inside the Documentation directory. Some pages from this document
-       (including this document itself) have been moved there, and might
-       be more up to date than the web version.
-
-     * Name: "Linux Kernel Source Reference"
-       Author: Thomas Graichen.
-       URL: http://marc.info/?l=linux-kernel&m=96446640102205&w=4
-       Keywords: CVS, web, cvsweb, browsing source code.
-       Description: Web interface to a CVS server with the kernel
-       sources. "Here you can have a look at any file of the Linux kernel
-       sources of any version starting from 1.0 up to the (daily updated)
-       current version available. Also you can check the differences
-       between two versions of a file".
-
-     * Name: "Cross-Referencing Linux"
-       URL: http://lxr.free-electrons.com/
-       Keywords: Browsing source code.
-       Description: Another web-based Linux kernel source code browser.
-       Lots of cross references to variables and functions. You can see
-       where they are defined and where they are used.
-
-     * Name: "Linux Weekly News"
-       URL: http://lwn.net
-       Keywords: latest kernel news.
-       Description: The title says it all. There's a fixed kernel section
-       summarizing developers' work, bug fixes, new features and versions
-       produced during the week. Published every Thursday.
-
-     * Name: "Kernel Traffic"
-       URL: http://kt.earth.li/kernel-traffic/index.html
-       Keywords: linux-kernel mailing list, weekly kernel news.
-       Description: Weekly newsletter covering the most relevant
-       discussions of the linux-kernel mailing list.
-
-     * Name: "CuTTiNG.eDGe.LiNuX"
-       URL: http://edge.kernelnotes.org
-       Keywords: changelist.
-       Description: Site which provides the changelist for every kernel
-       release. What's new, what's better, what's changed. Myrdraal reads
-       the patches and describes them. Pointers to the patches are there,
-       too.
-
-     * Name: "New linux-kernel Mailing List FAQ"
-       URL: http://www.tux.org/lkml/
-       Keywords: linux-kernel mailing list FAQ.
-       Description: linux-kernel is a mailing list for developers to
-       communicate. This FAQ builds on the previous linux-kernel mailing
-       list FAQ maintained by Frohwalt Egerer, who no longer maintains
-       it. Read it to see how to join the mailing list. Dozens of
-       interesting questions regarding the list, Linux, developers (who
-       is ...?), terms (what is...?) are answered here too. Just read it.
-
-     * Name: "Linux Virtual File System"
-       Author: Peter J. Braam.
-       URL: http://www.coda.cs.cmu.edu/doc/talks/linuxvfs/
-       Keywords: slides, VFS, inode, superblock, dentry, dcache.
-       Description: Set of slides, presumably from a presentation on the
-       Linux VFS layer. Covers version 2.1.x, with dentries and the
-       dcache.
-
-     * Name: "Gary's Encyclopedia - The Linux Kernel"
-       Author: Gary (I suppose...).
-       URL: http://slencyclopedia.berlios.de/index.html
-       Keywords: linux, community, everything!
-       Description: Gary's Encyclopedia exists to allow the rapid finding
-       of documentation and other information of interest to GNU/Linux
-       users. It has about 4000 links to external pages in 150 major
-       categories. This link is for kernel-specific links, documents,
-       sites...  This list is now hosted by developer.Berlios.de,
-       but seems not to have been updated since sometime in 1999.
-
-     * Name: "The home page of Linux-MM"
-       Author: The Linux-MM team.
-       URL: http://linux-mm.org/
-       Keywords: memory management, Linux-MM, mm patches, TODO, docs,
-       mailing list.
-       Description: Site devoted to Linux Memory Management development.
-       Memory related patches, HOWTOs, links, mm developers... Don't miss
-       it if you are interested in memory management development!
-
-     * Name: "Kernel Newbies IRC Channel and Website"
-       URL: http://www.kernelnewbies.org
-       Keywords: IRC, newbies, channel, asking doubts.
-       Description: #kernelnewbies on irc.oftc.net.
-       #kernelnewbies is an IRC network dedicated to the 'newbie'
-       kernel hacker. The audience mostly consists of people who are
-       learning about the kernel, working on kernel projects or
-       professional kernel hackers that want to help less seasoned kernel
-       people.
-       #kernelnewbies is on the OFTC IRC Network.
-       Try irc.oftc.net as your server and then /join #kernelnewbies.
-       The kernelnewbies website also hosts articles, documents, FAQs...
-       
-     * Name: "linux-kernel mailing list archives and search engines"
-       URL: http://vger.kernel.org/vger-lists.html
-       URL: http://www.uwsg.indiana.edu/hypermail/linux/kernel/index.html
-       URL: http://marc.theaimsgroup.com/?l=linux-kernel
-       URL: http://groups.google.com/group/mlist.linux.kernel
-       URL: http://www.cs.helsinki.fi/linux/linux-kernel/
-       URL: http://www.lib.uaa.alaska.edu/linux-kernel/
-       Keywords: linux-kernel, archives, search.
-       Description: Some of the linux-kernel mailing list archivers. If
-       you have a better/another one, please let me know.
-     _________________________________________________________________
-   
-   Document last updated on Sat 2005-NOV-19
+.. note::
+ The latest version of this document may be found at:
+ :http://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html
+
+The need for a document like this one became apparent in the
+linux-kernel mailing list as the same questions, asking for pointers
+to information, appeared again and again.
+
+Fortunately, as more and more people get to GNU/Linux, more and more
+get interested in the Kernel. But reading the sources is not always
+enough. It is easy to understand the code, but miss the concepts, the
+philosophy and design decisions behind this code.
+
+Unfortunately, not many documents are available for beginners to
+start. And, even if they exist, there was no "well-known" place which
+kept track of them. These lines try to cover this lack. All documents
+available on line known by the author are listed, while some reference
+books are also mentioned.
+
+PLEASE, if you know any paper not listed here or write a new document,
+send me an e-mail, and I'll include a reference to it here. Any
+corrections, ideas or comments are also welcomed.
+
+The papers that follow are listed in no particular order. All are
+cataloged with the following fields: the document's "Title", the
+"Author"/s, the "URL" where they can be found, some "Keywords" helpful
+when searching for specific topics, and a brief "Description" of the
+Document.
+
+Enjoy!
+
+ON-LINE DOCS
+------------
+
+     * Title: **Linux Device Drivers, Third Edition**
+
+       :Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman
+       :URL: http://lwn.net/Kernel/LDD3/
+       :Description: A 600-page book covering the (2.6.10) driver
+         programming API and kernel hacking in general.  Available under the
+         Creative Commons Attribution-ShareAlike 2.0 license.
+
+     * Title: **The Linux Kernel**
+
+       :Author: David A. Rusling.
+       :URL: http://www.tldp.org/LDP/tlk/tlk.html
+       :Keywords: everything!, book.
+       :Description: On line, 200 pages book describing most aspects of
+         the Linux Kernel. Probably, the first reference for beginners.
+         Lots of illustrations explaining data structures use and
+         relationships in the purest Richard W. Stevens' style. Contents:
+         "1.-Hardware Basics, 2.-Software Basics, 3.-Memory Management,
+         4.-Processes, 5.-Interprocess Communication Mechanisms, 6.-PCI,
+         7.-Interrupts and Interrupt Handling, 8.-Device Drivers, 9.-The
+         File system, 10.-Networks, 11.-Kernel Mechanisms, 12.-Modules,
+         13.-The Linux Kernel Sources, A.-Linux Data Structures, B.-The
+         Alpha AXP Processor, C.-Useful Web and FTP Sites, D.-The GNU
+         General Public License, Glossary". In short: a must have.
+
+     * Title: **Linux Device Drivers, 2nd Edition**
+
+       :Author: Alessandro Rubini and Jonathan Corbet.
+       :URL: http://www.xml.com/ldd/chapter/book/index.html
+       :Keywords: device drivers, modules, debugging, memory, hardware,
+         interrupt handling, char drivers, block drivers, kmod, mmap, DMA,
+         buses.
+       :Description: O'Reilly's popular book, now also on-line under the
+         GNU Free Documentation License.
+       :Notes: You can also buy it in paper-form from O'Reilly. See below
+         under BOOKS (Not on-line).
+
+     * Title: **Conceptual Architecture of the Linux Kernel**
+
+       :Author: Ivan T. Bowman.
+       :URL: http://plg.uwaterloo.ca/
+       :Keywords: conceptual software architecture, extracted design,
+         reverse engineering, system structure.
+       :Description: Conceptual software architecture of the Linux kernel,
+         automatically extracted from the source code. Very detailed. Good
+         figures. Gives good overall kernel understanding.
+
+     * Title: **Concrete Architecture of the Linux Kernel**
+
+       :Author: Ivan T. Bowman, Saheem Siddiqi, and Meyer C. Tanuan.
+       :URL: http://plg.uwaterloo.ca/
+       :Keywords: concrete architecture, extracted design, reverse
+         engineering, system structure, dependencies.
+       :Description: Concrete architecture of the Linux kernel,
+         automatically extracted from the source code. Very detailed. Good
+         figures. Gives good overall kernel understanding. This papers
+         focus on lower details than its predecessor (files, variables...).
+
+     * Title: **Linux as a Case Study: Its Extracted Software Architecture**
+
+       :Author: Ivan T. Bowman, Richard C. Holt and Neil V. Brewster.
+       :URL: http://plg.uwaterloo.ca/
+       :Keywords: software architecture, architecture recovery,
+         redocumentation.
+       :Description: Paper appeared at ICSE'99, Los Angeles, May 16-22,
+         1999. A mixture of the previous two documents from the same
+         author.
+
+     * Title: **Overview of the Virtual File System**
+
+       :Author: Richard Gooch.
+       :URL: http://www.mjmwired.net/kernel/Documentation/filesystems/vfs.txt
+       :Keywords: VFS, File System, mounting filesystems, opening files,
+         dentries, dcache.
+       :Description: Brief introduction to the Linux Virtual File System.
+         What is it, how it works, operations taken when opening a file or
+         mounting a file system and description of important data
+         structures explaining the purpose of each of their entries.
+
+     * Title: **The Linux RAID-1, 4, 5 Code**
+
+       :Author: Ingo Molnar, Gadi Oxman and Miguel de Icaza.
+       :URL: http://www.linuxjournal.com/article.php?sid=2391
+       :Keywords: RAID, MD driver.
+       :Description: Linux Journal Kernel Korner article. Here is its
+       :Abstract: *A description of the implementation of the RAID-1,
+         RAID-4 and RAID-5 personalities of the MD device driver in the
+         Linux kernel, providing users with high performance and reliable,
+         secondary-storage capability using software*.
+
+     * Title: **Dynamic Kernels: Modularized Device Drivers**
+
+       :Author: Alessandro Rubini.
+       :URL: http://www.linuxjournal.com/article.php?sid=1219
+       :Keywords: device driver, module, loading/unloading modules,
+         allocating resources.
+       :Description: Linux Journal Kernel Korner article. Here is its
+       :Abstract: *This is the first of a series of four articles
+         co-authored by Alessandro Rubini and Georg Zezchwitz which present
+         a practical approach to writing Linux device drivers as kernel
+         loadable modules. This installment presents an introduction to the
+         topic, preparing the reader to understand next month's
+         installment*.
+
+     * Title: **Dynamic Kernels: Discovery**
+
+       :Author: Alessandro Rubini.
+       :URL: http://www.linuxjournal.com/article.php?sid=1220
+       :Keywords: character driver, init_module, clean_up module,
+         autodetection, mayor number, minor number, file operations,
+         open(), close().
+       :Description: Linux Journal Kernel Korner article. Here is its
+       :Abstract: *This article, the second of four, introduces part of
+         the actual code to create custom module implementing a character
+         device driver. It describes the code for module initialization and
+         cleanup, as well as the open() and close() system calls*.
+
+     * Title: **The Devil's in the Details**
+
+       :Author: Georg v. Zezschwitz and Alessandro Rubini.
+       :URL: http://www.linuxjournal.com/article.php?sid=1221
+       :Keywords: read(), write(), select(), ioctl(), blocking/non
+         blocking mode, interrupt handler.
+       :Description: Linux Journal Kernel Korner article. Here is its
+       :Abstract: *This article, the third of four on writing character
+         device drivers, introduces concepts of reading, writing, and using
+         ioctl-calls*.
+
+     * Title: **Dissecting Interrupts and Browsing DMA**
+
+       :Author: Alessandro Rubini and Georg v. Zezschwitz.
+       :URL: http://www.linuxjournal.com/article.php?sid=1222
+       :Keywords: interrupts, irqs, DMA, bottom halves, task queues.
+       :Description: Linux Journal Kernel Korner article. Here is its
+       :Abstract: *This is the fourth in a series of articles about
+         writing character device drivers as loadable kernel modules. This
+         month, we further investigate the field of interrupt handling.
+         Though it is conceptually simple, practical limitations and
+         constraints make this an ''interesting'' part of device driver
+         writing, and several different facilities have been provided for
+         different situations. We also investigate the complex topic of
+         DMA*.
+
+     * Title: **Device Drivers Concluded**
+
+       :Author: Georg v. Zezschwitz.
+       :URL: http://www.linuxjournal.com/article.php?sid=1287
+       :Keywords: address spaces, pages, pagination, page management,
+         demand loading, swapping, memory protection, memory mapping, mmap,
+         virtual memory areas (VMAs), vremap, PCI.
+       :Description: Finally, the above turned out into a five articles
+         series. This latest one's introduction reads: "This is the last of
+         five articles about character device drivers. In this final
+         section, Georg deals with memory mapping devices, beginning with
+         an overall description of the Linux memory management concepts".
+
+     * Title: **Network Buffers And Memory Management**
+
+       :Author: Alan Cox.
+       :URL: http://www.linuxjournal.com/article.php?sid=1312
+       :Keywords: sk_buffs, network devices, protocol/link layer
+         variables, network devices flags, transmit, receive,
+         configuration, multicast.
+       :Description: Linux Journal Kernel Korner.
+       :Abstract: *Writing a network device driver for Linux is fundamentally
+         simple---most of the complexity (other than talking to the
+         hardware) involves managing network packets in memory*.
+
+     * Title: **Linux Kernel Hackers' Guide**
+
+       :Author: Michael K. Johnson.
+       :URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html
+       :Keywords: device drivers, files, VFS, kernel interface, character vs
+         block devices, hardware interrupts, scsi, DMA, access to user memory,
+         memory allocation, timers.
+       :Description: A guide designed to help you get up to speed on the
+         concepts that are not intuitevly obvious, and to document the internal
+         structures of Linux.
+
+     * Title: **The Venus kernel interface**
+
+       :Author: Peter J. Braam.
+       :URL: http://www.coda.cs.cmu.edu/doc/html/kernel-venus-protocol.html
+       :Keywords: coda, filesystem, venus, cache manager.
+       :Description: "This document describes the communication between
+         Venus and kernel level file system code needed for the operation
+         of the Coda filesystem. This version document is meant to describe
+         the current interface (version 1.0) as well as improvements we
+         envisage".
+
+     * Title: **Programming PCI-Devices under Linux**
+
+       :Author: Claus Schroeter.
+       :URL: ftp://ftp.llp.fu-berlin.de/pub/linux/LINUX-LAB/whitepapers/pcip.ps.gz
+       :Keywords: PCI, device, busmastering.
+       :Description: 6 pages tutorial on PCI programming under Linux.
+         Gives the basic concepts on the architecture of the PCI subsystem,
+         as long as basic functions and macros to read/write the devices
+         and perform busmastering.
+
+     * Title: **Writing Character Device Driver for Linux**
+
+       :Author: R. Baruch and C. Schroeter.
+       :URL: ftp://ftp.llp.fu-berlin.de/pub/linux/LINUX-LAB/whitepapers/drivers.ps.gz
+       :Keywords: character device drivers, I/O, signals, DMA, accessing
+         ports in user space, kernel environment.
+       :Description: 68 pages paper on writing character drivers. A little
+         bit old (1.993, 1.994) although still useful.
+
+     * Title: **Design and Implementation of the Second Extended Filesystem**
+
+       :Author: Rémy Card, Theodore Ts'o, Stephen Tweedie.
+       :URL: http://web.mit.edu/tytso/www/linux/ext2intro.html
+       :Keywords: ext2, linux fs history, inode, directory, link, devices,
+         VFS, physical structure, performance, benchmarks, ext2fs library,
+         ext2fs tools, e2fsck.
+       :Description: Paper written by three of the top ext2 hackers.
+         Covers Linux filesystems history, ext2 motivation, ext2 features,
+         design, physical structure on disk, performance, benchmarks,
+         e2fsck's passes description... A must read!
+       :Notes: This paper was first published in the Proceedings of the
+         First Dutch International Symposium on Linux, ISBN 90-367-0385-9.
+
+     * Title: **Analysis of the Ext2fs structure**
+
+       :Author: Louis-Dominique Dubeau.
+       :URL: http://teaching.csse.uwa.edu.au/units/CITS2002/fs-ext2/
+       :Keywords: ext2, filesystem, ext2fs.
+       :Description: Description of ext2's blocks, directories, inodes,
+         bitmaps, invariants...
+
+     * Title: **Journaling the Linux ext2fs Filesystem**
+
+       :Author: Stephen C. Tweedie.
+       :URL: ftp://ftp.uk.linux.org/pub/linux/sct/fs/jfs/journal-design.ps.gz
+       :Keywords: ext3, journaling.
+       :Description: Excellent 8-pages paper explaining the journaling
+         capabilities added to ext2 by the author, showing different
+         problems faced and the alternatives chosen.
+
+     * Title: **Kernel API changes from 2.0 to 2.2**
+
+       :Author: Richard Gooch.
+       :URL: http://www.safe-mbox.com/~rgooch/linux/docs/porting-to-2.2.html
+       :Keywords: 2.2, changes.
+       :Description: Kernel functions/structures/variables which changed
+         from 2.0.x to 2.2.x.
+
+     * Title: **Kernel API changes from 2.2 to 2.4**
+
+       :Author: Richard Gooch.
+       :URL: http://www.safe-mbox.com/~rgooch/linux/docs/porting-to-2.4.html
+       :Keywords: 2.4, changes.
+       :Description: Kernel functions/structures/variables which changed
+         from 2.2.x to 2.4.x.
+
+     * Title: **Linux Kernel Module Programming Guide**
+
+       :Author: Ori Pomerantz.
+       :URL: http://tldp.org/LDP/lkmpg/2.6/html/index.html
+       :Keywords: modules, GPL book, /proc, ioctls, system calls,
+         interrupt handlers .
+       :Description: Very nice 92 pages GPL book on the topic of modules
+         programming. Lots of examples.
+
+     * Title: **I/O Event Handling Under Linux**
+
+       :Author: Richard Gooch.
+       :Keywords: IO, I/O, select(2), poll(2), FDs, aio_read(2), readiness
+         event queues.
+       :Description: From the Introduction: "I/O Event handling is about
+         how your Operating System allows you to manage a large number of
+         open files (file descriptors in UNIX/POSIX, or FDs) in your
+         application. You want the OS to notify you when FDs become active
+         (have data ready to be read or are ready for writing). Ideally you
+         want a mechanism that is scalable. This means a large number of
+         inactive FDs cost very little in memory and CPU time to manage".
+
+     * Title: **The Kernel Hacking HOWTO**
+
+       :Author: Various Talented People, and Rusty.
+       :Location: in kernel tree, Documentation/DocBook/kernel-hacking.tmpl
+         (must be built as "make {htmldocs | psdocs | pdfdocs})
+       :Keywords: HOWTO, kernel contexts, deadlock, locking, modules,
+         symbols, return conventions.
+       :Description: From the Introduction: "Please understand that I
+         never wanted to write this document, being grossly underqualified,
+         but I always wanted to read it, and this was the only way. I
+         simply explain some best practices, and give reading entry-points
+         into the kernel sources. I avoid implementation details: that's
+         what the code is for, and I ignore whole tracts of useful
+         routines. This document assumes familiarity with C, and an
+         understanding of what the kernel is, and how it is used. It was
+         originally written for the 2.3 kernels, but nearly all of it
+         applies to 2.2 too; 2.0 is slightly different".
+
+     * Title: **Writing an ALSA Driver**
+
+       :Author: Takashi Iwai <tiwai@suse.de>
+       :URL: http://www.alsa-project.org/~iwai/writing-an-alsa-driver/index.html
+       :Keywords: ALSA, sound, soundcard, driver, lowlevel, hardware.
+       :Description: Advanced Linux Sound Architecture for developers,
+         both at kernel and user-level sides. ALSA is the Linux kernel
+         sound architecture in the 2.6 kernel version.
+
+     * Title: **Programming Guide for Linux USB Device Drivers**
+
+       :Author: Detlef Fliegl.
+       :URL: http://usb.in.tum.de/usbdoc/
+       :Keywords: USB, universal serial bus.
+       :Description: A must-read. From the Preface: "This document should
+         give detailed information about the current state of the USB
+         subsystem and its API for USB device drivers. The first section
+         will deal with the basics of USB devices. You will learn about
+         different types of devices and their properties. Going into detail
+         you will see how USB devices communicate on the bus. The second
+         section gives an overview of the Linux USB subsystem [2] and the
+         device driver framework. Then the API and its data structures will
+         be explained step by step. The last section of this document
+         contains a reference of all API calls and their return codes".
+       :Notes: Beware: the main page states: "This document may not be
+         published, printed or used in excerpts without explicit permission
+         of the author". Fortunately, it may still be read...
+
+     * Title: **Linux Kernel Mailing List Glossary**
+
+       :Author: various
+       :URL: http://kernelnewbies.org/glossary/
+       :Keywords: glossary, terms, linux-kernel.
+       :Description: From the introduction: "This glossary is intended as
+         a brief description of some of the acronyms and terms you may hear
+         during discussion of the Linux kernel".
+
+     * Title: **Linux Kernel Locking HOWTO**
+
+       :Author: Various Talented People, and Rusty.
+       :Location: in kernel tree, Documentation/DocBook/kernel-locking.tmpl
+         (must be built as "make {htmldocs | psdocs | pdfdocs})
+       :Keywords: locks, locking, spinlock, semaphore, atomic, race
+         condition, bottom halves, tasklets, softirqs.
+       :Description: The title says it all: document describing the
+         locking system in the Linux Kernel either in uniprocessor or SMP
+         systems.
+       :Notes: "It was originally written for the later (>2.3.47) 2.3
+         kernels, but most of it applies to 2.2 too; 2.0 is slightly
+         different". Freely redistributable under the conditions of the GNU
+         General Public License.
+
+     * Title: **Global spinlock list and usage**
+
+       :Author: Rick Lindsley.
+       :URL: http://lse.sourceforge.net/lockhier/global-spin-lock
+       :Keywords: spinlock.
+       :Description: This is an attempt to document both the existence and
+         usage of the spinlocks in the Linux 2.4.5 kernel. Comprehensive
+         list of spinlocks showing when they are used, which functions
+         access them, how each lock is acquired, under what conditions it
+         is held, whether interrupts can occur or not while it is held...
+
+     * Title: **Porting Linux 2.0 Drivers To Linux 2.2: Changes and New Features**
+
+       :Author: Alan Cox.
+       :URL: http://www.linux-mag.com/1999-05/gear_01.html
+       :Keywords: ports, porting.
+       :Description: Article from Linux Magazine on porting from 2.0 to
+         2.2 kernels.
+
+     * Title: **Porting Device Drivers To Linux 2.2: part II**
+
+       :Author: Alan Cox.
+       :URL: http://www.linux-mag.com/id/238
+       :Keywords: ports, porting.
+       :Description: Second part on porting from 2.0 to 2.2 kernels.
+
+     * Title: **How To Make Sure Your Driver Will Work On The Power Macintosh**
+
+       :Author: Paul Mackerras.
+       :URL: http://www.linux-mag.com/id/261
+       :Keywords: Mac, Power Macintosh, porting, drivers, compatibility.
+       :Description: The title says it all.
+
+     * Title: **An Introduction to SCSI Drivers**
+
+       :Author: Alan Cox.
+       :URL: http://www.linux-mag.com/id/284
+       :Keywords: SCSI, device, driver.
+       :Description: The title says it all.
+
+     * Title: **Advanced SCSI Drivers And Other Tales**
+
+       :Author: Alan Cox.
+       :URL: http://www.linux-mag.com/id/307
+       :Keywords: SCSI, device, driver, advanced.
+       :Description: The title says it all.
+
+     * Title: **Writing Linux Mouse Drivers**
+
+       :Author: Alan Cox.
+       :URL: http://www.linux-mag.com/id/330
+       :Keywords: mouse, driver, gpm.
+       :Description: The title says it all.
+
+     * Title: **More on Mouse Drivers**
+
+       :Author: Alan Cox.
+       :URL: http://www.linux-mag.com/id/356
+       :Keywords: mouse, driver, gpm, races, asynchronous I/O.
+       :Description: The title still says it all.
+
+     * Title: **Writing Video4linux Radio Driver**
+
+       :Author: Alan Cox.
+       :URL: http://www.linux-mag.com/id/381
+       :Keywords: video4linux, driver, radio, radio devices.
+       :Description: The title says it all.
+
+     * Title: **Video4linux Drivers, Part 1: Video-Capture Device**
+
+       :Author: Alan Cox.
+       :URL: http://www.linux-mag.com/id/406
+       :Keywords: video4linux, driver, video capture, capture devices,
+         camera driver.
+       :Description: The title says it all.
+
+     * Title: **Video4linux Drivers, Part 2: Video-capture Devices**
+
+       :Author: Alan Cox.
+       :URL: http://www.linux-mag.com/id/429
+       :Keywords: video4linux, driver, video capture, capture devices,
+         camera driver, control, query capabilities, capability, facility.
+       :Description: The title says it all.
+
+     * Title: **PCI Management in Linux 2.2**
+
+       :Author: Alan Cox.
+       :URL: http://www.linux-mag.com/id/452
+       :Keywords: PCI, bus, bus-mastering.
+       :Description: The title says it all.
+
+     * Title: **Linux 2.4 Kernel Internals**
+
+       :Author: Tigran Aivazian and Christoph Hellwig.
+       :URL: http://www.moses.uklinux.net/patches/lki.html
+       :Keywords: Linux, kernel, booting, SMB boot, VFS, page cache.
+       :Description: A little book used for a short training course.
+         Covers building the kernel image, booting (including SMP bootup),
+         process management, VFS and more.
+
+     * Title: **Linux IP Networking. A Guide to the Implementation and Modification of the Linux Protocol Stack.**
+
+       :Author: Glenn Herrin.
+       :URL: http://www.cs.unh.edu/cnrg/gherrin
+       :Keywords: network, networking, protocol, IP, UDP, TCP, connection,
+         socket, receiving, transmitting, forwarding, routing, packets,
+         modules, /proc, sk_buff, FIB, tags.
+       :Description: Excellent paper devoted to the Linux IP Networking,
+         explaining anything from the kernel's to the user space
+         configuration tools' code. Very good to get a general overview of
+         the kernel networking implementation and understand all steps
+         packets follow from the time they are received at the network
+         device till they are delivered to applications. The studied kernel
+         code is from 2.2.14 version. Provides code for a working packet
+         dropper example.
+
+     * Title: **Get those boards talking under Linux.**
+
+       :Author: Alex Ivchenko.
+       :URL: http://www.edn.com/article/CA46968.html
+       :Keywords: data-acquisition boards, drivers, modules, interrupts,
+         memory allocation.
+       :Description: Article written for people wishing to make their data
+         acquisition boards work on their GNU/Linux machines. Gives a basic
+         overview on writing drivers, from the naming of functions to
+         interrupt handling.
+       :Notes: Two-parts article. Part II is at
+       :URL: http://www.edn.com/article/CA46998.html
+
+     * Title: **Linux PCMCIA Programmer's Guide**
+
+       :Author: David Hinds.
+       :URL: http://pcmcia-cs.sourceforge.net/ftp/doc/PCMCIA-PROG.html
+       :Keywords: PCMCIA.
+       :Description: "This document describes how to write kernel device
+         drivers for the Linux PCMCIA Card Services interface. It also
+         describes how to write user-mode utilities for communicating with
+         Card Services.
+
+     * Title: **The Linux Kernel NFSD Implementation**
+
+       :Author: Neil Brown.
+       :URL: http://www.cse.unsw.edu.au/~neilb/oss/linux-commentary/nfsd.html
+       :Keywords: knfsd, nfsd, NFS, RPC, lockd, mountd, statd.
+       :Description: The title says it all.
+       :Notes: Covers knfsd's version 1.4.7 (patch against 2.2.7 kernel).
+
+     * Title: **A Linux vm README**
+
+       :Author: Kanoj Sarcar.
+       :URL: http://kos.enix.org/pub/linux-vmm.html
+       :Keywords: virtual memory, mm, pgd, vma, page, page flags, page
+         cache, swap cache, kswapd.
+       :Description: Telegraphic, short descriptions and definitions
+         relating the Linux virtual memory implementation.
+
+     * Title: **(nearly) Complete Linux Loadable Kernel Modules. The definitive guide for hackers, virus coders and system administrators.**
+
+       :Author: pragmatic/THC.
+       :URL: http://packetstormsecurity.org/docs/hack/LKM_HACKING.html
+       :Keywords: syscalls, intercept, hide, abuse, symbol table.
+       :Description: Interesting paper on how to abuse the Linux kernel in
+         order to intercept and modify syscalls, make
+         files/directories/processes invisible, become root, hijack ttys,
+         write kernel modules based virus... and solutions for admins to
+         avoid all those abuses.
+       :Notes: For 2.0.x kernels. Gives guidances to port it to 2.2.x
+         kernels.
+
+BOOKS: (Not on-line)
+--------------------
+
+     * Title: **Linux Device Drivers**
+
+       :Author: Alessandro Rubini.
+       :Publisher: O'Reilly & Associates.
+       :Date: 1998.
+       :Pages: 439.
+       :ISBN: 1-56592-292-1
+
+     * Title: **Linux Device Drivers, 2nd Edition**
+
+       :Author: Alessandro Rubini and Jonathan Corbet.
+       :Publisher: O'Reilly & Associates.
+       :Date: 2001.
+       :Pages: 586.
+       :ISBN: 0-59600-008-1
+       :Notes: Further information in
+         http://www.oreilly.com/catalog/linuxdrive2/
+
+     * Title: **Linux Device Drivers, 3rd Edition**
+
+       :Authors: Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman
+       :Publisher: O'Reilly & Associates.
+       :Date: 2005.
+       :Pages: 636.
+       :ISBN: 0-596-00590-3
+       :Notes: Further information in
+         http://www.oreilly.com/catalog/linuxdrive3/
+         PDF format, URL: http://lwn.net/Kernel/LDD3/
+
+     * Title: **Linux Kernel Internals**
+
+       :Author: Michael Beck.
+       :Publisher: Addison-Wesley.
+       :Date: 1997.
+       :ISBN: 0-201-33143-8 (second edition)
+
+     * Title: **The Design of the UNIX Operating System**
+
+       :Author: Maurice J. Bach.
+       :Publisher: Prentice Hall.
+       :Date: 1986.
+       :Pages: 471.
+       :ISBN: 0-13-201757-1
+
+     * Title: **The Design and Implementation of the 4.3 BSD UNIX Operating System**
+
+       :Author: Samuel J. Leffler, Marshall Kirk McKusick, Michael J.
+         Karels, John S. Quarterman.
+       :Publisher: Addison-Wesley.
+       :Date: 1989 (reprinted with corrections on October, 1990).
+       :ISBN: 0-201-06196-1
+
+     * Title: **The Design and Implementation of the 4.4 BSD UNIX Operating System**
+
+       :Author: Marshall Kirk McKusick, Keith Bostic, Michael J. Karels,
+         John S. Quarterman.
+       :Publisher: Addison-Wesley.
+       :Date: 1996.
+       :ISBN: 0-201-54979-4
+
+     * Title: **Programmation Linux 2.0 API systeme et fonctionnement du noyau**
+
+       :Author: Remy Card, Eric Dumas, Franck Mevel.
+       :Publisher: Eyrolles.
+       :Date: 1997.
+       :Pages: 520.
+       :ISBN: 2-212-08932-5
+       :Notes: French.
+
+     * Title: **Unix internals -- the new frontiers**
+
+       :Author: Uresh Vahalia.
+       :Publisher: Prentice Hall.
+       :Date: 1996.
+       :Pages: 600.
+       :ISBN: 0-13-101908-2
+
+     * Title: **Programming for the real world - POSIX.4**
+
+       :Author: Bill O. Gallmeister.
+       :Publisher: O'Reilly & Associates, Inc..
+       :Date: 1995.
+       :Pages: ???.
+       :ISBN: I-56592-074-0
+       :Notes: Though not being directly about Linux, Linux aims to be
+         POSIX. Good reference.
+
+     * Title:  **UNIX  Systems  for  Modern Architectures: Symmetric Multiprocessing and Caching for Kernel Programmers**
+
+       :Author: Curt Schimmel.
+       :Publisher: Addison Wesley.
+       :Date: June, 1994.
+       :Pages: 432.
+       :ISBN: 0-201-63338-8
+
+     * Title: **Linux Kernel Development, 3rd Edition**
+
+       :Author: Robert Love
+       :Publisher: Addison-Wesley.
+       :Date: July, 2010
+       :Pages: 440
+       :ISBN: 978-0672329463
+
+MISCELLANEOUS
+-------------
+
+     * Name: **linux/Documentation**
+
+       :Author: Many.
+       :URL: Just look inside your kernel sources.
+       :Keywords: anything, DocBook.
+       :Description: Documentation that comes with the kernel sources,
+         inside the Documentation directory. Some pages from this document
+         (including this document itself) have been moved there, and might
+         be more up to date than the web version.
+
+     * Name: **Linux Kernel Source Reference**
+
+       :Author: Thomas Graichen.
+       :URL: http://marc.info/?l=linux-kernel&m=96446640102205&w=4
+       :Keywords: CVS, web, cvsweb, browsing source code.
+       :Description: Web interface to a CVS server with the kernel
+         sources. "Here you can have a look at any file of the Linux kernel
+         sources of any version starting from 1.0 up to the (daily updated)
+         current version available. Also you can check the differences
+         between two versions of a file".
+
+     * Name: **Cross-Referencing Linux**
+
+       :URL: http://lxr.free-electrons.com/
+       :Keywords: Browsing source code.
+       :Description: Another web-based Linux kernel source code browser.
+         Lots of cross references to variables and functions. You can see
+         where they are defined and where they are used.
+
+     * Name: **Linux Weekly News**
+
+       :URL: http://lwn.net
+       :Keywords: latest kernel news.
+       :Description: The title says it all. There's a fixed kernel section
+         summarizing developers' work, bug fixes, new features and versions
+         produced during the week. Published every Thursday.
+
+     * Name: **Kernel Traffic**
+
+       :URL: http://kt.earth.li/kernel-traffic/index.html
+       :Keywords: linux-kernel mailing list, weekly kernel news.
+       :Description: Weekly newsletter covering the most relevant
+         discussions of the linux-kernel mailing list.
+
+     * Name: **CuTTiNG.eDGe.LiNuX**
+
+       :URL: http://edge.kernelnotes.org
+       :Keywords: changelist.
+       :Description: Site which provides the changelist for every kernel
+         release. What's new, what's better, what's changed. Myrdraal reads
+         the patches and describes them. Pointers to the patches are there,
+         too.
+
+     * Name: **New linux-kernel Mailing List FAQ**
+
+       :URL: http://www.tux.org/lkml/
+       :Keywords: linux-kernel mailing list FAQ.
+       :Description: linux-kernel is a mailing list for developers to
+         communicate. This FAQ builds on the previous linux-kernel mailing
+         list FAQ maintained by Frohwalt Egerer, who no longer maintains
+         it. Read it to see how to join the mailing list. Dozens of
+         interesting questions regarding the list, Linux, developers (who
+         is ...?), terms (what is...?) are answered here too. Just read it.
+
+     * Name: **Linux Virtual File System**
+
+       :Author: Peter J. Braam.
+       :URL: http://www.coda.cs.cmu.edu/doc/talks/linuxvfs/
+       :Keywords: slides, VFS, inode, superblock, dentry, dcache.
+       :Description: Set of slides, presumably from a presentation on the
+         Linux VFS layer. Covers version 2.1.x, with dentries and the
+         dcache.
+
+     * Name: **Gary's Encyclopedia - The Linux Kernel**
+
+       :Author: Gary (I suppose...).
+       :URL: http://slencyclopedia.berlios.de/index.html
+       :Keywords: linux, community, everything!
+       :Description: Gary's Encyclopedia exists to allow the rapid finding
+         of documentation and other information of interest to GNU/Linux
+         users. It has about 4000 links to external pages in 150 major
+         categories. This link is for kernel-specific links, documents,
+         sites...  This list is now hosted by developer.Berlios.de,
+         but seems not to have been updated since sometime in 1999.
+
+     * Name: **The home page of Linux-MM**
+
+       :Author: The Linux-MM team.
+       :URL: http://linux-mm.org/
+       :Keywords: memory management, Linux-MM, mm patches, TODO, docs,
+         mailing list.
+       :Description: Site devoted to Linux Memory Management development.
+         Memory related patches, HOWTOs, links, mm developers... Don't miss
+         it if you are interested in memory management development!
+
+     * Name: **Kernel Newbies IRC Channel and Website**
+
+       :URL: http://www.kernelnewbies.org
+       :Keywords: IRC, newbies, channel, asking doubts.
+       :Description: #kernelnewbies on irc.oftc.net.
+         #kernelnewbies is an IRC network dedicated to the 'newbie'
+         kernel hacker. The audience mostly consists of people who are
+         learning about the kernel, working on kernel projects or
+         professional kernel hackers that want to help less seasoned kernel
+         people.
+         #kernelnewbies is on the OFTC IRC Network.
+         Try irc.oftc.net as your server and then /join #kernelnewbies.
+         The kernelnewbies website also hosts articles, documents, FAQs...
+
+     * Name: **linux-kernel mailing list archives and search engines**
+
+       :URL: http://vger.kernel.org/vger-lists.html
+       :URL: http://www.uwsg.indiana.edu/hypermail/linux/kernel/index.html
+       :URL: http://marc.theaimsgroup.com/?l=linux-kernel
+       :URL: http://groups.google.com/group/mlist.linux.kernel
+       :URL: http://www.cs.helsinki.fi/linux/linux-kernel/
+       :URL: http://www.lib.uaa.alaska.edu/linux-kernel/
+       :Keywords: linux-kernel, archives, search.
+       :Description: Some of the linux-kernel mailing list archivers. If
+         you have a better/another one, please let me know.
+
+-------
+
+Document last updated on Sat 2005-NOV-19
-- 
2.7.4

[PATCH v2 10/20] ManagementStyle.rst: convert it to ReST markup

[Mauro Carvalho Chehab]

- Convert document name to ReST;
- Convert footnotes;
- Convert sections to ReST format;
- Don't use _foo_, as Sphinx doesn't support underline. Instead,
  use bold;
- While here, remove whitespaces at the end of lines.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 .../development-process/ManagementStyle.rst        | 152 +++++++++++----------
 1 file changed, 80 insertions(+), 72 deletions(-)

diff --git a/Documentation/development-process/ManagementStyle.rst b/Documentation/development-process/ManagementStyle.rst
index a211ee8d8b44..86c5a19e08f3 100644
--- a/Documentation/development-process/ManagementStyle.rst
+++ b/Documentation/development-process/ManagementStyle.rst
@@ -1,10 +1,10 @@
-
-                Linux kernel management style
+Linux kernel management style
+=============================
 
 This is a short document describing the preferred (or made up, depending
 on who you ask) management style for the linux kernel.  It's meant to
 mirror the CodingStyle document to some degree, and mainly written to
-avoid answering (*) the same (or similar) questions over and over again. 
+avoid answering [#f1]_  the same (or similar) questions over and over again.
 
 Management style is very personal and much harder to quantify than
 simple coding style rules, so this document may or may not have anything
@@ -14,50 +14,52 @@ might not actually be true. You'll have to decide for yourself.
 Btw, when talking about "kernel manager", it's all about the technical
 lead persons, not the people who do traditional management inside
 companies.  If you sign purchase orders or you have any clue about the
-budget of your group, you're almost certainly not a kernel manager. 
-These suggestions may or may not apply to you. 
+budget of your group, you're almost certainly not a kernel manager.
+These suggestions may or may not apply to you.
 
 First off, I'd suggest buying "Seven Habits of Highly Effective
-People", and NOT read it.  Burn it, it's a great symbolic gesture. 
+People", and NOT read it.  Burn it, it's a great symbolic gesture.
 
-(*) This document does so not so much by answering the question, but by
-making it painfully obvious to the questioner that we don't have a clue
-to what the answer is. 
+.. [#f1] This document does so not so much by answering the question, but by
+  making it painfully obvious to the questioner that we don't have a clue
+  to what the answer is.
 
 Anyway, here goes:
 
+.. _decisions:
 
-		Chapter 1: Decisions
+Decisions
+---------
 
 Everybody thinks managers make decisions, and that decision-making is
 important.  The bigger and more painful the decision, the bigger the
 manager must be to make it.  That's very deep and obvious, but it's not
-actually true. 
+actually true.
 
-The name of the game is to _avoid_ having to make a decision.  In
+The name of the game is to **avoid** having to make a decision.  In
 particular, if somebody tells you "choose (a) or (b), we really need you
 to decide on this", you're in trouble as a manager.  The people you
 manage had better know the details better than you, so if they come to
 you for a technical decision, you're screwed.  You're clearly not
-competent to make that decision for them. 
+competent to make that decision for them.
 
 (Corollary:if the people you manage don't know the details better than
-you, you're also screwed, although for a totally different reason. 
-Namely that you are in the wrong job, and that _they_ should be managing
-your brilliance instead). 
+you, you're also screwed, although for a totally different reason.
+Namely that you are in the wrong job, and that **they** should be managing
+your brilliance instead).
 
-So the name of the game is to _avoid_ decisions, at least the big and
+So the name of the game is to **avoid** decisions, at least the big and
 painful ones.  Making small and non-consequential decisions is fine, and
 makes you look like you know what you're doing, so what a kernel manager
 needs to do is to turn the big and painful ones into small things where
-nobody really cares. 
+nobody really cares.
 
 It helps to realize that the key difference between a big decision and a
 small one is whether you can fix your decision afterwards.  Any decision
 can be made small by just always making sure that if you were wrong (and
-you _will_ be wrong), you can always undo the damage later by
+you **will** be wrong), you can always undo the damage later by
 backtracking.  Suddenly, you get to be doubly managerial for making
-_two_ inconsequential decisions - the wrong one _and_ the right one. 
+**two** inconsequential decisions - the wrong one **and** the right one.
 
 And people will even see that as true leadership (*cough* bullshit
 *cough*).
@@ -65,10 +67,10 @@ And people will even see that as true leadership (*cough* bullshit
 Thus the key to avoiding big decisions becomes to just avoiding to do
 things that can't be undone.  Don't get ushered into a corner from which
 you cannot escape.  A cornered rat may be dangerous - a cornered manager
-is just pitiful. 
+is just pitiful.
 
 It turns out that since nobody would be stupid enough to ever really let
-a kernel manager have huge fiscal responsibility _anyway_, it's usually
+a kernel manager have huge fiscal responsibility **anyway**, it's usually
 fairly easy to backtrack.  Since you're not going to be able to waste
 huge amounts of money that you might not be able to repay, the only
 thing you can backtrack on is a technical decision, and there
@@ -76,113 +78,116 @@ back-tracking is very easy: just tell everybody that you were an
 incompetent nincompoop, say you're sorry, and undo all the worthless
 work you had people work on for the last year.  Suddenly the decision
 you made a year ago wasn't a big decision after all, since it could be
-easily undone. 
+easily undone.
 
 It turns out that some people have trouble with this approach, for two
 reasons:
+
  - admitting you were an idiot is harder than it looks.  We all like to
    maintain appearances, and coming out in public to say that you were
-   wrong is sometimes very hard indeed. 
+   wrong is sometimes very hard indeed.
  - having somebody tell you that what you worked on for the last year
    wasn't worthwhile after all can be hard on the poor lowly engineers
-   too, and while the actual _work_ was easy enough to undo by just
+   too, and while the actual **work** was easy enough to undo by just
    deleting it, you may have irrevocably lost the trust of that
    engineer.  And remember: "irrevocable" was what we tried to avoid in
    the first place, and your decision ended up being a big one after
-   all. 
+   all.
 
 Happily, both of these reasons can be mitigated effectively by just
 admitting up-front that you don't have a friggin' clue, and telling
 people ahead of the fact that your decision is purely preliminary, and
 might be the wrong thing.  You should always reserve the right to change
-your mind, and make people very _aware_ of that.  And it's much easier
-to admit that you are stupid when you haven't _yet_ done the really
+your mind, and make people very **aware** of that.  And it's much easier
+to admit that you are stupid when you haven't **yet** done the really
 stupid thing.
 
 Then, when it really does turn out to be stupid, people just roll their
-eyes and say "Oops, he did it again".  
+eyes and say "Oops, he did it again".
 
 This preemptive admission of incompetence might also make the people who
 actually do the work also think twice about whether it's worth doing or
-not.  After all, if _they_ aren't certain whether it's a good idea, you
+not.  After all, if **they** aren't certain whether it's a good idea, you
 sure as hell shouldn't encourage them by promising them that what they
 work on will be included.  Make them at least think twice before they
-embark on a big endeavor. 
+embark on a big endeavor.
 
 Remember: they'd better know more about the details than you do, and
 they usually already think they have the answer to everything.  The best
 thing you can do as a manager is not to instill confidence, but rather a
-healthy dose of critical thinking on what they do. 
+healthy dose of critical thinking on what they do.
 
 Btw, another way to avoid a decision is to plaintively just whine "can't
 we just do both?" and look pitiful.  Trust me, it works.  If it's not
 clear which approach is better, they'll eventually figure it out.  The
 answer may end up being that both teams get so frustrated by the
-situation that they just give up. 
+situation that they just give up.
 
 That may sound like a failure, but it's usually a sign that there was
 something wrong with both projects, and the reason the people involved
 couldn't decide was that they were both wrong.  You end up coming up
 smelling like roses, and you avoided yet another decision that you could
-have screwed up on. 
+have screwed up on.
 
 
-		Chapter 2: People
+People
+------
 
 Most people are idiots, and being a manager means you'll have to deal
-with it, and perhaps more importantly, that _they_ have to deal with
-_you_. 
+with it, and perhaps more importantly, that **they** have to deal with
+**you**.
 
 It turns out that while it's easy to undo technical mistakes, it's not
 as easy to undo personality disorders.  You just have to live with
-theirs - and yours. 
+theirs - and yours.
 
 However, in order to prepare yourself as a kernel manager, it's best to
 remember not to burn any bridges, bomb any innocent villagers, or
 alienate too many kernel developers. It turns out that alienating people
 is fairly easy, and un-alienating them is hard. Thus "alienating"
 immediately falls under the heading of "not reversible", and becomes a
-no-no according to Chapter 1.
+no-no according to :ref:`decisions`.
 
 There's just a few simple rules here:
  (1) don't call people d*ckheads (at least not in public)
  (2) learn how to apologize when you forgot rule (1)
 
 The problem with #1 is that it's very easy to do, since you can say
-"you're a d*ckhead" in millions of different ways (*), sometimes without
+"you're a d*ckhead" in millions of different ways [#f2]_, sometimes without
 even realizing it, and almost always with a white-hot conviction that
-you are right. 
+you are right.
 
 And the more convinced you are that you are right (and let's face it,
-you can call just about _anybody_ a d*ckhead, and you often _will_ be
-right), the harder it ends up being to apologize afterwards. 
+you can call just about **anybody** a d*ckhead, and you often **will** be
+right), the harder it ends up being to apologize afterwards.
 
 To solve this problem, you really only have two options:
  - get really good at apologies
  - spread the "love" out so evenly that nobody really ends up feeling
    like they get unfairly targeted.  Make it inventive enough, and they
-   might even be amused. 
+   might even be amused.
 
 The option of being unfailingly polite really doesn't exist. Nobody will
 trust somebody who is so clearly hiding his true character.
 
-(*) Paul Simon sang "Fifty Ways to Leave Your Lover", because quite
-frankly, "A Million Ways to Tell a Developer He Is a D*ckhead" doesn't
-scan nearly as well.  But I'm sure he thought about it. 
+.. [#f2] Paul Simon sang "Fifty Ways to Leave Your Lover", because quite
+  frankly, "A Million Ways to Tell a Developer He Is a D*ckhead" doesn't
+  scan nearly as well.  But I'm sure he thought about it.
 
 
-		Chapter 3: People II - the Good Kind
+People II - the Good Kind
+-------------------------
 
 While it turns out that most people are idiots, the corollary to that is
 sadly that you are one too, and that while we can all bask in the secure
 knowledge that we're better than the average person (let's face it,
 nobody ever believes that they're average or below-average), we should
 also admit that we're not the sharpest knife around, and there will be
-other people that are less of an idiot than you are. 
+other people that are less of an idiot than you are.
 
-Some people react badly to smart people.  Others take advantage of them. 
+Some people react badly to smart people.  Others take advantage of them.
 
-Make sure that you, as a kernel maintainer, are in the second group. 
+Make sure that you, as a kernel maintainer, are in the second group.
 Suck up to them, because they are the people who will make your job
 easier. In particular, they'll be able to make your decisions for you,
 which is what the game is all about.
@@ -191,7 +196,7 @@ So when you find somebody smarter than you are, just coast along.  Your
 management responsibilities largely become ones of saying "Sounds like a
 good idea - go wild", or "That sounds good, but what about xxx?".  The
 second version in particular is a great way to either learn something
-new about "xxx" or seem _extra_ managerial by pointing out something the
+new about "xxx" or seem **extra** managerial by pointing out something the
 smarter person hadn't thought about.  In either case, you win.
 
 One thing to look out for is to realize that greatness in one area does
@@ -199,47 +204,49 @@ not necessarily translate to other areas.  So you might prod people in
 specific directions, but let's face it, they might be good at what they
 do, and suck at everything else.  The good news is that people tend to
 naturally gravitate back to what they are good at, so it's not like you
-are doing something irreversible when you _do_ prod them in some
+are doing something irreversible when you **do** prod them in some
 direction, just don't push too hard.
 
 
-		Chapter 4: Placing blame
+Placing blame
+-------------
 
 Things will go wrong, and people want somebody to blame. Tag, you're it.
 
 It's not actually that hard to accept the blame, especially if people
-kind of realize that it wasn't _all_ your fault.  Which brings us to the
+kind of realize that it wasn't **all** your fault.  Which brings us to the
 best way of taking the blame: do it for another guy. You'll feel good
 for taking the fall, he'll feel good about not getting blamed, and the
 guy who lost his whole 36GB porn-collection because of your incompetence
 will grudgingly admit that you at least didn't try to weasel out of it.
 
 Then make the developer who really screwed up (if you can find him) know
-_in_private_ that he screwed up.  Not just so he can avoid it in the
+**in_private** that he screwed up.  Not just so he can avoid it in the
 future, but so that he knows he owes you one.  And, perhaps even more
 importantly, he's also likely the person who can fix it.  Because, let's
-face it, it sure ain't you. 
+face it, it sure ain't you.
 
-Taking the blame is also why you get to be manager in the first place. 
+Taking the blame is also why you get to be manager in the first place.
 It's part of what makes people trust you, and allow you the potential
 glory, because you're the one who gets to say "I screwed up".  And if
 you've followed the previous rules, you'll be pretty good at saying that
-by now. 
+by now.
 
 
-		Chapter 5: Things to avoid
+Things to avoid
+---------------
 
 There's one thing people hate even more than being called "d*ckhead",
 and that is being called a "d*ckhead" in a sanctimonious voice.  The
 first you can apologize for, the second one you won't really get the
 chance.  They likely will no longer be listening even if you otherwise
-do a good job. 
+do a good job.
 
 We all think we're better than anybody else, which means that when
-somebody else puts on airs, it _really_ rubs us the wrong way.  You may
+somebody else puts on airs, it **really** rubs us the wrong way.  You may
 be morally and intellectually superior to everybody around you, but
-don't try to make it too obvious unless you really _intend_ to irritate
-somebody (*). 
+don't try to make it too obvious unless you really **intend** to irritate
+somebody [#f3]_.
 
 Similarly, don't be too polite or subtle about things. Politeness easily
 ends up going overboard and hiding the problem, and as they say, "On the
@@ -251,15 +258,16 @@ Some humor can help pad both the bluntness and the moralizing.  Going
 overboard to the point of being ridiculous can drive a point home
 without making it painful to the recipient, who just thinks you're being
 silly.  It can thus help get through the personal mental block we all
-have about criticism. 
+have about criticism.
 
-(*) Hint: internet newsgroups that are not directly related to your work
-are great ways to take out your frustrations at other people. Write
-insulting posts with a sneer just to get into a good flame every once in
-a while, and you'll feel cleansed. Just don't crap too close to home.
+.. [#f3] Hint: internet newsgroups that are not directly related to your work
+  are great ways to take out your frustrations at other people. Write
+  insulting posts with a sneer just to get into a good flame every once in
+  a while, and you'll feel cleansed. Just don't crap too close to home.
 
 
-		Chapter 6: Why me?
+Why me?
+-------
 
 Since your main responsibility seems to be to take the blame for other
 peoples mistakes, and make it painfully obvious to everybody else that
@@ -268,9 +276,9 @@ first place?
 
 First off, while you may or may not get screaming teenage girls (or
 boys, let's not be judgmental or sexist here) knocking on your dressing
-room door, you _will_ get an immense feeling of personal accomplishment
+room door, you **will** get an immense feeling of personal accomplishment
 for being "in charge".  Never mind the fact that you're really leading
 by trying to keep up with everybody else and running after them as fast
-as you can.  Everybody will still think you're the person in charge. 
+as you can.  Everybody will still think you're the person in charge.
 
 It's a great job if you can hack it.
-- 
2.7.4

[PATCH v2 11/20] SecurityBugs.rst: convert it to ReST markup

[Mauro Carvalho Chehab]

Add a name for the document and convert the sections to
ReST markups.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/development-process/SecurityBugs.rst | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/Documentation/development-process/SecurityBugs.rst b/Documentation/development-process/SecurityBugs.rst
index a660d494c8ed..5f61bd4bc8ef 100644
--- a/Documentation/development-process/SecurityBugs.rst
+++ b/Documentation/development-process/SecurityBugs.rst
@@ -1,9 +1,13 @@
+Security bugs
+=============
+
 Linux kernel developers take security very seriously.  As such, we'd
 like to know when a security bug is found so that it can be fixed and
 disclosed as quickly as possible.  Please report security bugs to the
 Linux kernel security team.
 
-1) Contact
+Contact
+-------
 
 The Linux kernel security team can be contacted by email at
 <security@kernel.org>.  This is a private list of security officers
@@ -17,7 +21,8 @@ REPORTING-BUGS if you are unclear about what information is helpful.
 Any exploit code is very helpful and will not be released without
 consent from the reporter unless it has already been made public.
 
-2) Disclosure
+Disclosure
+----------
 
 The goal of the Linux kernel security team is to work with the
 bug submitter to bug resolution as well as disclosure.  We prefer
@@ -32,7 +37,8 @@ disclosure is from immediate (esp. if it's already publicly known)
 to a few weeks.  As a basic default policy, we expect report date to
 disclosure date to be on the order of 7 days.
 
-3) Non-disclosure agreements
+Non-disclosure agreements
+-------------------------
 
 The Linux kernel security team is not a formal body and therefore unable
 to enter any non-disclosure agreements.
-- 
2.7.4

[PATCH v2 12/20] stable_api_nonsense.rst: convert it to ReST markup

[Mauro Carvalho Chehab]

Add markups for it to be properly parsed by Sphinx.

As people browsing this document may not notice that the source
file title is "stable_api_nonsense", I opted to use bold to
the rationale for this document. I also found it better to
add a note when it says that the nonsense applies only to the
kABI/kAPI, and not to uAPI.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 .../development-process/stable_api_nonsense.rst    | 33 +++++++++++++++-------
 1 file changed, 23 insertions(+), 10 deletions(-)

diff --git a/Documentation/development-process/stable_api_nonsense.rst b/Documentation/development-process/stable_api_nonsense.rst
index db3be892afb2..0d375c115b0c 100644
--- a/Documentation/development-process/stable_api_nonsense.rst
+++ b/Documentation/development-process/stable_api_nonsense.rst
@@ -1,17 +1,24 @@
 The Linux Kernel Driver Interface
+==================================
+
 (all of your questions answered and then some)
 
 Greg Kroah-Hartman <greg@kroah.com>
 
-This is being written to try to explain why Linux does not have a binary
-kernel interface, nor does it have a stable kernel interface.  Please
-realize that this article describes the _in kernel_ interfaces, not the
-kernel to userspace interfaces.  The kernel to userspace interface is
-the one that application programs use, the syscall interface.  That
-interface is _very_ stable over time, and will not break.  I have old
-programs that were built on a pre 0.9something kernel that still work
-just fine on the latest 2.6 kernel release.  That interface is the one
-that users and application programmers can count on being stable.
+This is being written to try to explain why Linux **does not have a binary
+kernel interface, nor does it have a stable kernel interface**.
+
+.. note::
+
+  Please realize that this article describes the **in kernel** interfaces, not
+  the kernel to userspace interfaces.
+
+  The kernel to userspace interface is the one that application programs use,
+  the syscall interface.  That interface is **very** stable over time, and
+  will not break.  I have old programs that were built on a pre 0.9something
+  kernel that still work just fine on the latest 2.6 kernel release.
+  That interface is the one that users and application programmers can count
+  on being stable.
 
 
 Executive Summary
@@ -51,19 +58,23 @@ Binary Kernel Interface
 Assuming that we had a stable kernel source interface for the kernel, a
 binary interface would naturally happen too, right?  Wrong.  Please
 consider the following facts about the Linux kernel:
+
   - Depending on the version of the C compiler you use, different kernel
     data structures will contain different alignment of structures, and
     possibly include different functions in different ways (putting
     functions inline or not.)  The individual function organization
     isn't that important, but the different data structure padding is
     very important.
+
   - Depending on what kernel build options you select, a wide range of
     different things can be assumed by the kernel:
+
       - different structures can contain different fields
       - Some functions may not be implemented at all, (i.e. some locks
 	compile away to nothing for non-SMP builds.)
       - Memory within the kernel can be aligned in different ways,
 	depending on the build options.
+
   - Linux runs on a wide range of different processor architectures.
     There is no way that binary drivers from one architecture will run
     on another architecture properly.
@@ -105,6 +116,7 @@ As a specific examples of this, the in-kernel USB interfaces have
 undergone at least three different reworks over the lifetime of this
 subsystem.  These reworks were done to address a number of different
 issues:
+
   - A change from a synchronous model of data streams to an asynchronous
     one.  This reduced the complexity of a number of drivers and
     increased the throughput of all USB drivers such that we are now
@@ -166,6 +178,7 @@ very little effort on your part.
 
 The very good side effects of having your driver in the main kernel tree
 are:
+
   - The quality of the driver will rise as the maintenance costs (to the
     original developer) will decrease.
   - Other developers will add features to your driver.
@@ -175,7 +188,7 @@ are:
     changes require it.
   - The driver automatically gets shipped in all Linux distributions
     without having to ask the distros to add it.
-    
+
 As Linux supports a larger number of different devices "out of the box"
 than any other operating system, and it supports these devices on more
 different processor architectures than any other operating system, this
-- 
2.7.4

[PATCH v2 13/20] stable_kernel_rules.rst: convert it to ReST markup

[Mauro Carvalho Chehab]

- use ReST markups for section headers;
- add cross-references to the options;
- mark code blocks;
- a few minor changes to make Sphinx happy.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 .../development-process/stable_kernel_rules.rst    | 101 ++++++++++++++-------
 1 file changed, 68 insertions(+), 33 deletions(-)

diff --git a/Documentation/development-process/stable_kernel_rules.rst b/Documentation/development-process/stable_kernel_rules.rst
index ffd4575ec9f2..387d8a44eda2 100644
--- a/Documentation/development-process/stable_kernel_rules.rst
+++ b/Documentation/development-process/stable_kernel_rules.rst
@@ -1,4 +1,5 @@
-Everything you ever wanted to know about Linux -stable releases.
+Everything you ever wanted to know about Linux -stable releases
+===============================================================
 
 Rules on what kind of patches are accepted, and which ones are not, into the
 "-stable" tree:
@@ -27,7 +28,8 @@ Rules on what kind of patches are accepted, and which ones are not, into the
  - It or an equivalent fix must already exist in Linus' tree (upstream).
 
 
-Procedure for submitting patches to the -stable tree:
+Procedure for submitting patches to the -stable tree
+----------------------------------------------------
 
  - If the patch covers files in net/ or drivers/net please follow netdev stable
    submission guidelines as described in
@@ -35,56 +37,78 @@ Procedure for submitting patches to the -stable tree:
  - Security patches should not be handled (solely) by the -stable review
    process but should follow the procedures in Documentation/SecurityBugs.
 
-For all other submissions, choose one of the following procedures:
+For all other submissions, choose one of the following procedures
+-----------------------------------------------------------------
 
-   --- Option 1 ---
+.. _option_1:
+
+Option 1
+********
+
+To have the patch automatically included in the stable tree, add the tag
+
+.. code-block:: none
 
-   To have the patch automatically included in the stable tree, add the tag
      Cc: stable@vger.kernel.org
-   in the sign-off area. Once the patch is merged it will be applied to
-   the stable tree without anything else needing to be done by the author
-   or subsystem maintainer.
 
-   --- Option 2 ---
+in the sign-off area. Once the patch is merged it will be applied to
+the stable tree without anything else needing to be done by the author
+or subsystem maintainer.
 
-   After the patch has been merged to Linus' tree, send an email to
-   stable@vger.kernel.org containing the subject of the patch, the commit ID,
-   why you think it should be applied, and what kernel version you wish it to
-   be applied to.
+.. _option_2:
 
-   --- Option 3 ---
+Option 2
+********
 
-   Send the patch, after verifying that it follows the above rules, to
-   stable@vger.kernel.org.  You must note the upstream commit ID in the
-   changelog of your submission, as well as the kernel version you wish
-   it to be applied to.
+After the patch has been merged to Linus' tree, send an email to
+stable@vger.kernel.org containing the subject of the patch, the commit ID,
+why you think it should be applied, and what kernel version you wish it to
+be applied to.
 
-Option 1 is *strongly* preferred, is the easiest and most common.  Options 2 and
-3 are more useful if the patch isn't deemed worthy at the time it is applied to
-a public git tree (for instance, because it deserves more regression testing
-first).  Option 3 is especially useful if the patch needs some special handling
-to apply to an older kernel (e.g., if API's have changed in the meantime).
+.. _option_3:
 
-Note that for Option 3, if the patch deviates from the original upstream patch
-(for example because it had to be backported) this must be very clearly
-documented and justified in the patch description.
+Option 3
+********
+
+Send the patch, after verifying that it follows the above rules, to
+stable@vger.kernel.org.  You must note the upstream commit ID in the
+changelog of your submission, as well as the kernel version you wish
+it to be applied to.
+
+:ref:`option_1` is **strongly** preferred, is the easiest and most common.
+:ref:`option_2` and :ref:`option_3` are more useful if the patch isn't deemed
+worthy at the time it is applied to a public git tree (for instance, because
+it deserves more regression testing first).  :ref:`option_3` is especially
+useful if the patch needs some special handling to apply to an older kernel
+(e.g., if API's have changed in the meantime).
+
+Note that for :ref:`option_3`, if the patch deviates from the original
+upstream patch (for example because it had to be backported) this must be very
+clearly documented and justified in the patch description.
 
 The upstream commit ID must be specified with a separate line above the commit
 text, like this:
 
+.. code-block:: none
+
     commit <sha1> upstream.
 
 Additionally, some patches submitted via Option 1 may have additional patch
 prerequisites which can be cherry-picked. This can be specified in the following
 format in the sign-off area:
 
+.. code-block:: none
+
      Cc: <stable@vger.kernel.org> # 3.3.x: a1f84a3: sched: Check for idle
      Cc: <stable@vger.kernel.org> # 3.3.x: 1b9508f: sched: Rate-limit newidle
      Cc: <stable@vger.kernel.org> # 3.3.x: fd21073: sched: Fix affinity logic
      Cc: <stable@vger.kernel.org> # 3.3.x
-    Signed-off-by: Ingo Molnar <mingo@elte.hu>
+     Signed-off-by: Ingo Molnar <mingo@elte.hu>
+
+The tag sequence has the meaning of:
+
+.. code-block:: none
 
-   The tag sequence has the meaning of:
      git cherry-pick a1f84a3
      git cherry-pick 1b9508f
      git cherry-pick fd21073
@@ -93,12 +117,17 @@ format in the sign-off area:
 Also, some patches may have kernel version prerequisites.  This can be
 specified in the following format in the sign-off area:
 
+.. code-block:: none
+
      Cc: <stable@vger.kernel.org> # 3.3.x-
 
-   The tag has the meaning of:
+The tag has the meaning of:
+
+.. code-block:: none
+
      git cherry-pick <this commit>
 
-   For each "-stable" tree starting with the specified version.
+For each "-stable" tree starting with the specified version.
 
 Following the submission:
 
@@ -109,7 +138,8 @@ Following the submission:
    other developers and by the relevant subsystem maintainer.
 
 
-Review cycle:
+Review cycle
+------------
 
  - When the -stable maintainers decide for a review cycle, the patches will be
    sent to the review committee, and the maintainer of the affected area of
@@ -125,17 +155,22 @@ Review cycle:
    security kernel team, and not go through the normal review cycle.
    Contact the kernel security team for more details on this procedure.
 
-Trees:
+Trees
+-----
 
  - The queues of patches, for both completed versions and in progress
    versions can be found at:
+
 	http://git.kernel.org/?p=linux/kernel/git/stable/stable-queue.git
+
  - The finalized and tagged releases of all stable kernels can be found
    in separate branches per version at:
+
 	http://git.kernel.org/?p=linux/kernel/git/stable/linux-stable.git
 
 
-Review committee:
+Review committee
+----------------
 
  - This is made up of a number of kernel developers who have volunteered for
    this task, and a few that haven't.
-- 
2.7.4

[PATCH v2 14/20] SubmittingDrivers.rst: convert it to ReST markup

[Mauro Carvalho Chehab]

- Change the document title markup to make it on a higher level;
- Add blank lines as needed, to improve the output;
- use italics for the country-code at kernel.org ftp URL.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 .../development-process/SubmittingDrivers.rst      | 45 +++++++++++++++-------
 1 file changed, 31 insertions(+), 14 deletions(-)

diff --git a/Documentation/development-process/SubmittingDrivers.rst b/Documentation/development-process/SubmittingDrivers.rst
index 31d372609ac0..a2f30a9e28d1 100644
--- a/Documentation/development-process/SubmittingDrivers.rst
+++ b/Documentation/development-process/SubmittingDrivers.rst
@@ -1,5 +1,5 @@
 Submitting Drivers For The Linux Kernel
----------------------------------------
+=======================================
 
 This document is intended to explain how to submit device drivers to the
 various kernel trees. Note that if you are interested in video card drivers
@@ -46,34 +46,39 @@ Linux 2.6:
 What Criteria Determine Acceptance
 ----------------------------------
 
-Licensing:	The code must be released to us under the
+Licensing:
+		The code must be released to us under the
 		GNU General Public License. We don't insist on any kind
 		of exclusive GPL licensing, and if you wish the driver
 		to be useful to other communities such as BSD you may well
 		wish to release under multiple licenses.
 		See accepted licenses at include/linux/module.h
 
-Copyright:	The copyright owner must agree to use of GPL.
+Copyright:
+		The copyright owner must agree to use of GPL.
 		It's best if the submitter and copyright owner
 		are the same person/entity. If not, the name of
 		the person/entity authorizing use of GPL should be
 		listed in case it's necessary to verify the will of
 		the copyright owner.
 
-Interfaces:	If your driver uses existing interfaces and behaves like
+Interfaces:
+		If your driver uses existing interfaces and behaves like
 		other drivers in the same class it will be much more likely
 		to be accepted than if it invents gratuitous new ones.
 		If you need to implement a common API over Linux and NT
 		drivers do it in userspace.
 
-Code:		Please use the Linux style of code formatting as documented
+Code:
+		Please use the Linux style of code formatting as documented
 		in Documentation/CodingStyle. If you have sections of code
 		that need to be in other formats, for example because they
 		are shared with a windows driver kit and you want to
 		maintain them just once separate them out nicely and note
 		this fact.
 
-Portability:	Pointers are not always 32bits, not all computers are little
+Portability:
+		Pointers are not always 32bits, not all computers are little
 		endian, people do not all have floating point and you
 		shouldn't use inline x86 assembler in your driver without
 		careful thought. Pure x86 drivers generally are not popular.
@@ -81,12 +86,14 @@ Portability:	Pointers are not always 32bits, not all computers are little
 		but it is easy to make sure the code can easily be made
 		portable.
 
-Clarity:	It helps if anyone can see how to fix the driver. It helps
+Clarity:
+		It helps if anyone can see how to fix the driver. It helps
 		you because you get patches not bug reports. If you submit a
 		driver that intentionally obfuscates how the hardware works
 		it will go in the bitbucket.
 
-PM support:	Since Linux is used on many portable and desktop systems, your
+PM support:
+		Since Linux is used on many portable and desktop systems, your
 		driver is likely to be used on such a system and therefore it
 		should support basic power management by implementing, if
 		necessary, the .suspend and .resume methods used during the
@@ -101,7 +108,8 @@ PM support:	Since Linux is used on many portable and desktop systems, your
 		complete overview of the power management issues related to
 		drivers see Documentation/power/devices.txt .
 
-Control:	In general if there is active maintenance of a driver by
+Control:
+		In general if there is active maintenance of a driver by
 		the author then patches will be redirected to them unless
 		they are totally obvious and without need of checking.
 		If you want to be the contact and update point for the
@@ -111,13 +119,15 @@ Control:	In general if there is active maintenance of a driver by
 What Criteria Do Not Determine Acceptance
 -----------------------------------------
 
-Vendor:		Being the hardware vendor and maintaining the driver is
+Vendor:
+		Being the hardware vendor and maintaining the driver is
 		often a good thing. If there is a stable working driver from
 		other people already in the tree don't expect 'we are the
 		vendor' to get your driver chosen. Ideally work with the
 		existing driver author to build a single perfect driver.
 
-Author:		It doesn't matter if a large Linux company wrote the driver,
+Author:
+		It doesn't matter if a large Linux company wrote the driver,
 		or you did. Nobody has any special access to the kernel
 		tree. Anyone who tells you otherwise isn't telling the
 		whole story.
@@ -127,8 +137,10 @@ Resources
 ---------
 
 Linux kernel master tree:
-	ftp.??.kernel.org:/pub/linux/kernel/...
-	?? == your country code, such as "us", "uk", "fr", etc.
+	ftp.\ *country_code*\ .kernel.org:/pub/linux/kernel/...
+
+	where *country_code* == your country code, such as
+	**us**, **uk**, **fr**, etc.
 
 	http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git
 
@@ -141,14 +153,19 @@ Linux Device Drivers, Third Edition (covers 2.6.10):
 
 LWN.net:
 	Weekly summary of kernel development activity - http://lwn.net/
+
 	2.6 API changes:
+
 		http://lwn.net/Articles/2.6-kernel-api/
+
 	Porting drivers from prior kernels to 2.6:
+
 		http://lwn.net/Articles/driver-porting/
 
 KernelNewbies:
 	Documentation and assistance for new kernel programmers
-	http://kernelnewbies.org/
+
+		http://kernelnewbies.org/
 
 Linux USB project:
 	http://www.linux-usb.org/
-- 
2.7.4

[PATCH v2 15/20] SubmittingPatches.rst: convert it to ReST markup

[Mauro Carvalho Chehab]

- Change the sections to use ReST markup;
- Add cross-references where needed;
- convert aspas to verbatim text;
- use code block tags;
- make Sphinx happy.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 .../development-process/SubmittingPatches.rst      | 233 ++++++++++++---------
 1 file changed, 133 insertions(+), 100 deletions(-)

diff --git a/Documentation/development-process/SubmittingPatches.rst b/Documentation/development-process/SubmittingPatches.rst
index 8c79f1d53731..f47cea0ff615 100644
--- a/Documentation/development-process/SubmittingPatches.rst
+++ b/Documentation/development-process/SubmittingPatches.rst
@@ -1,9 +1,6 @@
 
-	How to Get Your Change Into the Linux Kernel
-		or
-	Care And Operation Of Your Linus Torvalds
-
-
+How to Get Your Change Into the Linux Kernel or Care And Operation Of Your Linus Torvalds
+=========================================================================================
 
 For a person or company who wishes to submit a change to the Linux
 kernel, the process can sometimes be daunting if you're not familiar
@@ -24,46 +21,49 @@ of the mechanical work done for you, though you'll still need to prepare
 and document a sensible set of patches.  In general, use of git will make
 your life as a kernel developer easier.
 
---------------------------------------------
-SECTION 1 - CREATING AND SENDING YOUR CHANGE
---------------------------------------------
+Creating and Sending your Change
+********************************
 
 
-0) Obtain a current source tree
--------------------------------
+Obtain a current source tree
+----------------------------
 
 If you do not have a repository with the current kernel source handy, use
 git to obtain one.  You'll want to start with the mainline repository,
 which can be grabbed with:
 
-  git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git 
+::
+
+  git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
 
 Note, however, that you may not want to develop against the mainline tree
 directly.  Most subsystem maintainers run their own trees and want to see
-patches prepared against those trees.  See the "T:" entry for the subsystem
+patches prepared against those trees.  See the **T:** entry for the subsystem
 in the MAINTAINERS file to find that tree, or simply ask the maintainer if
 the tree is not listed there.
 
 It is still possible to download kernel releases via tarballs (as described
 in the next section), but that is the hard way to do kernel development.
 
-1) "diff -up"
+``diff -up``
 ------------
 
-If you must generate your patches by hand, use "diff -up" or "diff -uprN"
+If you must generate your patches by hand, use ``diff -up`` or ``diff -uprN``
 to create patches.  Git generates patches in this form by default; if
 you're using git, you can skip this section entirely.
 
 All changes to the Linux kernel occur in the form of patches, as
 generated by diff(1).  When creating your patch, make sure to create it
-in "unified diff" format, as supplied by the '-u' argument to diff(1).
-Also, please use the '-p' argument which shows which C function each
+in "unified diff" format, as supplied by the ``-u`` argument to diff(1).
+Also, please use the ``-p`` argument which shows which C function each
 change is in - that makes the resultant diff a lot easier to read.
 Patches should be based in the root kernel source directory,
 not in any lower subdirectory.
 
 To create a patch for a single file, it is often sufficient to do:
 
+::
+
 	SRCTREE= linux
 	MYFILE=  drivers/net/mydriver.c
 
@@ -77,6 +77,8 @@ To create a patch for multiple files, you should unpack a "vanilla",
 or unmodified kernel source tree, and generate a diff against your
 own source tree.  For example:
 
+::
+
 	MYSRC= /devel/linux
 
 	tar xvfz linux-3.19.tar.gz
@@ -84,7 +86,7 @@ own source tree.  For example:
 	diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \
 		linux-3.19-vanilla $MYSRC > /tmp/patch
 
-"dontdiff" is a list of files which are generated by the kernel during
+``dontdiff`` is a list of files which are generated by the kernel during
 the build process, and should be ignored in any diff(1)-generated
 patch.
 
@@ -93,18 +95,18 @@ belong in a patch submission.  Make sure to review your patch -after-
 generating it with diff(1), to ensure accuracy.
 
 If your changes produce a lot of deltas, you need to split them into
-individual patches which modify things in logical stages; see section
-#3.  This will facilitate review by other kernel developers,
+individual patches which modify things in logical stages; see
+:ref:`split_changes`.  This will facilitate review by other kernel developers,
 very important if you want your patch accepted.
 
-If you're using git, "git rebase -i" can help you with this process.  If
+If you're using git, ``git rebase -i`` can help you with this process.  If
 you're not using git, quilt <http://savannah.nongnu.org/projects/quilt>
 is another popular alternative.
 
+.. _describe_changes:
 
-
-2) Describe your changes.
--------------------------
+Describe your changes
+---------------------
 
 Describe your problem.  Whether your patch is a one-line bug fix or
 5000 lines of a new feature, there must be an underlying problem that
@@ -137,11 +139,11 @@ as you intend it to.
 
 The maintainer will thank you if you write your patch description in a
 form which can be easily pulled into Linux's source code management
-system, git, as a "commit log".  See #15, below.
+system, git, as a "commit log".  See :ref:`explicit_in_reply_to`.
 
 Solve only one problem per patch.  If your description starts to get
 long, that's a sign that you probably need to split up your patch.
-See #3, next.
+See :ref:`split_changes`.
 
 When you submit or resubmit a patch or patch series, include the
 complete patch description and justification for it.  Don't just
@@ -173,6 +175,8 @@ SHA-1 ID of the commit. Please also include the oneline summary of
 the commit, to make it easier for reviewers to know what it is about.
 Example:
 
+::
+
 	Commit e21d2170f36602ae2708 ("video: remove unnecessary
 	platform_set_drvdata()") removed the unnecessary
 	platform_set_drvdata(), but left the variable "dev" unused,
@@ -188,20 +192,26 @@ If your patch fixes a bug in a specific commit, e.g. you found an issue using
 git-bisect, please use the 'Fixes:' tag with the first 12 characters of the
 SHA-1 ID, and the one line summary.  For example:
 
+::
+
 	Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()")
 
 The following git-config settings can be used to add a pretty format for
 outputting the above style in the git log or git show commands
 
+::
+
 	[core]
 		abbrev = 12
 	[pretty]
 		fixes = Fixes: %h (\"%s\")
 
-3) Separate your changes.
--------------------------
+.. _split_changes:
 
-Separate each _logical change_ into a separate patch.
+Separate your changes
+---------------------
+
+Separate each **logical change** into a separate patch.
 
 For example, if your changes include both bug fixes and performance
 enhancements for a single driver, separate those changes into two
@@ -217,12 +227,12 @@ change that can be verified by reviewers.  Each patch should be justifiable
 on its own merits.
 
 If one patch depends on another patch in order for a change to be
-complete, that is OK.  Simply note "this patch depends on patch X"
+complete, that is OK.  Simply note **"this patch depends on patch X"**
 in your patch description.
 
 When dividing your change into a series of patches, take special care to
 ensure that the kernel builds and runs properly after each patch in the
-series.  Developers using "git bisect" to track down a problem can end up
+series.  Developers using ``git bisect`` to track down a problem can end up
 splitting your patch series at any point; they will not thank you if you
 introduce bugs in the middle.
 
@@ -231,8 +241,8 @@ then only post say 15 or so at a time and wait for review and integration.
 
 
 
-4) Style-check your changes.
-----------------------------
+Style-check your changes
+------------------------
 
 Check your patch for basic style violations, details of which can be
 found in Documentation/CodingStyle.  Failure to do so simply wastes
@@ -260,8 +270,8 @@ You should be able to justify all violations that remain in your
 patch.
 
 
-5) Select the recipients for your patch.
-----------------------------------------
+Select the recipients for your patch
+------------------------------------
 
 You should always copy the appropriate subsystem maintainer(s) on any patch
 to code that they maintain; look through the MAINTAINERS file and the
@@ -297,6 +307,8 @@ obviously, the patch should not be sent to any public lists.
 Patches that fix a severe bug in a released kernel should be directed
 toward the stable maintainers by putting a line like this:
 
+::
+
   Cc: stable@vger.kernel.org
 
 into the sign-off area of your patch (note, NOT an email recipient).  You
@@ -312,12 +324,14 @@ If changes affect userland-kernel interfaces, please send the MAN-PAGES
 maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at
 least a notification of the change, so that some information makes its way
 into the manual pages.  User-space API changes should also be copied to
-linux-api@vger.kernel.org. 
+linux-api@vger.kernel.org.
 
 For small patches you may want to CC the Trivial Patch Monkey
 trivial@kernel.org which collects "trivial" patches. Have a look
 into the MAINTAINERS file for its current manager.
+
 Trivial patches must qualify for one of the following rules:
+
  Spelling fixes in documentation
  Spelling fixes for errors which could break grep(1)
  Warning fixes (cluttering with useless warnings is bad)
@@ -332,8 +346,8 @@ Trivial patches must qualify for one of the following rules:
 
 
 
-6) No MIME, no links, no compression, no attachments.  Just plain text.
------------------------------------------------------------------------
+No MIME, no links, no compression, no attachments.  Just plain text
+-------------------------------------------------------------------
 
 Linus and other kernel developers need to be able to read and comment
 on the changes you are submitting.  It is important for a kernel
@@ -356,8 +370,8 @@ you to re-send them using MIME.
 See Documentation/email-clients.txt for hints about configuring
 your e-mail client so that it sends your patches untouched.
 
-7) E-mail size.
----------------
+E-mail size
+-----------
 
 Large changes are not appropriate for mailing lists, and some
 maintainers.  If your patch, uncompressed, exceeds 300 kB in size,
@@ -366,8 +380,8 @@ server, and provide instead a URL (link) pointing to your patch.  But note
 that if your patch exceeds 300 kB, it almost certainly needs to be broken up
 anyway.
 
-8) Respond to review comments.
-------------------------------
+Respond to review comments
+--------------------------
 
 Your patch will almost certainly get comments from reviewers on ways in
 which the patch can be improved.  You must respond to those comments;
@@ -382,8 +396,8 @@ reviewers sometimes get grumpy.  Even in that case, though, respond
 politely and address the problems they have pointed out.
 
 
-9) Don't get discouraged - or impatient.
-----------------------------------------
+Don't get discouraged - or impatient
+------------------------------------
 
 After you have submitted your change, be patient and wait.  Reviewers are
 busy people and may not get to your patch right away.
@@ -396,8 +410,8 @@ one week before resubmitting or pinging reviewers - possibly longer during
 busy times like merge windows.
 
 
-10) Include PATCH in the subject
---------------------------------
+Include PATCH in the subject
+----------------------------
 
 Due to high e-mail traffic to Linus, and to linux-kernel, it is common
 convention to prefix your subject line with [PATCH].  This lets Linus
@@ -406,8 +420,8 @@ e-mail discussions.
 
 
 
-11) Sign your work
-------------------
+Sign your work
+--------------
 
 To improve tracking of who did what, especially with patches that can
 percolate to their final resting place in the kernel through several
@@ -419,9 +433,10 @@ patch, which certifies that you wrote it or otherwise have the right to
 pass it on as an open-source patch.  The rules are pretty simple: if you
 can certify the below:
 
-        Developer's Certificate of Origin 1.1
+Developer's Certificate of Origin 1.1
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-        By making a contribution to this project, I certify that:
+By making a contribution to this project, I certify that:
 
         (a) The contribution was created in whole or in part by me and I
             have the right to submit it under the open source license
@@ -447,6 +462,8 @@ can certify the below:
 
 then you just add a line saying
 
+::
+
 	Signed-off-by: Random J Developer <random@developer.example.org>
 
 using your real name (sorry, no pseudonyms or anonymous contributions.)
@@ -466,7 +483,9 @@ you add a line between the last Signed-off-by header and yours, indicating
 the nature of your changes. While there is nothing mandatory about this, it
 seems like prepending the description with your mail and/or name, all
 enclosed in square brackets, is noticeable enough to make it obvious that
-you are responsible for last-minute changes. Example :
+you are responsible for last-minute changes. Example:
+
+::
 
 	Signed-off-by: Random J Developer <random@developer.example.org>
 	[lucky@maintainer.example.org: struct foo moved from foo.c to foo.h]
@@ -483,7 +502,9 @@ to insert an indication of the origin of a patch at the top of the commit
 message (just after the subject line) to facilitate tracking. For instance,
 here's what we see in a 3.x-stable release:
 
-Date:   Tue Oct 7 07:26:38 2014 -0400
+::
+
+  Date:   Tue Oct 7 07:26:38 2014 -0400
 
     libata: Un-break ATA blacklist
 
@@ -491,6 +512,8 @@ Date:   Tue Oct 7 07:26:38 2014 -0400
 
 And here's what might appear in an older kernel once a patch is backported:
 
+::
+
     Date:   Tue May 13 22:12:27 2008 +0200
 
         wireless, airo: waitbusy() won't delay
@@ -502,8 +525,8 @@ tracking your trees, and to people trying to troubleshoot bugs in your
 tree.
 
 
-12) When to use Acked-by: and Cc:
----------------------------------
+When to use Acked-by: and Cc
+----------------------------
 
 The Signed-off-by: tag indicates that the signer was involved in the
 development of the patch, or that he/she was in the patch's delivery path.
@@ -529,15 +552,15 @@ When in doubt people should refer to the original discussion in the mailing
 list archives.
 
 If a person has had the opportunity to comment on a patch, but has not
-provided such comments, you may optionally add a "Cc:" tag to the patch.
+provided such comments, you may optionally add a ``Cc:`` tag to the patch.
 This is the only tag which might be added without an explicit action by the
 person it names - but it should indicate that this person was copied on the
 patch.  This tag documents that potentially interested parties
 have been included in the discussion.
 
 
-13) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes:
---------------------------------------------------------------------------
+Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes
+---------------------------------------------------------------------
 
 The Reported-by tag gives credit to people who find bugs and report them and it
 hopefully inspires them to help us again in the future.  Please note that if
@@ -552,9 +575,10 @@ future patches, and ensures credit for the testers.
 Reviewed-by:, instead, indicates that the patch has been reviewed and found
 acceptable according to the Reviewer's Statement:
 
-	Reviewer's statement of oversight
+Reviewer's statement of oversight
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-	By offering my Reviewed-by: tag, I state that:
+By offering my Reviewed-by: tag, I state that:
 
  	 (a) I have carried out a technical review of this patch to
 	     evaluate its appropriateness and readiness for inclusion into
@@ -594,24 +618,27 @@ A Fixes: tag indicates that the patch fixes an issue in a previous commit. It
 is used to make it easy to determine where a bug originated, which can help
 review a bug fix. This tag also assists the stable kernel team in determining
 which stable kernel versions should receive your fix. This is the preferred
-method for indicating a bug fixed by the patch. See #2 above for more details.
+method for indicating a bug fixed by the patch. See :ref:`describe_changes`
+for more details.
 
 
-14) The canonical patch format
-------------------------------
+The canonical patch format
+--------------------------
 
 This section describes how the patch itself should be formatted.  Note
 that, if you have your patches stored in a git repository, proper patch
-formatting can be had with "git format-patch".  The tools cannot create
+formatting can be had with ``git format-patch``.  The tools cannot create
 the necessary text, though, so read the instructions below anyway.
 
 The canonical patch subject line is:
 
+::
+
     Subject: [PATCH 001/123] subsystem: summary phrase
 
 The canonical patch message body contains the following:
 
-  - A "from" line specifying the patch author (only needed if the person
+  - A ``from`` line specifying the patch author (only needed if the person
     sending the patch is not the author).
 
   - An empty line.
@@ -619,10 +646,10 @@ The canonical patch message body contains the following:
   - The body of the explanation, line wrapped at 75 columns, which will
     be copied to the permanent changelog to describe this patch.
 
-  - The "Signed-off-by:" lines, described above, which will
+  - The ``Signed-off-by:`` lines, described above, which will
     also go in the changelog.
 
-  - A marker line containing simply "---".
+  - A marker line containing simply ``---``.
 
   - Any additional comments not suitable for the changelog.
 
@@ -633,32 +660,32 @@ alphabetically by subject line - pretty much any email reader will
 support that - since because the sequence number is zero-padded,
 the numerical and alphabetic sort is the same.
 
-The "subsystem" in the email's Subject should identify which
+The ``subsystem`` in the email's Subject should identify which
 area or subsystem of the kernel is being patched.
 
-The "summary phrase" in the email's Subject should concisely
-describe the patch which that email contains.  The "summary
-phrase" should not be a filename.  Do not use the same "summary
-phrase" for every patch in a whole patch series (where a "patch
-series" is an ordered sequence of multiple, related patches).
+The ``summary phrase`` in the email's Subject should concisely
+describe the patch which that email contains.  The ``summary
+phrase`` should not be a filename.  Do not use the same ``summary
+phrase`` for every patch in a whole patch series (where a ``patch
+series`` is an ordered sequence of multiple, related patches).
 
-Bear in mind that the "summary phrase" of your email becomes a
+Bear in mind that the ``summary phrase`` of your email becomes a
 globally-unique identifier for that patch.  It propagates all the way
-into the git changelog.  The "summary phrase" may later be used in
+into the git changelog.  The ``summary phrase`` may later be used in
 developer discussions which refer to the patch.  People will want to
-google for the "summary phrase" to read discussion regarding that
+google for the ``summary phrase`` to read discussion regarding that
 patch.  It will also be the only thing that people may quickly see
 when, two or three months later, they are going through perhaps
-thousands of patches using tools such as "gitk" or "git log
+thousands of patches using tools such as ``gitk`` or "git log
 --oneline".
 
-For these reasons, the "summary" must be no more than 70-75
+For these reasons, the ``summary`` must be no more than 70-75
 characters, and it must describe both what the patch changes, as well
 as why the patch might be necessary.  It is challenging to be both
 succinct and descriptive, but that is what a well-written summary
 should do.
 
-The "summary phrase" may be prefixed by tags enclosed in square
+The ``summary phrase`` may be prefixed by tags enclosed in square
 brackets: "Subject: [PATCH <tag>...] <summary phrase>".  The tags are
 not considered part of the summary phrase, but describe how the patch
 should be treated.  Common tags might include a version descriptor if
@@ -672,17 +699,19 @@ the patch series.
 
 A couple of example Subjects:
 
+::
+
     Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching
     Subject: [PATCH v2 01/27] x86: fix eflags tracking
 
-The "from" line must be the very first line in the message body,
+The ``from`` line must be the very first line in the message body,
 and has the form:
 
         From: Original Author <author@example.com>
 
-The "from" line specifies who will be credited as the author of the
-patch in the permanent changelog.  If the "from" line is missing,
-then the "From:" line from the email header will be used to determine
+The ``from`` line specifies who will be credited as the author of the
+patch in the permanent changelog.  If the ``from`` line is missing,
+then the ``From:`` line from the email header will be used to determine
 the patch author in the changelog.
 
 The explanation body will be committed to the permanent source
@@ -694,23 +723,23 @@ especially useful for people who might be searching the commit logs
 looking for the applicable patch.  If a patch fixes a compile failure,
 it may not be necessary to include _all_ of the compile failures; just
 enough that it is likely that someone searching for the patch can find
-it.  As in the "summary phrase", it is important to be both succinct as
+it.  As in the ``summary phrase``, it is important to be both succinct as
 well as descriptive.
 
-The "---" marker line serves the essential purpose of marking for patch
+The ``---`` marker line serves the essential purpose of marking for patch
 handling tools where the changelog message ends.
 
-One good use for the additional comments after the "---" marker is for
+One good use for the additional comments after the ``---`` marker is for
 a diffstat, to show what files have changed, and the number of
 inserted and deleted lines per file.  A diffstat is especially useful
 on bigger patches.  Other comments relevant only to the moment or the
 maintainer, not suitable for the permanent changelog, should also go
-here.  A good example of such comments might be "patch changelogs"
+here.  A good example of such comments might be ``patch changelogs``
 which describe what has changed between the v1 and v2 version of the
 patch.
 
-If you are going to include a diffstat after the "---" marker, please
-use diffstat options "-p 1 -w 70" so that filenames are listed from
+If you are going to include a diffstat after the ``---`` marker, please
+use diffstat options ``-p 1 -w 70`` so that filenames are listed from
 the top of the kernel source tree and don't use too much horizontal
 space (easily fit in 80 columns, maybe with some indentation).  (git
 generates appropriate diffstats by default.)
@@ -718,11 +747,13 @@ generates appropriate diffstats by default.)
 See more details on the proper patch format in the following
 references.
 
-15) Explicit In-Reply-To headers
---------------------------------
+.. _explicit_in_reply_to:
+
+Explicit In-Reply-To headers
+----------------------------
 
 It can be helpful to manually add In-Reply-To: headers to a patch
-(e.g., when using "git send-email") to associate the patch with
+(e.g., when using ``git send-email``) to associate the patch with
 previous relevant discussion, e.g. to link a bug fix to the email with
 the bug report.  However, for a multi-patch series, it is generally
 best to avoid using In-Reply-To: to link to older versions of the
@@ -732,12 +763,12 @@ helpful, you can use the https://lkml.kernel.org/ redirector (e.g., in
 the cover email text) to link to an earlier version of the patch series.
 
 
-16) Sending "git pull" requests
--------------------------------
+Sending ``git pull`` requests
+-----------------------------
 
 If you have a series of patches, it may be most convenient to have the
 maintainer pull them directly into the subsystem repository with a
-"git pull" operation.  Note, however, that pulling patches from a developer
+``git pull`` operation.  Note, however, that pulling patches from a developer
 requires a higher degree of trust than taking patches from a mailing list.
 As a result, many subsystem maintainers are reluctant to take pull
 requests, especially from new, unknown developers.  If in doubt you can use
@@ -748,6 +779,8 @@ A pull request should have [GIT] or [PULL] in the subject line.  The
 request itself should include the repository name and the branch of
 interest on a single line; it should look something like:
 
+::
+
   Please pull from
 
       git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus
@@ -755,10 +788,10 @@ interest on a single line; it should look something like:
   to get these changes:
 
 A pull request should also include an overall message saying what will be
-included in the request, a "git shortlog" listing of the patches
+included in the request, a ``git shortlog`` listing of the patches
 themselves, and a diffstat showing the overall effect of the patch series.
 The easiest way to get all this information together is, of course, to let
-git do it for you with the "git request-pull" command.
+git do it for you with the ``git request-pull`` command.
 
 Some maintainers (including Linus) want to see pull requests from signed
 commits; that increases their confidence that the request actually came
@@ -771,7 +804,7 @@ new developers, but there is no way around it.  Attending conferences can
 be a good way to find developers who can sign your key.
 
 Once you have prepared a patch series in git that you wish to have somebody
-pull, create a signed tag with "git tag -s".  This will create a new tag
+pull, create a signed tag with ``git tag -s``.  This will create a new tag
 identifying the last commit in the series and containing a signature
 created with your private key.  You will also have the opportunity to add a
 changelog-style message to the tag; this is an ideal place to describe the
@@ -784,12 +817,13 @@ public tree.
 When generating your pull request, use the signed tag as the target.  A
 command like this will do the trick:
 
+::
+
   git request-pull master git://my.public.tree/linux.git my-signed-tag
 
 
-----------------------
-SECTION 2 - REFERENCES
-----------------------
+REFERENCES
+**********
 
 Andrew Morton, "The perfect patch" (tpp).
   <http://www.ozlabs.org/~akpm/stuff/tpp.txt>
@@ -818,4 +852,3 @@ Andi Kleen, "On submitting kernel patches"
   Some strategies to get difficult or controversial changes in.
   http://halobates.de/on-submitting-patches.pdf
 
---
-- 
2.7.4

[PATCH v2 16/20] HOWTO.rst: add cross-references to other documents

[Mauro Carvalho Chehab]

The other documents at kernel-development are all mentioned
by HOWTO. Convert those mention to cross-references.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/development-process/Changes.rst          |  2 ++
 Documentation/development-process/CodingStyle.rst      |  1 +
 Documentation/development-process/HOWTO.rst            | 18 +++++++++---------
 Documentation/development-process/ManagementStyle.rst  |  2 ++
 Documentation/development-process/SecurityBugs.rst     |  2 ++
 .../development-process/SubmittingDrivers.rst          |  2 ++
 .../development-process/SubmittingPatches.rst          |  1 +
 Documentation/development-process/applying-patches.rst |  1 +
 Documentation/development-process/kernel-docs.rst      |  2 ++
 .../development-process/stable_api_nonsense.rst        |  2 ++
 .../development-process/stable_kernel_rules.rst        |  2 ++
 11 files changed, 26 insertions(+), 9 deletions(-)

diff --git a/Documentation/development-process/Changes.rst b/Documentation/development-process/Changes.rst
index a9f365d864c7..97f7bf178340 100644
--- a/Documentation/development-process/Changes.rst
+++ b/Documentation/development-process/Changes.rst
@@ -1,3 +1,5 @@
+.. _changes:
+
 Minimal requerements to compile the Kernel
 ++++++++++++++++++++++++++++++++++++++++++
 
diff --git a/Documentation/development-process/CodingStyle.rst b/Documentation/development-process/CodingStyle.rst
index d9debafbd2eb..510063361b04 100644
--- a/Documentation/development-process/CodingStyle.rst
+++ b/Documentation/development-process/CodingStyle.rst
@@ -1,3 +1,4 @@
+.. _codingstyle:
 
 Linux kernel coding style
 =========================
diff --git a/Documentation/development-process/HOWTO.rst b/Documentation/development-process/HOWTO.rst
index 5a85e3a8112b..31c8df5d20c7 100644
--- a/Documentation/development-process/HOWTO.rst
+++ b/Documentation/development-process/HOWTO.rst
@@ -90,19 +90,19 @@ required reading:
     what is necessary to do to configure and build the kernel.  People
     who are new to the kernel should start here.
 
-  Documentation/Changes
+  :ref:`Documentation/Changes <changes>`
     This file gives a list of the minimum levels of various software
     packages that are necessary to build and run the kernel
     successfully.
 
-  Documentation/CodingStyle
+  :ref:`Documentation/CodingStyle <codingstyle>`
     This describes the Linux kernel coding style, and some of the
     rationale behind it. All new code is expected to follow the
     guidelines in this document. Most maintainers will only accept
     patches if these rules are followed, and many people will only
     review code if it is in the proper style.
 
-  Documentation/SubmittingPatches and Documentation/SubmittingDrivers
+  :ref:`Documentation/SubmittingPatches <submittingpatches>` and :ref:`Documentation/SubmittingDrivers <submittingdrivers>`
     These files describe in explicit detail how to successfully create
     and send a patch, including (but not limited to):
 
@@ -124,7 +124,7 @@ required reading:
 
 		http://linux.yyz.us/patch-format.html
 
-  Documentation/stable_api_nonsense.txt
+  :ref:`Documentation/stable_api_nonsense.txt <stable_api_nonsense>`
     This file describes the rationale behind the conscious decision to
     not have a stable API within the kernel, including things like:
 
@@ -137,29 +137,29 @@ required reading:
     philosophy and is very important for people moving to Linux from
     development on other Operating Systems.
 
-  Documentation/SecurityBugs
+  :ref:`Documentation/SecurityBugs <securitybugs>`
     If you feel you have found a security problem in the Linux kernel,
     please follow the steps in this document to help notify the kernel
     developers, and help solve the issue.
 
-  Documentation/ManagementStyle
+  :ref:`Documentation/ManagementStyle <managementstyle>`
     This document describes how Linux kernel maintainers operate and the
     shared ethos behind their methodologies.  This is important reading
     for anyone new to kernel development (or anyone simply curious about
     it), as it resolves a lot of common misconceptions and confusion
     about the unique behavior of kernel maintainers.
 
-  Documentation/stable_kernel_rules.txt
+  :ref:`Documentation/stable_kernel_rules.txt <stable_kernel_rules>`
     This file describes the rules on how the stable kernel releases
     happen, and what to do if you want to get a change into one of these
     releases.
 
-  Documentation/kernel-docs.txt
+  :ref:`Documentation/kernel-docs.txt <kernel_docs>`
     A list of external documentation that pertains to kernel
     development.  Please consult this list if you do not find what you
     are looking for within the in-kernel documentation.
 
-  Documentation/applying-patches.txt
+  :ref:`Documentation/applying-patches.txt <applying_patches>`
     A good introduction describing exactly what a patch is and how to
     apply it to the different development branches of the kernel.
 
diff --git a/Documentation/development-process/ManagementStyle.rst b/Documentation/development-process/ManagementStyle.rst
index 86c5a19e08f3..f76219cdc869 100644
--- a/Documentation/development-process/ManagementStyle.rst
+++ b/Documentation/development-process/ManagementStyle.rst
@@ -1,3 +1,5 @@
+.. _managementstyle:
+
 Linux kernel management style
 =============================
 
diff --git a/Documentation/development-process/SecurityBugs.rst b/Documentation/development-process/SecurityBugs.rst
index 5f61bd4bc8ef..df795e22d08b 100644
--- a/Documentation/development-process/SecurityBugs.rst
+++ b/Documentation/development-process/SecurityBugs.rst
@@ -1,3 +1,5 @@
+.. _securitybugs:
+
 Security bugs
 =============
 
diff --git a/Documentation/development-process/SubmittingDrivers.rst b/Documentation/development-process/SubmittingDrivers.rst
index a2f30a9e28d1..2ac931645e53 100644
--- a/Documentation/development-process/SubmittingDrivers.rst
+++ b/Documentation/development-process/SubmittingDrivers.rst
@@ -1,3 +1,5 @@
+.. _submittingdrivers:
+
 Submitting Drivers For The Linux Kernel
 =======================================
 
diff --git a/Documentation/development-process/SubmittingPatches.rst b/Documentation/development-process/SubmittingPatches.rst
index f47cea0ff615..d856af3de9f5 100644
--- a/Documentation/development-process/SubmittingPatches.rst
+++ b/Documentation/development-process/SubmittingPatches.rst
@@ -1,3 +1,4 @@
+.. _submittingpatches:
 
 How to Get Your Change Into the Linux Kernel or Care And Operation Of Your Linus Torvalds
 =========================================================================================
diff --git a/Documentation/development-process/applying-patches.rst b/Documentation/development-process/applying-patches.rst
index 573eb3bee19e..2424f37c3ec5 100644
--- a/Documentation/development-process/applying-patches.rst
+++ b/Documentation/development-process/applying-patches.rst
@@ -1,3 +1,4 @@
+.. _applying_patches:
 
 Applying Patches To The Linux Kernel
 ++++++++++++++++++++++++++++++++++++
diff --git a/Documentation/development-process/kernel-docs.rst b/Documentation/development-process/kernel-docs.rst
index 7ca806184426..955f5b775e69 100644
--- a/Documentation/development-process/kernel-docs.rst
+++ b/Documentation/development-process/kernel-docs.rst
@@ -1,3 +1,5 @@
+.. _kernel_docs:
+
 Index of Documentation for People Interested in Writing and/or Understanding the Linux Kernel
 =============================================================================================
 
diff --git a/Documentation/development-process/stable_api_nonsense.rst b/Documentation/development-process/stable_api_nonsense.rst
index 0d375c115b0c..b681de99aae1 100644
--- a/Documentation/development-process/stable_api_nonsense.rst
+++ b/Documentation/development-process/stable_api_nonsense.rst
@@ -1,3 +1,5 @@
+.. _stable_api_nonsense:
+
 The Linux Kernel Driver Interface
 ==================================
 
diff --git a/Documentation/development-process/stable_kernel_rules.rst b/Documentation/development-process/stable_kernel_rules.rst
index 387d8a44eda2..1eba72708c7f 100644
--- a/Documentation/development-process/stable_kernel_rules.rst
+++ b/Documentation/development-process/stable_kernel_rules.rst
@@ -1,3 +1,5 @@
+.. _stable_kernel_rules:
+
 Everything you ever wanted to know about Linux -stable releases
 ===============================================================
 
-- 
2.7.4

[PATCH v2 17/20] doc: development-process: rename files to rst

[Mauro Carvalho Chehab]

Prepare conversion to ReST by renaming all files to .rst.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/development-process/{1.Intro => 1.Intro.rst}                | 0
 Documentation/development-process/{2.Process => 2.Process.rst}            | 0
 Documentation/development-process/{3.Early-stage => 3.Early-stage.rst}    | 0
 Documentation/development-process/{4.Coding => 4.Coding.rst}              | 0
 Documentation/development-process/{5.Posting => 5.Posting.rst}            | 0
 .../development-process/{6.Followthrough => 6.Followthrough.rst}          | 0
 .../development-process/{7.AdvancedTopics => 7.AdvancedTopics.rst}        | 0
 Documentation/development-process/{8.Conclusion => 8.Conclusion.rst}      | 0
 8 files changed, 0 insertions(+), 0 deletions(-)
 rename Documentation/development-process/{1.Intro => 1.Intro.rst} (100%)
 rename Documentation/development-process/{2.Process => 2.Process.rst} (100%)
 rename Documentation/development-process/{3.Early-stage => 3.Early-stage.rst} (100%)
 rename Documentation/development-process/{4.Coding => 4.Coding.rst} (100%)
 rename Documentation/development-process/{5.Posting => 5.Posting.rst} (100%)
 rename Documentation/development-process/{6.Followthrough => 6.Followthrough.rst} (100%)
 rename Documentation/development-process/{7.AdvancedTopics => 7.AdvancedTopics.rst} (100%)
 rename Documentation/development-process/{8.Conclusion => 8.Conclusion.rst} (100%)

diff --git a/Documentation/development-process/1.Intro b/Documentation/development-process/1.Intro.rst
similarity index 100%
rename from Documentation/development-process/1.Intro
rename to Documentation/development-process/1.Intro.rst
diff --git a/Documentation/development-process/2.Process b/Documentation/development-process/2.Process.rst
similarity index 100%
rename from Documentation/development-process/2.Process
rename to Documentation/development-process/2.Process.rst
diff --git a/Documentation/development-process/3.Early-stage b/Documentation/development-process/3.Early-stage.rst
similarity index 100%
rename from Documentation/development-process/3.Early-stage
rename to Documentation/development-process/3.Early-stage.rst
diff --git a/Documentation/development-process/4.Coding b/Documentation/development-process/4.Coding.rst
similarity index 100%
rename from Documentation/development-process/4.Coding
rename to Documentation/development-process/4.Coding.rst
diff --git a/Documentation/development-process/5.Posting b/Documentation/development-process/5.Posting.rst
similarity index 100%
rename from Documentation/development-process/5.Posting
rename to Documentation/development-process/5.Posting.rst
diff --git a/Documentation/development-process/6.Followthrough b/Documentation/development-process/6.Followthrough.rst
similarity index 100%
rename from Documentation/development-process/6.Followthrough
rename to Documentation/development-process/6.Followthrough.rst
diff --git a/Documentation/development-process/7.AdvancedTopics b/Documentation/development-process/7.AdvancedTopics.rst
similarity index 100%
rename from Documentation/development-process/7.AdvancedTopics
rename to Documentation/development-process/7.AdvancedTopics.rst
diff --git a/Documentation/development-process/8.Conclusion b/Documentation/development-process/8.Conclusion.rst
similarity index 100%
rename from Documentation/development-process/8.Conclusion
rename to Documentation/development-process/8.Conclusion.rst
-- 
2.7.4

[PATCH v2 18/20] doc: development-process: convert it to ReST markup

[Mauro Carvalho Chehab]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=true, Size: 30324 bytes --]

This document is on good shape: all it was needed was to
fix the section markups, add a toctree, convert the tables
and add a few code/quote blocks.

While not strictly required, I opted to use lowercase for
the titles, just like the other books that were converted
to Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/development-process/1.Intro.rst      | 68 ++++++++++------------
 Documentation/development-process/2.Process.rst    | 41 +++++++++----
 .../development-process/3.Early-stage.rst          | 22 +++++--
 Documentation/development-process/4.Coding.rst     | 46 ++++++++++-----
 Documentation/development-process/5.Posting.rst    | 26 +++++++--
 .../development-process/6.Followthrough.rst        | 14 +++--
 .../development-process/7.AdvancedTopics.rst       | 13 ++++-
 Documentation/development-process/8.Conclusion.rst |  8 ++-
 .../development-process/development-process.rst    | 27 +++++++++
 9 files changed, 179 insertions(+), 86 deletions(-)
 create mode 100644 Documentation/development-process/development-process.rst

diff --git a/Documentation/development-process/1.Intro.rst b/Documentation/development-process/1.Intro.rst
index 9b614480aa84..22642b3fe903 100644
--- a/Documentation/development-process/1.Intro.rst
+++ b/Documentation/development-process/1.Intro.rst
@@ -1,16 +1,8 @@
-1: A GUIDE TO THE KERNEL DEVELOPMENT PROCESS
+Introdution
+===========
 
-The purpose of this document is to help developers (and their managers)
-work with the development community with a minimum of frustration.  It is
-an attempt to document how this community works in a way which is
-accessible to those who are not intimately familiar with Linux kernel
-development (or, indeed, free software development in general).  While
-there is some technical material here, this is very much a process-oriented
-discussion which does not require a deep knowledge of kernel programming to
-understand.
-
-
-1.1: EXECUTIVE SUMMARY
+Executive summary
+-----------------
 
 The rest of this section covers the scope of the kernel development process
 and the kinds of frustrations that developers and their employers can
@@ -20,41 +12,41 @@ availability to users, community support in many forms, and the ability to
 influence the direction of kernel development.  Code contributed to the
 Linux kernel must be made available under a GPL-compatible license.
 
-Section 2 introduces the development process, the kernel release cycle, and
-the mechanics of the merge window.  The various phases in the patch
-development, review, and merging cycle are covered.  There is some
+:ref:`development_process` introduces the development process, the kernel
+release cycle, and the mechanics of the merge window.  The various phases in
+the patch development, review, and merging cycle are covered.  There is some
 discussion of tools and mailing lists.  Developers wanting to get started
 with kernel development are encouraged to track down and fix bugs as an
 initial exercise.
 
-Section 3 covers early-stage project planning, with an emphasis on
-involving the development community as soon as possible.
+:ref:`development_early_stage` covers early-stage project planning, with an
+emphasis on involving the development community as soon as possible.
 
-Section 4 is about the coding process; several pitfalls which have been
-encountered by other developers are discussed.  Some requirements for
+:ref:`development_coding` is about the coding process; several pitfalls which
+have been encountered by other developers are discussed.  Some requirements for
 patches are covered, and there is an introduction to some of the tools
 which can help to ensure that kernel patches are correct.
 
-Section 5 talks about the process of posting patches for review.  To be
-taken seriously by the development community, patches must be properly
-formatted and described, and they must be sent to the right place.
+:ref:`development_posting` talks about the process of posting patches for
+review. To be taken seriously by the development community, patches must be
+properly formatted and described, and they must be sent to the right place.
 Following the advice in this section should help to ensure the best
 possible reception for your work.
 
-Section 6 covers what happens after posting patches; the job is far from
-done at that point.  Working with reviewers is a crucial part of the
-development process; this section offers a number of tips on how to avoid
-problems at this important stage.  Developers are cautioned against
+:ref:`development_followthrough` covers what happens after posting patches; the
+job is far from done at that point.  Working with reviewers is a crucial part
+of the development process; this section offers a number of tips on how to
+avoid problems at this important stage.  Developers are cautioned against
 assuming that the job is done when a patch is merged into the mainline.
 
-Section 7 introduces a couple of "advanced" topics: managing patches with
-git and reviewing patches posted by others.
+:ref:`development_advancedtopics` introduces a couple of "advanced" topics:
+managing patches with git and reviewing patches posted by others.
 
-Section 8 concludes the document with pointers to sources for more
-information on kernel development.
+:ref:`development_conclusion` concludes the document with pointers to sources
+for more information on kernel development.
 
-
-1.2: WHAT THIS DOCUMENT IS ABOUT
+What this document is about
+---------------------------
 
 The Linux kernel, at over 8 million lines of code and well over 1000
 contributors to each release, is one of the largest and most active free
@@ -108,8 +100,8 @@ community is always in need of developers who will help to make the kernel
 better; the following text should help you - or those who work for you -
 join our community.
 
-
-1.3: CREDITS
+Credits
+-------
 
 This document was written by Jonathan Corbet, corbet@lwn.net.  It has been
 improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland
@@ -120,8 +112,8 @@ Jochen Voß.
 This work was supported by the Linux Foundation; thanks especially to
 Amanda McPherson, who saw the value of this effort and made it all happen.
 
-
-1.4: THE IMPORTANCE OF GETTING CODE INTO THE MAINLINE
+The importance of getting code into the mainline
+------------------------------------------------
 
 Some companies and developers occasionally wonder why they should bother
 learning how to work with the kernel community and get their code into the
@@ -233,8 +225,8 @@ commercial life, after which a new version must be released.  At that
 point, vendors whose code is in the mainline and well maintained will be
 much better positioned to get the new product ready for market quickly.
 
-
-1.5: LICENSING
+Licensing
+---------
 
 Code is contributed to the Linux kernel under a number of licenses, but all
 code must be compatible with version 2 of the GNU General Public License
diff --git a/Documentation/development-process/2.Process.rst b/Documentation/development-process/2.Process.rst
index c24e156a6118..ce5561bb3f8e 100644
--- a/Documentation/development-process/2.Process.rst
+++ b/Documentation/development-process/2.Process.rst
@@ -1,4 +1,7 @@
-2: HOW THE DEVELOPMENT PROCESS WORKS
+.. _development_process:
+
+How the development process works
+=================================
 
 Linux kernel development in the early 1990's was a pretty loose affair,
 with relatively small numbers of users and developers involved.  With a
@@ -7,19 +10,21 @@ course of one year, the kernel has since had to evolve a number of
 processes to keep development happening smoothly.  A solid understanding of
 how the process works is required in order to be an effective part of it.
 
-
-2.1: THE BIG PICTURE
+The big picture
+---------------
 
 The kernel developers use a loosely time-based release process, with a new
 major kernel release happening every two or three months.  The recent
 release history looks like this:
 
+	======  =================
 	2.6.38	March 14, 2011
 	2.6.37	January 4, 2011
 	2.6.36	October 20, 2010
 	2.6.35	August 1, 2010
 	2.6.34	May 15, 2010
 	2.6.33	February 24, 2010
+	======  =================
 
 Every 2.6.x release is a major kernel release with new features, internal
 API changes, and more.  A typical 2.6 release can contain nearly 10,000
@@ -68,6 +73,7 @@ At that point the whole process starts over again.
 As an example, here is how the 2.6.38 development cycle went (all dates in
 2011):
 
+	==============  ===============================
 	January 4	2.6.37 stable release
 	January 18	2.6.38-rc1, merge window closes
 	January 21	2.6.38-rc2
@@ -78,6 +84,7 @@ As an example, here is how the 2.6.38 development cycle went (all dates in
 	March 1		2.6.38-rc7
 	March 7		2.6.38-rc8
 	March 14	2.6.38 stable release
+	==============  ===============================
 
 How do the developers decide when to close the development cycle and create
 the stable release?  The most significant metric used is the list of
@@ -105,11 +112,13 @@ next development kernel.  Kernels will typically receive stable updates for
 a little more than one development cycle past their initial release.  So,
 for example, the 2.6.36 kernel's history looked like:
 
+	==============  ===============================
 	October 10	2.6.36 stable release
 	November 22	2.6.36.1
 	December 9	2.6.36.2
 	January 7	2.6.36.3
 	February 17	2.6.36.4
+	==============  ===============================
 
 2.6.36.4 was the final stable update for the 2.6.36 release.
 
@@ -117,9 +126,11 @@ Some kernels are designated "long term" kernels; they will receive support
 for a longer period.  As of this writing, the current long term kernels
 and their maintainers are:
 
+	======  ======================  ===========================
 	2.6.27	Willy Tarreau		(Deep-frozen stable kernel)
 	2.6.32	Greg Kroah-Hartman
 	2.6.35	Andi Kleen		(Embedded flag kernel)
+	======  ======================  ===========================
 
 The selection of a kernel for long-term support is purely a matter of a
 maintainer having the need and the time to maintain that release.  There
@@ -127,7 +138,8 @@ are no known plans for long-term support for any specific upcoming
 release.
 
 
-2.2: THE LIFECYCLE OF A PATCH
+The lifecycle of a patch
+------------------------
 
 Patches do not go directly from the developer's keyboard into the mainline
 kernel.  There is, instead, a somewhat involved (if somewhat informal)
@@ -195,8 +207,8 @@ is to try to cut the process down to a single "merging into the mainline"
 step.  This approach invariably leads to frustration for everybody
 involved.
 
-
-2.3: HOW PATCHES GET INTO THE KERNEL
+How patches get into the Kernel
+-------------------------------
 
 There is exactly one person who can merge patches into the mainline kernel
 repository: Linus Torvalds.  But, of the over 9,500 patches which went
@@ -242,7 +254,8 @@ finding the right maintainer.  Sending patches directly to Linus is not
 normally the right way to go.
 
 
-2.4: NEXT TREES
+Next trees
+----------
 
 The chain of subsystem trees guides the flow of patches into the kernel,
 but it also raises an interesting question: what if somebody wants to look
@@ -294,7 +307,8 @@ all patches merged during a given merge window should really have found
 their way into linux-next some time before the merge window opens.
 
 
-2.4.1: STAGING TREES
+Staging trees
+-------------
 
 The kernel source tree contains the drivers/staging/ directory, where
 many sub-directories for drivers or filesystems that are on their way to
@@ -322,7 +336,8 @@ staging drivers.  So staging is, at best, a stop on the way toward becoming
 a proper mainline driver.
 
 
-2.5: TOOLS
+Tools
+-----
 
 As can be seen from the above text, the kernel development process depends
 heavily on the ability to herd collections of patches in various
@@ -368,7 +383,8 @@ upstream.  For the management of certain kinds of trees (-mm, for example),
 quilt is the best tool for the job.
 
 
-2.6: MAILING LISTS
+Mailing lists
+-------------
 
 A great deal of Linux kernel development work is done by way of mailing
 lists.  It is hard to be a fully-functioning member of the community
@@ -436,7 +452,8 @@ filesystem, etc. subsystems.  The best place to look for mailing lists is
 in the MAINTAINERS file packaged with the kernel source.
 
 
-2.7: GETTING STARTED WITH KERNEL DEVELOPMENT
+Getting started with Kernel development
+---------------------------------------
 
 Questions about how to get started with the kernel development process are
 common - from both individuals and companies.  Equally common are missteps
@@ -463,6 +480,8 @@ they wish for by these means.
 
 Andrew Morton gives this advice for aspiring kernel developers
 
+::
+
 	The #1 project for all kernel beginners should surely be "make sure
 	that the kernel runs perfectly at all times on all machines which
 	you can lay your hands on".  Usually the way to do this is to work
diff --git a/Documentation/development-process/3.Early-stage.rst b/Documentation/development-process/3.Early-stage.rst
index f87ba7b3fbac..af2c0af931d6 100644
--- a/Documentation/development-process/3.Early-stage.rst
+++ b/Documentation/development-process/3.Early-stage.rst
@@ -1,4 +1,7 @@
-3: EARLY-STAGE PLANNING
+.. _development_early_stage:
+
+Early-stage planning
+====================
 
 When contemplating a Linux kernel development project, it can be tempting
 to jump right in and start coding.  As with any significant project,
@@ -7,7 +10,8 @@ line of code is written.  Some time spent in early planning and
 communication can save far more time later on.
 
 
-3.1: SPECIFYING THE PROBLEM
+Specifying the problem
+----------------------
 
 Like any engineering project, a successful kernel enhancement starts with a
 clear description of the problem to be solved.  In some cases, this step is
@@ -64,7 +68,8 @@ answers to a short set of questions:
 Only then does it make sense to start considering possible solutions.
 
 
-3.2: EARLY DISCUSSION
+Early discussion
+----------------
 
 When planning a kernel development project, it makes great sense to hold
 discussions with the community before launching into implementation.  Early
@@ -117,7 +122,8 @@ In each of these cases, a great deal of pain and extra work could have been
 avoided with some early discussion with the kernel developers.
 
 
-3.3: WHO DO YOU TALK TO?
+Who do you talk to?
+-------------------
 
 When developers decide to take their plans public, the next question will
 be: where do we start?  The answer is to find the right mailing list(s) and
@@ -141,6 +147,8 @@ development project.
 The task of finding the right maintainer is sometimes challenging enough
 that the kernel developers have added a script to ease the process:
 
+::
+
 	.../scripts/get_maintainer.pl
 
 This script will return the current maintainer(s) for a given file or
@@ -155,7 +163,8 @@ If all else fails, talking to Andrew Morton can be an effective way to
 track down a maintainer for a specific piece of code.
 
 
-3.4: WHEN TO POST?
+When to post?
+-------------
 
 If possible, posting your plans during the early stages can only be
 helpful.  Describe the problem being solved and any plans that have been
@@ -179,7 +188,8 @@ idea.  The best thing to do in this situation is to proceed, keeping the
 community informed as you go.
 
 
-3.5: GETTING OFFICIAL BUY-IN
+Getting official buy-in
+-----------------------
 
 If your work is being done in a corporate environment - as most Linux
 kernel work is - you must, obviously, have permission from suitably
diff --git a/Documentation/development-process/4.Coding.rst b/Documentation/development-process/4.Coding.rst
index 9a3ee77cefb1..9d5cef996f7f 100644
--- a/Documentation/development-process/4.Coding.rst
+++ b/Documentation/development-process/4.Coding.rst
@@ -1,4 +1,7 @@
-4: GETTING THE CODE RIGHT
+.. _development_coding:
+
+Getting the code right
+======================
 
 While there is much to be said for a solid and community-oriented design
 process, the proof of any kernel development project is in the resulting
@@ -12,9 +15,11 @@ will shift toward doing things right and the tools which can help in that
 quest.
 
 
-4.1: PITFALLS
+Pitfalls
+---------
 
-* Coding style
+Coding style
+************
 
 The kernel has long had a standard coding style, described in
 Documentation/CodingStyle.  For much of that time, the policies described
@@ -54,7 +59,8 @@ style (a line which becomes far less readable if split to fit within the
 80-column limit, for example), just do it.
 
 
-* Abstraction layers
+Abstraction layers
+******************
 
 Computer Science professors teach students to make extensive use of
 abstraction layers in the name of flexibility and information hiding.
@@ -87,7 +93,8 @@ implement that functionality at a higher level.  There is no value in
 replicating the same code throughout the kernel.
 
 
-* #ifdef and preprocessor use in general
+#ifdef and preprocessor use in general
+**************************************
 
 The C preprocessor seems to present a powerful temptation to some C
 programmers, who see it as a way to efficiently encode a great deal of
@@ -113,7 +120,8 @@ easier to read, do not evaluate their arguments multiple times, and allow
 the compiler to perform type checking on the arguments and return value.
 
 
-* Inline functions
+Inline functions
+****************
 
 Inline functions present a hazard of their own, though.  Programmers can
 become enamored of the perceived efficiency inherent in avoiding a function
@@ -137,7 +145,8 @@ placement of "inline" keywords may not just be excessive; it could also be
 irrelevant.
 
 
-* Locking
+Locking
+*******
 
 In May, 2006, the "Devicescape" networking stack was, with great
 fanfare, released under the GPL and made available for inclusion in the
@@ -151,7 +160,7 @@ This code showed a number of signs of having been developed behind
 corporate doors.  But one large problem in particular was that it was not
 designed to work on multiprocessor systems.  Before this networking stack
 (now called mac80211) could be merged, a locking scheme needed to be
-retrofitted onto it.  
+retrofitted onto it.
 
 Once upon a time, Linux kernel code could be developed without thinking
 about the concurrency issues presented by multiprocessor systems.  Now,
@@ -169,7 +178,8 @@ enough to pick the right tool for the job.  Code which shows a lack of
 attention to concurrency will have a difficult path into the mainline.
 
 
-* Regressions
+Regressions
+***********
 
 One final hazard worth mentioning is this: it can be tempting to make a
 change (which may bring big improvements) which causes something to break
@@ -185,6 +195,8 @@ change if it brings new functionality to ten systems for each one it
 breaks?  The best answer to this question was expressed by Linus in July,
 2007:
 
+::
+
 	So we don't fix bugs by introducing new problems.  That way lies
 	madness, and nobody ever knows if you actually make any real
 	progress at all. Is it two steps forwards, one step back, or one
@@ -201,8 +213,8 @@ reason, a great deal of thought, clear documentation, and wide review for
 user-space interfaces is always required.
 
 
-
-4.2: CODE CHECKING TOOLS
+Code checking tools
+-------------------
 
 For now, at least, the writing of error-free code remains an ideal that few
 of us can reach.  What we can hope to do, though, is to catch and fix as
@@ -250,7 +262,7 @@ testing purposes.  In particular, you should turn on:
 There are quite a few other debugging options, some of which will be
 discussed below.  Some of them have a significant performance impact and
 should not be used all of the time.  But some time spent learning the
-available options will likely be paid back many times over in short order. 
+available options will likely be paid back many times over in short order.
 
 One of the heavier debugging tools is the locking checker, or "lockdep."
 This tool will track the acquisition and release of every lock (spinlock or
@@ -263,7 +275,7 @@ occasion, deadlock.  This kind of problem can be painful (for both
 developers and users) in a deployed system; lockdep allows them to be found
 in an automated manner ahead of time.  Code with any sort of non-trivial
 locking should be run with lockdep enabled before being submitted for
-inclusion. 
+inclusion.
 
 As a diligent kernel programmer, you will, beyond doubt, check the return
 status of any operation (such as a memory allocation) which can fail.  The
@@ -300,7 +312,7 @@ Documentation/coccinelle.txt for more information.
 Other kinds of portability errors are best found by compiling your code for
 other architectures.  If you do not happen to have an S/390 system or a
 Blackfin development board handy, you can still perform the compilation
-step.  A large set of cross compilers for x86 systems can be found at 
+step.  A large set of cross compilers for x86 systems can be found at
 
 	http://www.kernel.org/pub/tools/crosstool/
 
@@ -308,7 +320,8 @@ Some time spent installing and using these compilers will help avoid
 embarrassment later.
 
 
-4.3: DOCUMENTATION
+Documentation
+-------------
 
 Documentation has often been more the exception than the rule with kernel
 development.  Even so, adequate documentation will help to ease the merging
@@ -364,7 +377,8 @@ out.  Anything which might tempt a code janitor to make an incorrect
 "cleanup" needs a comment saying why it is done the way it is.  And so on.
 
 
-4.4: INTERNAL API CHANGES
+Internal API changes
+--------------------
 
 The binary interface provided by the kernel to user space cannot be broken
 except under the most severe circumstances.  The kernel's internal
diff --git a/Documentation/development-process/5.Posting.rst b/Documentation/development-process/5.Posting.rst
index 8a48c9b62864..b511ddf7e82a 100644
--- a/Documentation/development-process/5.Posting.rst
+++ b/Documentation/development-process/5.Posting.rst
@@ -1,4 +1,7 @@
-5: POSTING PATCHES
+.. _development_posting:
+
+Posting patches
+===============
 
 Sooner or later, the time comes when your work is ready to be presented to
 the community for review and, eventually, inclusion into the mainline
@@ -11,7 +14,8 @@ SubmittingDrivers, and SubmitChecklist in the kernel documentation
 directory.
 
 
-5.1: WHEN TO POST
+When to post
+------------
 
 There is a constant temptation to avoid posting patches before they are
 completely "ready."  For simple patches, that is not a problem.  If the
@@ -27,7 +31,8 @@ patches which are known to be half-baked, but those who do will come in
 with the idea that they can help you drive the work in the right direction.
 
 
-5.2: BEFORE CREATING PATCHES
+Before creating patches
+-----------------------
 
 There are a number of things which should be done before you consider
 sending patches to the development community.  These include:
@@ -52,7 +57,8 @@ As a general rule, putting in some extra thought before posting code almost
 always pays back the effort in short order.
 
 
-5.3: PATCH PREPARATION
+Patch preparation
+-----------------
 
 The preparation of patches for posting can be a surprising amount of work,
 but, once again, attempting to save time here is not generally advisable
@@ -122,7 +128,8 @@ which takes quite a bit of time and thought after the "real work" has been
 done.  When done properly, though, it is time well spent.
 
 
-5.4: PATCH FORMATTING AND CHANGELOGS
+Patch formatting and changelogs
+-------------------------------
 
 So now you have a perfect series of patches for posting, but the work is
 not done quite yet.  Each patch needs to be formatted into a message which
@@ -140,6 +147,8 @@ that end, each patch will be composed of the following:
    subsystem name first, followed by the purpose of the patch.  For
    example:
 
+   ::
+
 	gpio: fix build on CONFIG_GPIO_SYSFS=n
 
  - A blank line followed by a detailed description of the contents of the
@@ -192,6 +201,8 @@ been associated with the development of this patch.  They are described in
 detail in the SubmittingPatches document; what follows here is a brief
 summary.  Each of these lines has the format:
 
+::
+
 	tag: Full Name <email address>  optional-other-stuff
 
 The tags in common use are:
@@ -225,7 +236,8 @@ Be careful in the addition of tags to your patches: only Cc: is appropriate
 for addition without the explicit permission of the person named.
 
 
-5.5: SENDING THE PATCH
+Sending the patch
+-----------------
 
 Before you mail your patches, there are a couple of other things you should
 take care of:
@@ -287,6 +299,8 @@ obvious maintainer, Andrew Morton is often the patch target of last resort.
 Patches need good subject lines.  The canonical format for a patch line is
 something like:
 
+::
+
 	[PATCH nn/mm] subsys: one-line description of the patch
 
 where "nn" is the ordinal number of the patch, "mm" is the total number of
diff --git a/Documentation/development-process/6.Followthrough.rst b/Documentation/development-process/6.Followthrough.rst
index 41d324a9420d..a173cd5f93d2 100644
--- a/Documentation/development-process/6.Followthrough.rst
+++ b/Documentation/development-process/6.Followthrough.rst
@@ -1,4 +1,7 @@
-6: FOLLOWTHROUGH
+.. _development_followthrough:
+
+Followthrough
+=============
 
 At this point, you have followed the guidelines given so far and, with the
 addition of your own engineering skills, have posted a perfect series of
@@ -16,7 +19,8 @@ standards.  A failure to participate in this process is quite likely to
 prevent the inclusion of your patches into the mainline.
 
 
-6.1: WORKING WITH REVIEWERS
+Working with reviewers
+----------------------
 
 A patch of any significance will result in a number of comments from other
 developers as they review the code.  Working with reviewers can be, for
@@ -97,7 +101,8 @@ though, and not before all other alternatives have been explored.  And bear
 in mind, of course, that he may not agree with you either.
 
 
-6.2: WHAT HAPPENS NEXT
+What happens next
+-----------------
 
 If a patch is considered to be a good thing to add to the kernel, and once
 most of the review issues have been resolved, the next step is usually
@@ -177,7 +182,8 @@ it with the assumption that you will not be around to maintain it
 afterward.
 
 
-6.3: OTHER THINGS THAT CAN HAPPEN
+Other things that can happen
+-----------------------------
 
 One day, you may open your mail client and see that somebody has mailed you
 a patch to your code.  That is one of the advantages of having your code
diff --git a/Documentation/development-process/7.AdvancedTopics.rst b/Documentation/development-process/7.AdvancedTopics.rst
index 26dc3fa196e4..81d61c5d62dd 100644
--- a/Documentation/development-process/7.AdvancedTopics.rst
+++ b/Documentation/development-process/7.AdvancedTopics.rst
@@ -1,11 +1,15 @@
-7: ADVANCED TOPICS
+.. _development_advancedtopics:
+
+Advanced topics
+===============
 
 At this point, hopefully, you have a handle on how the development process
 works.  There is still more to learn, however!  This section will cover a
 number of topics which can be helpful for developers wanting to become a
 regular part of the Linux kernel development process.
 
-7.1: MANAGING PATCHES WITH GIT
+Managing patches with git
+-------------------------
 
 The use of distributed version control for the kernel began in early 2002,
 when Linus first started playing with the proprietary BitKeeper
@@ -114,6 +118,8 @@ radar.  Kernel developers tend to get unhappy when they see that kind of
 thing happening; putting up a git tree with unreviewed or off-topic patches
 can affect your ability to get trees pulled in the future.  Quoting Linus:
 
+::
+
 	You can send me patches, but for me to pull a git patch from you, I
 	need to know that you know what you're doing, and I need to be able
 	to trust things *without* then having to go and check every
@@ -141,7 +147,8 @@ format the request as other developers expect, and will also check to be
 sure that you have remembered to push those changes to the public server.
 
 
-7.2: REVIEWING PATCHES
+Reviewing patches
+-----------------
 
 Some readers will certainly object to putting this section with "advanced
 topics" on the grounds that even beginning kernel developers should be
diff --git a/Documentation/development-process/8.Conclusion.rst b/Documentation/development-process/8.Conclusion.rst
index caef69022e9c..23ec7cbc2d2b 100644
--- a/Documentation/development-process/8.Conclusion.rst
+++ b/Documentation/development-process/8.Conclusion.rst
@@ -1,4 +1,7 @@
-8: FOR MORE INFORMATION
+.. _development_conclusion:
+
+For more information
+====================
 
 There are numerous sources of information on Linux kernel development and
 related topics.  First among those will always be the Documentation
@@ -47,7 +50,8 @@ Documentation for git can be found at:
 	http://www.kernel.org/pub/software/scm/git/docs/user-manual.html
 
 
-9: CONCLUSION
+Conclusion
+==========
 
 Congratulations to anybody who has made it through this long-winded
 document.  Hopefully it has provided a helpful understanding of how the
diff --git a/Documentation/development-process/development-process.rst b/Documentation/development-process/development-process.rst
new file mode 100644
index 000000000000..d431a1098875
--- /dev/null
+++ b/Documentation/development-process/development-process.rst
@@ -0,0 +1,27 @@
+A guide to the Kernel Development Process
+=========================================
+
+Contents:
+
+.. toctree::
+   :numbered:
+   :maxdepth: 2
+
+   1.Intro
+   2.Process
+   3.Early-stage
+   4.Coding
+   5.Posting
+   6.Followthrough
+   7.AdvancedTopics
+   8.Conclusion
+
+The purpose of this document is to help developers (and their managers)
+work with the development community with a minimum of frustration.  It is
+an attempt to document how this community works in a way which is
+accessible to those who are not intimately familiar with Linux kernel
+development (or, indeed, free software development in general).  While
+there is some technical material here, this is very much a process-oriented
+discussion which does not require a deep knowledge of kernel programming to
+understand.
+
-- 
2.7.4

[PATCH v2 19/20] doc: adjust references to development-process

[Mauro Carvalho Chehab]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=true, Size: 66128 bytes --]

Several files got moved into development-process, and had
a .rst appended. Fix references where it occurs.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/ABI/README                           |  2 +-
 Documentation/BUG-HUNTING                          |  2 +-
 Documentation/DocBook/kernel-hacking.tmpl          |  4 ++--
 Documentation/SubmitChecklist                      |  4 ++--
 Documentation/adding-syscalls.txt                  |  2 +-
 Documentation/development-process/4.Coding.rst     |  2 +-
 Documentation/development-process/5.Posting.rst    |  4 ++--
 Documentation/development-process/HOWTO.rst        | 22 ++++++++---------
 .../development-process/SubmittingDrivers.rst      |  4 ++--
 .../development-process/SubmittingPatches.rst      | 10 ++++----
 .../development-process/stable_kernel_rules.rst    |  4 ++--
 .../devicetree/bindings/submitting-patches.txt     |  2 +-
 Documentation/filesystems/locks.txt                |  2 +-
 Documentation/hwmon/submitting-patches             |  6 ++---
 Documentation/isdn/README                          |  2 +-
 Documentation/ja_JP/HOWTO                          | 28 +++++++++++-----------
 Documentation/ja_JP/SubmitChecklist                |  2 +-
 Documentation/ja_JP/SubmittingPatches              | 14 +++++------
 Documentation/ja_JP/stable_api_nonsense.txt        |  4 ++--
 Documentation/ja_JP/stable_kernel_rules.txt        |  6 ++---
 Documentation/ko_KR/HOWTO                          | 28 +++++++++++-----------
 Documentation/ko_KR/stable_api_nonsense.txt        |  4 ++--
 Documentation/networking/PLIP.txt                  |  2 +-
 Documentation/networking/netdev-FAQ.txt            |  8 +++----
 Documentation/scsi/scsi_mid_low_api.txt            |  2 +-
 Documentation/virtual/kvm/review-checklist.txt     |  4 ++--
 .../watchdog/convert_drivers_to_kernel_api.txt     |  2 +-
 Documentation/zh_CN/CodingStyle                    |  4 ++--
 Documentation/zh_CN/HOWTO                          | 28 +++++++++++-----------
 Documentation/zh_CN/SecurityBugs                   |  4 ++--
 Documentation/zh_CN/SubmittingDrivers              |  8 +++----
 Documentation/zh_CN/SubmittingPatches              | 10 ++++----
 Documentation/zh_CN/stable_api_nonsense.txt        |  4 ++--
 Documentation/zh_CN/stable_kernel_rules.txt        |  6 ++---
 MAINTAINERS                                        |  2 +-
 README                                             |  4 ++--
 REPORTING-BUGS                                     |  2 +-
 drivers/net/ppp/Kconfig                            |  2 +-
 drivers/pcmcia/Kconfig                             |  2 +-
 fs/Kconfig.binfmt                                  |  2 +-
 fs/fuse/Kconfig                                    |  2 +-
 net/Kconfig                                        |  4 ++--
 scripts/ver_linux                                  |  2 +-
 tools/testing/selftests/futex/README               |  2 +-
 44 files changed, 132 insertions(+), 132 deletions(-)

diff --git a/Documentation/ABI/README b/Documentation/ABI/README
index 1fafc4b0753b..232cade3a59c 100644
--- a/Documentation/ABI/README
+++ b/Documentation/ABI/README
@@ -84,4 +84,4 @@ stable:
 
 - Kernel-internal symbols.  Do not rely on the presence, absence, location, or
   type of any kernel symbol, either in System.map files or the kernel binary
-  itself.  See Documentation/stable_api_nonsense.txt.
+  itself.  See Documentation/development-process/stable_api_nonsense.rst.
diff --git a/Documentation/BUG-HUNTING b/Documentation/BUG-HUNTING
index 65022a87bf17..e0e4637fb30a 100644
--- a/Documentation/BUG-HUNTING
+++ b/Documentation/BUG-HUNTING
@@ -242,5 +242,5 @@ Once you have worked out a fix please submit it upstream. After all open
 source is about sharing what you do and don't you want to be recognised for
 your genius?
 
-Please do read Documentation/SubmittingPatches though to help your code get
+Please do read Documentation/development-process/SubmittingPatches.rst though to help your code get
 accepted.
diff --git a/Documentation/DocBook/kernel-hacking.tmpl b/Documentation/DocBook/kernel-hacking.tmpl
index 589b40cc5eb5..562c0648738e 100644
--- a/Documentation/DocBook/kernel-hacking.tmpl
+++ b/Documentation/DocBook/kernel-hacking.tmpl
@@ -1208,8 +1208,8 @@ static struct block_device_operations opt_fops = {
    
    <listitem>
     <para>
-     Finally, don't forget to read <filename>Documentation/SubmittingPatches</filename>
-     and possibly <filename>Documentation/SubmittingDrivers</filename>.
+     Finally, don't forget to read <filename>Documentation/development-process/SubmittingPatches.rst</filename>
+     and possibly <filename>Documentation/development-process/SubmittingDrivers.rst</filename>.
     </para>
    </listitem>
   </itemizedlist>
diff --git a/Documentation/SubmitChecklist b/Documentation/SubmitChecklist
index 2b7e32dfe00d..d646b1d47db1 100644
--- a/Documentation/SubmitChecklist
+++ b/Documentation/SubmitChecklist
@@ -5,7 +5,7 @@ Here are some basic things that developers should do if they want to see their
 kernel patch submissions accepted more quickly.
 
 These are all above and beyond the documentation that is provided in
-Documentation/SubmittingPatches and elsewhere regarding submitting Linux
+Documentation/development-process/SubmittingPatches.rst and elsewhere regarding submitting Linux
 kernel patches.
 
 
@@ -27,7 +27,7 @@ kernel patches.
    tends to use `unsigned long' for 64-bit quantities.
 
 5: Check your patch for general style as detailed in
-   Documentation/CodingStyle.  Check for trivial violations with the
+   Documentation/development-process/CodingStyle.rst.  Check for trivial violations with the
    patch style checker prior to submission (scripts/checkpatch.pl).
    You should be able to justify all violations that remain in
    your patch.
diff --git a/Documentation/adding-syscalls.txt b/Documentation/adding-syscalls.txt
index bbb31e091b28..7dd00b344844 100644
--- a/Documentation/adding-syscalls.txt
+++ b/Documentation/adding-syscalls.txt
@@ -3,7 +3,7 @@ Adding a New System Call
 
 This document describes what's involved in adding a new system call to the
 Linux kernel, over and above the normal submission advice in
-Documentation/SubmittingPatches.
+Documentation/development-process/SubmittingPatches.rst.
 
 
 System Call Alternatives
diff --git a/Documentation/development-process/4.Coding.rst b/Documentation/development-process/4.Coding.rst
index 9d5cef996f7f..a52465835c7b 100644
--- a/Documentation/development-process/4.Coding.rst
+++ b/Documentation/development-process/4.Coding.rst
@@ -22,7 +22,7 @@ Coding style
 ************
 
 The kernel has long had a standard coding style, described in
-Documentation/CodingStyle.  For much of that time, the policies described
+Documentation/development-process/CodingStyle.rst.  For much of that time, the policies described
 in that file were taken as being, at most, advisory.  As a result, there is
 a substantial amount of code in the kernel which does not meet the coding
 style guidelines.  The presence of that code leads to two independent
diff --git a/Documentation/development-process/5.Posting.rst b/Documentation/development-process/5.Posting.rst
index b511ddf7e82a..d75260f4fc1d 100644
--- a/Documentation/development-process/5.Posting.rst
+++ b/Documentation/development-process/5.Posting.rst
@@ -210,7 +210,7 @@ The tags in common use are:
  - Signed-off-by: this is a developer's certification that he or she has
    the right to submit the patch for inclusion into the kernel.  It is an
    agreement to the Developer's Certificate of Origin, the full text of
-   which can be found in Documentation/SubmittingPatches.  Code without a
+   which can be found in Documentation/development-process/SubmittingPatches.rst.  Code without a
    proper signoff cannot be merged into the mainline.
 
  - Acked-by: indicates an agreement by another developer (often a
@@ -221,7 +221,7 @@ The tags in common use are:
    it to work.
 
  - Reviewed-by: the named developer has reviewed the patch for correctness;
-   see the reviewer's statement in Documentation/SubmittingPatches for more
+   see the reviewer's statement in Documentation/development-process/SubmittingPatches.rst for more
    detail.
 
  - Reported-by: names a user who reported a problem which is fixed by this
diff --git a/Documentation/development-process/HOWTO.rst b/Documentation/development-process/HOWTO.rst
index 31c8df5d20c7..9a06de24b755 100644
--- a/Documentation/development-process/HOWTO.rst
+++ b/Documentation/development-process/HOWTO.rst
@@ -90,19 +90,19 @@ required reading:
     what is necessary to do to configure and build the kernel.  People
     who are new to the kernel should start here.
 
-  :ref:`Documentation/Changes <changes>`
+  :ref:`Documentation/development-process/Changes.rst <changes>`
     This file gives a list of the minimum levels of various software
     packages that are necessary to build and run the kernel
     successfully.
 
-  :ref:`Documentation/CodingStyle <codingstyle>`
+  :ref:`Documentation/development-process/CodingStyle.rst <codingstyle>`
     This describes the Linux kernel coding style, and some of the
     rationale behind it. All new code is expected to follow the
     guidelines in this document. Most maintainers will only accept
     patches if these rules are followed, and many people will only
     review code if it is in the proper style.
 
-  :ref:`Documentation/SubmittingPatches <submittingpatches>` and :ref:`Documentation/SubmittingDrivers <submittingdrivers>`
+  :ref:`Documentation/development-process/SubmittingPatches.rst <submittingpatches>` and :ref:`Documentation/development-process/SubmittingDrivers.rst <submittingdrivers>`
     These files describe in explicit detail how to successfully create
     and send a patch, including (but not limited to):
 
@@ -124,7 +124,7 @@ required reading:
 
 		http://linux.yyz.us/patch-format.html
 
-  :ref:`Documentation/stable_api_nonsense.txt <stable_api_nonsense>`
+  :ref:`Documentation/development-process/stable_api_nonsense.rst <stable_api_nonsense>`
     This file describes the rationale behind the conscious decision to
     not have a stable API within the kernel, including things like:
 
@@ -137,29 +137,29 @@ required reading:
     philosophy and is very important for people moving to Linux from
     development on other Operating Systems.
 
-  :ref:`Documentation/SecurityBugs <securitybugs>`
+  :ref:`Documentation/development-process/SecurityBugs.rst <securitybugs>`
     If you feel you have found a security problem in the Linux kernel,
     please follow the steps in this document to help notify the kernel
     developers, and help solve the issue.
 
-  :ref:`Documentation/ManagementStyle <managementstyle>`
+  :ref:`Documentation/development-process/ManagementStyle.rst <managementstyle>`
     This document describes how Linux kernel maintainers operate and the
     shared ethos behind their methodologies.  This is important reading
     for anyone new to kernel development (or anyone simply curious about
     it), as it resolves a lot of common misconceptions and confusion
     about the unique behavior of kernel maintainers.
 
-  :ref:`Documentation/stable_kernel_rules.txt <stable_kernel_rules>`
+  :ref:`Documentation/development-process/stable_kernel_rules.rst <stable_kernel_rules>`
     This file describes the rules on how the stable kernel releases
     happen, and what to do if you want to get a change into one of these
     releases.
 
-  :ref:`Documentation/kernel-docs.txt <kernel_docs>`
+  :ref:`Documentation/development-process/kernel-docs.rst <kernel_docs>`
     A list of external documentation that pertains to kernel
     development.  Please consult this list if you do not find what you
     are looking for within the in-kernel documentation.
 
-  :ref:`Documentation/applying-patches.txt <applying_patches>`
+  :ref:`Documentation/development-process/applying-patches.rst <applying_patches>`
     A good introduction describing exactly what a patch is and how to
     apply it to the different development branches of the kernel.
 
@@ -301,7 +301,7 @@ two weeks, but it can be longer if there are no pressing problems.  A
 security-related problem, instead, can cause a release to happen almost
 instantly.
 
-The file Documentation/stable_kernel_rules.txt in the kernel tree
+The file Documentation/development-process/stable_kernel_rules.rst in the kernel tree
 documents what kinds of changes are acceptable for the -stable tree, and
 how the release process works.
 
@@ -433,7 +433,7 @@ add your statements between the individual quoted sections instead of
 writing at the top of the mail.
 
 If you add patches to your mail, make sure they are plain readable text
-as stated in Documentation/SubmittingPatches. Kernel developers don't
+as stated in Documentation/development-process/SubmittingPatches.rst. Kernel developers don't
 want to deal with attachments or compressed patches; they may want
 to comment on individual lines of your patch, which works only that way.
 Make sure you use a mail program that does not mangle spaces and tab
diff --git a/Documentation/development-process/SubmittingDrivers.rst b/Documentation/development-process/SubmittingDrivers.rst
index 2ac931645e53..621d17af20fd 100644
--- a/Documentation/development-process/SubmittingDrivers.rst
+++ b/Documentation/development-process/SubmittingDrivers.rst
@@ -8,7 +8,7 @@ various kernel trees. Note that if you are interested in video card drivers
 you should probably talk to XFree86 (http://www.xfree86.org/) and/or X.Org
 (http://x.org/) instead.
 
-Also read the Documentation/SubmittingPatches document.
+Also read the Documentation/development-process/SubmittingPatches.rst document.
 
 
 Allocating Device Numbers
@@ -73,7 +73,7 @@ Interfaces:
 
 Code:
 		Please use the Linux style of code formatting as documented
-		in Documentation/CodingStyle. If you have sections of code
+		in Documentation/development-process/CodingStyle.rst. If you have sections of code
 		that need to be in other formats, for example because they
 		are shared with a windows driver kit and you want to
 		maintain them just once separate them out nicely and note
diff --git a/Documentation/development-process/SubmittingPatches.rst b/Documentation/development-process/SubmittingPatches.rst
index d856af3de9f5..b0bf22510c3d 100644
--- a/Documentation/development-process/SubmittingPatches.rst
+++ b/Documentation/development-process/SubmittingPatches.rst
@@ -13,7 +13,7 @@ format.  For detailed information on how the kernel development process
 works, see Documentation/development-process.  Also, read
 Documentation/SubmitChecklist for a list of items to check before
 submitting code.  If you are submitting a driver, also read
-Documentation/SubmittingDrivers; for device tree binding patches, read
+Documentation/development-process/SubmittingDrivers.rst; for device tree binding patches, read
 Documentation/devicetree/bindings/submitting-patches.txt.
 
 Many of these steps describe the default behavior of the git version
@@ -246,7 +246,7 @@ Style-check your changes
 ------------------------
 
 Check your patch for basic style violations, details of which can be
-found in Documentation/CodingStyle.  Failure to do so simply wastes
+found in Documentation/development-process/CodingStyle.rst.  Failure to do so simply wastes
 the reviewers time and will get your patch rejected, probably
 without even being read.
 
@@ -313,7 +313,7 @@ toward the stable maintainers by putting a line like this:
   Cc: stable@vger.kernel.org
 
 into the sign-off area of your patch (note, NOT an email recipient).  You
-should also read Documentation/stable_kernel_rules.txt in addition to this
+should also read Documentation/development-process/stable_kernel_rules.rst in addition to this
 file.
 
 Note, however, that some subsystem maintainers want to come to their own
@@ -843,8 +843,8 @@ Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
 NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
   <https://lkml.org/lkml/2005/7/11/336>
 
-Kernel Documentation/CodingStyle:
-  <Documentation/CodingStyle>
+Kernel Documentation/development-process/CodingStyle.rst:
+  <Documentation/development-process/CodingStyle.rst>
 
 Linus Torvalds's mail on the canonical patch format:
   <http://lkml.org/lkml/2005/4/7/183>
diff --git a/Documentation/development-process/stable_kernel_rules.rst b/Documentation/development-process/stable_kernel_rules.rst
index 1eba72708c7f..533be00260e6 100644
--- a/Documentation/development-process/stable_kernel_rules.rst
+++ b/Documentation/development-process/stable_kernel_rules.rst
@@ -26,7 +26,7 @@ Rules on what kind of patches are accepted, and which ones are not, into the
    race can be exploited is also provided.
  - It cannot contain any "trivial" fixes in it (spelling changes,
    whitespace cleanups, etc).
- - It must follow the Documentation/SubmittingPatches rules.
+ - It must follow the Documentation/development-process/SubmittingPatches.rst rules.
  - It or an equivalent fix must already exist in Linus' tree (upstream).
 
 
@@ -37,7 +37,7 @@ Procedure for submitting patches to the -stable tree
    submission guidelines as described in
    Documentation/networking/netdev-FAQ.txt
  - Security patches should not be handled (solely) by the -stable review
-   process but should follow the procedures in Documentation/SecurityBugs.
+   process but should follow the procedures in Documentation/development-process/SecurityBugs.rst.
 
 For all other submissions, choose one of the following procedures
 -----------------------------------------------------------------
diff --git a/Documentation/devicetree/bindings/submitting-patches.txt b/Documentation/devicetree/bindings/submitting-patches.txt
index 7d44eae7ab0b..5fa11b9b8410 100644
--- a/Documentation/devicetree/bindings/submitting-patches.txt
+++ b/Documentation/devicetree/bindings/submitting-patches.txt
@@ -3,7 +3,7 @@
 
 I. For patch submitters
 
-  0) Normal patch submission rules from Documentation/SubmittingPatches
+  0) Normal patch submission rules from Documentation/development-process/SubmittingPatches.rst
      applies.
 
   1) The Documentation/ portion of the patch should be a separate patch.
diff --git a/Documentation/filesystems/locks.txt b/Documentation/filesystems/locks.txt
index 2cf81082581d..8af1ee4a6399 100644
--- a/Documentation/filesystems/locks.txt
+++ b/Documentation/filesystems/locks.txt
@@ -19,7 +19,7 @@ forever.
 
 This should not cause problems for anybody, since everybody using a
 2.1.x kernel should have updated their C library to a suitable version
-anyway (see the file "Documentation/Changes".)
+anyway (see the file "Documentation/development-process/Changes.rst".)
 
 1.2 Allow Mixed Locks Again
 ---------------------------
diff --git a/Documentation/hwmon/submitting-patches b/Documentation/hwmon/submitting-patches
index 57f60307accc..371baf7a43e2 100644
--- a/Documentation/hwmon/submitting-patches
+++ b/Documentation/hwmon/submitting-patches
@@ -11,9 +11,9 @@ increase the chances of your change being accepted.
 
 * It should be unnecessary to mention, but please read and follow
     Documentation/SubmitChecklist
-    Documentation/SubmittingDrivers
-    Documentation/SubmittingPatches
-    Documentation/CodingStyle
+    Documentation/development-process/SubmittingDrivers.rst
+    Documentation/development-process/SubmittingPatches.rst
+    Documentation/development-process/CodingStyle.rst
 
 * Please run your patch through 'checkpatch --strict'. There should be no
   errors, no warnings, and few if any check messages. If there are any
diff --git a/Documentation/isdn/README b/Documentation/isdn/README
index cfb1884342ee..508817c06a53 100644
--- a/Documentation/isdn/README
+++ b/Documentation/isdn/README
@@ -321,7 +321,7 @@ README for the ISDN-subsystem
   ATTENTION!
 
   Always use the latest module utilities. The current version is
-  named in Documentation/Changes. Some old versions of insmod
+  named in Documentation/development-process/Changes.rst. Some old versions of insmod
   are not capable of setting the driver-Ids correctly.
 
 3. Lowlevel-driver configuration.
diff --git a/Documentation/ja_JP/HOWTO b/Documentation/ja_JP/HOWTO
index 581c14bdd7be..465b238e7d1d 100644
--- a/Documentation/ja_JP/HOWTO
+++ b/Documentation/ja_JP/HOWTO
@@ -1,5 +1,5 @@
 NOTE:
-This is a version of Documentation/HOWTO translated into Japanese.
+This is a version of Documentation/development-process/HOWTO.rst translated into Japanese.
 This document is maintained by Tsugikazu Shibata <tshibata@ab.jp.nec.com>
 and the JF Project team <www.linux.or.jp/JF>.
 If you find any difference between this document and the original file
@@ -14,7 +14,7 @@ to update the original English file first.
 Last Updated: 2013/07/19
 ==================================
 これは、
-linux-3.10/Documentation/HOWTO
+linux-3.10/Documentation/development-process/HOWTO.rst
 の和訳です。
 
 翻訳団体： JF プロジェクト < http://linuxjf.sourceforge.jp/ >
@@ -122,20 +122,20 @@ linux-api@ver.kernel.org に送ることを勧めます。
     ています。カーネルに関して初めての人はここからスタートすると良いで
     しょう。
 
-  Documentation/Changes
+  Documentation/development-process/Changes.rst
      このファイルはカーネルをうまく生成(訳注 build )し、走らせるのに最
      小限のレベルで必要な数々のソフトウェアパッケージの一覧を示してい
      ます。
 
-  Documentation/CodingStyle
+  Documentation/development-process/CodingStyle.rst
     これは Linux カーネルのコーディングスタイルと背景にある理由を記述
     しています。全ての新しいコードはこのドキュメントにあるガイドライン
     に従っていることを期待されています。大部分のメンテナはこれらのルー
     ルに従っているものだけを受け付け、多くの人は正しいスタイルのコード
     だけをレビューします。
 
-  Documentation/SubmittingPatches
-  Documentation/SubmittingDrivers
+  Documentation/development-process/SubmittingPatches.rst
+  Documentation/development-process/SubmittingDrivers.rst
      これらのファイルには、どうやってうまくパッチを作って投稿するかに
      ついて非常に詳しく書かれており、以下を含みます(これだけに限らない
      けれども)
@@ -153,7 +153,7 @@ linux-api@ver.kernel.org に送ることを勧めます。
 	"Linux kernel patch submission format"
 		http://linux.yyz.us/patch-format.html
 
-  Documentation/stable_api_nonsense.txt
+  Documentation/development-process/stable_api_nonsense.rst
      このファイルはカーネルの中に不変のAPIを持たないことにした意識的な
      決断の背景にある理由について書かれています。以下のようなことを含
      んでいます-
@@ -164,29 +164,29 @@ linux-api@ver.kernel.org に送ることを勧めます。
      このドキュメントは Linux 開発の思想を理解するのに非常に重要です。
      そして、他のOSでの開発者が Linux に移る時にとても重要です。
 
-  Documentation/SecurityBugs
+  Documentation/development-process/SecurityBugs.rst
     もし Linux カーネルでセキュリティ問題を発見したように思ったら、こ
     のドキュメントのステップに従ってカーネル開発者に連絡し、問題解決を
     支援してください。
 
-  Documentation/ManagementStyle
+  Documentation/development-process/ManagementStyle.rst
     このドキュメントは Linux カーネルのメンテナ達がどう行動するか、
     彼らの手法の背景にある共有されている精神について記述しています。こ
     れはカーネル開発の初心者なら（もしくは、単に興味があるだけの人でも）
     重要です。なぜならこのドキュメントは、カーネルメンテナ達の独特な
     行動についての多くの誤解や混乱を解消するからです。
 
-  Documentation/stable_kernel_rules.txt
+  Documentation/development-process/stable_kernel_rules.rst
     このファイルはどのように stable カーネルのリリースが行われるかのルー
     ルが記述されています。そしてこれらのリリースの中のどこかで変更を取
     り入れてもらいたい場合に何をすれば良いかが示されています。
 
-  Documentation/kernel-docs.txt
+  Documentation/development-process/kernel-docs.rst
 　　カーネル開発に付随する外部ドキュメントのリストです。もしあなたが
     探しているものがカーネル内のドキュメントでみつからなかった場合、
     このリストをあたってみてください。
 
-  Documentation/applying-patches.txt
+  Documentation/development-process/applying-patches.rst
     パッチとはなにか、パッチをどうやって様々なカーネルの開発ブランチに
     適用するのかについて正確に記述した良い入門書です。
 
@@ -314,7 +314,7 @@ Andrew Morton が Linux-kernel メーリングリストにカーネルリリー
 た問題がなければもう少し長くなることもあります。セキュリティ関連の問題
 の場合はこれに対してだいたいの場合、すぐにリリースがされます。
 
-カーネルツリーに入っている、Documentation/stable_kernel_rules.txt ファ
+カーネルツリーに入っている、Documentation/development-process/stable_kernel_rules.rst ファ
 イルにはどのような種類の変更が -stable ツリーに受け入れ可能か、またリ
 リースプロセスがどう動くかが記述されています。
 
@@ -438,7 +438,7 @@ MAINTAINERS ファイルにリストがありますので参照してくださ
 メールの先頭でなく、各引用行の間にあなたの言いたいことを追加するべきで
 す。
 
-もしパッチをメールに付ける場合は、Documentation/SubmittingPatches に提
+もしパッチをメールに付ける場合は、Documentation/development-process/SubmittingPatches.rst に提
 示されているように、それは プレーンな可読テキストにすることを忘れない
 ようにしましょう。カーネル開発者は 添付や圧縮したパッチを扱いたがりま
 せん-
diff --git a/Documentation/ja_JP/SubmitChecklist b/Documentation/ja_JP/SubmitChecklist
index cb5507b1ac81..c0020797d6b9 100644
--- a/Documentation/ja_JP/SubmitChecklist
+++ b/Documentation/ja_JP/SubmitChecklist
@@ -27,7 +27,7 @@ Linux カーネルパッチ投稿者向けチェックリスト
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 本書では、パッチをより素早く取り込んでもらいたい開発者が実践すべき基本的な事柄
-をいくつか紹介します。ここにある全ての事柄は、Documentation/SubmittingPatches
+をいくつか紹介します。ここにある全ての事柄は、Documentation/development-process/SubmittingPatches.rst
 などのLinuxカーネルパッチ投稿に際しての心得を補足するものです。
 
  1: 妥当なCONFIGオプションや変更されたCONFIGオプション、つまり =y, =m, =n
diff --git a/Documentation/ja_JP/SubmittingPatches b/Documentation/ja_JP/SubmittingPatches
index 5d6ae639bfa0..aed86762a6d3 100644
--- a/Documentation/ja_JP/SubmittingPatches
+++ b/Documentation/ja_JP/SubmittingPatches
@@ -1,5 +1,5 @@
 NOTE:
-This is a version of Documentation/SubmittingPatches into Japanese.
+This is a version of Documentation/development-process/SubmittingPatches.rst into Japanese.
 This document is maintained by Keiichi KII <k-keiichi@bx.jp.nec.com>
 and the JF Project team <http://www.linux.or.jp/JF/>.
 If you find any difference between this document and the original file
@@ -15,7 +15,7 @@ Last Updated: 2011/06/09
 
 ==================================
 これは、
-linux-2.6.39/Documentation/SubmittingPatches の和訳
+linux-2.6.39/Documentation/development-process/SubmittingPatches.rst の和訳
 です。
 翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
 翻訳日： 2011/06/09
@@ -36,7 +36,7 @@ Linux カーネルに変更を加えたいと思っている個人又は会社
 
 コードを投稿する前に、Documentation/SubmitChecklist の項目リストに目
 を通してチェックしてください。もしあなたがドライバーを投稿しようとし
-ているなら、Documentation/SubmittingDrivers にも目を通してください。
+ているなら、Documentation/development-process/SubmittingDrivers.rst にも目を通してください。
 
 --------------------------------------------
 セクション1 パッチの作り方と送り方
@@ -148,7 +148,7 @@ http://savannah.nongnu.org/projects/quilt
 4) パッチのスタイルチェック
 
 あなたのパッチが基本的な( Linux カーネルの)コーディングスタイルに違反し
-ていないかをチェックして下さい。その詳細を Documentation/CodingStyle で
+ていないかをチェックして下さい。その詳細を Documentation/development-process/CodingStyle.rst で
 見つけることができます。コーディングスタイルの違反はレビューする人の
 時間を無駄にするだけなので、恐らくあなたのパッチは読まれることすらなく
 拒否されるでしょう。
@@ -609,7 +609,7 @@ diffstat の結果を生成するために「 git diff -M --stat --summary 」
 し例外を適用するには、本当に妥当な理由が不可欠です。あなたは恐らくこの
 セクションを Linus のコンピュータ・サイエンス101と呼ぶでしょう。
 
-1) Documentation/CodingStyleを参照
+1) Documentation/development-process/CodingStyle.rstを参照
 
 言うまでもなく、あなたのコードがこのコーディングスタイルからあまりに
 も逸脱していると、レビューやコメントなしに受け取ってもらえないかもし
@@ -704,8 +704,8 @@ Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
 NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
   <https://lkml.org/lkml/2005/7/11/336>
 
-Kernel Documentation/CodingStyle:
-  <http://users.sosdg.org/~qiyong/lxr/source/Documentation/CodingStyle>
+Kernel Documentation/development-process/CodingStyle.rst:
+  <http://users.sosdg.org/~qiyong/lxr/source/Documentation/development-process/CodingStyle.rst>
 
 Linus Torvalds's mail on the canonical patch format:
   <http://lkml.org/lkml/2005/4/7/183>
diff --git a/Documentation/ja_JP/stable_api_nonsense.txt b/Documentation/ja_JP/stable_api_nonsense.txt
index 7653b5cbfed2..fa54dc9ee9f0 100644
--- a/Documentation/ja_JP/stable_api_nonsense.txt
+++ b/Documentation/ja_JP/stable_api_nonsense.txt
@@ -1,5 +1,5 @@
 NOTE:
-This is a version of Documentation/stable_api_nonsense.txt into Japanese.
+This is a version of Documentation/development-process/stable_api_nonsense.rst into Japanese.
 This document is maintained by IKEDA, Munehiro <m-ikeda@ds.jp.nec.com>
 and the JF Project team <http://www.linux.or.jp/JF/>.
 If you find any difference between this document and the original file
@@ -14,7 +14,7 @@ to update the original English file first.
 Last Updated: 2007/07/18
 ==================================
 これは、
-linux-2.6.22-rc4/Documentation/stable_api_nonsense.txt の和訳
+linux-2.6.22-rc4/Documentation/development-process/stable_api_nonsense.rst の和訳
 です。
 翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
 翻訳日 ： 2007/06/11
diff --git a/Documentation/ja_JP/stable_kernel_rules.txt b/Documentation/ja_JP/stable_kernel_rules.txt
index 9dbda9b5d21e..b7a201258c76 100644
--- a/Documentation/ja_JP/stable_kernel_rules.txt
+++ b/Documentation/ja_JP/stable_kernel_rules.txt
@@ -1,5 +1,5 @@
 NOTE:
-This is Japanese translated version of "Documentation/stable_kernel_rules.txt".
+This is Japanese translated version of "Documentation/development-process/stable_kernel_rules.rst".
 This one is maintained by Tsugikazu Shibata <tshibata@ab.jp.nec.com>
 and JF Project team <www.linux.or.jp/JF>.
 If you find difference with original file or problem in translation,
@@ -12,7 +12,7 @@ file at first.
 
 ==================================
 これは、
-linux-2.6.29/Documentation/stable_kernel_rules.txt
+linux-2.6.29/Documentation/development-process/stable_kernel_rules.rst
 の和訳です。
 
 翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
@@ -43,7 +43,7 @@ linux-2.6.29/Documentation/stable_kernel_rules.txt
    "理論的には競合状態になる"ようなものは不可。
  - いかなる些細な修正も含めることはできない。(スペルの修正、空白のクリー
    ンアップなど)
- - Documentation/SubmittingPatches の規則に従ったものでなければならない。
+ - Documentation/development-process/SubmittingPatches.rst の規則に従ったものでなければならない。
  - パッチ自体か同等の修正が Linus のツリーに既に存在しなければならない。
 　 Linus のツリーでのコミットID を -stable へのパッチ投稿の際に引用す
    ること。
diff --git a/Documentation/ko_KR/HOWTO b/Documentation/ko_KR/HOWTO
index 9a3e65924d54..a3f13e62da9e 100644
--- a/Documentation/ko_KR/HOWTO
+++ b/Documentation/ko_KR/HOWTO
@@ -1,5 +1,5 @@
 NOTE:
-This is a version of Documentation/HOWTO translated into korean
+This is a version of Documentation/development-process/HOWTO.rst translated into korean
 This document is maintained by Minchan Kim <minchan@kernel.org>
 If you find any difference between this document and the original file or
 a problem with the translation, please contact the maintainer of this file.
@@ -11,7 +11,7 @@ try to update the original English file first.
 
 ==================================
 이 문서는
-Documentation/HOWTO
+Documentation/development-process/HOWTO.rst
 의 한글 번역입니다.
 
 역자： 김민찬 <minchan@kernel.org>
@@ -98,18 +98,18 @@ mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다.
     빌드하기 위해 필요한 것을 설명한다. 커널에 입문하는 사람들은 여기서
     시작해야 한다.
 
-  Documentation/Changes
+  Documentation/development-process/Changes.rst
     이 파일은 커널을 성공적으로 빌드하고 실행시키기 위해 필요한 다양한
     소프트웨어 패키지들의 최소 버젼을 나열한다.
 
-  Documentation/CodingStyle
+  Documentation/development-process/CodingStyle.rst
     이 문서는 리눅스 커널 코딩 스타일과 그렇게 한 몇몇 이유를 설명한다.
     모든 새로운 코드는 이 문서에 가이드라인들을 따라야 한다. 대부분의
     메인테이너들은 이 규칙을 따르는 패치들만을 받아들일 것이고 많은 사람들이
     그 패치가 올바른 스타일일 경우만 코드를 검토할 것이다.
 
-  Documentation/SubmittingPatches
-  Documentation/SubmittingDrivers
+  Documentation/development-process/SubmittingPatches.rst
+  Documentation/development-process/SubmittingDrivers.rst
     이 파일들은 성공적으로 패치를 만들고 보내는 법을 다음의 내용들로
     굉장히 상세히 설명하고 있다(그러나 다음으로 한정되진 않는다).
        - Email 내용들
@@ -126,7 +126,7 @@ mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다.
     "Linux kernel patch submission format"
         http://linux.yyz.us/patch-format.html
 
-   Documentation/stable_api_nonsense.txt
+   Documentation/development-process/stable_api_nonsense.rst
     이 문서는 의도적으로 커널이 불변하는 API를 갖지 않도록 결정한
     이유를 설명하며 다음과 같은 것들을 포함한다.
        - 서브시스템 shim-layer(호환성을 위해?)
@@ -136,12 +136,12 @@ mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다.
     리눅스로 전향하는 사람들에게는 매우 중요하다.
 
 
-  Documentation/SecurityBugs
+  Documentation/development-process/SecurityBugs.rst
     여러분들이 리눅스 커널의 보안 문제를 발견했다고 생각한다면 이 문서에
     나온 단계에 따라서 커널 개발자들에게 알리고 그 문제를 해결할 수 있도록
     도와 달라.
 
-  Documentation/ManagementStyle
+  Documentation/development-process/ManagementStyle.rst
     이 문서는 리눅스 커널 메인테이너들이 그들의 방법론에 녹아 있는
     정신을 어떻게 공유하고 운영하는지를 설명한다. 이것은 커널 개발에 입문하는
     모든 사람들(또는 커널 개발에 작은 호기심이라도 있는 사람들)이
@@ -149,17 +149,17 @@ mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다.
     독특한 행동에 관하여 흔히 있는 오해들과 혼란들을 해소하고 있기
     때문이다.
 
-  Documentation/stable_kernel_rules.txt
+  Documentation/development-process/stable_kernel_rules.rst
     이 문서는 안정적인 커널 배포가 이루어지는 규칙을 설명하고 있으며
     여러분들이 이러한 배포들 중 하나에 변경을 하길 원한다면
     무엇을 해야 하는지를 설명한다.
 
-  Documentation/kernel-docs.txt
+  Documentation/development-process/kernel-docs.rst
     커널 개발에 관계된 외부 문서의 리스트이다. 커널 내의 포함된 문서들
     중에 여러분이 찾고 싶은 문서를 발견하지 못할 경우 이 리스트를
     살펴보라.
 
-  Documentation/applying-patches.txt
+  Documentation/development-process/applying-patches.rst
     패치가 무엇이며 그것을 커널의 다른 개발 브랜치들에 어떻게
     적용하는지에 관하여 자세히 설명하고 있는 좋은 입문서이다.
 
@@ -276,7 +276,7 @@ Andrew Morton의 글이 있다.
 4.x.y는 "stable" 팀<stable@vger.kernel.org>에 의해 관리되며 거의 매번 격주로
 배포된다.
 
-커널 트리 문서들 내에 Documentation/stable_kernel_rules.txt 파일은 어떤
+커널 트리 문서들 내에 Documentation/development-process/stable_kernel_rules.rst 파일은 어떤
 종류의 변경들이 -stable 트리로 들어왔는지와 배포 프로세스가 어떻게
 진행되는지를 설명한다.
 
@@ -391,7 +391,7 @@ bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메
 "John 커널해커는 작성했다...."를 유지하며 여러분들의 의견을 그 메일의 윗부분에
 작성하지 말고 각 인용한 단락들 사이에 넣어라.
 
-여러분들이 패치들을 메일에 넣는다면 그것들은 Documentation/SubmittingPatches에
+여러분들이 패치들을 메일에 넣는다면 그것들은 Documentation/development-process/SubmittingPatches.rst에
 나와있는데로 명백히(plain) 읽을 수 있는 텍스트여야 한다. 커널 개발자들은
 첨부파일이나 압축된 패치들을 원하지 않는다. 그들은 여러분들의 패치의
 각 라인 단위로 코멘트를 하길 원하며 압축하거나 첨부하지 않고 보내는 것이
diff --git a/Documentation/ko_KR/stable_api_nonsense.txt b/Documentation/ko_KR/stable_api_nonsense.txt
index 3ba10b11d556..aaf163197ac0 100644
--- a/Documentation/ko_KR/stable_api_nonsense.txt
+++ b/Documentation/ko_KR/stable_api_nonsense.txt
@@ -1,5 +1,5 @@
 NOTE:
-This is a version of Documentation/stable_api_nonsense.txt translated
+This is a version of Documentation/development-process/stable_api_nonsense.rst translated
 into korean
 This document is maintained by Minchan Kim <minchan@kernel.org>
 If you find any difference between this document and the original file or
@@ -12,7 +12,7 @@ try to update the original English file first.
 
 ==================================
 이 문서는
-Documentation/stable_api_nonsense.txt
+Documentation/development-process/stable_api_nonsense.rst
 의 한글 번역입니다.
 
 역자： 김민찬 <minchan@kernel.org>
diff --git a/Documentation/networking/PLIP.txt b/Documentation/networking/PLIP.txt
index ad7e3f7c3bbf..0a1e70c39bf2 100644
--- a/Documentation/networking/PLIP.txt
+++ b/Documentation/networking/PLIP.txt
@@ -102,7 +102,7 @@ reason, bits are dropped.
 
 A utility that can perform this change in Linux is plipconfig, which is part
 of the net-tools package (its location can be found in the
-Documentation/Changes file). An example command would be
+Documentation/development-process/Changes.rst file). An example command would be
 'plipconfig plipX trigger 10000', where plipX is the appropriate
 PLIP device.
 
diff --git a/Documentation/networking/netdev-FAQ.txt b/Documentation/networking/netdev-FAQ.txt
index 0fe1c6e0dbcd..ec20b077f8d1 100644
--- a/Documentation/networking/netdev-FAQ.txt
+++ b/Documentation/networking/netdev-FAQ.txt
@@ -136,14 +136,14 @@ A: Normally Greg Kroah-Hartman collects stable commits himself, but
 
 Q: I see a network patch and I think it should be backported to stable.
    Should I request it via "stable@vger.kernel.org" like the references in
-   the kernel's Documentation/stable_kernel_rules.txt file say?
+   the kernel's Documentation/development-process/stable_kernel_rules.rst file say?
 
 A: No, not for networking.  Check the stable queues as per above 1st to see
    if it is already queued.  If not, then send a mail to netdev, listing
    the upstream commit ID and why you think it should be a stable candidate.
 
    Before you jump to go do the above, do note that the normal stable rules
-   in Documentation/stable_kernel_rules.txt still apply.  So you need to
+   in Documentation/development-process/stable_kernel_rules.rst still apply.  So you need to
    explicitly indicate why it is a critical fix and exactly what users are
    impacted.  In addition, you need to convince yourself that you _really_
    think it has been overlooked, vs. having been considered and rejected.
@@ -165,7 +165,7 @@ A: No.  See above answer.  In short, if you think it really belongs in
 
    If you think there is some valid information relating to it being in
    stable that does _not_ belong in the commit log, then use the three
-   dash marker line as described in Documentation/SubmittingPatches to
+   dash marker line as described in Documentation/development-process/SubmittingPatches.rst to
    temporarily embed that information into the patch that you send.
 
 Q: Someone said that the comment style and coding convention is different
@@ -220,5 +220,5 @@ A: Attention to detail.  Re-read your own work as if you were the
    If it is your first patch, mail it to yourself so you can test apply
    it to an unpatched tree to confirm infrastructure didn't mangle it.
 
-   Finally, go back and read Documentation/SubmittingPatches to be
+   Finally, go back and read Documentation/development-process/SubmittingPatches.rst to be
    sure you are not repeating some common mistake documented there.
diff --git a/Documentation/scsi/scsi_mid_low_api.txt b/Documentation/scsi/scsi_mid_low_api.txt
index 255075157511..1117d4e39d1e 100644
--- a/Documentation/scsi/scsi_mid_low_api.txt
+++ b/Documentation/scsi/scsi_mid_low_api.txt
@@ -336,7 +336,7 @@ in parallel by these functions.
 Conventions
 ===========
 First, Linus Torvalds's thoughts on C coding style can be found in the
-Documentation/CodingStyle file. 
+Documentation/development-process/CodingStyle.rst file. 
 
 Next, there is a movement to "outlaw" typedefs introducing synonyms for 
 struct tags. Both can be still found in the SCSI subsystem, but
diff --git a/Documentation/virtual/kvm/review-checklist.txt b/Documentation/virtual/kvm/review-checklist.txt
index a850986ed684..2446242f366d 100644
--- a/Documentation/virtual/kvm/review-checklist.txt
+++ b/Documentation/virtual/kvm/review-checklist.txt
@@ -1,8 +1,8 @@
 Review checklist for kvm patches
 ================================
 
-1.  The patch must follow Documentation/CodingStyle and
-    Documentation/SubmittingPatches.
+1.  The patch must follow Documentation/development-process/CodingStyle.rst and
+    Documentation/development-process/SubmittingPatches.rst.
 
 2.  Patches should be against kvm.git master branch.
 
diff --git a/Documentation/watchdog/convert_drivers_to_kernel_api.txt b/Documentation/watchdog/convert_drivers_to_kernel_api.txt
index 271b8850dde7..cad8baa0ce1f 100644
--- a/Documentation/watchdog/convert_drivers_to_kernel_api.txt
+++ b/Documentation/watchdog/convert_drivers_to_kernel_api.txt
@@ -213,6 +213,6 @@ The entry for the driver now needs to select WATCHDOG_CORE:
 Create a patch and send it to upstream
 --------------------------------------
 
-Make sure you understood Documentation/SubmittingPatches and send your patch to
+Make sure you understood Documentation/development-process/SubmittingPatches.rst and send your patch to
 linux-watchdog@vger.kernel.org. We are looking forward to it :)
 
diff --git a/Documentation/zh_CN/CodingStyle b/Documentation/zh_CN/CodingStyle
index 12717791baac..cc9645d19ba3 100644
--- a/Documentation/zh_CN/CodingStyle
+++ b/Documentation/zh_CN/CodingStyle
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/CodingStyle
+Chinese translated version of Documentation/development-process/CodingStyle.rst
 
 If you have any comment or update to the content, please post to LKML directly.
 However, if you have problem communicating in English you can also ask the
@@ -7,7 +7,7 @@ translation is outdated or there is problem with translation.
 
 Chinese maintainer: Zhang Le <r0bertz@gentoo.org>
 ---------------------------------------------------------------------
-Documentation/CodingStyle的中文翻译
+Documentation/development-process/CodingStyle.rst的中文翻译
 
 如果想评论或更新本文的内容，请直接发信到LKML。如果你使用英文交流有困难的话，也可
 以向中文版维护者求助。如果本翻译更新不及时或者翻译存在问题，请联系中文版维护者。
diff --git a/Documentation/zh_CN/HOWTO b/Documentation/zh_CN/HOWTO
index f0613b92e0be..6d6fe1209b71 100644
--- a/Documentation/zh_CN/HOWTO
+++ b/Documentation/zh_CN/HOWTO
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/HOWTO
+Chinese translated version of Documentation/development-process/HOWTO.rst
 
 If you have any comment or update to the content, please contact the
 original document maintainer directly.  However, if you have a problem
@@ -9,7 +9,7 @@ or if there is a problem with the translation.
 Maintainer: Greg Kroah-Hartman <greg@kroah.com>
 Chinese maintainer: Li Yang <leoli@freescale.com>
 ---------------------------------------------------------------------
-Documentation/HOWTO 的中文翻译
+Documentation/development-process/HOWTO.rst 的中文翻译
 
 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
@@ -93,16 +93,16 @@ Linux内核代码中包含有大量的文档。这些文档对于学习如何与
     文件简要介绍了Linux内核的背景，并且描述了如何配置和编译内核。内核的
     新用户应该从这里开始。
 
-  Documentation/Changes
+  Documentation/development-process/Changes.rst
     文件给出了用来编译和使用内核所需要的最小软件包列表。
 
-  Documentation/CodingStyle
+  Documentation/development-process/CodingStyle.rst
     描述Linux内核的代码风格和理由。所有新代码需要遵守这篇文档中定义的规
     范。大多数维护者只会接收符合规定的补丁，很多人也只会帮忙检查符合风格
     的代码。
 
-  Documentation/SubmittingPatches
-  Documentation/SubmittingDrivers
+  Documentation/development-process/SubmittingPatches.rst
+  Documentation/development-process/SubmittingDrivers.rst
     这两份文档明确描述如何创建和发送补丁，其中包括（但不仅限于)：
        - 邮件内容
        - 邮件格式
@@ -116,7 +116,7 @@ Linux内核代码中包含有大量的文档。这些文档对于学习如何与
     "Linux kernel patch submission format"
         http://linux.yyz.us/patch-format.html
 
-  Documentation/stable_api_nonsense.txt
+  Documentation/development-process/stable_api_nonsense.rst
     论证内核为什么特意不包括稳定的内核内部API，也就是说不包括像这样的特
     性：
        - 子系统中间层（为了兼容性？）
@@ -125,23 +125,23 @@ Linux内核代码中包含有大量的文档。这些文档对于学习如何与
     这篇文档对于理解Linux的开发哲学至关重要。对于将开发平台从其他操作系
     统转移到Linux的人来说也很重要。
 
-  Documentation/SecurityBugs
+  Documentation/development-process/SecurityBugs.rst
     如果你认为自己发现了Linux内核的安全性问题，请根据这篇文档中的步骤来
     提醒其他内核开发者并帮助解决这个问题。
 
-  Documentation/ManagementStyle
+  Documentation/development-process/ManagementStyle.rst
     描述内核维护者的工作方法及其共有特点。这对于刚刚接触内核开发（或者对
     它感到好奇）的人来说很重要，因为它解释了很多对于内核维护者独特行为的
     普遍误解与迷惑。
 
-  Documentation/stable_kernel_rules.txt
+  Documentation/development-process/stable_kernel_rules.rst
     解释了稳定版内核发布的规则，以及如何将改动放入这些版本的步骤。
 
-  Documentation/kernel-docs.txt
+  Documentation/development-process/kernel-docs.rst
     有助于内核开发的外部文档列表。如果你在内核自带的文档中没有找到你想找
     的内容，可以查看这些文档。
 
-  Documentation/applying-patches.txt
+  Documentation/development-process/applying-patches.rst
     关于补丁是什么以及如何将它打在不同内核开发分支上的好介绍
 
 内核还拥有大量从代码自动生成的文档。它包含内核内部API的全面介绍以及如何
@@ -238,7 +238,7 @@ kernel.org网站的pub/linux/kernel/v2.6/目录下找到它。它的开发遵循
 2.6.x.y版本由“稳定版”小组（邮件地址<stable@vger.kernel.org>）维护，一般隔周发
 布新版本。
 
-内核源码中的Documentation/stable_kernel_rules.txt文件具体描述了可被稳定
+内核源码中的Documentation/development-process/stable_kernel_rules.rst文件具体描述了可被稳定
 版内核接受的修改类型以及发布的流程。
 
 
@@ -380,7 +380,7 @@ MAINTAINERS文件中可以找到不同话题对应的邮件列表。
 这几行。将你的评论加在被引用的段落之间而不要放在邮件的顶部。
 
 如果你在邮件中附带补丁，请确认它们是可以直接阅读的纯文本（如
-Documentation/SubmittingPatches文档中所述）。内核开发者们不希望遇到附件
+Documentation/development-process/SubmittingPatches.rst文档中所述）。内核开发者们不希望遇到附件
 或者被压缩了的补丁。只有这样才能保证他们可以直接评论你的每行代码。请确保
 你使用的邮件发送程序不会修改空格和制表符。一个防范性的测试方法是先将邮件
 发送给自己，然后自己尝试是否可以顺利地打上收到的补丁。如果测试不成功，请
diff --git a/Documentation/zh_CN/SecurityBugs b/Documentation/zh_CN/SecurityBugs
index d21eb07fe943..8b1a0af493e1 100644
--- a/Documentation/zh_CN/SecurityBugs
+++ b/Documentation/zh_CN/SecurityBugs
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/SecurityBugs
+Chinese translated version of Documentation/development-process/SecurityBugs.rst
 
 If you have any comment or update to the content, please contact the
 original document maintainer directly.  However, if you have a problem
@@ -8,7 +8,7 @@ or if there is a problem with the translation.
 
 Chinese maintainer: Harry Wei <harryxiyou@gmail.com>
 ---------------------------------------------------------------------
-Documentation/SecurityBugs 的中文翻译
+Documentation/development-process/SecurityBugs.rst 的中文翻译
 
 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
diff --git a/Documentation/zh_CN/SubmittingDrivers b/Documentation/zh_CN/SubmittingDrivers
index d313f5d8448d..b59caa9e8ac8 100644
--- a/Documentation/zh_CN/SubmittingDrivers
+++ b/Documentation/zh_CN/SubmittingDrivers
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/SubmittingDrivers
+Chinese translated version of Documentation/development-process/SubmittingDrivers.rst
 
 If you have any comment or update to the content, please contact the
 original document maintainer directly.  However, if you have a problem
@@ -8,7 +8,7 @@ or if there is a problem with the translation.
 
 Chinese maintainer: Li Yang <leo@zh-kernel.org>
 ---------------------------------------------------------------------
-Documentation/SubmittingDrivers 的中文翻译
+Documentation/development-process/SubmittingDrivers.rst 的中文翻译
 
 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
@@ -30,7 +30,7 @@ Documentation/SubmittingDrivers 的中文翻译
 兴趣的是显卡驱动程序，你也许应该访问 XFree86 项目(http://www.xfree86.org/)
 和／或 X.org 项目 (http://x.org)。
 
-另请参阅 Documentation/SubmittingPatches 文档。
+另请参阅 Documentation/development-process/SubmittingPatches.rst 文档。
 
 
 分配设备号
@@ -81,7 +81,7 @@ Linux 2.6:
 		如果你需要一个 Linux 和 NT 的通用驱动接口，那么请在用
 		户空间实现它。
 
-代码：		请使用 Documentation/CodingStyle 中所描述的 Linux 代码风
+代码：		请使用 Documentation/development-process/CodingStyle.rst 中所描述的 Linux 代码风
 		格。如果你的某些代码段（例如那些与 Windows 驱动程序包共
 		享的代码段）需要使用其他格式，而你却只希望维护一份代码，
 		那么请将它们很好地区分出来，并且注明原因。
diff --git a/Documentation/zh_CN/SubmittingPatches b/Documentation/zh_CN/SubmittingPatches
index 1d3a10f8746b..8b93acb3a75e 100644
--- a/Documentation/zh_CN/SubmittingPatches
+++ b/Documentation/zh_CN/SubmittingPatches
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/SubmittingPatches
+Chinese translated version of Documentation/development-process/SubmittingPatches.rst
 
 If you have any comment or update to the content, please contact the
 original document maintainer directly.  However, if you have a problem
@@ -8,7 +8,7 @@ or if there is a problem with the translation.
 
 Chinese maintainer: TripleX Chung <triplex@zh-kernel.org>
 ---------------------------------------------------------------------
-Documentation/SubmittingPatches 的中文翻译
+Documentation/development-process/SubmittingPatches.rst 的中文翻译
 
 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
@@ -32,7 +32,7 @@ Documentation/SubmittingPatches 的中文翻译
 的改动被接受的机会。
 阅读 Documentation/SubmitChecklist 来获得在提交代码前需要检查的项目的列
 表。如果你在提交一个驱动程序，那么同时阅读一下
-Documentation/SubmittingDrivers 。
+Documentation/development-process/SubmittingDrivers.rst 。
 
 
 --------------------------
@@ -404,8 +404,8 @@ Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
 NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
   <https://lkml.org/lkml/2005/7/11/336>
 
-Kernel Documentation/CodingStyle:
-  <http://sosdg.org/~coywolf/lxr/source/Documentation/CodingStyle>
+Kernel Documentation/development-process/CodingStyle.rst:
+  <http://sosdg.org/~coywolf/lxr/source/Documentation/development-process/CodingStyle.rst>
 
 Linus Torvalds's mail on the canonical patch format:
   <http://lkml.org/lkml/2005/4/7/183>
diff --git a/Documentation/zh_CN/stable_api_nonsense.txt b/Documentation/zh_CN/stable_api_nonsense.txt
index c26a27d1ee7d..5f37f56ab7ec 100644
--- a/Documentation/zh_CN/stable_api_nonsense.txt
+++ b/Documentation/zh_CN/stable_api_nonsense.txt
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/stable_api_nonsense.txt
+Chinese translated version of Documentation/development-process/stable_api_nonsense.rst
 
 If you have any comment or update to the content, please contact the
 original document maintainer directly.  However, if you have problem
@@ -9,7 +9,7 @@ is problem with translation.
 Maintainer: Greg Kroah-Hartman <greg@kroah.com>
 Chinese maintainer: TripleX Chung <zhongyu@18mail.cn>
 ---------------------------------------------------------------------
-Documentation/stable_api_nonsense.txt 的中文翻译
+Documentation/development-process/stable_api_nonsense.rst 的中文翻译
 
 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
diff --git a/Documentation/zh_CN/stable_kernel_rules.txt b/Documentation/zh_CN/stable_kernel_rules.txt
index 26ea5ed7cd9c..e8e09a9a1891 100644
--- a/Documentation/zh_CN/stable_kernel_rules.txt
+++ b/Documentation/zh_CN/stable_kernel_rules.txt
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/stable_kernel_rules.txt
+Chinese translated version of Documentation/development-process/stable_kernel_rules.rst
 
 If you have any comment or update to the content, please contact the
 original document maintainer directly.  However, if you have a problem
@@ -8,7 +8,7 @@ or if there is a problem with the translation.
 
 Chinese maintainer: TripleX Chung <triplex@zh-kernel.org>
 ---------------------------------------------------------------------
-Documentation/stable_kernel_rules.txt 的中文翻译
+Documentation/development-process/stable_kernel_rules.rst 的中文翻译
 
 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
@@ -38,7 +38,7 @@ Documentation/stable_kernel_rules.txt 的中文翻译
   - 没有“理论上的竞争条件”，除非能给出竞争条件如何被利用的解释。
   - 不能存在任何的“琐碎的”修正（拼写修正，去掉多余空格之类的）。
   - 必须被相关子系统的维护者接受。
-  - 必须遵循Documentation/SubmittingPatches里的规则。
+  - 必须遵循Documentation/development-process/SubmittingPatches.rst里的规则。
 
 向稳定版代码树提交补丁的过程：
 
diff --git a/MAINTAINERS b/MAINTAINERS
index 9c4469949f28..5c64195f00ee 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -35,7 +35,7 @@ trivial patch so apply some common sense.
 
 	PLEASE check your patch with the automated style checker
 	(scripts/checkpatch.pl) to catch trivial style violations.
-	See Documentation/CodingStyle for guidance here.
+	See Documentation/development-process/CodingStyle.rst for guidance here.
 
 	PLEASE CC: the maintainers and mailing lists that are generated
 	by scripts/get_maintainer.pl.  The results returned by the
diff --git a/README b/README
index 09f34f78f2bb..0a5a8d862021 100644
--- a/README
+++ b/README
@@ -114,7 +114,7 @@ SOFTWARE REQUIREMENTS
 
    Compiling and running the 4.x kernels requires up-to-date
    versions of various software packages.  Consult
-   Documentation/Changes for the minimum version numbers required
+   Documentation/development-process/Changes.rst for the minimum version numbers required
    and how to get updates for these packages.  Beware that using
    excessively old versions of these packages can cause indirect
    errors that are very difficult to track down, so don't assume that
@@ -245,7 +245,7 @@ CONFIGURING the kernel:
 COMPILING the kernel:
 
  - Make sure you have at least gcc 3.2 available.
-   For more information, refer to Documentation/Changes.
+   For more information, refer to Documentation/development-process/Changes.rst.
 
    Please note that you can still run a.out user programs with this kernel.
 
diff --git a/REPORTING-BUGS b/REPORTING-BUGS
index 914baf9cf5fa..853c264bd092 100644
--- a/REPORTING-BUGS
+++ b/REPORTING-BUGS
@@ -55,7 +55,7 @@ files to the get_maintainer.pl script:
 
 If it is a security bug, please copy the Security Contact listed in the
 MAINTAINERS file.  They can help coordinate bugfix and disclosure.  See
-Documentation/SecurityBugs for more information.
+Documentation/development-process/SecurityBugs.rst for more information.
 
 If you can't figure out which subsystem caused the issue, you should file
 a bug in kernel.org bugzilla and send email to
diff --git a/drivers/net/ppp/Kconfig b/drivers/net/ppp/Kconfig
index 1373c6d7278d..49c93a693b67 100644
--- a/drivers/net/ppp/Kconfig
+++ b/drivers/net/ppp/Kconfig
@@ -15,7 +15,7 @@ config PPP
 	  To use PPP, you need an additional program called pppd as described
 	  in the PPP-HOWTO, available at
 	  <http://www.tldp.org/docs.html#howto>.  Make sure that you have
-	  the version of pppd recommended in <file:Documentation/Changes>.
+	  the version of pppd recommended in <file:Documentation/development-process/Changes.rst>.
 	  The PPP option enlarges your kernel by about 16 KB.
 
 	  There are actually two versions of PPP: the traditional PPP for
diff --git a/drivers/pcmcia/Kconfig b/drivers/pcmcia/Kconfig
index d3c378b4db6c..b8ef9e674a49 100644
--- a/drivers/pcmcia/Kconfig
+++ b/drivers/pcmcia/Kconfig
@@ -26,7 +26,7 @@ config PCMCIA
 	   only using 32-bit CardBus cards, say Y or M here.
 
 	   To use 16-bit PCMCIA cards, you will need supporting software in
-	   most cases. (see the file <file:Documentation/Changes> for
+	   most cases. (see the file <file:Documentation/development-process/Changes.rst> for
 	   location and details).
 
 	   To compile this driver as modules, choose M here: the
diff --git a/fs/Kconfig.binfmt b/fs/Kconfig.binfmt
index c7efddf6e038..aba0e09a0053 100644
--- a/fs/Kconfig.binfmt
+++ b/fs/Kconfig.binfmt
@@ -21,7 +21,7 @@ config BINFMT_ELF
 	  If you find that after upgrading from Linux kernel 1.2 and saying Y
 	  here, you still can't run any ELF binaries (they just crash), then
 	  you'll have to install the newest ELF runtime libraries, including
-	  ld.so (check the file <file:Documentation/Changes> for location and
+	  ld.so (check the file <file:Documentation/development-process/Changes.rst> for location and
 	  latest version).
 
 config COMPAT_BINFMT_ELF
diff --git a/fs/fuse/Kconfig b/fs/fuse/Kconfig
index 1b2f6c2c3aaf..f55c3596c21e 100644
--- a/fs/fuse/Kconfig
+++ b/fs/fuse/Kconfig
@@ -11,7 +11,7 @@ config FUSE_FS
 	  installed if you've installed the "fuse" package itself.
 
 	  See <file:Documentation/filesystems/fuse.txt> for more information.
-	  See <file:Documentation/Changes> for needed library/utility version.
+	  See <file:Documentation/development-process/Changes.rst> for needed library/utility version.
 
 	  If you want to develop a userspace FS, or if you want to use
 	  a filesystem based on FUSE, answer Y or M.
diff --git a/net/Kconfig b/net/Kconfig
index c2cdbce629bd..71edecbb7ee9 100644
--- a/net/Kconfig
+++ b/net/Kconfig
@@ -17,7 +17,7 @@ menuconfig NET
 	  should consider updating your networking tools too because changes
 	  in the kernel and the tools often go hand in hand. The tools are
 	  contained in the package net-tools, the location and version number
-	  of which are given in <file:Documentation/Changes>.
+	  of which are given in <file:Documentation/development-process/Changes.rst>.
 
 	  For a general introduction to Linux networking, it is highly
 	  recommended to read the NET-HOWTO, available from
@@ -159,7 +159,7 @@ menuconfig NETFILTER
 	  Various modules exist for netfilter which replace the previous
 	  masquerading (ipmasqadm), packet filtering (ipchains), transparent
 	  proxying, and portforwarding mechanisms. Please see
-	  <file:Documentation/Changes> under "iptables" for the location of
+	  <file:Documentation/development-process/Changes.rst> under "iptables" for the location of
 	  these packages.
 
 if NETFILTER
diff --git a/scripts/ver_linux b/scripts/ver_linux
index 0d8bd29b1bd6..931e933c4bcf 100755
--- a/scripts/ver_linux
+++ b/scripts/ver_linux
@@ -5,7 +5,7 @@
 # differ on your system.
 #
 echo 'If some fields are empty or look unusual you may have an old version.'
-echo 'Compare to the current minimal requirements in Documentation/Changes.'
+echo 'Compare to the current minimal requirements in Documentation/development-process/Changes.rst.'
 echo ' '
 
 uname -a
diff --git a/tools/testing/selftests/futex/README b/tools/testing/selftests/futex/README
index 0558bb9ce0a6..5253e7efd120 100644
--- a/tools/testing/selftests/futex/README
+++ b/tools/testing/selftests/futex/README
@@ -59,4 +59,4 @@ o FIXME: decide on a sane test naming scheme.  Currently the tests are named
 Coding Style
 ------------
 o The Futex Test project adheres to the coding standards set forth by Linux
-  kernel as defined in the Linux source Documentation/CodingStyle.
+  kernel as defined in the Linux source Documentation/development-process/CodingStyle.rst.
-- 
2.7.4

[PATCH v2 20/20] doc: Add the development-process to Sphinx build

[Mauro Carvalho Chehab]

Add an index and put it at Documentation/index.rst, in order
to allow building the Kernel develpment documentation on Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/conf.py                       |  2 ++
 Documentation/development-process/conf.py   | 10 ++++++++++
 Documentation/development-process/index.rst | 31 +++++++++++++++++++++++++++++
 Documentation/index.rst                     |  1 +
 4 files changed, 44 insertions(+)
 create mode 100644 Documentation/development-process/conf.py
 create mode 100644 Documentation/development-process/index.rst

diff --git a/Documentation/conf.py b/Documentation/conf.py
index c25e95d46272..bf6f310e5170 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -338,6 +338,8 @@ latex_elements = {
 latex_documents = [
     ('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel Documentation',
      'The kernel development community', 'manual'),
+    ('development-process/index', 'development-process.tex', 'Linux Kernel Development Documentation',
+     'The kernel development community', 'manual'),
     ('gpu/index', 'gpu.tex', 'Linux GPU Driver Developer\'s Guide',
      'The kernel development community', 'manual'),
     ('media/index', 'media.tex', 'Linux Media Subsystem Documentation',
diff --git a/Documentation/development-process/conf.py b/Documentation/development-process/conf.py
new file mode 100644
index 000000000000..4b4a12dace02
--- /dev/null
+++ b/Documentation/development-process/conf.py
@@ -0,0 +1,10 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = 'Linux Kernel Development Documentation'
+
+tags.add("subproject")
+
+latex_documents = [
+    ('index', 'development-process.tex', 'Linux Kernel Development Documentation',
+     'The kernel development community', 'manual'),
+]
diff --git a/Documentation/development-process/index.rst b/Documentation/development-process/index.rst
new file mode 100644
index 000000000000..f4bf8f714298
--- /dev/null
+++ b/Documentation/development-process/index.rst
@@ -0,0 +1,31 @@
+Linux Kernel Development Documentation
+======================================
+
+Contents:
+
+.. toctree::
+   :numbered:
+   :maxdepth: 2
+
+   HOWTO
+   Changes
+   CodingStyle
+   SubmittingPatches
+   SubmittingDrivers
+   stable_api_nonsense
+   SecurityBugs
+   ManagementStyle
+   stable_kernel_rules
+   kernel-docs
+   applying-patches
+
+   development-process
+
+.. only::  subproject
+
+   Indices
+   =======
+
+   * :ref:`genindex`
+
+
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 05eded59820e..c6cf3971788d 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -12,6 +12,7 @@ Contents:
    :maxdepth: 2
 
    kernel-documentation
+   development-process/index
    dev-tools/tools
    media/index
    gpu/index
-- 
2.7.4