Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1756114AbcK2KjH (ORCPT ); Tue, 29 Nov 2016 05:39:07 -0500 Received: from mga05.intel.com ([192.55.52.43]:19645 "EHLO mga05.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753150AbcK2Ki6 (ORCPT ); Tue, 29 Nov 2016 05:38:58 -0500 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.31,568,1473145200"; d="scan'208";a="792058177" From: Jani Nikula To: Daniel Vetter , LKML Cc: Daniel Vetter , Jonathan Corbet , linux-doc@vger.kernel.org, Christoph Hellwig , Peter Zijlstra , Mauro Carvalho Chehab , Daniel Vetter Subject: Re: [PATCH] doc: Explain light-handed markup preference a bit better In-Reply-To: <20161129092314.351-1-daniel.vetter@ffwll.ch> Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo References: <20161129092314.351-1-daniel.vetter@ffwll.ch> Date: Tue, 29 Nov 2016 12:38:55 +0200 Message-ID: <87k2bmtvsw.fsf@intel.com> MIME-Version: 1.0 Content-Type: text/plain Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 5941 Lines: 150 On Tue, 29 Nov 2016, 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. When I wrote most of the document originally, I put a lot of effort into make it clear and consice. I don't approve of the changes here. This is going to sound like bikeshedding, but I just couldn't make myself not reply. > 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 | 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. I wrote that, and I left it short intentionally. I really don't think prose will help here. This document is primarily a reference. Keep it as concise as you possibly can. I'd go with adding bullets along the lines of: --- * Please don't go overboard with reStructuredText markup. Keep it simple. For the most part the documentation should be plain text with just enough consistency in formatting that it can be converted to other formats. * Please keep the formatting changes minimal when converting existing documentation to reStructuredText. * Also update the content, not just the formatting, when converting documentation. --- I think those capture the essence. Less is more. Please note how I intentionally left out things like "core kernel developers prefer plain text", "please align with the wishes of the maintainer", "...would be rather harmful if the text itself is entirely outdated". Personally, I simply do not think they have a place here. > +* 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. I don't think this hunk belongs under "the C domain" section. I'd just stick it at the end of the earlier bullet list. Condensing from my earlier mail [1], I'd go with just: --- * For inserting fixed width text blocks (for code examples, use case examples, etc.), use ``::`` for anything that doesn't really benefit from syntax highlighting, especially short snippets. Use ``.. code-block:: `` for longer code blocks that benefit from highlighting. --- Again, I think this is a reference, not a tutorial. Please refer to Sphinx/reStructuredText documentation for details instead of duplicating the same information. BR, Jani. [1] http://mid.mail-archive.com/87y407tyvv.fsf@intel.com > + > + > list tables > ----------- -- Jani Nikula, Intel Open Source Technology Center