On Fri, Jul 24 2020, Steven Rostedt wrote: > 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] Do you read Jane Austen at all? "I certainly have not the talent which some people possess," said Darcy, "of conversing easily with those I have never seen before. I cannot catch their tone of conversation, or appear interested in their concerns, as I often see done." "My fingers," said Elizabeth, "do not move over this instrument in the masterly manner which I see so many women's do. They have not the same force or rapidity, and do not produce the same expression. But then I have always supposed it to be my own fault--because I will not take the trouble of practising." :-) NeilBrown > >> 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
Attachment:
signature.asc
Description: PGP signature
