Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
Date:   Fri, 24 Jul 2020 14:51:48 -0400
From:   Steven Rostedt <rostedt@goodmis.org>
To:     Matthew Wilcox <willy@infradead.org>
Cc:     Jonathan Corbet <corbet@lwn.net>,
        Peter Zijlstra <peterz@infradead.org>,
        linux-doc@vger.kernel.org, LKML <linux-kernel@vger.kernel.org>
Subject: Re: Minor RST rant
Message-ID: <20200724145148.58836d66@oasis.local.home>
In-Reply-To: <20200724174130.GC23808@casper.infradead.org>
References: <20200724132200.51fd2065@oasis.local.home>
        <20200724174130.GC23808@casper.infradead.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

On Fri, 24 Jul 2020 18:41:30 +0100
Matthew Wilcox <willy@infradead.org> 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