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

[Mauro Carvalho Chehab]

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.

Thanks,
Mauro