linux-kernel - Re: Minor RST rant

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <871rl0v51w.fsf@notabene.neil.brown.name>
Date:   Sat, 25 Jul 2020 09:58:35 +1000
From:   NeilBrown <neilb@...e.de>
To:     Steven Rostedt <rostedt@...dmis.org>,
        Matthew Wilcox <willy@...radead.org>
Cc:     Jonathan Corbet <corbet@....net>,
        Peter Zijlstra <peterz@...radead.org>,
        linux-doc@...r.kernel.org, LKML <linux-kernel@...r.kernel.org>
Subject: Re: Minor RST rant

On Fri, Jul 24 2020, Steven Rostedt wrote:

> On Fri, 24 Jul 2020 18:41:30 +0100
> Matthew Wilcox <willy@...radead.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

Download attachment "signature.asc" of type "application/pgp-signature" (833 bytes)