Linux-Doc Archive on
 help / color / Atom feed
* Minor RST rant
@ 2020-07-24 17:22 Steven Rostedt
  2020-07-24 17:33 ` Jonathan Corbet
  2020-07-24 17:41 ` Matthew Wilcox
  0 siblings, 2 replies; 16+ messages in thread
From: Steven Rostedt @ 2020-07-24 17:22 UTC (permalink / raw)
  To: Jonathan Corbet; +Cc: Peter Zijlstra, linux-doc, LKML

Hi Jon,

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.

I'm looking into how to make the event directory tree be created on the
fly, and not waste a lot of space on all these dentry and inodes that
are allocated for the thousands of events in the kernel. This is to
also make instances have a smaller memory footprint since each instance
creates a copy of those 1000s of events. But I really don't understand
the VFS layer. I decided to jump into Documentation/filesystems and try
to learn how to do this for tracefs.

Now for my rant.

I just finished reading Documentation/filesystems/path-lookup.txt and
learned a lot. It was even an enjoyable read.

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.

Again, I really like the effort to pull all this useful information in
the Documentation directory into other formats that others can enjoy,
but this is just to give you some feedback where this format can be a
real distraction for those that much prefer to read a simple text file
than a web page or pdf file.

Just my $0.02.

-- Steve

^ permalink raw reply	[flat|nested] 16+ messages in thread

end of thread, back to index

Thread overview: 16+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-07-24 17:22 Minor RST rant 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
2020-07-24 18:14   ` David Sterba
2020-07-24 18:51   ` Steven Rostedt
2020-07-24 23:58     ` NeilBrown

Linux-Doc Archive on

Archives are clonable:
	git clone --mirror 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/ \
	public-inbox-index linux-doc

Example config snippet for mirrors

Newsgroup available over NNTP:

AGPL code for this site: git clone