lkml.org 
[lkml]   [2020]   [Jul]   [24]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    Date
    From
    SubjectRe: Minor RST rant
    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

    \
     
     \ /
      Last update: 2020-07-24 20:52    [W:4.108 / U:0.276 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site