* [PATCH 00/36] Convert DocBook documents to ReST @ 2017-05-12 13:59 Mauro Carvalho Chehab 2017-05-12 14:00 ` [PATCH 31/36] net: fix some identation issues at 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 31/36] net: fix some identation issues at 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, Andrew Lunn, Florian Fainelli, David S. Miller, Eric Dumazet, Paolo Abeni, Al Viro, Hannes Frederic Sowa, Ding Tianhong, Alexander Duyck, Soheil Hassas Yeganeh, Ursula Braun, Johannes Weiner, Sridhar Samudrala, David Howells, Josh Hunt, netdev Sphinx is very pedantic with regards to identation and escape sequences: ./include/net/sock.h:1967: ERROR: Unexpected indentation. ./include/net/sock.h:1969: ERROR: Unexpected indentation. ./include/net/sock.h:1970: WARNING: Block quote ends without a blank line; unexpected unindent. ./include/net/sock.h:1971: WARNING: Block quote ends without a blank line; unexpected unindent. ./include/net/sock.h:2268: WARNING: Inline emphasis start-string without end-string. ./net/core/sock.c:2686: ERROR: Unexpected indentation. ./net/core/sock.c:2687: WARNING: Block quote ends without a blank line; unexpected unindent. ./net/core/datagram.c:182: WARNING: Inline emphasis start-string without end-string. ./include/linux/netdevice.h:1444: ERROR: Unexpected indentation. ./drivers/net/phy/phy.c:381: ERROR: Unexpected indentation. ./drivers/net/phy/phy.c:382: WARNING: Block quote ends without a blank line; unexpected unindent. - Fix spacing where needed; - Properly escape constants; - Use a literal block for a race description. No functional changes. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- drivers/net/phy/phy.c | 1 + include/linux/netdevice.h | 9 +++++---- include/net/sock.h | 9 ++++----- net/core/datagram.c | 2 +- net/core/sock.c | 7 +++++-- 5 files changed, 16 insertions(+), 12 deletions(-) diff --git a/drivers/net/phy/phy.c b/drivers/net/phy/phy.c index 82ab8fb82587..709b8be53443 100644 --- a/drivers/net/phy/phy.c +++ b/drivers/net/phy/phy.c @@ -377,6 +377,7 @@ static void phy_sanitize_settings(struct phy_device *phydev) * @cmd: ethtool_cmd * * A few notes about parameter checking: + * * - We don't set port or transceiver, so we don't care what they * were set to. * - phy_start_aneg() will make sure forced settings are sane, and diff --git a/include/linux/netdevice.h b/include/linux/netdevice.h index 9c23bd2efb56..56d54b6fac45 100644 --- a/include/linux/netdevice.h +++ b/include/linux/netdevice.h @@ -1433,13 +1433,14 @@ enum netdev_priv_flags { /** * struct net_device - The DEVICE structure. - * Actually, this whole structure is a big mistake. It mixes I/O - * data with strictly "high-level" data, and it has to know about - * almost every data structure used in the INET module. + * + * Actually, this whole structure is a big mistake. It mixes I/O + * data with strictly "high-level" data, and it has to know about + * almost every data structure used in the INET module. * * @name: This is the first field of the "visible" part of this structure * (i.e. as seen by users in the "Space.c" file). It is the name - * of the interface. + * of the interface. * * @name_hlist: Device name hash chain, please keep it close to name[] * @ifalias: SNMP alias diff --git a/include/net/sock.h b/include/net/sock.h index 66349e49d468..9ca99b5c1328 100644 --- a/include/net/sock.h +++ b/include/net/sock.h @@ -1953,11 +1953,10 @@ static inline bool sk_has_allocations(const struct sock *sk) * The purpose of the skwq_has_sleeper and sock_poll_wait is to wrap the memory * barrier call. They were added due to the race found within the tcp code. * - * Consider following tcp code paths: + * Consider following tcp code paths:: * - * CPU1 CPU2 - * - * sys_select receive packet + * CPU1 CPU2 + * sys_select receive packet * ... ... * __add_wait_queue update tp->rcv_nxt * ... ... @@ -2264,7 +2263,7 @@ void __sock_tx_timestamp(__u16 tsflags, __u8 *tx_flags); * @tsflags: timestamping flags to use * @tx_flags: completed with instructions for time stamping * - * Note : callers should take care of initial *tx_flags value (usually 0) + * Note: callers should take care of initial ``*tx_flags`` value (usually 0) */ static inline void sock_tx_timestamp(const struct sock *sk, __u16 tsflags, __u8 *tx_flags) diff --git a/net/core/datagram.c b/net/core/datagram.c index db1866f2ffcf..4dd594741b6d 100644 --- a/net/core/datagram.c +++ b/net/core/datagram.c @@ -181,7 +181,7 @@ static struct sk_buff *skb_set_peeked(struct sk_buff *skb) * * This function will lock the socket if a skb is returned, so * the caller needs to unlock the socket in that case (usually by - * calling skb_free_datagram). Returns NULL with *err set to + * calling skb_free_datagram). Returns NULL with @err set to * -EAGAIN if no data was available or to some other value if an * error was detected. * diff --git a/net/core/sock.c b/net/core/sock.c index 79c6aee6af9b..6adc69edfdd6 100644 --- a/net/core/sock.c +++ b/net/core/sock.c @@ -2682,9 +2682,12 @@ EXPORT_SYMBOL(release_sock); * @sk: socket * * This version should be used for very small section, where process wont block - * return false if fast path is taken + * return false if fast path is taken: + * * sk_lock.slock locked, owned = 0, BH disabled - * return true if slow path is taken + * + * return true if slow path is taken: + * * sk_lock.slock unlocked, owned = 1, BH enabled */ bool lock_sock_fast(struct sock *sk) -- 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 31/36] net: fix some identation issues at 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 31/36] net: fix some identation issues at 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; as well as URLs for NNTP newsgroup(s).