From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752840AbcK1Rvg (ORCPT ); Mon, 28 Nov 2016 12:51:36 -0500 Received: from ec2-52-27-115-49.us-west-2.compute.amazonaws.com ([52.27.115.49]:40203 "EHLO osg.samsung.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1751203AbcK1Rv3 (ORCPT ); Mon, 28 Nov 2016 12:51:29 -0500 Date: Mon, 28 Nov 2016 15:51:21 -0200 From: Mauro Carvalho Chehab To: Daniel Vetter Cc: LKML , Jonathan Corbet , linux-doc@vger.kernel.org, Christoph Hellwig , Peter Zijlstra , Jani Nikula , Daniel Vetter Subject: Re: [PATCH] doc: Explain light-handed markup preference a bit better Message-ID: <20161128155121.31b7b689@vento.lan> In-Reply-To: <20161128161622.906-1-daniel.vetter@ffwll.ch> References: <20161128161622.906-1-daniel.vetter@ffwll.ch> Organization: Samsung X-Mailer: Claws Mail 3.14.0 (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 Em Mon, 28 Nov 2016 17:16:22 +0100 Daniel Vetter escreveu: > 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. Good idea! Please see below for some suggestions. > > Cc: Jonathan Corbet > Cc: linux-doc@vger.kernel.org > Cc: Christoph Hellwig > Cc: Peter Zijlstra > Cc: Jani Nikula > Cc: Mauro Carvalho Chehab > Signed-off-by: Daniel Vetter > --- > Documentation/kernel-documentation.rst | 11 ++++++++++- > 1 file changed, 10 insertions(+), 1 deletion(-) > > diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst > index 0dd17069bc0b..ceb17d428278 100644 > --- a/Documentation/kernel-documentation.rst > +++ b/Documentation/kernel-documentation.rst > @@ -77,7 +77,16 @@ 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. And > + 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. > + > + Be especially considerate when converting existing .txt 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. Looks good to me. > * Please stick to this order of heading adornments: I would actually relax the heading adornments order. IMHO, if a document to be converted has already some adornments order, the best is to just keep using them. So, IMHO, I would be changing the above to: * Please stick to the heading adornments that are already present on a document, if you're converting it to ReST. If you're writing it from scratch, please prefer this order of heading adornments: I would also mention to prefer using "::" over ".. code-block::" when converting existing documents. Thanks, Mauro