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.
Cc: Jonathan Corbet <[email protected]>
Cc: [email protected]
Cc: Christoph Hellwig <[email protected]>
Cc: Peter Zijlstra <[email protected]>
Cc: Jani Nikula <[email protected]>
Cc: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Daniel Vetter <[email protected]>
---
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.
* Please stick to this order of heading adornments:
--
2.10.2
Em Mon, 28 Nov 2016 17:16:22 +0100
Daniel Vetter <[email protected]> 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 <[email protected]>
> Cc: [email protected]
> Cc: Christoph Hellwig <[email protected]>
> Cc: Peter Zijlstra <[email protected]>
> Cc: Jani Nikula <[email protected]>
> Cc: Mauro Carvalho Chehab <[email protected]>
> Signed-off-by: Daniel Vetter <[email protected]>
> ---
> 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