On Fri, 24 Jul 2020 18:41:30 +0100 Matthew Wilcox <willy@xxxxxxxxxxxxx> wrote: > Great example. Some people definitely go too far with rst markup, and > we generally try to discourage it. And I'm pretty sure we take patches I'd send patches but I suck at markup ;-) [1] > to remove excessive markup where it's gone too far [1]. > > You can see how this renders in html at > https://www.kernel.org/doc/html/latest/filesystems/path-lookup.html or > run 'make htmldocs' to build it locally. Personally, I don't think > the markup style it uses works very well in the html either. > > I'd like to see this paragraph written as: > > > It is tempting to describe the second kind as starting with a > > component, but that isn't always accurate: a pathname can lack both > > slashes and components, it can be empty, in other words. This is > > generally forbidden in POSIX, but some of the "*at()" system calls > > in Linux permit it when the ``AT_EMPTY_PATH`` flag is given. For > > example, if you have an open file descriptor on an executable file you > > can execute it by calling execveat() passing the file descriptor, an > > empty path, and the ``AT_EMPTY_PATH`` flag. > > I think we're all pretty comfortable seeing function names adorned with > a closing pair of parens. The ``...`` to adorn constants feels OK to me, > but maybe not to you? If that feels excessive, can you suggest something > that would distinguish between POSIX and AT_EMPTY_PATH? Honestly, it's the context that distinguishes the two for me. I don't need any markup. But yeah, the double backtick still seems awkward. Funny thing is, markup like this: <b>AT_EMPTY_PATH</b> doesn't bother me as much. Not sure why though :-/ My frustration with this stood out quite a bit because I went from one file (with the same name) in .txt format, and went through that fast and quickly where everything made a lot of sense, and then jumping to this file, and feeling like I came to a stand-still in my understanding of the material. > > [1] Too far being a subjective measure, of course. My preferences > are on display in core-api/xarray.rst [1] I maintain trace/ftrace.rst, but the markup in that was written by others, and I gave a lot of pushback when I found that the markup made it hard to read with "less". -- Steve
