* [PATCH 00/36] Convert DocBook documents to ReST @ 2017-05-12 13:59 Mauro Carvalho Chehab 2017-05-12 14:00 ` [PATCH 34/36] scsi: fix some kernel-doc markups Mauro Carvalho Chehab 2017-05-15 17:11 ` [PATCH 00/36] Convert DocBook documents to ReST Jonathan Corbet 0 siblings, 2 replies; 4+ messages in thread From: Mauro Carvalho Chehab @ 2017-05-12 13:59 UTC (permalink / raw) To: linux-kernel, Linux Doc Mailing List Cc: Andrew Lunn, alsa-devel, Takashi Iwai, Jan Kiszka, Herton R. Krzesinski, Alexei Starovoitov, J. Bruce Fields, linux-ide, Eric Dumazet, netdev, Jeff Layton, Jan Kara, Soheil Hassas Yeganeh, linux-s390, Florian Fainelli, James E.J. Bottomley, Herbert Xu, linux-scsi, Jonathan Corbet, Ursula Braun, Rafael J. Wysocki, Mauro Carvalho Chehab, Peter Zijlstra, Julian Anastasov, Ingo 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 ^ permalink raw reply [flat|nested] 4+ messages in thread
* [PATCH 34/36] scsi: fix some kernel-doc markups 2017-05-12 13:59 [PATCH 00/36] Convert DocBook documents to ReST Mauro Carvalho Chehab @ 2017-05-12 14:00 ` Mauro Carvalho Chehab 2017-05-15 17:11 ` [PATCH 00/36] Convert DocBook documents to ReST Jonathan Corbet 1 sibling, 0 replies; 4+ messages in thread From: Mauro Carvalho Chehab @ 2017-05-12 14:00 UTC (permalink / raw) To: linux-kernel, Linux Doc Mailing List Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, James E.J. Bottomley, Martin K. Petersen, linux-scsi Sphinx is very pedantic with regards to ident/spacing. Fix some kernel-doc markups in order to solve those errors/warnings: ./drivers/scsi/scsicam.c:121: WARNING: Inline emphasis start-string without end-string. ./drivers/scsi/scsicam.c:121: WARNING: Inline emphasis start-string without end-string. ./drivers/scsi/scsicam.c:121: WARNING: Inline emphasis start-string without end-string. ./drivers/scsi/scsi_scan.c:1056: ERROR: Unexpected indentation. ./drivers/scsi/scsi_scan.c:1057: WARNING: Block quote ends without a blank line; unexpected unindent. ./drivers/scsi/scsi_transport_fc.c:2918: ERROR: Unexpected indentation. ./drivers/scsi/scsi_transport_fc.c:2921: WARNING: Block quote ends without a blank line; unexpected unindent. ./drivers/scsi/scsi_transport_fc.c:2922: WARNING: Enumerated list ends without a blank line; unexpected unindent. No functional changes. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- drivers/scsi/scsi_scan.c | 7 ++++--- drivers/scsi/scsi_transport_fc.c | 18 ++++++++++-------- drivers/scsi/scsicam.c | 4 ++-- 3 files changed, 16 insertions(+), 13 deletions(-) diff --git a/drivers/scsi/scsi_scan.c b/drivers/scsi/scsi_scan.c index 6f7128f49c30..69979574004f 100644 --- a/drivers/scsi/scsi_scan.c +++ b/drivers/scsi/scsi_scan.c @@ -1051,10 +1051,11 @@ static unsigned char *scsi_inq_str(unsigned char *buf, unsigned char *inq, * allocate and set it up by calling scsi_add_lun. * * Return: - * SCSI_SCAN_NO_RESPONSE: could not allocate or setup a scsi_device - * SCSI_SCAN_TARGET_PRESENT: target responded, but no device is + * + * - SCSI_SCAN_NO_RESPONSE: could not allocate or setup a scsi_device + * - SCSI_SCAN_TARGET_PRESENT: target responded, but no device is * attached at the LUN - * SCSI_SCAN_LUN_PRESENT: a new scsi_device was allocated and initialized + * - SCSI_SCAN_LUN_PRESENT: a new scsi_device was allocated and initialized **/ static int scsi_probe_and_add_lun(struct scsi_target *starget, u64 lun, int *bflagsp, diff --git a/drivers/scsi/scsi_transport_fc.c b/drivers/scsi/scsi_transport_fc.c index d4cf32d55546..1df77453f6b6 100644 --- a/drivers/scsi/scsi_transport_fc.c +++ b/drivers/scsi/scsi_transport_fc.c @@ -2914,16 +2914,18 @@ EXPORT_SYMBOL(fc_remote_port_add); * port is no longer part of the topology. Note: Although a port * may no longer be part of the topology, it may persist in the remote * ports displayed by the fc_host. We do this under 2 conditions: + * * 1) If the port was a scsi target, we delay its deletion by "blocking" it. - * This allows the port to temporarily disappear, then reappear without - * disrupting the SCSI device tree attached to it. During the "blocked" - * period the port will still exist. + * This allows the port to temporarily disappear, then reappear without + * disrupting the SCSI device tree attached to it. During the "blocked" + * period the port will still exist. + * * 2) If the port was a scsi target and disappears for longer than we - * expect, we'll delete the port and the tear down the SCSI device tree - * attached to it. However, we want to semi-persist the target id assigned - * to that port if it eventually does exist. The port structure will - * remain (although with minimal information) so that the target id - * bindings remails. + * expect, we'll delete the port and the tear down the SCSI device tree + * attached to it. However, we want to semi-persist the target id assigned + * to that port if it eventually does exist. The port structure will + * remain (although with minimal information) so that the target id + * bindings remails. * * If the remote port is not an FCP Target, it will be fully torn down * and deallocated, including the fc_remote_port class device. diff --git a/drivers/scsi/scsicam.c b/drivers/scsi/scsicam.c index 910f4a7a3924..31273468589c 100644 --- a/drivers/scsi/scsicam.c +++ b/drivers/scsi/scsicam.c @@ -116,8 +116,8 @@ EXPORT_SYMBOL(scsicam_bios_param); * @hds: put heads here * @secs: put sectors here * - * Description: determine the BIOS mapping/geometry used to create the partition - * table, storing the results in *cyls, *hds, and *secs + * Determine the BIOS mapping/geometry used to create the partition + * table, storing the results in @cyls, @hds, and @secs * * Returns: -1 on failure, 0 on success. */ -- 2.9.3 ^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCH 00/36] Convert DocBook documents to ReST 2017-05-12 13:59 [PATCH 00/36] Convert DocBook documents to ReST Mauro Carvalho Chehab 2017-05-12 14:00 ` [PATCH 34/36] scsi: fix some kernel-doc markups Mauro Carvalho Chehab @ 2017-05-15 17:11 ` Jonathan Corbet 2017-05-15 17:41 ` Mauro Carvalho Chehab 1 sibling, 1 reply; 4+ messages in thread From: Jonathan Corbet @ 2017-05-15 17:11 UTC (permalink / raw) To: Mauro Carvalho Chehab Cc: Andrew Lunn, alsa-devel, Linux Doc Mailing List, Takashi Iwai, Jan Kiszka, Herton R. Krzesinski, Alexei Starovoitov, Takashi Iwai, J. Bruce Fields, linux-ide, Eric Dumazet, netdev, Jeff Layton, Jan Kara, Soheil Hassas Yeganeh, linux-s390, Florian Fainelli, James E.J. Bottomley, Herbert Xu, linux-scsi, Ursula Braun, Rafael J. Wysocki, Peter Zijlstra, Julian Anastasov, Ingo 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 ^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH 00/36] Convert DocBook documents to ReST 2017-05-15 17:11 ` [PATCH 00/36] Convert DocBook documents to ReST Jonathan Corbet @ 2017-05-15 17:41 ` Mauro Carvalho Chehab 0 siblings, 0 replies; 4+ messages in thread From: Mauro Carvalho Chehab @ 2017-05-15 17:41 UTC (permalink / raw) To: Jonathan Corbet Cc: Andrew Lunn, alsa-devel, Linux Doc Mailing List, Takashi Iwai, Jan Kiszka, Herton R. Krzesinski, Alexei Starovoitov, Takashi Iwai, J. Bruce Fields, linux-ide, Eric Dumazet, netdev, Jeff Layton, Jan Kara, Soheil Hassas Yeganeh, linux-s390, Florian Fainelli, James E.J. Bottomley, Herbert Xu, linux-scsi, Ursula Braun, Rafael J. Wysocki, Peter Zijlstra, Julian Anastasov, Ingo 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 ^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2017-05-15 17:41 UTC | newest] Thread overview: 4+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2017-05-12 13:59 [PATCH 00/36] Convert DocBook documents to ReST Mauro Carvalho Chehab 2017-05-12 14:00 ` [PATCH 34/36] scsi: fix some kernel-doc markups Mauro Carvalho Chehab 2017-05-15 17:11 ` [PATCH 00/36] Convert DocBook documents to ReST Jonathan Corbet 2017-05-15 17:41 ` Mauro Carvalho Chehab
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox