From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1757287AbcK2NR7 (ORCPT ); Tue, 29 Nov 2016 08:17:59 -0500 Received: from mail-wm0-f67.google.com ([74.125.82.67]:36364 "EHLO mail-wm0-f67.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1755393AbcK2NRv (ORCPT ); Tue, 29 Nov 2016 08:17:51 -0500 Date: Tue, 29 Nov 2016 14:17:52 +0100 From: Daniel Vetter To: LKML , Peter Zijlstra Cc: Daniel Vetter , Jonathan Corbet , linux-doc@vger.kernel.org, Christoph Hellwig , Peter Zijlstra , Jani Nikula , Mauro Carvalho Chehab , Daniel Vetter Subject: Re: [PATCH] doc: Explain light-handed markup preference a bit better Message-ID: <20161129131752.63443vbvoudxe6sy@phenom.ffwll.local> Mail-Followup-To: LKML , Peter Zijlstra , Jonathan Corbet , linux-doc@vger.kernel.org, Christoph Hellwig , Jani Nikula , Mauro Carvalho Chehab , Daniel Vetter References: <20161129092314.351-1-daniel.vetter@ffwll.ch> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20161129092314.351-1-daniel.vetter@ffwll.ch> X-Operating-System: Linux phenom 4.8.0-1-amd64 User-Agent: NeoMutt/20161104 (1.7.1) Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Hi Peter, On Tue, Nov 29, 2016 at 10:23:14AM +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. > > v2: > - Mention that existing headings should be kept when converting > existing .txt files (Mauro). > - Explain that we prefer :: for quoting code, it's easier on the > eyes (Mauro). > - Explain that blindly converting outdated docs is harmful. Motived > by comments Peter did in our discussion. > > 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 Since this was motivated by a discussion you've (re)started, does this sufficiently address your concerns for conversion from plain text .txt to plain text .rst of existing documents? Anything you'd want to see changed? Thanks, Daniel > --- > Documentation/kernel-documentation.rst | 44 ++++++++++++++++++++++++++++++++-- > 1 file changed, 42 insertions(+), 2 deletions(-) > > diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst > index 0dd17069bc0b..d04cecdb498d 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. > + > +* Don't just blindly convert documents, also carefully review them and fix up > + any issues in the text itself. Updated docs might trick readers into believing > + they're accurately reflecting current best practice, which would be rather > + harmful if the text itself is entirely outdated. > + > +* When converting existing documents, please try to retain the existing heading > + styles as much as possible. Sphinx accept almost anything, as long as it's > + consistent and headings all start in column 1. > + > + For new documents please stick to this order of heading adornments: > > 1. ``=`` with overline for document title:: > > @@ -136,6 +154,28 @@ changed to ``VIDIOC_LOG_STATUS`` and the function can now referenced by: > :c:func:`VIDIOC_LOG_STATUS` > > > +For inserting code examples and use-cases use the simple fixed-width quoting > +style ``::`` which can either be on a line of it's own, or at the end of a > +preceeding paragraph. If there's no space before the double-colon it will be > +converted to a normal ``:``, which makes the overall text flow fairly reasonable > + > +.. code-block:: rst > + > + Some text explaing what you need to do:: > + > + code_example() > + > + More text explaining the next step:: > + > + if (condition) > + more_function_calls(); > + > + > +Sphinx also supports ``.. code-block::`` annotations, which also allow you to > +specify the language used for hightlight. But that should only be used when > +really necessary. > + > + > list tables > ----------- > > -- > 2.10.2 > -- Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch