On Fri, 24 Jul 2020 18:41:30 +0100
Matthew Wilcox [off-list ref] 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:

quoted

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