Minor RST rant

Minor RST rant

[Steven Rostedt]

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

Re: Minor RST rant

[Jonathan Corbet]

On Fri, 24 Jul 2020 13:22:00 -0400
Steven Rostedt <rostedt@goodmis.org> wrote:

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

Give people a tool, some of them will make more use of it than you might
like. I do my best to push back against excessive markup (which all of the
above qualifies as, as far as I'm concerned), but I can't really even do
that will all that goes through my tree, much less all the docs stuff
merged by others.

The markup in question was seemingly added by Neil; I've added him to CC
in case he wants to comment on it.

I'm not sure what to do other than to continue to push for minimal use of
intrusive markup.

jon

Re: Minor RST rant

[Matthew Wilcox]

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

Re: Minor RST rant

[David Sterba]

On Fri, Jul 24, 2020 at 06:41:30PM +0100, Matthew Wilcox wrote:
> 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

I like that minimalistic style and I'd suggest to use the quotes only
for the document-specific definitions, eg. the XA_ macros, and drop
quotes around NULL or other standard macros like LONG_MAX.  The quotes
are hilighted in vim and seeing NULL is actually distracting.

Functions get automatically converted to html links so this does not
need to be explicitly quoted, but similar to wikipedia style, the first
mention could be quoted to provide a visual anchor.

Re: Minor RST rant

[Steven Rostedt]

On Fri, 24 Jul 2020 11:33:25 -0600
Jonathan Corbet <corbet@lwn.net> wrote:

> Give people a tool, some of them will make more use of it than you might
> like. I do my best to push back against excessive markup (which all of the
> above qualifies as, as far as I'm concerned), but I can't really even do
> that will all that goes through my tree, much less all the docs stuff
> merged by others.
> 
> The markup in question was seemingly added by Neil; I've added him to CC
> in case he wants to comment on it.

I saw Neil as the author and should have Cc'd him.

Neil, you can read my full email here:

  https://lore.kernel.org/r/20200724132200.51fd2065@oasis.local.home

> 
> I'm not sure what to do other than to continue to push for minimal use of
> intrusive markup.

Yeah, I really didn't expect an action item to come from this. It was
just some feedback, and perhaps you can use this as an example of "too
much markup" when dealing with others.

Looking at the web page that Matthew pointed out to, does make it much
easier to read. But one still needs to remember that a large audience
of this work is still those of us that will read the plain text.

My viewer of choice is "less" ;-)

-- Steve

Re: Minor RST rant

[Steven Rostedt]

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

Re: Minor RST rant

[NeilBrown]

[-- Attachment #1: Type: text/plain, Size: 2810 bytes --]

On Fri, Jul 24 2020, Steven Rostedt wrote:

> On Fri, 24 Jul 2020 11:33:25 -0600
> Jonathan Corbet <corbet@lwn.net> wrote:
>
>> Give people a tool, some of them will make more use of it than you might
>> like. I do my best to push back against excessive markup (which all of the
>> above qualifies as, as far as I'm concerned), but I can't really even do
>> that will all that goes through my tree, much less all the docs stuff
>> merged by others.
>> 
>> The markup in question was seemingly added by Neil; I've added him to CC
>> in case he wants to comment on it.
>
> I saw Neil as the author and should have Cc'd him.
>
> Neil, you can read my full email here:
>
>   https://lore.kernel.org/r/20200724132200.51fd2065@oasis.local.home
>
>> 
>> I'm not sure what to do other than to continue to push for minimal use of
>> intrusive markup.
>
> Yeah, I really didn't expect an action item to come from this. It was
> just some feedback, and perhaps you can use this as an example of "too
> much markup" when dealing with others.
>
> Looking at the web page that Matthew pointed out to, does make it much
> easier to read. But one still needs to remember that a large audience
> of this work is still those of us that will read the plain text.
>
> My viewer of choice is "less" ;-)
>
> -- Steve

Hi Steven,
 thanks for your rants - and under appreciated art form I believe.

 Short answer is: I don't much care and if someone were to remove the
 markup, I possibly wouldn't even notice and certainly wouldn't object.

 Longer answer is that I think visual appearance is important.  I
 originally wrote that document as an article for lwn.net.  I wanted the
 code fragments - even when a single word like AT_EMPTY_PATH - to be
 rendered like code (constant-width font).  The markdown markup for that
 is  `code goes here`, so that is what I sent to Jon (he graciously uses
 a markdown-to-html tool to munge what I send), and that is what I
 placed in Documentation.
 I subsequently converted this to rst (7bbfd9ad8eb2) which involved
 converting single ` to double ``.
 I agree this was not an improvement when reading the text, but maybe
 that is the price of using rst.  Or maybe the price is not being able
 to say what you mean.

 A brief look over the file suggests that most uses of `` are to
 highlight one of:
    - paths
    - function names
    - constant names.

 All these must be used widely throughout the documentation - whatever
 is the common standard should definitely be imposed.
 Constant names stand out least effectively by themselves.  In
 kernel-doc comments they are preceded by a '%'.  Would that make the
 text more readable for you?  Does our doc infrastructure honour that in
 .rst documents?

Thanks,
NeilBrown

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

Re: Minor RST rant

[NeilBrown]

[-- Attachment #1: Type: text/plain, Size: 3128 bytes --]

On Fri, Jul 24 2020, Steven Rostedt wrote:

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

Do you read Jane Austen at all?

   "I certainly have not the talent which some people possess," said
   Darcy, "of conversing easily with those I have never seen before.
   I cannot catch their tone of conversation, or appear interested
   in their concerns, as I often see done."

   "My fingers," said Elizabeth, "do not move over this instrument
   in the masterly manner which I see so many women's do.  They
   have not the same force or rapidity, and do not produce the
   same expression.  But then I have always supposed it to be my
   own fault--because I will not take the trouble of practising."

:-)
NeilBrown


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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

Re: Minor RST rant

[peterz]

On Fri, Jul 24, 2020 at 11:33:25AM -0600, Jonathan Corbet wrote:

> I'm not sure what to do other than to continue to push for minimal use of
> intrusive markup.

Perhaps make it clearer in:

  Documentation/doc-guide/

because people claim they follow that, but the result is that I get
completely unreadable garbage from them.

Like I've written many times before, I'm starting to loathe RST, it's an
absolute failure. I'm near the point where I'm looking to write a script
that will silently convert any RST crap to plain text in my commit
script.

Re: Minor RST rant

[Steven Rostedt]

On Tue, 28 Jul 2020 14:52:52 +0200
peterz@infradead.org wrote:

> On Fri, Jul 24, 2020 at 11:33:25AM -0600, Jonathan Corbet wrote:
> 
> > I'm not sure what to do other than to continue to push for minimal use of
> > intrusive markup.  
> 
> Perhaps make it clearer in:
> 
>   Documentation/doc-guide/

Well, it's currently in:

https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#specific-guidelines-for-the-kernel-documentation

	Please don’t go overboard with reStructuredText markup. Keep it
	simple. For the most part the documentation should be plain text
	with just enough consistency in formatting that it can be
	converted to other formats.

But perhaps we should stress that in other locations and make it more
prevalent in the documentation.

> 
> because people claim they follow that, but the result is that I get
> completely unreadable garbage from them.
> 
> Like I've written many times before, I'm starting to loathe RST, it's an
> absolute failure. I'm near the point where I'm looking to write a script
> that will silently convert any RST crap to plain text in my commit
> script.

Sometimes I do look at the html output on kernel.org, and it is nicely
organized. The future of developers will probably prefer that format
over plain text whether we like it or not, so I encourage that we
continue using RST. That said, people still need to be very careful not
to make their markup in the text files focused so much on the html
output, that they make it unreadable for the rest of us.

I think Jon has been doing a great job at having the rst files still be
readable in their raw formats, but people still get carried away.
Instead of writing scripts to rip it out, we need to continue the
conversations to educate people that some of us need these files to
remain readable as plain text.

-- Steve

Re: Minor RST rant

[peterz]

On Tue, Jul 28, 2020 at 11:28:28AM -0400, Steven Rostedt wrote:
> Sometimes I do look at the html output on kernel.org, and it is nicely
> organized. The future of developers will probably prefer that format
> over plain text whether we like it or not, so I encourage that we

The future is doomed.

Anyway, the last time I checked, it was possible to select a monospace
font in HTML. For bonus points, use a green bar paper css [1], add
some line numbers, and use a daisy wheel font [2].

That renders any actual .txt document with style, even if you absolutely
must use a browser.


[1] https://gist.github.com/BigEd/56f6c0001c8670d1647d5448e91346d6
[2] https://www.dafont.com/daisy-wheel.font

Re: Minor RST rant

[peterz]

On Sat, Jul 25, 2020 at 09:46:55AM +1000, NeilBrown wrote:

>  Constant names stand out least effectively by themselves.  In
>  kernel-doc comments they are preceded by a '%'.  Would that make the
>  text more readable for you?  Does our doc infrastructure honour that in
>  .rst documents?

It does not. It also still reads really weird.

And for some reason firefox chokes on the HTML file I tried it with, and
make htmldocs takes for bloody ever.

Give me a plain text file, please. All this modern crap just doesn't
work.

Re: Re: Minor RST rant

[Vegard Nossum]

On 2020-07-29 14:44, peterz@infradead.org wrote:
> On Sat, Jul 25, 2020 at 09:46:55AM +1000, NeilBrown wrote:
> 
>>   Constant names stand out least effectively by themselves.  In
>>   kernel-doc comments they are preceded by a '%'.  Would that make the
>>   text more readable for you?  Does our doc infrastructure honour that in
>>   .rst documents?
> 
> It does not. It also still reads really weird.
> 
> And for some reason firefox chokes on the HTML file I tried it with, and
> make htmldocs takes for bloody ever.
> 
> Give me a plain text file, please. All this modern crap just doesn't
> work.
> 

FWIW, I *really* like how the extra markup renders in a browser, and I
don't think I'm the only one.

If you want to read .rst files in a terminal, I would suggest using
something like this:

$ pandoc -t plain Documentation/core-api/atomic_ops.rst | less

It looks pretty readable to me, things like lists and code are properly
indented, the only thing it's missing as far as I'm concerned is marking
headings more prominently.

The new online documentation is a great way to attract more people to
kernel development (and just spread typical kernel knowledge to
non-Linux/non-kernel programmers). The old Documentation/ was kind of
hidden away and you only really came across it by accident if you did a
treewide 'git grep'; the new online docs, on the other hand, are a
pleasure to browse and explore and frequently show up in google searches
for random kernel-related topics.


Vegard

Re: Re: Minor RST rant

[peterz]

On Wed, Aug 05, 2020 at 04:49:50PM +0200, Vegard Nossum wrote:
> FWIW, I *really* like how the extra markup renders in a browser, and I
> don't think I'm the only one.

The thing is, I write code in a text editor, not a browser. When a
header file says: read Documentation/foo I do 'gf' and that file gets
opened in a buffer.

Needing a browser is a fail.

> If you want to read .rst files in a terminal, I would suggest using
> something like this:
> 
> $ pandoc -t plain Documentation/core-api/atomic_ops.rst | less

That doesn't help me with people sending me that abysmal shite in diff
format.

Re: Minor RST rant

[Christoph Hellwig]

On Wed, Aug 05, 2020 at 05:12:30PM +0200, peterz@infradead.org wrote:
> On Wed, Aug 05, 2020 at 04:49:50PM +0200, Vegard Nossum wrote:
> > FWIW, I *really* like how the extra markup renders in a browser, and I
> > don't think I'm the only one.
> 
> The thing is, I write code in a text editor, not a browser. When a
> header file says: read Documentation/foo I do 'gf' and that file gets
> opened in a buffer.
> 
> Needing a browser is a fail.

And that is my main problem with all the RST craze.  It optmizes for
shiny display in a browser, but copletely messed up the typical
developer flow.

Re: Minor RST rant

[Vegard Nossum]

On 2020-08-06 08:48, Christoph Hellwig wrote:
> On Wed, Aug 05, 2020 at 05:12:30PM +0200, peterz@infradead.org wrote:
>> On Wed, Aug 05, 2020 at 04:49:50PM +0200, Vegard Nossum wrote:
>>> FWIW, I *really* like how the extra markup renders in a browser, and I
>>> don't think I'm the only one.
>>
>> The thing is, I write code in a text editor, not a browser. When a
>> header file says: read Documentation/foo I do 'gf' and that file gets
>> opened in a buffer.
>>
>> Needing a browser is a fail.
> 
> And that is my main problem with all the RST craze.  It optmizes for
> shiny display in a browser, but copletely messed up the typical
> developer flow.
> 

If you are using vim, you can put this in ~/.vim/after/syntax/rst.vim:

   syn region rstInlineLiteral matchgroup=Special start="``" end="``" 
concealends
   syn region rstEmphasis matchgroup=Special start="\*\*" end="\*\*" 
concealends
   setlocal conceallevel=2

This will hide the ``foo`` and **bar** markup on lines that are not
currently under the cursor.


Vegard