docs: rcu: convert some articles from html to ReST

There are 4 RCU articles that are written on html format. The way they are, they can't be part of the Linux Kernel documentation body nor share the styles and pdf output. So, convert them to ReST format. This way, make htmldocs and make pdfdocs will produce a documentation output that will be like the original ones, but will be part of the Linux Kernel documentation body. Part of the conversion was done with the help of pandoc, but the result had some broken things that had to be manually fixed. Following are manual changes Mauro made when doing the automatic conversion: Quoting from: https://lore.kernel.org/rcu/20190726154550.5eeae294@coco.lan/ > > At least the pandoc's version I used here has a bug: its conversion > > from html to ReST on those files only start after a <body> tag - or > > when the first quiz table starts. I only discovered that adding a > > <body> at the beginning of the file solve this book at the last > > conversions. > > > > So, for most html->ReST conversions, I manually converted the first > > part of the document, basically stripping html paragraph tags and > > by replacing highlights by the ReST syntax. > > > > Also, all the quiz tables seem to assume some javascript macro or > > css style that would be hiding the answer part until the mouse moves > > to it. Such macro/css was not there at the kernel tree. So, the quiz > > answers have the same color as the background, making them invisible. > > Even if we had such macro/css, this is not portable for pdf/LaTeX output > > (and I'm not sure if this would work with ePub). > > > > So, I ended by manually doing the table conversion. > > > > Finally, I double-checked if the conversions ended ok, addressing any > > issues that might have heppened. > > > > So, after both automatic conversion and manual fixes, I opened both the > > html files produced by Sphinx and the original ones and compared them > > line per line (except for the indexes, as Sphinx produces them > > automatically), in order to see if all information from the original > > files will be there on a format close to what we have on other ReST > > files, fixing any pending issues if any. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>

docs: rcu: convert some articles from html to ReST
There are 4 RCU articles that are written on html format. The way they are, they can't be part of the Linux Kernel documentation body nor share the styles and pdf output. So, convert them to ReST format. This way, make htmldocs and make pdfdocs will produce a documentation output that will be like the original ones, but will be part of the Linux Kernel documentation body. Part of the conversion was done with the help of pandoc, but the result had some broken things that had to be manually fixed. Following are manual changes Mauro made when doing the automatic conversion: Quoting from: https://lore.kernel.org/rcu/20190726154550.5eeae294@coco.lan/ > > At least the pandoc's version I used here has a bug: its conversion > > from html to ReST on those files only start after a <body> tag - or > > when the first quiz table starts. I only discovered that adding a > > <body> at the beginning of the file solve this book at the last > > conversions. > > > > So, for most html->ReST conversions, I manually converted the first > > part of the document, basically stripping html paragraph tags and > > by replacing highlights by the ReST syntax. > > > > Also, all the quiz tables seem to assume some javascript macro or > > css style that would be hiding the answer part until the mouse moves > > to it. Such macro/css was not there at the kernel tree. So, the quiz > > answers have the same color as the background, making them invisible. > > Even if we had such macro/css, this is not portable for pdf/LaTeX output > > (and I'm not sure if this would work with ePub). > > > > So, I ended by manually doing the table conversion. > > > > Finally, I double-checked if the conversions ended ok, addressing any > > issues that might have heppened. > > > > So, after both automatic conversion and manual fixes, I opened both the > > html files produced by Sphinx and the original ones and compared them > > line per line (except for the indexes, as Sphinx produces them > > automatically), in order to see if all information from the original > > files will be there on a format close to what we have on other ReST > > files, fixing any pending issues if any. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
ccc9971e · Mauro Carvalho Chehab · Paul E. McKenney · c07e6f36 · c07e6f36 · ccc9971e
Commit ccc9971e authored Aug 01, 2019 by Mauro Carvalho Chehab Committed by Paul E. McKenney Oct 29, 2019
11 changed files
--- a/Documentation/RCU/Design/Data-Structures/Data-Structures.html
+++ b/Documentation/RCU/Design/Data-Structures/Data-Structures.html
--- a/Documentation/RCU/Design/Data-Structures/Data-Structures.rst
+++ b/Documentation/RCU/Design/Data-Structures/Data-Structures.rst
--- a/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.html
+++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.html
--- a/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst
+++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst
--- a/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Diagram.html
+++ b/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Diagram.html
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
-        "http://www.w3.org/TR/html4/loose.dtd">
-        <html>
-        <head><title>A Diagram of TREE_RCU's Grace-Period Memory Ordering</title>
-        <meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
-<p><img src="TreeRCU-gp.svg" alt="TreeRCU-gp.svg">
-</body></html>
--- a/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.html
+++ b/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.html
--- a/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst
+++ b/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst
--- a/Documentation/RCU/Design/Requirements/Requirements.html
+++ b/Documentation/RCU/Design/Requirements/Requirements.html
--- a/Documentation/RCU/Design/Requirements/Requirements.rst
+++ b/Documentation/RCU/Design/Requirements/Requirements.rst
--- a/Documentation/RCU/index.rst
+++ b/Documentation/RCU/index.rst
@@ -11,6 +11,11 @@ RCU concepts
   listRCU
   UP
+   Design/Memory-Ordering/Tree-RCU-Memory-Ordering
+   Design/Expedited-Grace-Periods/Expedited-Grace-Periods
+   Design/Requirements/Requirements
+   Design/Data-Structures/Data-Structures
 .. only:: subproject and html
   Indices

--- a/Documentation/RCU/whatisRCU.txt
+++ b/Documentation/RCU/whatisRCU.txt
@@ -302,7 +302,7 @@ rcu_dereference()
 	must prohibit.	The rcu_dereference_protected() variant takes
 	a lockdep expression to indicate which locks must be acquired
 	by the caller. If the indicated protection is not provided,
-	a lockdep splat is emitted.  See RCU/Design/Requirements/Requirements.html
+	a lockdep splat is emitted.  See Documentation/RCU/Design/Requirements/Requirements.rst
 	and the API's code comments for more details and example usage.
 The following diagram shows how each API communicates among the
@@ -630,7 +630,7 @@ been able to write-acquire the lock otherwise.  The smp_mb__after_spinlock()
 promotes synchronize_rcu() to a full memory barrier in compliance with
 the "Memory-Barrier Guarantees" listed in:
-	Documentation/RCU/Design/Requirements/Requirements.html.
+	Documentation/RCU/Design/Requirements/Requirements.rst
 It is possible to nest rcu_read_lock(), since reader-writer locks may
 be recursively acquired.  Note also that rcu_read_lock() is immune