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
kernel-doc will try to interpret a foo() string, except if
properly escaped.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
fs/jbd2/transaction.c | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/fs/jbd2/transaction.c b/fs/jbd2/transaction.c
index fe7f4a373436..38e1dcabbaca 100644
--- a/fs/jbd2/transaction.c
+++ b/fs/jbd2/transaction.c
@@ -1066,10 +1066,10 @@ static bool jbd2_write_access_granted(handle_t *handle, struct buffer_head *bh,
* @handle: transaction to add buffer modifications to
* @bh: bh to be used for metadata writes
*
- * Returns an error code or 0 on success.
+ * Returns: error code or 0 on success.
*
* In full data journalling mode the buffer may be of type BJ_AsyncData,
- * because we're write()ing a buffer which is also part of a shared mapping.
+ * because we're ``write()ing`` a buffer which is also part of a shared mapping.
*/
int jbd2_journal_get_write_access(handle_t *handle, struct buffer_head *bh)
--
2.9.3
kernel-doc script expects that a function documentation to
be just before the function, otherwise it will be ignored.
So, move the kernel-doc markup to the right place.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
fs/jbd2/transaction.c | 38 +++++++++++++++++++-------------------
1 file changed, 19 insertions(+), 19 deletions(-)
diff --git a/fs/jbd2/transaction.c b/fs/jbd2/transaction.c
index 9ee4832b6f8b..fe7f4a373436 100644
--- a/fs/jbd2/transaction.c
+++ b/fs/jbd2/transaction.c
@@ -409,25 +409,6 @@ static handle_t *new_handle(int nblocks)
return handle;
}
-/**
- * handle_t *jbd2_journal_start() - Obtain a new handle.
- * @journal: Journal to start transaction on.
- * @nblocks: number of block buffer we might modify
- *
- * We make sure that the transaction can guarantee at least nblocks of
- * modified buffers in the log. We block until the log can guarantee
- * that much space. Additionally, if rsv_blocks > 0, we also create another
- * handle with rsv_blocks reserved blocks in the journal. This handle is
- * is stored in h_rsv_handle. It is not attached to any particular transaction
- * and thus doesn't block transaction commit. If the caller uses this reserved
- * handle, it has to set h_rsv_handle to NULL as otherwise jbd2_journal_stop()
- * on the parent handle will dispose the reserved one. Reserved handle has to
- * be converted to a normal handle using jbd2_journal_start_reserved() before
- * it can be used.
- *
- * Return a pointer to a newly allocated handle, or an ERR_PTR() value
- * on failure.
- */
handle_t *jbd2__journal_start(journal_t *journal, int nblocks, int rsv_blocks,
gfp_t gfp_mask, unsigned int type,
unsigned int line_no)
@@ -478,6 +459,25 @@ handle_t *jbd2__journal_start(journal_t *journal, int nblocks, int rsv_blocks,
EXPORT_SYMBOL(jbd2__journal_start);
+/**
+ * handle_t *jbd2_journal_start() - Obtain a new handle.
+ * @journal: Journal to start transaction on.
+ * @nblocks: number of block buffer we might modify
+ *
+ * We make sure that the transaction can guarantee at least nblocks of
+ * modified buffers in the log. We block until the log can guarantee
+ * that much space. Additionally, if rsv_blocks > 0, we also create another
+ * handle with rsv_blocks reserved blocks in the journal. This handle is
+ * is stored in h_rsv_handle. It is not attached to any particular transaction
+ * and thus doesn't block transaction commit. If the caller uses this reserved
+ * handle, it has to set h_rsv_handle to NULL as otherwise jbd2_journal_stop()
+ * on the parent handle will dispose the reserved one. Reserved handle has to
+ * be converted to a normal handle using jbd2_journal_start_reserved() before
+ * it can be used.
+ *
+ * Return a pointer to a newly allocated handle, or an ERR_PTR() value
+ * on failure.
+ */
handle_t *jbd2_journal_start(journal_t *journal, int nblocks)
{
return jbd2__journal_start(journal, nblocks, 0, GFP_NOFS, 0, 0);
--
2.9.3
On Fri 12-05-17 11:00:07, Mauro Carvalho Chehab wrote:
> kernel-doc will try to interpret a foo() string, except if
> properly escaped.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Looks good. You can add:
Reviewed-by: Jan Kara <[email protected]>
Honza
> ---
> fs/jbd2/transaction.c | 4 ++--
> 1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/fs/jbd2/transaction.c b/fs/jbd2/transaction.c
> index fe7f4a373436..38e1dcabbaca 100644
> --- a/fs/jbd2/transaction.c
> +++ b/fs/jbd2/transaction.c
> @@ -1066,10 +1066,10 @@ static bool jbd2_write_access_granted(handle_t *handle, struct buffer_head *bh,
> * @handle: transaction to add buffer modifications to
> * @bh: bh to be used for metadata writes
> *
> - * Returns an error code or 0 on success.
> + * Returns: error code or 0 on success.
> *
> * In full data journalling mode the buffer may be of type BJ_AsyncData,
> - * because we're write()ing a buffer which is also part of a shared mapping.
> + * because we're ``write()ing`` a buffer which is also part of a shared mapping.
> */
>
> int jbd2_journal_get_write_access(handle_t *handle, struct buffer_head *bh)
> --
> 2.9.3
>
>
--
Jan Kara <[email protected]>
SUSE Labs, CR
On Fri 12-05-17 11:00:02, Mauro Carvalho Chehab wrote:
> kernel-doc script expects that a function documentation to
> be just before the function, otherwise it will be ignored.
>
> So, move the kernel-doc markup to the right place.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Looks good. You can add:
Reviewed-by: Jan Kara <[email protected]>
Honza
> ---
> fs/jbd2/transaction.c | 38 +++++++++++++++++++-------------------
> 1 file changed, 19 insertions(+), 19 deletions(-)
>
> diff --git a/fs/jbd2/transaction.c b/fs/jbd2/transaction.c
> index 9ee4832b6f8b..fe7f4a373436 100644
> --- a/fs/jbd2/transaction.c
> +++ b/fs/jbd2/transaction.c
> @@ -409,25 +409,6 @@ static handle_t *new_handle(int nblocks)
> return handle;
> }
>
> -/**
> - * handle_t *jbd2_journal_start() - Obtain a new handle.
> - * @journal: Journal to start transaction on.
> - * @nblocks: number of block buffer we might modify
> - *
> - * We make sure that the transaction can guarantee at least nblocks of
> - * modified buffers in the log. We block until the log can guarantee
> - * that much space. Additionally, if rsv_blocks > 0, we also create another
> - * handle with rsv_blocks reserved blocks in the journal. This handle is
> - * is stored in h_rsv_handle. It is not attached to any particular transaction
> - * and thus doesn't block transaction commit. If the caller uses this reserved
> - * handle, it has to set h_rsv_handle to NULL as otherwise jbd2_journal_stop()
> - * on the parent handle will dispose the reserved one. Reserved handle has to
> - * be converted to a normal handle using jbd2_journal_start_reserved() before
> - * it can be used.
> - *
> - * Return a pointer to a newly allocated handle, or an ERR_PTR() value
> - * on failure.
> - */
> handle_t *jbd2__journal_start(journal_t *journal, int nblocks, int rsv_blocks,
> gfp_t gfp_mask, unsigned int type,
> unsigned int line_no)
> @@ -478,6 +459,25 @@ handle_t *jbd2__journal_start(journal_t *journal, int nblocks, int rsv_blocks,
> EXPORT_SYMBOL(jbd2__journal_start);
>
>
> +/**
> + * handle_t *jbd2_journal_start() - Obtain a new handle.
> + * @journal: Journal to start transaction on.
> + * @nblocks: number of block buffer we might modify
> + *
> + * We make sure that the transaction can guarantee at least nblocks of
> + * modified buffers in the log. We block until the log can guarantee
> + * that much space. Additionally, if rsv_blocks > 0, we also create another
> + * handle with rsv_blocks reserved blocks in the journal. This handle is
> + * is stored in h_rsv_handle. It is not attached to any particular transaction
> + * and thus doesn't block transaction commit. If the caller uses this reserved
> + * handle, it has to set h_rsv_handle to NULL as otherwise jbd2_journal_stop()
> + * on the parent handle will dispose the reserved one. Reserved handle has to
> + * be converted to a normal handle using jbd2_journal_start_reserved() before
> + * it can be used.
> + *
> + * Return a pointer to a newly allocated handle, or an ERR_PTR() value
> + * on failure.
> + */
> handle_t *jbd2_journal_start(journal_t *journal, int nblocks)
> {
> return jbd2__journal_start(journal, nblocks, 0, GFP_NOFS, 0, 0);
> --
> 2.9.3
>
>
--
Jan Kara <[email protected]>
SUSE Labs, CR
On Fri, 12 May 2017 10:59:43 -0300
Mauro Carvalho Chehab <[email protected]> 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
Em Mon, 15 May 2017 11:11:41 -0600
Jonathan Corbet <[email protected]> escreveu:
> On Fri, 12 May 2017 10:59:43 -0300
> Mauro Carvalho Chehab <[email protected]> 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