| Message ID | cover.1587487612.git.mchehab+huawei@kernel.org (mailing list archive) |
|---|---|
| Headers | show |
| Series | fs: convert remaining docs to ReST file format | expand |
NAK, this makes the document significantly harder to read.
On Tue, Apr 21, 2020 at 06:55:34PM +0200, Christoph Hellwig wrote:
> NAK, this makes the document significantly harder to read.
Really? It reads more easily to me in the new format. Enclosing
section headers in [] is really weird.
On Tue, Apr 21, 2020 at 10:02:23AM -0700, Matthew Wilcox wrote: > On Tue, Apr 21, 2020 at 06:55:34PM +0200, Christoph Hellwig wrote: > > NAK, this makes the document significantly harder to read. > > Really? It reads more easily to me in the new format. Enclosing > section headers in [] is really weird. It wasn't entirely uncommon, but that's not really the point. The Problem is all the weird ".." or "::" annotations that really kill the flow, or things like "|copy|" that have no reason to exist.
On Tue, Apr 21, 2020 at 07:23:37PM +0200, Christoph Hellwig wrote: > On Tue, Apr 21, 2020 at 10:02:23AM -0700, Matthew Wilcox wrote: > > On Tue, Apr 21, 2020 at 06:55:34PM +0200, Christoph Hellwig wrote: > > > NAK, this makes the document significantly harder to read. > > > > Really? It reads more easily to me in the new format. Enclosing > > section headers in [] is really weird. > > It wasn't entirely uncommon, but that's not really the point. The > Problem is all the weird ".." or "::" annotations that really kill > the flow, or things like "|copy|" that have no reason to exist. FWIW, I consider the rst transformations to be an improvement, even when reading them as a text mode. - Ted
On Tue, 21 Apr 2020 19:23:37 +0200 Christoph Hellwig <hch@lst.de> wrote: > On Tue, Apr 21, 2020 at 10:02:23AM -0700, Matthew Wilcox wrote: > > On Tue, Apr 21, 2020 at 06:55:34PM +0200, Christoph Hellwig wrote: > > > NAK, this makes the document significantly harder to read. > > > > Really? It reads more easily to me in the new format. Enclosing > > section headers in [] is really weird. > > It wasn't entirely uncommon, but that's not really the point. The > Problem is all the weird ".." or "::" annotations that really kill > the flow, or things like "|copy|" that have no reason to exist. This sounds sort of like "my markup is good, yours is bad", honestly. If somebody were trying to add bracketed headings to a new document, I suspect we'd get similar complaints. The markup can certainly be toned down. If you don't like |copy|, it can just as easily remain "(c)" or become ©, or just go away entirely. That would get rid of the ".. include:: <isonum.txt>" line too. I would happily make a rule that we don't bother with markup like |copy| anywhere in the kernel docs. The SPDX line is supposed to exist in all files, of course. If Mauro does that, can you live with "::" to mark a literal block? It doesn't seem like a whole lot of noise...? Thanks, jon
On 21/04/2020 18:23, Christoph Hellwig wrote: > It wasn't entirely uncommon, but that's not really the point. The > Problem is all the weird ".." or "::" annotations that really kill > the flow, or things like "|copy|" that have no reason to exist. You aren't supposed to read REST documentation files - as opposed to kerneldoc comments in the C source - any more than you read HTML. [ Exactly what should or should not be in C source kerneldoc is another matter. ] Developers are used to reading plain ol' text files for quick reference. But there is no make target to generate the text files. Can we create a method to build text *output* files?
On Fri, 24 Apr 2020 18:28:54 +0100 Peter Lister <peter@bikeshed.quignogs.org.uk> wrote: > On 21/04/2020 18:23, Christoph Hellwig wrote: > > It wasn't entirely uncommon, but that's not really the point. The > > Problem is all the weird ".." or "::" annotations that really kill > > the flow, or things like "|copy|" that have no reason to exist. > > You aren't supposed to read REST documentation files - as opposed to > kerneldoc comments in the C source - any more than you read HTML. I am sorry, but that is not the approach we take at all. RST was chosen *because* it is readable plain text, and the readability of the source docs is of high importance; that's not going to change. Thanks, jon
On Fri, Apr 24, 2020 at 06:28:54PM +0100, Peter Lister wrote: > On 21/04/2020 18:23, Christoph Hellwig wrote: >> It wasn't entirely uncommon, but that's not really the point. The >> Problem is all the weird ".." or "::" annotations that really kill >> the flow, or things like "|copy|" that have no reason to exist. > > You aren't supposed to read REST documentation files - as opposed to > kerneldoc comments in the C source - any more than you read HTML. And that is the whole problem. Optimizing for reading in a browser might be an okay tradeoff for end-user documentation. But it is absolutely the wrong thing for internal API documentation where you want to jump to them by opening them in the same text editor.
On Tue, Apr 21, 2020 at 04:53:17PM -0600, Jonathan Corbet wrote: > > It wasn't entirely uncommon, but that's not really the point. The > > Problem is all the weird ".." or "::" annotations that really kill > > the flow, or things like "|copy|" that have no reason to exist. > > This sounds sort of like "my markup is good, yours is bad", honestly. If > somebody were trying to add bracketed headings to a new document, I > suspect we'd get similar complaints. Not really. It is a "less markup is better". > The markup can certainly be toned down. If you don't like |copy|, it can > just as easily remain "(c)" or become ©, or just go away entirely. That > would get rid of the ".. include:: <isonum.txt>" line too. I would > happily make a rule that we don't bother with markup like |copy| > anywhere in the kernel docs. That is a good start. > The SPDX line is supposed to exist in all files, of course. No problem with that. I'll happily take a SPDX patch any time. > If Mauro does that, can you live with "::" to mark a literal block? It > doesn't seem like a whole lot of noise...? That is in fact one of my favourite pet pevees with the whole RST thing.
Em Tue, 21 Apr 2020 16:53:17 -0600 Jonathan Corbet <corbet@lwn.net> escreveu: > On Tue, 21 Apr 2020 19:23:37 +0200 > Christoph Hellwig <hch@lst.de> wrote: > > > On Tue, Apr 21, 2020 at 10:02:23AM -0700, Matthew Wilcox wrote: > > > On Tue, Apr 21, 2020 at 06:55:34PM +0200, Christoph Hellwig wrote: > > > > NAK, this makes the document significantly harder to read. > > > > > > Really? It reads more easily to me in the new format. Enclosing > > > section headers in [] is really weird. > > > > It wasn't entirely uncommon, but that's not really the point. The > > Problem is all the weird ".." or "::" annotations that really kill > > the flow, or things like "|copy|" that have no reason to exist. > > This sounds sort of like "my markup is good, yours is bad", honestly. If > somebody were trying to add bracketed headings to a new document, I > suspect we'd get similar complaints. > > The markup can certainly be toned down. If you don't like |copy|, it can > just as easily remain "(c)" or become ©, or just go away entirely. That > would get rid of the ".. include:: <isonum.txt>" line too. I would > happily make a rule that we don't bother with markup like |copy| > anywhere in the kernel docs. > > The SPDX line is supposed to exist in all files, of course. > > If Mauro does that, can you live with "::" to mark a literal block? It > doesn't seem like a whole lot of noise...? Yeah, I can remove most of the markups, preserving the "::". Will send a new patchset in a few. Thanks, Mauro
This patch series convert the remaining files under Documentation/filesystems to the ReST file format (except for dax.txt and patch-lookup.txt). It is based on linux-next (next-2020021). PS.: I opted to add mainly ML from the output of get_maintainers.pl to the c/c list of patch 00/34, because otherwise the number of c/c would be too many, with would very likely cause ML servers to reject it. The results of those changes (together with other changes from my pending doc patches) are available at: https://www.infradead.org/~mchehab/kernel_docs/filesystems/index.html And the series is also on my git tree: https://git.linuxtv.org/mchehab/experimental.git/log/?h=fs_docs If you prefer, feel free to merge the patches via the filesystems git tree(s). - v2: - Removed dax.txt, in order to prevent a merge conflict with a dax patchset; - Removed patch-lookup.txt conversion, due to patch-lookup.rst. (I'll revisit this on some future) - Removed a patch that was already merged; - Added some Acked-by. Mauro Carvalho Chehab (29): docs: filesystems: convert caching/object.txt to ReST docs: filesystems: convert caching/fscache.txt to ReST format docs: filesystems: caching/netfs-api.txt: convert it to ReST docs: filesystems: caching/operations.txt: convert it to ReST docs: filesystems: caching/cachefiles.txt: convert to ReST docs: filesystems: caching/backend-api.txt: convert it to ReST docs: filesystems: convert cifs/cifsroot.txt to ReST docs: filesystems: convert configfs.txt to ReST docs: filesystems: convert automount-support.txt to ReST docs: filesystems: convert coda.txt to ReST docs: filesystems: convert devpts.txt to ReST docs: filesystems: convert dnotify.txt to ReST docs: filesystems: convert fiemap.txt to ReST docs: filesystems: convert files.txt to ReST docs: filesystems: convert fuse-io.txt to ReST docs: filesystems: convert locks.txt to ReST docs: filesystems: convert mandatory-locking.txt to ReST docs: filesystems: convert mount_api.txt to ReST docs: filesystems: convert quota.txt to ReST docs: filesystems: convert seq_file.txt to ReST docs: filesystems: convert sharedsubtree.txt to ReST docs: filesystems: split spufs.txt into 3 separate files docs: filesystems: convert spufs/spu_create.txt to ReST docs: filesystems: convert spufs/spufs.txt to ReST docs: filesystems: convert spufs/spu_run.txt to ReST docs: filesystems: convert sysfs-pci.txt to ReST docs: filesystems: convert sysfs-tagging.txt to ReST docs: filesystems: convert xfs-delayed-logging-design.txt to ReST docs: filesystems: convert xfs-self-describing-metadata.txt to ReST Documentation/admin-guide/sysctl/kernel.rst | 2 +- ...ount-support.txt => automount-support.rst} | 23 +- .../{backend-api.txt => backend-api.rst} | 165 +- .../{cachefiles.txt => cachefiles.rst} | 139 +- Documentation/filesystems/caching/fscache.rst | 565 ++++++ Documentation/filesystems/caching/fscache.txt | 448 ----- Documentation/filesystems/caching/index.rst | 14 + .../caching/{netfs-api.txt => netfs-api.rst} | 172 +- .../caching/{object.txt => object.rst} | 43 +- .../{operations.txt => operations.rst} | 45 +- .../cifs/{cifsroot.txt => cifsroot.rst} | 56 +- Documentation/filesystems/coda.rst | 1670 ++++++++++++++++ Documentation/filesystems/coda.txt | 1676 ----------------- .../{configfs/configfs.txt => configfs.rst} | 129 +- Documentation/filesystems/devpts.rst | 36 + Documentation/filesystems/devpts.txt | 26 - .../filesystems/{dnotify.txt => dnotify.rst} | 11 +- .../filesystems/{fiemap.txt => fiemap.rst} | 133 +- .../filesystems/{files.txt => files.rst} | 15 +- .../filesystems/{fuse-io.txt => fuse-io.rst} | 6 + Documentation/filesystems/index.rst | 23 + .../filesystems/{locks.txt => locks.rst} | 14 +- ...tory-locking.txt => mandatory-locking.rst} | 25 +- .../{mount_api.txt => mount_api.rst} | 329 ++-- Documentation/filesystems/proc.rst | 2 +- .../filesystems/{quota.txt => quota.rst} | 41 +- .../{seq_file.txt => seq_file.rst} | 61 +- .../{sharedsubtree.txt => sharedsubtree.rst} | 394 ++-- Documentation/filesystems/spufs/index.rst | 13 + .../filesystems/spufs/spu_create.rst | 131 ++ Documentation/filesystems/spufs/spu_run.rst | 138 ++ .../{spufs.txt => spufs/spufs.rst} | 304 +-- .../{sysfs-pci.txt => sysfs-pci.rst} | 23 +- .../{sysfs-tagging.txt => sysfs-tagging.rst} | 22 +- ...ign.txt => xfs-delayed-logging-design.rst} | 65 +- ...a.txt => xfs-self-describing-metadata.rst} | 182 +- Documentation/iio/iio_configfs.rst | 2 +- Documentation/usb/gadget_configfs.rst | 4 +- MAINTAINERS | 14 +- fs/cachefiles/Kconfig | 4 +- fs/coda/Kconfig | 2 +- fs/configfs/inode.c | 2 +- fs/configfs/item.c | 2 +- fs/fscache/Kconfig | 8 +- fs/fscache/cache.c | 8 +- fs/fscache/cookie.c | 2 +- fs/fscache/object.c | 4 +- fs/fscache/operation.c | 2 +- fs/locks.c | 2 +- include/linux/configfs.h | 2 +- include/linux/fs_context.h | 2 +- include/linux/fscache-cache.h | 4 +- include/linux/fscache.h | 42 +- include/linux/lsm_hooks.h | 2 +- 54 files changed, 3844 insertions(+), 3405 deletions(-) rename Documentation/filesystems/{automount-support.txt => automount-support.rst} (92%) rename Documentation/filesystems/caching/{backend-api.txt => backend-api.rst} (87%) rename Documentation/filesystems/caching/{cachefiles.txt => cachefiles.rst} (90%) create mode 100644 Documentation/filesystems/caching/fscache.rst delete mode 100644 Documentation/filesystems/caching/fscache.txt create mode 100644 Documentation/filesystems/caching/index.rst rename Documentation/filesystems/caching/{netfs-api.txt => netfs-api.rst} (91%) rename Documentation/filesystems/caching/{object.txt => object.rst} (95%) rename Documentation/filesystems/caching/{operations.txt => operations.rst} (90%) rename Documentation/filesystems/cifs/{cifsroot.txt => cifsroot.rst} (72%) create mode 100644 Documentation/filesystems/coda.rst delete mode 100644 Documentation/filesystems/coda.txt rename Documentation/filesystems/{configfs/configfs.txt => configfs.rst} (87%) create mode 100644 Documentation/filesystems/devpts.rst delete mode 100644 Documentation/filesystems/devpts.txt rename Documentation/filesystems/{dnotify.txt => dnotify.rst} (90%) rename Documentation/filesystems/{fiemap.txt => fiemap.rst} (70%) rename Documentation/filesystems/{files.txt => files.rst} (95%) rename Documentation/filesystems/{fuse-io.txt => fuse-io.rst} (95%) rename Documentation/filesystems/{locks.txt => locks.rst} (91%) rename Documentation/filesystems/{mandatory-locking.txt => mandatory-locking.rst} (91%) rename Documentation/filesystems/{mount_api.txt => mount_api.rst} (79%) rename Documentation/filesystems/{quota.txt => quota.rst} (81%) rename Documentation/filesystems/{seq_file.txt => seq_file.rst} (92%) rename Documentation/filesystems/{sharedsubtree.txt => sharedsubtree.rst} (72%) create mode 100644 Documentation/filesystems/spufs/index.rst create mode 100644 Documentation/filesystems/spufs/spu_create.rst create mode 100644 Documentation/filesystems/spufs/spu_run.rst rename Documentation/filesystems/{spufs.txt => spufs/spufs.rst} (57%) rename Documentation/filesystems/{sysfs-pci.txt => sysfs-pci.rst} (92%) rename Documentation/filesystems/{sysfs-tagging.txt => sysfs-tagging.rst} (72%) rename Documentation/filesystems/{xfs-delayed-logging-design.txt => xfs-delayed-logging-design.rst} (97%) rename Documentation/filesystems/{xfs-self-describing-metadata.txt => xfs-self-describing-metadata.rst} (83%)