Linux-Doc Archive on lore.kernel.org
 help / color / Atom feed
From: NeilBrown <neilb@suse.de>
To: Steven Rostedt <rostedt@goodmis.org>, Jonathan Corbet <corbet@lwn.net>
Cc: Peter Zijlstra <peterz@infradead.org>,
	linux-doc@vger.kernel.org, LKML <linux-kernel@vger.kernel.org>
Subject: Re: Minor RST rant
Date: Sat, 25 Jul 2020 09:46:55 +1000
Message-ID: <877dusv5lc.fsf@notabene.neil.brown.name> (raw)
In-Reply-To: <20200724144234.3227b501@oasis.local.home>


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

  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 [this message]
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

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=877dusv5lc.fsf@notabene.neil.brown.name \
    --to=neilb@suse.de \
    --cc=corbet@lwn.net \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=peterz@infradead.org \
    --cc=rostedt@goodmis.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