* 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
* Re: Minor RST rant 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-28 12:52 ` peterz 2020-07-24 17:41 ` Matthew Wilcox 1 sibling, 2 replies; 16+ messages in thread From: Jonathan Corbet @ 2020-07-24 17:33 UTC (permalink / raw) To: Steven Rostedt; +Cc: Peter Zijlstra, linux-doc, LKML, Neil Brown 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 ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Minor RST rant 2020-07-24 17:33 ` Jonathan Corbet @ 2020-07-24 18:42 ` Steven Rostedt 2020-07-24 23:46 ` NeilBrown 2020-07-28 12:52 ` peterz 1 sibling, 1 reply; 16+ messages in thread From: Steven Rostedt @ 2020-07-24 18:42 UTC (permalink / raw) To: Jonathan Corbet; +Cc: Peter Zijlstra, linux-doc, LKML, Neil Brown 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 ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Minor RST rant 2020-07-24 18:42 ` Steven Rostedt @ 2020-07-24 23:46 ` NeilBrown 2020-07-29 12:44 ` peterz 0 siblings, 1 reply; 16+ messages in thread From: NeilBrown @ 2020-07-24 23:46 UTC (permalink / raw) To: Steven Rostedt, Jonathan Corbet; +Cc: Peter Zijlstra, linux-doc, LKML [-- 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 --] ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Minor RST rant 2020-07-24 23:46 ` NeilBrown @ 2020-07-29 12:44 ` peterz 2020-08-05 14:49 ` Vegard Nossum 0 siblings, 1 reply; 16+ messages in thread From: peterz @ 2020-07-29 12:44 UTC (permalink / raw) To: NeilBrown; +Cc: Steven Rostedt, Jonathan Corbet, linux-doc, LKML 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. ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Re: Minor RST rant 2020-07-29 12:44 ` peterz @ 2020-08-05 14:49 ` Vegard Nossum 2020-08-05 15:12 ` peterz 0 siblings, 1 reply; 16+ messages in thread From: Vegard Nossum @ 2020-08-05 14:49 UTC (permalink / raw) To: peterz, NeilBrown; +Cc: Steven Rostedt, Jonathan Corbet, linux-doc, LKML 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 ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Re: Minor RST rant 2020-08-05 14:49 ` Vegard Nossum @ 2020-08-05 15:12 ` peterz 2020-08-06 6:48 ` Christoph Hellwig 0 siblings, 1 reply; 16+ messages in thread From: peterz @ 2020-08-05 15:12 UTC (permalink / raw) To: Vegard Nossum; +Cc: NeilBrown, Steven Rostedt, Jonathan Corbet, linux-doc, LKML 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. ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Minor RST rant 2020-08-05 15:12 ` peterz @ 2020-08-06 6:48 ` Christoph Hellwig 2020-08-06 8:36 ` Vegard Nossum 0 siblings, 1 reply; 16+ messages in thread From: Christoph Hellwig @ 2020-08-06 6:48 UTC (permalink / raw) To: peterz Cc: Vegard Nossum, NeilBrown, Steven Rostedt, Jonathan Corbet, linux-doc, LKML 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. ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Minor RST rant 2020-08-06 6:48 ` Christoph Hellwig @ 2020-08-06 8:36 ` Vegard Nossum 0 siblings, 0 replies; 16+ messages in thread From: Vegard Nossum @ 2020-08-06 8:36 UTC (permalink / raw) To: Christoph Hellwig, peterz Cc: NeilBrown, Steven Rostedt, Jonathan Corbet, linux-doc, LKML 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 ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Minor RST rant 2020-07-24 17:33 ` Jonathan Corbet 2020-07-24 18:42 ` Steven Rostedt @ 2020-07-28 12:52 ` peterz 2020-07-28 15:28 ` Steven Rostedt 1 sibling, 1 reply; 16+ messages in thread From: peterz @ 2020-07-28 12:52 UTC (permalink / raw) To: Jonathan Corbet; +Cc: Steven Rostedt, linux-doc, LKML, Neil Brown 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. ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Minor RST rant 2020-07-28 12:52 ` peterz @ 2020-07-28 15:28 ` Steven Rostedt 2020-07-29 9:36 ` peterz 0 siblings, 1 reply; 16+ messages in thread From: Steven Rostedt @ 2020-07-28 15:28 UTC (permalink / raw) To: peterz; +Cc: Jonathan Corbet, linux-doc, LKML, Neil Brown 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 ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Minor RST rant 2020-07-28 15:28 ` Steven Rostedt @ 2020-07-29 9:36 ` peterz 0 siblings, 0 replies; 16+ messages in thread From: peterz @ 2020-07-29 9:36 UTC (permalink / raw) To: Steven Rostedt; +Cc: Jonathan Corbet, linux-doc, LKML, Neil Brown 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 ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Minor RST rant 2020-07-24 17:22 Minor RST rant Steven Rostedt 2020-07-24 17:33 ` Jonathan Corbet @ 2020-07-24 17:41 ` Matthew Wilcox 2020-07-24 18:14 ` David Sterba 2020-07-24 18:51 ` Steven Rostedt 1 sibling, 2 replies; 16+ messages in thread From: Matthew Wilcox @ 2020-07-24 17:41 UTC (permalink / raw) To: Steven Rostedt; +Cc: Jonathan Corbet, Peter Zijlstra, linux-doc, LKML 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 ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Minor RST rant 2020-07-24 17:41 ` Matthew Wilcox @ 2020-07-24 18:14 ` David Sterba 2020-07-24 18:51 ` Steven Rostedt 1 sibling, 0 replies; 16+ messages in thread From: David Sterba @ 2020-07-24 18:14 UTC (permalink / raw) To: Matthew Wilcox Cc: Steven Rostedt, Jonathan Corbet, Peter Zijlstra, linux-doc, LKML 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. ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Minor RST rant 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 1 sibling, 1 reply; 16+ messages in thread From: Steven Rostedt @ 2020-07-24 18:51 UTC (permalink / raw) To: Matthew Wilcox; +Cc: Jonathan Corbet, Peter Zijlstra, linux-doc, LKML 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 ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: Minor RST rant 2020-07-24 18:51 ` Steven Rostedt @ 2020-07-24 23:58 ` NeilBrown 0 siblings, 0 replies; 16+ messages in thread From: NeilBrown @ 2020-07-24 23:58 UTC (permalink / raw) To: Steven Rostedt, Matthew Wilcox Cc: Jonathan Corbet, Peter Zijlstra, linux-doc, LKML [-- 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 --] ^ permalink raw reply [flat|nested] 16+ messages in thread
end of thread, other threads:[~2020-08-06 11:05 UTC | newest] 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
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).