[PATCH 00/36] Convert DocBook documents to ReST

[PATCH 00/36] Convert DocBook documents to ReST

[Mauro Carvalho Chehab]

This patch series convert the following books from
DocBook to ReST:

   - filesystems
   - kernel-hacking
   - kernel-locking
   - kgdb
   - libata
   - networking
   - rapidio
   - s390-drivers
   - scsi
   - w1
   - z8530book

It also adjusts some Sphinx-pedantic errors/warnings on
some kernel-doc markups.

I also added some patches here to add PDF output for all
existing ReST books.

I did my best to check if what's there is not too outdated, but
the best is if the subsystem maintainers could check it.

After this series, there are only 4 DocBook remaining conversion:
   - librs
   - lsm
   - mtdnand
   - sh

I'll likely convert those remaining ones during this weekend.

-

This patch series is based on docs tree (next branch).
The full patch series is on this tree:

   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 (36):
  docs-rst: convert kernel-hacking to ReST
  kernel-hacking: update document
  docs-rst: convert kernel-locking to ReST
  mutex, futex: adjust kernel-doc markups to generate ReST
  locking.rst: reformat locking table
  locking.rst: add captions to two tables
  locking.rst: Update some ReST markups
  docs-rst: convert kgdb DocBook to ReST
  kgdb.rst: Adjust ReST markups
  conf.py: define a color for important markup on PDF output
  docs-rst: conf.py: sort LaTeX documents in alphabetical order
  docs-rst: conf.py: remove kernel-documentation from LaTeX
  docs-rst: add crypto API book to pdf output
  docs-rst: add dev-tools book to pdf output
  docs-rst: add sound book to pdf output
  docs-rst: add userspace API book to pdf output
  docs-rst: convert filesystems book to ReST
  docs-rst: filesystems: use c domain references where needed
  fs: jbd2: make jbd2_journal_start() kernel-doc parseable
  docs-rst: don't ignore internal functions for jbd2 docs
  fs: locks: Fix some troubles at kernel-doc comments
  fs: add a blank lines on some kernel-doc comments
  fs: eventfd: fix identation on kernel-doc
  fs: jbd2: escape a string with special chars on a kernel-doc
  docs-rst: convert libata book to ReST
  libata.rst: add c function and struct cross-references
  libata: fix identation on a kernel-doc markup
  docs-rst: convert s390-drivers DocBook to ReST
  docs-rst: convert networking book to ReST
  net: skbuff.h: properly escape a macro name on kernel-doc
  net: fix some identation issues at kernel-doc markups
  docs-rst: convert z8530book DocBook to ReST
  docs-rst: convert scsi DocBook to ReST
  scsi: fix some kernel-doc markups
  docs-rst: convert w1 book to ReST
  docs-rst: convert rapidio book to ReST

 Documentation/DocBook/Makefile            |   11 +-
 Documentation/DocBook/filesystems.tmpl    |  381 -----
 Documentation/DocBook/kernel-hacking.tmpl | 1312 ------------------
 Documentation/DocBook/kernel-locking.tmpl | 2151 -----------------------------
 Documentation/DocBook/kgdb.tmpl           |  918 ------------
 Documentation/DocBook/libata.tmpl         | 1625 ----------------------
 Documentation/DocBook/networking.tmpl     |  111 --
 Documentation/DocBook/rapidio.tmpl        |  155 ---
 Documentation/DocBook/s390-drivers.tmpl   |  161 ---
 Documentation/DocBook/scsi.tmpl           |  409 ------
 Documentation/DocBook/w1.tmpl             |  101 --
 Documentation/DocBook/z8530book.tmpl      |  371 -----
 Documentation/conf.py                     |   35 +-
 Documentation/crypto/conf.py              |   10 +
 Documentation/dev-tools/index.rst         |    1 +
 Documentation/dev-tools/kgdb.rst          |  907 ++++++++++++
 Documentation/driver-api/index.rst        |    5 +
 Documentation/driver-api/libata.rst       | 1031 ++++++++++++++
 Documentation/driver-api/rapidio.rst      |  107 ++
 Documentation/driver-api/s390-drivers.rst |  111 ++
 Documentation/driver-api/scsi.rst         |  344 +++++
 Documentation/driver-api/w1.rst           |   70 +
 Documentation/filesystems/conf.py         |   10 +
 Documentation/filesystems/index.rst       |  317 +++++
 Documentation/index.rst                   |    3 +
 Documentation/kernel-hacking/conf.py      |   10 +
 Documentation/kernel-hacking/hacking.rst  |  811 +++++++++++
 Documentation/kernel-hacking/index.rst    |    5 +
 Documentation/kernel-hacking/locking.rst  | 1446 +++++++++++++++++++
 Documentation/networking/conf.py          |   10 +
 Documentation/networking/index.rst        |   18 +
 Documentation/networking/kapi.rst         |  147 ++
 Documentation/networking/z8530book.rst    |  256 ++++
 Documentation/sound/conf.py               |   10 +
 drivers/ata/libata-scsi.c                 |    7 +-
 drivers/net/phy/phy.c                     |    1 +
 drivers/scsi/scsi_scan.c                  |    7 +-
 drivers/scsi/scsi_transport_fc.c          |   18 +-
 drivers/scsi/scsicam.c                    |    4 +-
 fs/eventfd.c                              |    4 +-
 fs/fs-writeback.c                         |   12 +-
 fs/jbd2/transaction.c                     |   42 +-
 fs/locks.c                                |   18 +-
 fs/mpage.c                                |    1 +
 fs/namei.c                                |    1 +
 include/linux/mutex.h                     |    6 +-
 include/linux/netdevice.h                 |    9 +-
 include/linux/skbuff.h                    |    2 +-
 include/net/sock.h                        |    9 +-
 kernel/futex.c                            |   40 +-
 kernel/locking/mutex.c                    |    6 +-
 net/core/datagram.c                       |    2 +-
 net/core/sock.c                           |    7 +-
 53 files changed, 5764 insertions(+), 7802 deletions(-)
 delete mode 100644 Documentation/DocBook/filesystems.tmpl
 delete mode 100644 Documentation/DocBook/kernel-hacking.tmpl
 delete mode 100644 Documentation/DocBook/kernel-locking.tmpl
 delete mode 100644 Documentation/DocBook/kgdb.tmpl
 delete mode 100644 Documentation/DocBook/libata.tmpl
 delete mode 100644 Documentation/DocBook/networking.tmpl
 delete mode 100644 Documentation/DocBook/rapidio.tmpl
 delete mode 100644 Documentation/DocBook/s390-drivers.tmpl
 delete mode 100644 Documentation/DocBook/scsi.tmpl
 delete mode 100644 Documentation/DocBook/w1.tmpl
 delete mode 100644 Documentation/DocBook/z8530book.tmpl
 create mode 100644 Documentation/crypto/conf.py
 create mode 100644 Documentation/dev-tools/kgdb.rst
 create mode 100644 Documentation/driver-api/libata.rst
 create mode 100644 Documentation/driver-api/rapidio.rst
 create mode 100644 Documentation/driver-api/s390-drivers.rst
 create mode 100644 Documentation/driver-api/scsi.rst
 create mode 100644 Documentation/driver-api/w1.rst
 create mode 100644 Documentation/filesystems/conf.py
 create mode 100644 Documentation/filesystems/index.rst
 create mode 100644 Documentation/kernel-hacking/conf.py
 create mode 100644 Documentation/kernel-hacking/hacking.rst
 create mode 100644 Documentation/kernel-hacking/index.rst
 create mode 100644 Documentation/kernel-hacking/locking.rst
 create mode 100644 Documentation/networking/conf.py
 create mode 100644 Documentation/networking/index.rst
 create mode 100644 Documentation/networking/kapi.rst
 create mode 100644 Documentation/networking/z8530book.rst
 create mode 100644 Documentation/sound/conf.py

-- 
2.9.3

[PATCH 21/36] fs: locks: Fix some troubles at kernel-doc comments

[Mauro Carvalho Chehab]

There are a few syntax violations that cause outputs of
a few comments to not be properly parsed in ReST format.

No functional changes.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 fs/locks.c | 18 ++++++++----------
 1 file changed, 8 insertions(+), 10 deletions(-)

diff --git a/fs/locks.c b/fs/locks.c
index 26811321d39b..bdce708e4251 100644
--- a/fs/locks.c
+++ b/fs/locks.c
@@ -1858,8 +1858,8 @@ EXPORT_SYMBOL(generic_setlease);
  *
  * Call this to establish a lease on the file. The "lease" argument is not
  * used for F_UNLCK requests and may be NULL. For commands that set or alter
- * an existing lease, the (*lease)->fl_lmops->lm_break operation must be set;
- * if not, this function will return -ENOLCK (and generate a scary-looking
+ * an existing lease, the ``(*lease)->fl_lmops->lm_break`` operation must be
+ * set; if not, this function will return -ENOLCK (and generate a scary-looking
  * stack trace).
  *
  * The "priv" pointer is passed directly to the lm_setup function as-is. It
@@ -1972,15 +1972,13 @@ EXPORT_SYMBOL(locks_lock_inode_wait);
  *	@cmd: the type of lock to apply.
  *
  *	Apply a %FL_FLOCK style lock to an open file descriptor.
- *	The @cmd can be one of
+ *	The @cmd can be one of:
  *
- *	%LOCK_SH -- a shared lock.
- *
- *	%LOCK_EX -- an exclusive lock.
- *
- *	%LOCK_UN -- remove an existing lock.
- *
- *	%LOCK_MAND -- a `mandatory' flock.  This exists to emulate Windows Share Modes.
+ *	- %LOCK_SH -- a shared lock.
+ *	- %LOCK_EX -- an exclusive lock.
+ *	- %LOCK_UN -- remove an existing lock.
+ *	- %LOCK_MAND -- a 'mandatory' flock.
+ *	  This exists to emulate Windows Share Modes.
  *
  *	%LOCK_MAND can be combined with %LOCK_READ or %LOCK_WRITE to allow other
  *	processes read and write access respectively.
-- 
2.9.3

[PATCH 22/36] fs: add a blank lines on some kernel-doc comments

[Mauro Carvalho Chehab]

Sphinx gets confused when it finds identation without a
good reason for it and without a preceding blank line:

	./fs/mpage.c:347: ERROR: Unexpected indentation.
	./fs/namei.c:4303: ERROR: Unexpected indentation.
	./fs/fs-writeback.c:2060: ERROR: Unexpected indentation.

No functional changes.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 fs/fs-writeback.c | 12 +++++++-----
 fs/mpage.c        |  1 +
 fs/namei.c        |  1 +
 3 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/fs/fs-writeback.c b/fs/fs-writeback.c
index 63ee2940775c..8b426f83909f 100644
--- a/fs/fs-writeback.c
+++ b/fs/fs-writeback.c
@@ -2052,11 +2052,13 @@ static noinline void block_dump___mark_inode_dirty(struct inode *inode)
 }
 
 /**
- *	__mark_inode_dirty -	internal function
- *	@inode: inode to mark
- *	@flags: what kind of dirty (i.e. I_DIRTY_SYNC)
- *	Mark an inode as dirty. Callers should use mark_inode_dirty or
- *  	mark_inode_dirty_sync.
+ * __mark_inode_dirty -	internal function
+ *
+ * @inode: inode to mark
+ * @flags: what kind of dirty (i.e. I_DIRTY_SYNC)
+ *
+ * Mark an inode as dirty. Callers should use mark_inode_dirty or
+ * mark_inode_dirty_sync.
  *
  * Put the inode on the super block's dirty list.
  *
diff --git a/fs/mpage.c b/fs/mpage.c
index baff8f820c29..4760a0c09a4e 100644
--- a/fs/mpage.c
+++ b/fs/mpage.c
@@ -344,6 +344,7 @@ do_mpage_readpage(struct bio *bio, struct page *page, unsigned nr_pages,
  *
  * So an mpage read of the first 16 blocks of an ext2 file will cause I/O to be
  * submitted in the following order:
+ *
  * 	12 0 1 2 3 4 5 6 7 8 9 10 11 13 14 15 16
  *
  * because the indirect block has to be read to get the mappings of blocks
diff --git a/fs/namei.c b/fs/namei.c
index 7286f87ce863..b5af8228e2d9 100644
--- a/fs/namei.c
+++ b/fs/namei.c
@@ -4300,6 +4300,7 @@ SYSCALL_DEFINE2(link, const char __user *, oldname, const char __user *, newname
  * The worst of all namespace operations - renaming directory. "Perverted"
  * doesn't even start to describe it. Somebody in UCB had a heck of a trip...
  * Problems:
+ *
  *	a) we can get into loop creation.
  *	b) race potential - two innocent renames can create a loop together.
  *	   That's where 4.4 screws up. Current fix: serialization on
-- 
2.9.3

[PATCH 23/36] fs: eventfd: fix identation on kernel-doc

[Mauro Carvalho Chehab]

Sphinx require explicit tags in order to use a list of possible
values, otherwise it produces this error:

	./fs/eventfd.c:219: WARNING: Option list ends without a blank line; unexpected unindent.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 fs/eventfd.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/fs/eventfd.c b/fs/eventfd.c
index 68b9fffcb2c8..beac8175de19 100644
--- a/fs/eventfd.c
+++ b/fs/eventfd.c
@@ -215,8 +215,8 @@ EXPORT_SYMBOL_GPL(eventfd_ctx_remove_wait_queue);
  *
  * Returns %0 if successful, or the following error codes:
  *
- * -EAGAIN      : The operation would have blocked but @no_wait was non-zero.
- * -ERESTARTSYS : A signal interrupted the wait operation.
+ *  - -EAGAIN      : The operation would have blocked but @no_wait was non-zero.
+ *  - -ERESTARTSYS : A signal interrupted the wait operation.
  *
  * If @no_wait is zero, the function might sleep until the eventfd internal
  * counter becomes greater than zero.
-- 
2.9.3

Re: [PATCH 21/36] fs: locks: Fix some troubles at kernel-doc comments

[Jeff Layton]

On Fri, 2017-05-12 at 11:00 -0300, Mauro Carvalho Chehab wrote:
> There are a few syntax violations that cause outputs of
> a few comments to not be properly parsed in ReST format.
> 
> No functional changes.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
>  fs/locks.c | 18 ++++++++----------
>  1 file changed, 8 insertions(+), 10 deletions(-)
> 
> diff --git a/fs/locks.c b/fs/locks.c
> index 26811321d39b..bdce708e4251 100644
> --- a/fs/locks.c
> +++ b/fs/locks.c
> @@ -1858,8 +1858,8 @@ EXPORT_SYMBOL(generic_setlease);
>   *
>   * Call this to establish a lease on the file. The "lease" argument is not
>   * used for F_UNLCK requests and may be NULL. For commands that set or alter
> - * an existing lease, the (*lease)->fl_lmops->lm_break operation must be set;
> - * if not, this function will return -ENOLCK (and generate a scary-looking
> + * an existing lease, the ``(*lease)->fl_lmops->lm_break`` operation must be
> + * set; if not, this function will return -ENOLCK (and generate a scary-looking
>   * stack trace).
>   *
>   * The "priv" pointer is passed directly to the lm_setup function as-is. It
> @@ -1972,15 +1972,13 @@ EXPORT_SYMBOL(locks_lock_inode_wait);
>   *	@cmd: the type of lock to apply.
>   *
>   *	Apply a %FL_FLOCK style lock to an open file descriptor.
> - *	The @cmd can be one of
> + *	The @cmd can be one of:
>   *
> - *	%LOCK_SH -- a shared lock.
> - *
> - *	%LOCK_EX -- an exclusive lock.
> - *
> - *	%LOCK_UN -- remove an existing lock.
> - *
> - *	%LOCK_MAND -- a `mandatory' flock.  This exists to emulate Windows Share Modes.
> + *	- %LOCK_SH -- a shared lock.
> + *	- %LOCK_EX -- an exclusive lock.
> + *	- %LOCK_UN -- remove an existing lock.
> + *	- %LOCK_MAND -- a 'mandatory' flock.
> + *	  This exists to emulate Windows Share Modes.
>   *
>   *	%LOCK_MAND can be combined with %LOCK_READ or %LOCK_WRITE to allow other
>   *	processes read and write access respectively.

LGTM. Do you need me or Bruce to pick this one up?

Reviewed-by: Jeff Layton <jlayton@poochiereds.net>

Re: [PATCH 21/36] fs: locks: Fix some troubles at kernel-doc comments

[Mauro Carvalho Chehab]

Hi Jeff,

Em Fri, 12 May 2017 10:02:56 -0400
Jeff Layton <jlayton@poochiereds.net> escreveu:

> On Fri, 2017-05-12 at 11:00 -0300, Mauro Carvalho Chehab wrote:
> > There are a few syntax violations that cause outputs of
> > a few comments to not be properly parsed in ReST format.
> > 
> > No functional changes.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > ---
> >  fs/locks.c | 18 ++++++++----------
> >  1 file changed, 8 insertions(+), 10 deletions(-)
> > 
> > diff --git a/fs/locks.c b/fs/locks.c
> > index 26811321d39b..bdce708e4251 100644
> > --- a/fs/locks.c
> > +++ b/fs/locks.c
> > @@ -1858,8 +1858,8 @@ EXPORT_SYMBOL(generic_setlease);
> >   *
> >   * Call this to establish a lease on the file. The "lease" argument is not
> >   * used for F_UNLCK requests and may be NULL. For commands that set or alter
> > - * an existing lease, the (*lease)->fl_lmops->lm_break operation must be set;
> > - * if not, this function will return -ENOLCK (and generate a scary-looking
> > + * an existing lease, the ``(*lease)->fl_lmops->lm_break`` operation must be
> > + * set; if not, this function will return -ENOLCK (and generate a scary-looking
> >   * stack trace).
> >   *
> >   * The "priv" pointer is passed directly to the lm_setup function as-is. It
> > @@ -1972,15 +1972,13 @@ EXPORT_SYMBOL(locks_lock_inode_wait);
> >   *	@cmd: the type of lock to apply.
> >   *
> >   *	Apply a %FL_FLOCK style lock to an open file descriptor.
> > - *	The @cmd can be one of
> > + *	The @cmd can be one of:
> >   *
> > - *	%LOCK_SH -- a shared lock.
> > - *
> > - *	%LOCK_EX -- an exclusive lock.
> > - *
> > - *	%LOCK_UN -- remove an existing lock.
> > - *
> > - *	%LOCK_MAND -- a `mandatory' flock.  This exists to emulate Windows Share Modes.
> > + *	- %LOCK_SH -- a shared lock.
> > + *	- %LOCK_EX -- an exclusive lock.
> > + *	- %LOCK_UN -- remove an existing lock.
> > + *	- %LOCK_MAND -- a 'mandatory' flock.
> > + *	  This exists to emulate Windows Share Modes.
> >   *
> >   *	%LOCK_MAND can be combined with %LOCK_READ or %LOCK_WRITE to allow other
> >   *	processes read and write access respectively.  
> 
> LGTM. Do you need me or Bruce to pick this one up?

Feel free to pick it, if it works best for you.

> Reviewed-by: Jeff Layton <jlayton@poochiereds.net>


Thanks,
Mauro

Re: [PATCH 21/36] fs: locks: Fix some troubles at kernel-doc comments

[J. Bruce Fields]

On Sat, May 13, 2017 at 06:14:06AM -0300, Mauro Carvalho Chehab wrote:
> Hi Jeff,
> 
> Em Fri, 12 May 2017 10:02:56 -0400
> Jeff Layton <jlayton@poochiereds.net> escreveu:
> 
> > On Fri, 2017-05-12 at 11:00 -0300, Mauro Carvalho Chehab wrote:
> > > There are a few syntax violations that cause outputs of
> > > a few comments to not be properly parsed in ReST format.
> > > 
> > > No functional changes.
> > > 
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > > ---
> > >  fs/locks.c | 18 ++++++++----------
> > >  1 file changed, 8 insertions(+), 10 deletions(-)
> > > 
> > > diff --git a/fs/locks.c b/fs/locks.c
> > > index 26811321d39b..bdce708e4251 100644
> > > --- a/fs/locks.c
> > > +++ b/fs/locks.c
> > > @@ -1858,8 +1858,8 @@ EXPORT_SYMBOL(generic_setlease);
> > >   *
> > >   * Call this to establish a lease on the file. The "lease" argument is not
> > >   * used for F_UNLCK requests and may be NULL. For commands that set or alter
> > > - * an existing lease, the (*lease)->fl_lmops->lm_break operation must be set;
> > > - * if not, this function will return -ENOLCK (and generate a scary-looking
> > > + * an existing lease, the ``(*lease)->fl_lmops->lm_break`` operation must be
> > > + * set; if not, this function will return -ENOLCK (and generate a scary-looking
> > >   * stack trace).
> > >   *
> > >   * The "priv" pointer is passed directly to the lm_setup function as-is. It
> > > @@ -1972,15 +1972,13 @@ EXPORT_SYMBOL(locks_lock_inode_wait);
> > >   *	@cmd: the type of lock to apply.
> > >   *
> > >   *	Apply a %FL_FLOCK style lock to an open file descriptor.
> > > - *	The @cmd can be one of
> > > + *	The @cmd can be one of:
> > >   *
> > > - *	%LOCK_SH -- a shared lock.
> > > - *
> > > - *	%LOCK_EX -- an exclusive lock.
> > > - *
> > > - *	%LOCK_UN -- remove an existing lock.
> > > - *
> > > - *	%LOCK_MAND -- a `mandatory' flock.  This exists to emulate Windows Share Modes.
> > > + *	- %LOCK_SH -- a shared lock.
> > > + *	- %LOCK_EX -- an exclusive lock.
> > > + *	- %LOCK_UN -- remove an existing lock.
> > > + *	- %LOCK_MAND -- a 'mandatory' flock.
> > > + *	  This exists to emulate Windows Share Modes.
> > >   *
> > >   *	%LOCK_MAND can be combined with %LOCK_READ or %LOCK_WRITE to allow other
> > >   *	processes read and write access respectively.  
> > 
> > LGTM. Do you need me or Bruce to pick this one up?
> 
> Feel free to pick it, if it works best for you.
> 
> > Reviewed-by: Jeff Layton <jlayton@poochiereds.net>

I'll take it for 4.13.  Thanks!

--b.

Re: [PATCH 00/36] Convert DocBook documents to ReST

[Jonathan Corbet]

On Fri, 12 May 2017 10:59:43 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:

> This patch series convert the following books from
> DocBook to ReST:
> 
>    - filesystems
>    - kernel-hacking
>    - kernel-locking
>    - kgdb
>    - libata
>    - networking
>    - rapidio
>    - s390-drivers
>    - scsi
>    - w1
>    - z8530book
> 
> It also adjusts some Sphinx-pedantic errors/warnings on
> some kernel-doc markups.
> 
> I also added some patches here to add PDF output for all
> existing ReST books.

So I've been through the series (including digging out the parts that
weren't sent to me).  

> I did my best to check if what's there is not too outdated, but
> the best is if the subsystem maintainers could check it.

That has been my real concern with those remaining books; many of them
have not been touched in any significant way in at least ten years.  Just
shoveling a bunch of stuff into RST doesn't really solve the problem that
Documentation/ is an unorganized jumble of sometimes highly outdated
documentation.

But, then, I guess there's value in having a disorganized jumble that
depends on only one fragile toolchain rather than two :)  So maybe we
should just do this.

I only had one real comment with the series beyond the general stuff
here.  I see Markus had a few.  When the tweaks are done, can you send me
a series for the stuff I can apply, and I'll do it?

Thanks,

jon

Re: [PATCH 00/36] Convert DocBook documents to ReST

[Mauro Carvalho Chehab]

Em Mon, 15 May 2017 11:11:41 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Fri, 12 May 2017 10:59:43 -0300
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> > This patch series convert the following books from
> > DocBook to ReST:
> > 
> >    - filesystems
> >    - kernel-hacking
> >    - kernel-locking
> >    - kgdb
> >    - libata
> >    - networking
> >    - rapidio
> >    - s390-drivers
> >    - scsi
> >    - w1
> >    - z8530book
> > 
> > It also adjusts some Sphinx-pedantic errors/warnings on
> > some kernel-doc markups.
> > 
> > I also added some patches here to add PDF output for all
> > existing ReST books.  
> 
> So I've been through the series (including digging out the parts that
> weren't sent to me).  
> 
> > I did my best to check if what's there is not too outdated, but
> > the best is if the subsystem maintainers could check it.  
> 
> That has been my real concern with those remaining books; many of them
> have not been touched in any significant way in at least ten years. Just
> shoveling a bunch of stuff into RST doesn't really solve the problem that
> Documentation/ is an unorganized jumble of sometimes highly outdated
> documentation.

True. Yet, on the checks I did, on the books that have API descriptions,
the C domain references still exist. On the books that just have
kernel-doc tags, I wouldn't expect any changes there, as the API
changes should be, instead, at the C code.

So, I guess that it is not that bad, and, by having them in ReST will
make them easier to be updated, as ReST is basically ascii with benefits.

> But, then, I guess there's value in having a disorganized jumble that
> depends on only one fragile toolchain rather than two :)  So maybe we
> should just do this.
> 
> I only had one real comment with the series beyond the general stuff
> here.  I see Markus had a few.  When the tweaks are done, can you send me
> a series for the stuff I can apply, and I'll do it?

Sure, I'm addressing the comments and will send you a new series.

Thanks,
Mauro