[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <74833f93f6082c7b44f4fa8a3093ea1a751d5539.camel@perches.com>
Date: Mon, 24 Jun 2019 15:37:42 -0700
From: Joe Perches <joe@...ches.com>
To: Jonathan Corbet <corbet@....net>
Cc: Gary R Hook <ghook@....com>, "Hook, Gary" <Gary.Hook@....com>,
"herbert@...dor.apana.org.au" <herbert@...dor.apana.org.au>,
"linux-doc@...r.kernel.org" <linux-doc@...r.kernel.org>,
"linux-kernel@...r.kernel.org" <linux-kernel@...r.kernel.org>,
"linux-crypto@...r.kernel.org" <linux-crypto@...r.kernel.org>,
"davem@...emloft.net" <davem@...emloft.net>
Subject: Re: [PATCH 0/3] Clean up crypto documentation
On Mon, 2019-06-24 at 14:37 -0600, Jonathan Corbet wrote:
> On Mon, 24 Jun 2019 13:29:42 -0700
> Joe Perches <joe@...ches.com> wrote:
>
> > > Finally, would you prefer a v2 of the patch set? Happy to do
> > > whatever is preferred, of course.
> >
> > Whatever Jonathan decides is fine with me.
> > Mine was just a plea to avoid unnecessarily
> > making the source text harder to read as
> > that's what I mostly use.
>
> Usually Herbert seems to take crypto docs, so it's not necessarily up to
> me :)
>
> I don't see much that's objectionable here. But...
>
> > I don't know if this extension is valid yet, but
> > I believe just using <function_name>() is more
> > readable as text than ``<function_name>`` or
> > :c:func:`<function_name>`
>
> It's been "valid" since I wrote it...it's just not upstream yet :) I
> expect it to be in 5.3, though. So the best way to refer to a kernel
> function, going forward, is just function() with no markup needed.
When that's actually "valid" I suggest doing:
$ git ls-files -- 'Documentation/*.rst' | \
xargs perl -pi -e 's/:c:func:`(\w+)(?:\(\))?`/\1()/g; s/``(\w+)\(\)``/\1()/g'
so function designations in Documentation are simpler to read.
Right now that's:
$ git diff --shortstat Documentation/
125 files changed, 1680 insertions(+), 1680 deletions(-)
Powered by blists - more mailing lists