Re: Minor RST rant

NeilBrown
2020-07-24T23:58:45Z

[-- 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:
>
> AT_EMPTY_PATH
>
> 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 --]