Linux-Doc Archive on lore.kernel.org
 help / color / Atom feed
From: Steven Rostedt <rostedt@goodmis.org>
To: peterz@infradead.org
Cc: Jonathan Corbet <corbet@lwn.net>,
	linux-doc@vger.kernel.org, LKML <linux-kernel@vger.kernel.org>,
	Neil Brown <neilb@suse.de>
Subject: Re: Minor RST rant
Date: Tue, 28 Jul 2020 11:28:28 -0400
Message-ID: <20200728112828.459307a5@oasis.local.home> (raw)
In-Reply-To: <20200728125252.GW119549@hirez.programming.kicks-ass.net>

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

  reply index

Thread overview: 16+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-07-24 17:22 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 [this message]
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

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200728112828.459307a5@oasis.local.home \
    --to=rostedt@goodmis.org \
    --cc=corbet@lwn.net \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=neilb@suse.de \
    --cc=peterz@infradead.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Linux-Doc Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-doc/0 linux-doc/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-doc linux-doc/ https://lore.kernel.org/linux-doc \
		linux-doc@vger.kernel.org
	public-inbox-index linux-doc

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.linux-doc


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git