docs: blockdev: convert to ReST

Rename the blockdev documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.

The drbd sub-directory contains some graphs and data flows.
Add those too to the documentation.

At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

9 files changed, 377 insertions, 224 deletions

diff --git a/Documentation/blockdev/drbd/data-structure-v9.txt b/Documentation/blockdev/drbd/data-structure-v9.rst
index 1e52a0e32624..66036b901644 100644
--- a/Documentation/blockdev/drbd/data-structure-v9.txt
+++ b/Documentation/blockdev/drbd/data-structure-v9.rst
@@ -1,3 +1,7 @@
+================================
+kernel data structure for DRBD-9
+================================
+
 This describes the in kernel data structure for DRBD-9. Starting with
 Linux v3.14 we are reorganizing DRBD to use this data structure.
 
@@ -10,7 +14,7 @@ device is represented by a block device locally.
 
 The DRBD objects are interconnected to form a matrix as depicted below; a
 drbd_peer_device object sits at each intersection between a drbd_device and a
-drbd_connection:
+drbd_connection::
 
   /--------------+---------------+.....+---------------\
   |   resource   |    device     |     |    device     |
diff --git a/Documentation/blockdev/drbd/figures.rst b/Documentation/blockdev/drbd/figures.rst
new file mode 100644
index 000000000000..3e3fd4b8a478
--- /dev/null
+++ b/Documentation/blockdev/drbd/figures.rst
@@ -0,0 +1,28 @@
+.. The here included files are intended to help understand the implementation
+
+Data flows that Relate some functions, and write packets
+========================================================
+
+.. kernel-figure:: DRBD-8.3-data-packets.svg
+    :alt:   DRBD-8.3-data-packets.svg
+    :align: center
+
+.. kernel-figure:: DRBD-data-packets.svg
+    :alt:   DRBD-data-packets.svg
+    :align: center
+
+
+Sub graphs of DRBD's state transitions
+======================================
+
+.. kernel-figure:: conn-states-8.dot
+    :alt:   conn-states-8.dot
+    :align: center
+
+.. kernel-figure:: disk-states-8.dot
+    :alt:   disk-states-8.dot
+    :align: center
+
+.. kernel-figure:: node-states-8.dot
+    :alt:   node-states-8.dot
+    :align: center
diff --git a/Documentation/blockdev/drbd/README.txt b/Documentation/blockdev/drbd/index.rst
index 627b0a1bf35e..68ecd5c113e9 100644
--- a/Documentation/blockdev/drbd/README.txt
+++ b/Documentation/blockdev/drbd/index.rst
@@ -1,4 +1,9 @@
+==========================================
+Distributed Replicated Block Device - DRBD
+==========================================
+
 Description
+===========
 
   DRBD is a shared-nothing, synchronously replicated block device. It
   is designed to serve as a building block for high availability
@@ -7,10 +12,8 @@ Description
 
   Please visit http://www.drbd.org to find out more.
 
-The here included files are intended to help understand the implementation
-
-DRBD-8.3-data-packets.svg, DRBD-data-packets.svg  
-  relates some functions, and write packets.
+.. toctree::
+   :maxdepth: 1
 
-conn-states-8.dot, disk-states-8.dot, node-states-8.dot
-  The sub graphs of DRBD's state transitions
+   data-structure-v9
+   figures
diff --git a/Documentation/blockdev/floppy.txt b/Documentation/blockdev/floppy.rst
index e2240f5ab64d..4a8f31cf4139 100644
--- a/Documentation/blockdev/floppy.txt
+++ b/Documentation/blockdev/floppy.rst
@@ -1,35 +1,37 @@
-This file describes the floppy driver.
+=============
+Floppy Driver
+=============
 
 FAQ list:
 =========
 
- A FAQ list may be found in the fdutils package (see below), and also
+A FAQ list may be found in the fdutils package (see below), and also
 at <http://fdutils.linux.lu/faq.html>.
 
 
 LILO configuration options (Thinkpad users, read this)
 ======================================================
 
- The floppy driver is configured using the 'floppy=' option in
+The floppy driver is configured using the 'floppy=' option in
 lilo. This option can be typed at the boot prompt, or entered in the
 lilo configuration file.
 
- Example: If your kernel is called linux-2.6.9, type the following line
-at the lilo boot prompt (if you have a thinkpad):
+Example: If your kernel is called linux-2.6.9, type the following line
+at the lilo boot prompt (if you have a thinkpad)::
 
  linux-2.6.9 floppy=thinkpad
 
 You may also enter the following line in /etc/lilo.conf, in the description
-of linux-2.6.9:
+of linux-2.6.9::
 
  append = "floppy=thinkpad"
 
- Several floppy related options may be given, example:
+Several floppy related options may be given, example::
 
  linux-2.6.9 floppy=daring floppy=two_fdc
  append = "floppy=daring floppy=two_fdc"
 
- If you give options both in the lilo config file and on the boot
+If you give options both in the lilo config file and on the boot
 prompt, the option strings of both places are concatenated, the boot
 prompt options coming last. That's why there are also options to
 restore the default behavior.
@@ -38,21 +40,23 @@ restore the default behavior.
 Module configuration options
 ============================
 
- If you use the floppy driver as a module, use the following syntax:
-modprobe floppy floppy="<options>"
+If you use the floppy driver as a module, use the following syntax::
 
-Example:
- modprobe floppy floppy="omnibook messages"
+	modprobe floppy floppy="<options>"
 
- If you need certain options enabled every time you load the floppy driver,
-you can put:
+Example::
 
- options floppy floppy="omnibook messages"
+	modprobe floppy floppy="omnibook messages"
+
+If you need certain options enabled every time you load the floppy driver,
+you can put::
+
+	options floppy floppy="omnibook messages"
 
 in a configuration file in /etc/modprobe.d/.
 
 
- The floppy driver related options are:
+The floppy driver related options are:
 
  floppy=asus_pci
 	Sets the bit mask to allow only units 0 and 1. (default)
@@ -70,8 +74,7 @@ in a configuration file in /etc/modprobe.d/.
 	Tells the floppy driver that you have only one floppy controller.
 	(default)
 
- floppy=two_fdc
- floppy=<address>,two_fdc
+ floppy=two_fdc / floppy=<address>,two_fdc
 	Tells the floppy driver that you have two floppy controllers.
 	The second floppy controller is assumed to be at <address>.
 	This option is not needed if the second controller is at address
@@ -84,8 +87,7 @@ in a configuration file in /etc/modprobe.d/.
  floppy=0,thinkpad
 	Tells the floppy driver that you don't have a Thinkpad.
 
- floppy=omnibook
- floppy=nodma
+ floppy=omnibook / floppy=nodma
 	Tells the floppy driver not to use Dma for data transfers.
 	This is needed on HP Omnibooks, which don't have a workable
 	DMA channel for the floppy driver. This option is also useful
@@ -144,14 +146,16 @@ in a configuration file in /etc/modprobe.d/.
 	described in the physical CMOS), or if your BIOS uses
 	non-standard CMOS types. The CMOS types are:
 
-		0 - Use the value of the physical CMOS
-		1 - 5 1/4 DD
-		2 - 5 1/4 HD
-		3 - 3 1/2 DD
-		4 - 3 1/2 HD
-		5 - 3 1/2 ED
-		6 - 3 1/2 ED
-	       16 - unknown or not installed
+	       ==  ==================================
+		0  Use the value of the physical CMOS
+		1  5 1/4 DD
+		2  5 1/4 HD
+		3  3 1/2 DD
+		4  3 1/2 HD
+		5  3 1/2 ED
+		6  3 1/2 ED
+	       16  unknown or not installed
+	       ==  ==================================
 
 	(Note: there are two valid types for ED drives. This is because 5 was
 	initially chosen to represent floppy *tapes*, and 6 for ED drives.
@@ -162,8 +166,7 @@ in a configuration file in /etc/modprobe.d/.
 	Print a warning message when an unexpected interrupt is received.
 	(default)
 
- floppy=no_unexpected_interrupts
- floppy=L40SX
+ floppy=no_unexpected_interrupts / floppy=L40SX
 	Don't print a message when an unexpected interrupt is received. This
 	is needed on IBM L40SX laptops in certain video modes. (There seems
 	to be an interaction between video and floppy. The unexpected
@@ -199,47 +202,54 @@ in a configuration file in /etc/modprobe.d/.
 	Sets the floppy DMA channel to <nr> instead of 2.
 
  floppy=slow
-	Use PS/2 stepping rate:
-	 " PS/2 floppies have much slower step rates than regular floppies.
+	Use PS/2 stepping rate::
+
+	   PS/2 floppies have much slower step rates than regular floppies.
 	   It's been recommended that take about 1/4 of the default speed
-	   in some more extreme cases."
+	   in some more extreme cases.
 
 
 Supporting utilities and additional documentation:
 ==================================================
 
- Additional parameters of the floppy driver can be configured at
+Additional parameters of the floppy driver can be configured at
 runtime. Utilities which do this can be found in the fdutils package.
 This package also contains a new version of mtools which allows to
 access high capacity disks (up to 1992K on a high density 3 1/2 disk!).
 It also contains additional documentation about the floppy driver.
 
 The latest version can be found at fdutils homepage:
+
  http://fdutils.linux.lu
 
 The fdutils releases can be found at:
+
  http://fdutils.linux.lu/download.html
+
  http://www.tux.org/pub/knaff/fdutils/
+
  ftp://metalab.unc.edu/pub/Linux/utils/disk-management/
 
 Reporting problems about the floppy driver
 ==========================================
 
- If you have a question or a bug report about the floppy driver, mail
+If you have a question or a bug report about the floppy driver, mail
 me at Alain.Knaff@poboxes.com . If you post to Usenet, preferably use
 comp.os.linux.hardware. As the volume in these groups is rather high,
 be sure to include the word "floppy" (or "FLOPPY") in the subject
 line.  If the reported problem happens when mounting floppy disks, be
 sure to mention also the type of the filesystem in the subject line.
 
- Be sure to read the FAQ before mailing/posting any bug reports!
+Be sure to read the FAQ before mailing/posting any bug reports!
 
- Alain
+Alain
 
 Changelog
 =========
 
-10-30-2004 :	Cleanup, updating, add reference to module configuration.
+10-30-2004 :
+		Cleanup, updating, add reference to module configuration.
 		James Nelson <james4765@gmail.com>
 
-6-3-2000 :	Original Document
+6-3-2000 :
+		Original Document
diff --git a/Documentation/blockdev/index.rst b/Documentation/blockdev/index.rst
new file mode 100644
index 000000000000..a9af6ed8b4aa
--- /dev/null
+++ b/Documentation/blockdev/index.rst
@@ -0,0 +1,16 @@
+:orphan:
+
+===========================
+The Linux RapidIO Subsystem
+===========================
+
+.. toctree::
+   :maxdepth: 1
+
+   floppy
+   nbd
+   paride
+   ramdisk
+   zram
+
+   drbd/index
diff --git a/Documentation/blockdev/nbd.txt b/Documentation/blockdev/nbd.rst
index db242ea2bce8..d78dfe559dcf 100644
--- a/Documentation/blockdev/nbd.txt
+++ b/Documentation/blockdev/nbd.rst
@@ -1,3 +1,4 @@
+==================================
 Network Block Device (TCP version)
 ==================================
 
@@ -28,4 +29,3 @@ max_part
 
 nbds_max
 	Number of block devices that should be initialized (default: 16).
-
diff --git a/Documentation/blockdev/paride.txt b/Documentation/blockdev/paride.rst
index ee6717e3771d..87b4278bf314 100644
--- a/Documentation/blockdev/paride.txt
+++ b/Documentation/blockdev/paride.rst
@@ -1,15 +1,17 @@
-
-		Linux and parallel port IDE devices
+===================================
+Linux and parallel port IDE devices
+===================================
 
 PARIDE v1.03   (c) 1997-8  Grant Guenther <grant@torque.net>
 
 1. Introduction
+===============
 
 Owing to the simplicity and near universality of the parallel port interface
 to personal computers, many external devices such as portable hard-disk,
 CD-ROM, LS-120 and tape drives use the parallel port to connect to their
 host computer.  While some devices (notably scanners) use ad-hoc methods
-to pass commands and data through the parallel port interface, most 
+to pass commands and data through the parallel port interface, most
 external devices are actually identical to an internal model, but with
 a parallel-port adapter chip added in.  Some of the original parallel port
 adapters were little more than mechanisms for multiplexing a SCSI bus.
@@ -28,47 +30,50 @@ were to open up a parallel port CD-ROM drive, for instance, one would
 find a standard ATAPI CD-ROM drive, a power supply, and a single adapter
 that interconnected a standard PC parallel port cable and a standard
 IDE cable.  It is usually possible to exchange the CD-ROM device with
-any other device using the IDE interface. 
+any other device using the IDE interface.
 
 The document describes the support in Linux for parallel port IDE
 devices.  It does not cover parallel port SCSI devices, "ditto" tape
-drives or scanners.  Many different devices are supported by the 
+drives or scanners.  Many different devices are supported by the
 parallel port IDE subsystem, including:
 
-	MicroSolutions backpack CD-ROM
-	MicroSolutions backpack PD/CD
-	MicroSolutions backpack hard-drives
-	MicroSolutions backpack 8000t tape drive
-	SyQuest EZ-135, EZ-230 & SparQ drives
-	Avatar Shark
-	Imation Superdisk LS-120
-	Maxell Superdisk LS-120
-	FreeCom Power CD 
-	Hewlett-Packard 5GB and 8GB tape drives
-	Hewlett-Packard 7100 and 7200 CD-RW drives
+	- MicroSolutions backpack CD-ROM
+	- MicroSolutions backpack PD/CD
+	- MicroSolutions backpack hard-drives
+	- MicroSolutions backpack 8000t tape drive
+	- SyQuest EZ-135, EZ-230 & SparQ drives
+	- Avatar Shark
+	- Imation Superdisk LS-120
+	- Maxell Superdisk LS-120
+	- FreeCom Power CD
+	- Hewlett-Packard 5GB and 8GB tape drives
+	- Hewlett-Packard 7100 and 7200 CD-RW drives
 
 as well as most of the clone and no-name products on the market.
 
 To support such a wide range of devices, PARIDE, the parallel port IDE
 subsystem, is actually structured in three parts.   There is a base
 paride module which provides a registry and some common methods for
-accessing the parallel ports.  The second component is a set of 
-high-level drivers for each of the different types of supported devices: 
+accessing the parallel ports.  The second component is a set of
+high-level drivers for each of the different types of supported devices:
 
+	===	=============
 	pd	IDE disk
 	pcd	ATAPI CD-ROM
 	pf	ATAPI disk
 	pt	ATAPI tape
 	pg	ATAPI generic
+	===	=============
 
 (Currently, the pg driver is only used with CD-R drives).
 
 The high-level drivers function according to the relevant standards.
 The third component of PARIDE is a set of low-level protocol drivers
 for each of the parallel port IDE adapter chips.  Thanks to the interest
-and encouragement of Linux users from many parts of the world, 
+and encouragement of Linux users from many parts of the world,
 support is available for almost all known adapter protocols:
 
+	====    ====================================== ====
         aten    ATEN EH-100                            (HK)
         bpck    Microsolutions backpack                (US)
         comm    DataStor (old-type) "commuter" adapter (TW)
@@ -83,9 +88,11 @@ support is available for almost all known adapter protocols:
 	ktti    KT Technology PHd adapter              (SG)
         on20    OnSpec 90c20                           (US)
         on26    OnSpec 90c26                           (US)
+	====    ====================================== ====
 
 
 2. Using the PARIDE subsystem
+=============================
 
 While configuring the Linux kernel, you may choose either to build
 the PARIDE drivers into your kernel, or to build them as modules.
@@ -94,10 +101,10 @@ In either case, you will need to select "Parallel port IDE device support"
 as well as at least one of the high-level drivers and at least one
 of the parallel port communication protocols.  If you do not know
 what kind of parallel port adapter is used in your drive, you could
-begin by checking the file names and any text files on your DOS 
+begin by checking the file names and any text files on your DOS
 installation floppy.  Alternatively, you can look at the markings on
 the adapter chip itself.  That's usually sufficient to identify the
-correct device.  
+correct device.
 
 You can actually select all the protocol modules, and allow the PARIDE
 subsystem to try them all for you.
@@ -105,8 +112,9 @@ subsystem to try them all for you.
 For the "brand-name" products listed above, here are the protocol
 and high-level drivers that you would use:
 
+	================	============	======	========
 	Manufacturer		Model		Driver	Protocol
-	
+	================	============	======	========
 	MicroSolutions		CD-ROM		pcd	bpck
 	MicroSolutions		PD drive	pf	bpck
 	MicroSolutions		hard-drive	pd	bpck
@@ -119,8 +127,10 @@ and high-level drivers that you would use:
 	Hewlett-Packard		5GB Tape	pt	epat
 	Hewlett-Packard		7200e (CD)	pcd	epat
 	Hewlett-Packard		7200e (CD-R)	pg	epat
+	================	============	======	========
 
 2.1  Configuring built-in drivers
+---------------------------------
 
 We recommend that you get to know how the drivers work and how to
 configure them as loadable modules, before attempting to compile a
@@ -143,7 +153,7 @@ protocol identification number and, for some devices, the drive's
 chain ID.  While your system is booting, a number of messages are
 displayed on the console.  Like all such messages, they can be
 reviewed with the 'dmesg' command.  Among those messages will be
-some lines like:
+some lines like::
 
 	paride: bpck registered as protocol 0
 	paride: epat registered as protocol 1
@@ -158,10 +168,10 @@ the last two digits of the drive's serial number (but read MicroSolutions'
 documentation about this).
 
 As an example, let's assume that you have a MicroSolutions PD/CD drive
-with unit ID number 36 connected to the parallel port at 0x378, a SyQuest 
-EZ-135 connected to the chained port on the PD/CD drive and also an 
-Imation Superdisk connected to port 0x278.  You could give the following 
-options on your boot command:
+with unit ID number 36 connected to the parallel port at 0x378, a SyQuest
+EZ-135 connected to the chained port on the PD/CD drive and also an
+Imation Superdisk connected to port 0x278.  You could give the following
+options on your boot command::
 
 	pd.drive0=0x378,1 pf.drive0=0x278,1 pf.drive1=0x378,0,36
 
@@ -169,24 +179,27 @@ In the last option, pf.drive1 configures device /dev/pf1, the 0x378
 is the parallel port base address, the 0 is the protocol registration
 number and 36 is the chain ID.
 
-Please note:  while PARIDE will work both with and without the 
+Please note:  while PARIDE will work both with and without the
 PARPORT parallel port sharing system that is included by the
 "Parallel port support" option, PARPORT must be included and enabled
 if you want to use chains of devices on the same parallel port.
 
 2.2  Loading and configuring PARIDE as modules
+----------------------------------------------
 
 It is much faster and simpler to get to understand the PARIDE drivers
-if you use them as loadable kernel modules.   
+if you use them as loadable kernel modules.
 
-Note 1:  using these drivers with the "kerneld" automatic module loading
-system is not recommended for beginners, and is not documented here.  
+Note 1:
+	using these drivers with the "kerneld" automatic module loading
+	system is not recommended for beginners, and is not documented here.
 
-Note 2:  if you build PARPORT support as a loadable module, PARIDE must
-also be built as loadable modules, and PARPORT must be loaded before the
-PARIDE modules.
+Note 2:
+	if you build PARPORT support as a loadable module, PARIDE must
+	also be built as loadable modules, and PARPORT must be loaded before
+	the PARIDE modules.
 
-To use PARIDE, you must begin by 
+To use PARIDE, you must begin by::
 
 	insmod paride
 
@@ -195,8 +208,8 @@ among other tasks.
 
 Then, load as many of the protocol modules as you think you might need.
 As you load each module, it will register the protocols that it supports,
-and print a log message to your kernel log file and your console. For 
-example:
+and print a log message to your kernel log file and your console. For
+example::
 
 	# insmod epat
 	paride: epat registered as protocol 0
@@ -205,22 +218,22 @@ example:
         paride: k971 registered as protocol 2
 
 Finally, you can load high-level drivers for each kind of device that
-you have connected.  By default, each driver will autoprobe for a single 
+you have connected.  By default, each driver will autoprobe for a single
 device, but you can support up to four similar devices by giving their
 individual co-ordinates when you load the driver.
 
 For example, if you had two no-name CD-ROM drives both using the
 KingByte KBIC-951A adapter, one on port 0x378 and the other on 0x3bc
-you could give the following command:
+you could give the following command::
 
 	# insmod pcd drive0=0x378,1 drive1=0x3bc,1
 
 For most adapters, giving a port address and protocol number is sufficient,
-but check the source files in linux/drivers/block/paride for more 
+but check the source files in linux/drivers/block/paride for more
 information.  (Hopefully someone will write some man pages one day !).
 
 As another example, here's what happens when PARPORT is installed, and
-a SyQuest EZ-135 is attached to port 0x378:
+a SyQuest EZ-135 is attached to port 0x378::
 
 	# insmod paride
 	paride: version 1.0 installed
@@ -237,46 +250,47 @@ Note that the last line is the output from the generic partition table
 scanner - in this case it reports that it has found a disk with one partition.
 
 2.3  Using a PARIDE device
+--------------------------
 
 Once the drivers have been loaded, you can access PARIDE devices in the
 same way as their traditional counterparts.  You will probably need to
 create the device "special files".  Here is a simple script that you can
-cut to a file and execute:
-
-#!/bin/bash
-#
-# mkd -- a script to create the device special files for the PARIDE subsystem
-#
-function mkdev {
-  mknod $1 $2 $3 $4 ; chmod 0660 $1 ; chown root:disk $1
-}
-#
-function pd {
-  D=$( printf \\$( printf "x%03x" $[ $1 + 97 ] ) )
-  mkdev pd$D b 45 $[ $1 * 16 ]
-  for P in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
-  do mkdev pd$D$P b 45 $[ $1 * 16 + $P ]
-  done
-}
-#
-cd /dev
-#
-for u in 0 1 2 3 ; do pd $u ; done
-for u in 0 1 2 3 ; do mkdev pcd$u b 46 $u ; done 
-for u in 0 1 2 3 ; do mkdev pf$u  b 47 $u ; done 
-for u in 0 1 2 3 ; do mkdev pt$u  c 96 $u ; done 
-for u in 0 1 2 3 ; do mkdev npt$u c 96 $[ $u + 128 ] ; done 
-for u in 0 1 2 3 ; do mkdev pg$u  c 97 $u ; done 
-#
-# end of mkd
+cut to a file and execute::
+
+  #!/bin/bash
+  #
+  # mkd -- a script to create the device special files for the PARIDE subsystem
+  #
+  function mkdev {
+    mknod $1 $2 $3 $4 ; chmod 0660 $1 ; chown root:disk $1
+  }
+  #
+  function pd {
+    D=$( printf \\$( printf "x%03x" $[ $1 + 97 ] ) )
+    mkdev pd$D b 45 $[ $1 * 16 ]
+    for P in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
+    do mkdev pd$D$P b 45 $[ $1 * 16 + $P ]
+    done
+  }
+  #
+  cd /dev
+  #
+  for u in 0 1 2 3 ; do pd $u ; done
+  for u in 0 1 2 3 ; do mkdev pcd$u b 46 $u ; done
+  for u in 0 1 2 3 ; do mkdev pf$u  b 47 $u ; done
+  for u in 0 1 2 3 ; do mkdev pt$u  c 96 $u ; done
+  for u in 0 1 2 3 ; do mkdev npt$u c 96 $[ $u + 128 ] ; done
+  for u in 0 1 2 3 ; do mkdev pg$u  c 97 $u ; done
+  #
+  # end of mkd
 
 With the device files and drivers in place, you can access PARIDE devices
-like any other Linux device.   For example, to mount a CD-ROM in pcd0, use:
+like any other Linux device.   For example, to mount a CD-ROM in pcd0, use::
 
 	mount /dev/pcd0 /cdrom
 
 If you have a fresh Avatar Shark cartridge, and the drive is pda, you
-might do something like:
+might do something like::
 
 	fdisk /dev/pda		-- make a new partition table with
 				   partition 1 of type 83
@@ -289,41 +303,46 @@ might do something like:
 
 Devices like the Imation superdisk work in the same way, except that
 they do not have a partition table.  For example to make a 120MB
-floppy that you could share with a DOS system:
+floppy that you could share with a DOS system::
 
 	mkdosfs /dev/pf0
 	mount /dev/pf0 /mnt
 
 
 2.4  The pf driver
+------------------
 
 The pf driver is intended for use with parallel port ATAPI disk
 devices.  The most common devices in this category are PD drives
 and LS-120 drives.  Traditionally, media for these devices are not
 partitioned.  Consequently, the pf driver does not support partitioned
-media.  This may be changed in a future version of the driver. 
+media.  This may be changed in a future version of the driver.
 
 2.5  Using the pt driver
+------------------------
 
 The pt driver for parallel port ATAPI tape drives is a minimal driver.
-It does not yet support many of the standard tape ioctl operations. 
+It does not yet support many of the standard tape ioctl operations.
 For best performance, a block size of 32KB should be used.  You will
 probably want to set the parallel port delay to 0, if you can.
 
 2.6  Using the pg driver
+------------------------
 
 The pg driver can be used in conjunction with the cdrecord program
 to create CD-ROMs.  Please get cdrecord version 1.6.1 or later
-from ftp://ftp.fokus.gmd.de/pub/unix/cdrecord/ .  To record CD-R media 
-your parallel port should ideally be set to EPP mode, and the "port delay" 
-should be set to 0.  With those settings it is possible to record at 2x 
+from ftp://ftp.fokus.gmd.de/pub/unix/cdrecord/ .  To record CD-R media
+your parallel port should ideally be set to EPP mode, and the "port delay"
+should be set to 0.  With those settings it is possible to record at 2x
 speed without any buffer underruns.  If you cannot get the driver to work
 in EPP mode, try to use "bidirectional" or "PS/2" mode and 1x speeds only.
 
 
 3. Troubleshooting
+==================
 
 3.1  Use EPP mode if you can
+----------------------------
 
 The most common problems that people report with the PARIDE drivers
 concern the parallel port CMOS settings.  At this time, none of the
@@ -332,6 +351,7 @@ If you are able to do so, please set your parallel port into EPP mode
 using your CMOS setup procedure.
 
 3.2  Check the port delay
+-------------------------
 
 Some parallel ports cannot reliably transfer data at full speed.  To
 offset the errors, the PARIDE protocol modules introduce a "port
@@ -347,23 +367,25 @@ read the comments at the beginning of the driver source files in
 linux/drivers/block/paride.
 
 3.3  Some drives need a printer reset
+-------------------------------------
 
 There appear to be a number of "noname" external drives on the market
 that do not always power up correctly.  We have noticed this with some
 drives based on OnSpec and older Freecom adapters.  In these rare cases,
 the adapter can often be reinitialised by issuing a "printer reset" on
-the parallel port.  As the reset operation is potentially disruptive in 
-multiple device environments, the PARIDE drivers will not do it 
-automatically.  You can however, force a printer reset by doing:
+the parallel port.  As the reset operation is potentially disruptive in
+multiple device environments, the PARIDE drivers will not do it
+automatically.  You can however, force a printer reset by doing::
 
 	insmod lp reset=1
 	rmmod lp
 
 If you have one of these marginal cases, you should probably build
 your paride drivers as modules, and arrange to do the printer reset
-before loading the PARIDE drivers. 
+before loading the PARIDE drivers.
 
 3.4  Use the verbose option and dmesg if you need help
+------------------------------------------------------
 
 While a lot of testing has gone into these drivers to make them work
 as smoothly as possible, problems will arise.  If you do have problems,
@@ -373,7 +395,7 @@ clues, then please make sure that only one drive is hooked to your system,
 and that either (a) PARPORT is enabled or (b) no other device driver
 is using your parallel port (check in /proc/ioports).  Then, load the
 appropriate drivers (you can load several protocol modules if you want)
-as in:
+as in::
 
 	# insmod paride
 	# insmod epat
@@ -394,12 +416,14 @@ by e-mail to grant@torque.net, or join the linux-parport mailing list
 and post your report there.
 
 3.5  For more information or help
+---------------------------------
 
 You can join the linux-parport mailing list by sending a mail message
-to 
+to:
+
 		linux-parport-request@torque.net
 
-with the single word 
+with the single word::
 
 		subscribe
 
@@ -412,6 +436,4 @@ have in your mail headers, when sending mail to the list server.
 You might also find some useful information on the linux-parport
 web pages (although they are not always up to date) at
 
-	http://web.archive.org/web/*/http://www.torque.net/parport/
-
-
+	http://web.archive.org/web/%2E/http://www.torque.net/parport/
diff --git a/Documentation/blockdev/ramdisk.txt b/Documentation/blockdev/ramdisk.rst
index 501e12e0323e..b7c2268f8dec 100644
--- a/Documentation/blockdev/ramdisk.txt
+++ b/Documentation/blockdev/ramdisk.rst
@@ -1,7 +1,8 @@
+==========================================
 Using the RAM disk block device with Linux
-------------------------------------------
+==========================================
 
-Contents:
+.. Contents:
 
 	1) Overview
 	2) Kernel Command Line Parameters
@@ -42,7 +43,7 @@ rescue floppy disk.
 2a) Kernel Command Line Parameters
 
 	ramdisk_size=N
-	==============
+		Size of the ramdisk.
 
 This parameter tells the RAM disk driver to set up RAM disks of N k size.  The
 default is 4096 (4 MB).
@@ -50,16 +51,13 @@ default is 4096 (4 MB).
 2b) Module parameters
 
 	rd_nr
-	=====
-	/dev/ramX devices created.
+		/dev/ramX devices created.
 
 	max_part
-	========
-	Maximum partition number.
+		Maximum partition number.
 
 	rd_size
-	=======
-	See ramdisk_size.
+		See ramdisk_size.
 
 3) Using "rdev -r"
 ------------------
@@ -71,11 +69,11 @@ to 2 MB (2^11) of where to find the RAM disk (this used to be the size). Bit
 prompt/wait sequence is to be given before trying to read the RAM disk. Since
 the RAM disk dynamically grows as data is being written into it, a size field
 is not required. Bits 11 to 13 are not currently used and may as well be zero.
-These numbers are no magical secrets, as seen below:
+These numbers are no magical secrets, as seen below::
 
-./arch/x86/kernel/setup.c:#define RAMDISK_IMAGE_START_MASK     0x07FF
-./arch/x86/kernel/setup.c:#define RAMDISK_PROMPT_FLAG          0x8000
-./arch/x86/kernel/setup.c:#define RAMDISK_LOAD_FLAG            0x4000
+  ./arch/x86/kernel/setup.c:#define RAMDISK_IMAGE_START_MASK     0x07FF
+  ./arch/x86/kernel/setup.c:#define RAMDISK_PROMPT_FLAG          0x8000
+  ./arch/x86/kernel/setup.c:#define RAMDISK_LOAD_FLAG            0x4000
 
 Consider a typical two floppy disk setup, where you will have the
 kernel on disk one, and have already put a RAM disk image onto disk #2.
@@ -92,20 +90,23 @@ sequence so that you have a chance to switch floppy disks.
 The command line equivalent is: "prompt_ramdisk=1"
 
 Putting that together gives 2^15 + 2^14 + 0 = 49152 for an rdev word.
-So to create disk one of the set, you would do:
+So to create disk one of the set, you would do::
 
 	/usr/src/linux# cat arch/x86/boot/zImage > /dev/fd0
 	/usr/src/linux# rdev /dev/fd0 /dev/fd0
 	/usr/src/linux# rdev -r /dev/fd0 49152
 
-If you make a boot disk that has LILO, then for the above, you would use:
+If you make a boot disk that has LILO, then for the above, you would use::
+
 	append = "ramdisk_start=0 load_ramdisk=1 prompt_ramdisk=1"
-Since the default start = 0 and the default prompt = 1, you could use:
+
+Since the default start = 0 and the default prompt = 1, you could use::
+
 	append = "load_ramdisk=1"
 
 
 4) An Example of Creating a Compressed RAM Disk
-----------------------------------------------
+-----------------------------------------------
 
 To create a RAM disk image, you will need a spare block device to
 construct it on. This can be the RAM disk device itself, or an
@@ -120,11 +121,11 @@ a) Decide on the RAM disk size that you want. Say 2 MB for this example.
    Create it by writing to the RAM disk device. (This step is not currently
    required, but may be in the future.) It is wise to zero out the
    area (esp. for disks) so that maximal compression is achieved for
-   the unused blocks of the image that you are about to create.
+   the unused blocks of the image that you are about to create::
 
 	dd if=/dev/zero of=/dev/ram0 bs=1k count=2048
 
-b) Make a filesystem on it. Say ext2fs for this example.
+b) Make a filesystem on it. Say ext2fs for this example::
 
 	mke2fs -vm0 /dev/ram0 2048
 
@@ -133,11 +134,11 @@ c) Mount it, copy the files you want to it (eg: /etc/* /dev/* ...)
 
 d) Compress the contents of the RAM disk. The level of compression
    will be approximately 50% of the space used by the files. Unused
-   space on the RAM disk will compress to almost nothing.
+   space on the RAM disk will compress to almost nothing::
 
 	dd if=/dev/ram0 bs=1k count=2048 | gzip -v9 > /tmp/ram_image.gz
 
-e) Put the kernel onto the floppy
+e) Put the kernel onto the floppy::
 
 	dd if=zImage of=/dev/fd0 bs=1k
 
@@ -146,13 +147,13 @@ f) Put the RAM disk image onto the floppy, after the kernel. Use an offset
    (possibly larger) kernel onto the same floppy later without overlapping
    the RAM disk image. An offset of 400 kB for kernels about 350 kB in
    size would be reasonable. Make sure offset+size of ram_image.gz is
-   not larger than the total space on your floppy (usually 1440 kB).
+   not larger than the total space on your floppy (usually 1440 kB)::
 
 	dd if=/tmp/ram_image.gz of=/dev/fd0 bs=1k seek=400
 
 g) Use "rdev" to set the boot device, RAM disk offset, prompt flag, etc.
    For prompt_ramdisk=1, load_ramdisk=1, ramdisk_start=400, one would
-   have 2^15 + 2^14 + 400 = 49552.
+   have 2^15 + 2^14 + 400 = 49552::
 
 	rdev /dev/fd0 /dev/fd0
 	rdev -r /dev/fd0 49552
@@ -160,15 +161,17 @@ g) Use "rdev" to set the boot device, RAM disk offset, prompt flag, etc.
 That is it. You now have your boot/root compressed RAM disk floppy. Some
 users may wish to combine steps (d) and (f) by using a pipe.
 
-----------------