Convert more books to ReST

This patch series convert the following books to ReST:
- librs
- mtdnand
- sh

And it is based on my previous series of conversion patches.

After this series, there will be just one DocBook pending conversion:
- lsm (Linux Security Modules)

This book is very outdated: no changes since the Kernel moved to git, in 2005 (except for a minor editorial fix in 2008).

I took a look on the described API: it doesn't seem to be describing the current security implementation.

The best here is if someone that works with LSM to convert it to ReST with:

	$ Documentation/sphinx/tmplcvt Documentation/DocBook/lsm.tmpl lsm.rst

And fix the document to produce something that reflects the current implementation. If nobody is interested, then maybe we could just drop it.

-

This patch series is based on my past 00/36 patch series, applied on the top of docs tree (next branch).

The full patch series is on this tree is at:

https://git.linuxtv.org//mchehab/experimental.git/log/?h=docbook

And the HTML output at:

http://www.infradead.org/~mchehab/kernel_docs/
https://mchehab.fedorapeople.org/kernel_docs/

Mauro Carvalho Chehab (5):
docs-rst: convert librs book to ReST
docs-rst: convert mtdnand book to ReST
mtdnand.rst: Fix some typos and group the "::" with previous line
mtd: adjust kernel-docs to avoid Sphinx/kerneldoc warnings
docs-rst: convert sh book to ReST

 Documentation/DocBook/Makefile       |    5 +-
 Documentation/DocBook/librs.tmpl     |  289 --------
 Documentation/DocBook/mtdnand.tmpl   | 1291 ----------------------------------
 Documentation/DocBook/sh.tmpl        |  105 ---
 Documentation/conf.py                |    2 +
 Documentation/core-api/index.rst     |    1 +
 Documentation/core-api/librs.rst     |  212 ++++++
 Documentation/driver-api/index.rst   |    1 +
 Documentation/driver-api/mtdnand.rst | 1007 ++++++++++++++++++++++++++
 Documentation/index.rst              |   11 +
 Documentation/sh/index.rst           |   59 ++
 drivers/mtd/nand/nand_base.c         |    7 +-
 include/linux/mtd/nand.h             |    2 +-
 13 files changed, 1300 insertions(+), 1692 deletions(-)
 delete mode 100644 Documentation/DocBook/librs.tmpl
 delete mode 100644 Documentation/DocBook/mtdnand.tmpl
 delete mode 100644 Documentation/DocBook/sh.tmpl
 create mode 100644 Documentation/core-api/librs.rst
 create mode 100644 Documentation/driver-api/mtdnand.rst
 create mode 100644 Documentation/sh/index.rst

2.9.3


--
To unsubscribe from this list: send the line "unsubscribe linux-security-module" in
the body of a message to majordomo at vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Use pandoc to convert documentation to ReST by calling Documentation/sphinx/tmplcvt script.

---
 Documentation/DocBook/Makefile   |   2 +-
 Documentation/DocBook/librs.tmpl | 289 ---------------------------------------
 Documentation/core-api/index.rst |   1 +
 Documentation/core-api/librs.rst | 212 ++++++++++++++++++++++++++++
 4 files changed, 214 insertions(+), 290 deletions(-)
 delete mode 100644 Documentation/DocBook/librs.tmpl
 create mode 100644 Documentation/core-api/librs.rst

index baedb14f3b40..0a82f6253682 100644
@@ -8,7 +8,7 @@
 
 DOCBOOKS := \
 	    lsm.xml \
-	    mtdnand.xml librs.xml \
+	    mtdnand.xml \
 	    sh.xml
 
 ifeq ($(DOCBOOKS),)

index 62abd36bfffb..0606be3a3111 100644
@@ -19,6 +19,7 @@ Core utilities
    workqueue
    genericirq
    flexible-arrays
+   librs
 
 Interfaces for kernel debugging
 ===============================

2.9.3

Use pandoc to convert documentation to ReST by calling Documentation/sphinx/tmplcvt script.

The tables were manually adjusted to fit into 80 columns.

---
 Documentation/DocBook/Makefile       |    1 -
 Documentation/DocBook/mtdnand.tmpl   | 1291 ----------------------------------
 Documentation/driver-api/index.rst   |    1 +
 Documentation/driver-api/mtdnand.rst | 1020 +++++++++++++++++++++++++++
 4 files changed, 1021 insertions(+), 1292 deletions(-)
 delete mode 100644 Documentation/DocBook/mtdnand.tmpl
 create mode 100644 Documentation/driver-api/mtdnand.rst

index 0a82f6253682..226e5e9fc801 100644
@@ -8,7 +8,6 @@
 
 DOCBOOKS := \
 	    lsm.xml \
-	    mtdnand.xml \
 	    sh.xml
 
 ifeq ($(DOCBOOKS),)

index 1f8517db39c7..3cf1acebc4ee 100644
@@ -34,6 +34,7 @@ available subsections can be seen below.
    edac
    scsi
    libata
+   mtdnand
    miscellaneous
    w1
    rapidio

2.9.3

Typo:

	ored -> ordered

While here, group the :: with the previous paragraph, in order to make it visually better when reading as a text file.

---
 Documentation/driver-api/mtdnand.rst | 24 +++++++-----------------
 1 file changed, 7 insertions(+), 17 deletions(-)

index 8723175f955e..e670f8b15a79 100644
@@ -843,10 +843,8 @@ Chip option constants
 Constants for chip id table
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-These constants are defined in nand.h. They are ored together to
-describe the chip functionality.
-
-::
+These constants are defined in nand.h. They are ordered together to
+describe the chip functionality::
 
     /* Buswitdh is 16 bit */
     #define NAND_BUSWIDTH_16    0x00000002

@@ -867,10 +865,8 @@ describe the chip functionality.
 Constants for runtime options
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-These constants are defined in nand.h. They are ored together to
-describe the functionality.
-
-::
+These constants are defined in nand.h. They are ordered together to
+describe the functionality::
 
     /* The hw ecc generator provides a syndrome instead a ecc value on read
      * This can only work if we have the ecc bytes directly behind the

@@ -881,9 +877,7 @@ describe the functionality.
 ECC selection constants
 -----------------------
 
-Use these constants to select the ECC algorithm.
-
-::
+Use these constants to select the ECC algorithm::
 
     /* No ECC. Usage is not recommended ! */
     #define NAND_ECC_NONE       0

@@ -903,9 +897,7 @@ Hardware control related constants
 ----------------------------------
 
 These constants describe the requested hardware access function when the
-boardspecific hardware control function is called
-
-::
+boardspecific hardware control function is called::
 
     /* Select the chip by setting nCE to low */
     #define NAND_CTL_SETNCE     1

@@ -929,9 +921,7 @@ Bad block table related constants
 ---------------------------------
 
 These constants describe the options used for bad block table
-descriptors.
-
-::
+descriptors::
 
     /* Options for the bad block table descriptors */
 

2.9.3

./drivers/mtd/nand/nand_bbt.c:1: warning: no structured comments found ./include/linux/mtd/nand.h:785: ERROR: Unexpected indentation. ./drivers/mtd/nand/nand_base.c:449: WARNING: Definition list ends without a blank line; unexpected unindent. ./drivers/mtd/nand/nand_base.c:1161: ERROR: Unexpected indentation. ./drivers/mtd/nand/nand_base.c:1162: WARNING: Block quote ends without a blank line; unexpected unindent.

---
 Documentation/driver-api/mtdnand.rst | 3 ---
 drivers/mtd/nand/nand_base.c         | 7 +++++--
 include/linux/mtd/nand.h             | 2 +-
 3 files changed, 6 insertions(+), 6 deletions(-)

index e670f8b15a79..4fe3bf00299b 100644
@@ -970,9 +970,6 @@ hints" for an explanation.
 .. kernel-doc:: drivers/mtd/nand/nand_base.c
    :export:
 
-.. kernel-doc:: drivers/mtd/nand/nand_bbt.c
-   :export:
-
 .. kernel-doc:: drivers/mtd/nand/nand_ecc.c
    :export:
 

index b0524f8accb6..c8988c01e0d7 100644
@@ -442,10 +442,12 @@ static int nand_default_block_markbad(struct mtd_info *mtd, loff_t ofs)
  * specify how to write bad block markers to OOB (chip->block_markbad).
  *
  * We try operations in the following order:
+ *
  *  (1) erase the affected block, to allow OOB marker to be written cleanly
  *  (2) write bad block marker to OOB area of affected block (unless flag
  *      NAND_BBT_NO_OOB_BBM is present)
  *  (3) update the BBT
+ *
  * Note that we retain the first error encountered in (2) or (3), finish the
  * procedures, and dump the error in the end.
 */

@@ -1155,9 +1157,10 @@ int nand_reset(struct nand_chip *chip, int chipnr)
  * @mtd: mtd info
  * @ofs: offset to start unlock from
  * @len: length to unlock
- * @invert: when = 0, unlock the range of blocks within the lower and
+ * @invert:
+ *        - when = 0, unlock the range of blocks within the lower and
  *                    upper boundary address
- *          when = 1, unlock the range of blocks outside the boundaries
+ *        - when = 1, unlock the range of blocks outside the boundaries
  *                    of the lower and upper boundary address
  *
  * Returs unlock status.

index 9591e0fbe5bd..3d5b20379ba3 100644
@@ -779,7 +779,7 @@ nand_get_sdr_timings(const struct nand_data_interface *conf)
  *			Minimum amount of bit errors per @ecc_step_ds guaranteed
  *			to be correctable. If unknown, set to zero.
  * @ecc_step_ds:	[INTERN] ECC step required by the @ecc_strength_ds,
- *                      also from the datasheet. It is the recommended ECC step
+ *			also from the datasheet. It is the recommended ECC step
  *			size, if known; if unknown, set to zero.
  * @onfi_timing_mode_default: [INTERN] default ONFI timing mode. This field is
  *			      set to the actually used ONFI mode if the chip is

2.9.3

Use pandoc to convert documentation to ReST by calling Documentation/sphinx/tmplcvt script.

---
 Documentation/DocBook/Makefile |   4 +-
 Documentation/DocBook/sh.tmpl  | 105 -----------------------------------------
 Documentation/conf.py          |   2 +
 Documentation/index.rst        |  11 +++++
 Documentation/sh/index.rst     |  59 +++++++++++++++++++++++
 5 files changed, 73 insertions(+), 108 deletions(-)
 delete mode 100644 Documentation/DocBook/sh.tmpl
 create mode 100644 Documentation/sh/index.rst

index 226e5e9fc801..efba7f980895 100644
@@ -6,9 +6,7 @@
 # To add a new book the only step required is to add the book to the
 # list of DOCBOOKS.
 
-DOCBOOKS := \
-	    lsm.xml \
-	    sh.xml
+DOCBOOKS := lsm.xml
 
 ifeq ($(DOCBOOKS),)
 

index dfe14f7525d0..77d47bb1df1d 100644
@@ -375,6 +375,8 @@ latex_documents = [
      'The kernel development community', 'manual'),
     ('security/index', 'security.tex', 'The kernel security subsystem manual',
      'The kernel development community', 'manual'),
+    ('sh/index', 'sh.tex', 'SuperH architecture implementation manual',
+     'The kernel development community', 'manual'),
     ('sound/index', 'sound.tex', 'Linux Sound Subsystem Documentation',
      'The kernel development community', 'manual'),
     ('userspace-api/index', 'userspace-api.tex', 'The Linux kernel user-space API guide',

index 25c4da41da6b..e9017bb3a6ce 100644
@@ -76,6 +76,17 @@ needed).
    crypto/index
    filesystems/index
 
+Architecture-specific documentation
+-----------------------------------
+
+These books provide programming details about architecture-specific
+implementation.
+
+.. toctree::
+   :maxdepth: 2
+
+   sh/index
+
 Korean translations
 -------------------
 

2.9.3

MTD maintainers did not receive the above patch. Can you Cc us the whole series next time.

BTW, I had a look at your branch and it seems the typo you're fixing is actually not a type. Flags are *OR-ed* (with the | operator) to form a valid combination of flags.

Not sure how you plan to merge these changes, but if it goes through a single tree I'll probably need an immutable topic branch, because I plan to change a few things in nand_base.c nand.h for the next release.

--
To unsubscribe from this list: send the line "unsubscribe linux-security-module" in the body of a message to majordomo at vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html

docs-next doesn't rebase, so there shouldn't be trouble there. But we could also just separate this patch into two pieces. I suspect we could live with a couple of warnings for a period during the 4.13 merge window without too much pain...

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-security-module" in the body of a message to majordomo at vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html

Hi Jonathan,

I like this idea. This way I can take the nand_base.c/nand.h changes through my tree and let you pick the Doc migration bits.

Thanks,

Boris
--
To unsubscribe from this list: send the line "unsubscribe linux-security-module" in the body of a message to majordomo at vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html

Em Mon, 15 May 2017 14:09:12 +0200
Boris Brezillon <[email protected]> escreveu:

Sorry. I'll add you on the whole series. It will be a big one, though, as it will contain the other docbook conversions on it (~50+ patches).

Ah! Ok, I updated the patch (see enclosed). Would that be OK for you?

At least the patches that touch at Documentation/* should go, IMHO, via a single tree:
git://git.lwn.net/linux.git docs-next

As Jon mentioned, he doesn't rebase it, so you should be able to get an immutable branch from it.

Thanks,
Mauro

---

[PATCH] mtdnand.rst: group the "::" with previous line

Group the :: with the previous paragraph, in order to make it visually better when reading as a text file.

While here, replace:
ored (with means "Covered or adorned with ore or metal")
by:
OR-ed

To reflect its true meaning.

index 8723175f955e..7c19795ebb4a 100644
@@ -843,10 +843,8 @@ Chip option constants
 Constants for chip id table
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-These constants are defined in nand.h. They are ored together to
-describe the chip functionality.
-
-::
+These constants are defined in nand.h. They are OR-ed together to
+describe the chip functionality::
 
     /* Buswitdh is 16 bit */
     #define NAND_BUSWIDTH_16    0x00000002

@@ -867,10 +865,8 @@ describe the chip functionality.
 Constants for runtime options
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-These constants are defined in nand.h. They are ored together to
-describe the functionality.
-
-::
+These constants are defined in nand.h. They are OR-ed together to
+describe the functionality::
 
     /* The hw ecc generator provides a syndrome instead a ecc value on read
      * This can only work if we have the ecc bytes directly behind the

@@ -881,9 +877,7 @@ describe the functionality.
 ECC selection constants
 -----------------------
 
-Use these constants to select the ECC algorithm.
-
-::
+Use these constants to select the ECC algorithm::
 
     /* No ECC. Usage is not recommended ! */
     #define NAND_ECC_NONE       0

@@ -903,9 +897,7 @@ Hardware control related constants
 ----------------------------------
 
 These constants describe the requested hardware access function when the
-boardspecific hardware control function is called
-
-::
+boardspecific hardware control function is called::
 
     /* Select the chip by setting nCE to low */
     #define NAND_CTL_SETNCE     1

@@ -929,9 +921,7 @@ Bad block table related constants
 ---------------------------------
 
 These constants describe the options used for bad block table
-descriptors.
-
-::
+descriptors::
 
     /* Options for the bad block table descriptors */
 

--
To unsubscribe from this list: send the line "unsubscribe linux-security-module" in the body of a message to majordomo at vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html