Linux-Doc Archive on lore.kernel.org
 help / color / Atom feed
From: Matthew Wilcox <willy@infradead.org>
To: Steven Rostedt <rostedt@goodmis.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
Date: Fri, 24 Jul 2020 18:41:30 +0100
Message-ID: <20200724174130.GC23808@casper.infradead.org> (raw)
In-Reply-To: <20200724132200.51fd2065@oasis.local.home>

On Fri, Jul 24, 2020 at 01:22:00PM -0400, Steven Rostedt wrote:
> I like how RST can help make for a better grouping of our documents
> and put it into other formats. But I have to rant a little because I'm
> currently experiencing some of the frustration that Peter commonly
> complains about.

Thanks for bringing this up in such a constructive manner.
I'm sympathetic to these concerns.

> Then I went to Documentation/filesystems/path-lookup.rst, and found
> myself constantly re-reading the same paragraph over again, and losing
> track of what I'm reading. I realized it wasn't due to the writing, but
> due to the constant inserted markup of quotes, that makes it terribly
> annoying to read, and unfortunately, not enjoyable at all.
> 
> For example:
> 
> > 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 those "xxx``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() <execveat_>`_ passing
> > the file descriptor, an empty path, and the ``AT_EMPTY_PATH`` flag.
> 
> All those `` are throwing me off to understanding what is being written.
> 
> I don't even know what those are suppose to represent.

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
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?

[1] Too far being a subjective measure, of course.  My preferences
are on display in core-api/xarray.rst

  parent reply index

Thread overview: 16+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-07-24 17:22 Steven Rostedt
2020-07-24 17:33 ` Jonathan Corbet
2020-07-24 18:42   ` Steven Rostedt
2020-07-24 23:46     ` NeilBrown
2020-07-29 12:44       ` peterz
2020-08-05 14:49         ` Vegard Nossum
2020-08-05 15:12           ` peterz
2020-08-06  6:48             ` Christoph Hellwig
2020-08-06  8:36               ` Vegard Nossum
2020-07-28 12:52   ` peterz
2020-07-28 15:28     ` Steven Rostedt
2020-07-29  9:36       ` peterz
2020-07-24 17:41 ` Matthew Wilcox [this message]
2020-07-24 18:14   ` David Sterba
2020-07-24 18:51   ` Steven Rostedt
2020-07-24 23:58     ` NeilBrown

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200724174130.GC23808@casper.infradead.org \
    --to=willy@infradead.org \
    --cc=corbet@lwn.net \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=peterz@infradead.org \
    --cc=rostedt@goodmis.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Linux-Doc Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-doc/0 linux-doc/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-doc linux-doc/ https://lore.kernel.org/linux-doc \
		linux-doc@vger.kernel.org
	public-inbox-index linux-doc

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.linux-doc


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git