Re: [PATCH] doc: Explain light-handed markup preference a bit better

From: Mauro Carvalho Chehab
Date: Mon Nov 28 2016 - 12:51:39 EST

Em Mon, 28 Nov 2016 17:16:22 +0100
Daniel Vetter <daniel.vetter@xxxxxxxx> 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 <corbet@xxxxxxx>
> Cc: linux-doc@xxxxxxxxxxxxxxx
> Cc: Christoph Hellwig <hch@xxxxxxxxxxxxx>
> Cc: Peter Zijlstra <peterz@xxxxxxxxxxxxx>
> Cc: Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx>
> Cc: Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>
> Signed-off-by: Daniel Vetter <daniel.vetter@xxxxxxxxx>
> ---
> 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.