Re: Minor RST rant

[Steven Rostedt]

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