lkml.org 
[lkml]   [2016]   [Nov]   [28]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [PATCH] doc: Explain light-handed markup preference a bit better
Em Mon, 28 Nov 2016 17:16:22 +0100
Daniel Vetter <daniel.vetter@ffwll.ch> 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@lwn.net>
> Cc: linux-doc@vger.kernel.org
> Cc: Christoph Hellwig <hch@infradead.org>
> Cc: Peter Zijlstra <peterz@infradead.org>
> Cc: Jani Nikula <jani.nikula@linux.intel.com>
> Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
> ---
> 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

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