[lkml]   [2016]   [Nov]   [28]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
Messages in this thread
SubjectRe: [PATCH] doc: Explain light-handed markup preference a bit better
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:
> 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.


 \ /
  Last update: 2016-11-28 18:52    [W:0.029 / U:0.492 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site