Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1754282AbcLLRrb (ORCPT ); Mon, 12 Dec 2016 12:47:31 -0500 Received: from ec2-52-27-115-49.us-west-2.compute.amazonaws.com ([52.27.115.49]:51287 "EHLO osg.samsung.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1754233AbcLLRr3 (ORCPT ); Mon, 12 Dec 2016 12:47:29 -0500 Date: Mon, 12 Dec 2016 15:47:21 -0200 From: Mauro Carvalho Chehab To: Daniel Vetter Cc: Jonathan Corbet , Jani Nikula , LKML , Linux Doc Mailing List , Christoph Hellwig , Peter Zijlstra , Daniel Vetter Subject: Re: [PATCH] doc: Explain light-handed markup preference a bit better Message-ID: <20161212154721.6b9f5db2@vento.lan> In-Reply-To: References: <20161207154258.23333-1-daniel.vetter@ffwll.ch> <20161207123924.4a47d777@lwn.net> <20161208071021.5cd73ec8@vento.lan> Organization: Samsung X-Mailer: Claws Mail 3.14.1 (GTK+ 2.24.31; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 3961 Lines: 82 Em Thu, 8 Dec 2016 23:06:57 +0100 Daniel Vetter escreveu: > On Thu, Dec 8, 2016 at 10:10 AM, Mauro Carvalho Chehab > wrote: > > Em Wed, 7 Dec 2016 12:39:24 -0700 > > Jonathan Corbet escreveu: > > > >> On Wed, 7 Dec 2016 16:42:58 +0100 > >> Daniel Vetter wrote: > >> > >> > We already had a super-short blurb, but worth extending it I think: > >> > We're still pretty far away from anything like a consensus, but > >> > there's clearly a lot of people who prefer an as-light as possible > >> > approach to converting existing .txt files to .rst. Make sure this is > >> > properly taken into account and clear. > >> > > >> > Motivated by discussions with Peter and Christoph and others. > >> > >> I do think we should put something in to guide people in the right > >> direction. And yes, it should, itself, be light-handed and minimal. > >> > >> [...] > >> > >> > Documentation/kernel-documentation.rst | 28 ++++++++++++++++++++++++++-- > >> > 1 file changed, 26 insertions(+), 2 deletions(-) > >> > >> I do, however, also believe that it should apply to relatively recent > >> docs-next :) > >> > >> > diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst > >> > index 0dd17069bc0b..5bffe5a418aa 100644 > >> > --- a/Documentation/kernel-documentation.rst > >> > +++ b/Documentation/kernel-documentation.rst > >> > @@ -77,9 +77,27 @@ Specific guidelines for the kernel documentation > >> > > >> > Here are some specific guidelines for the kernel documentation: > >> > > >> > -* Please don't go overboard with reStructuredText markup. Keep it simple. > >> > +* Please don't go overboard with reStructuredText markup. Keep it simple. A lot > >> > + of core kernel developers prefer plain text, with a big emphasis on plain. In > >> > + the end if we have pretty generated docs which the subject experts don't > >> > + like to edit and keep up-to-date everyone loses. > >> > > >> > -* Please stick to this order of heading adornments: > >> > + Be especially considerate when converting existing documentation. There's a > >> > + wide scale from annotating every little bit with in-line styles to only > >> > + touching up the bare minimum needed to integrate an existing file into the > >> > + larger documentation. Please align with the wishes of the maintainer to make > >> > + sure that documentations stays useful for everyone. > >> > >> I think this is about where I figured out why I'm not 100% ready to jump on > >> this. What we're doing here is mixing two things: information on how to > >> write documents, and information on how to convert existing documents. > >> > >> I'm not really opposed to applying the patch as-is, but I do wonder if what > >> we really need is a new section aimed specifically at people doing > >> conversions? The concerns *are* a bit different, and there's more > >> information we could put into a conversion section that isn't relevant to > >> others. Plus we could remove it some day far in the future when > >> everything's converted :) > > > > Yeah, a "conversion guide" section seems interesting. In the case of > > media, for example, we prefer to use as much as ReST provides, as nobody > > cares that the doc source would be as readable as the html/pdf output. > > So, we want to be sure that the enriched text output would look better > > to the ones using the documentation. > > > > In that case, I would go for something close to the text I wrote to Peter > > sometime ago: > > Hm yeah, separate conversion section makes sense. In that case I'll > adopt Jani's suggestion for more terseness in overview document, and > we can merge Mauro's proposal (or something like it) on top. And I'll > try to rebase onto latest doc-next too ;-) > > Does that sound like a plan, before I head of and respin v4? Sounds like a plan to me :-) Regards, Mauro