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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite for Android: free password hash cracker in your pocket

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Date:   Mon, 28 Nov 2016 17:16:22 +0100
From:   Daniel Vetter <daniel.vetter@...ll.ch>
To:     LKML <linux-kernel@...r.kernel.org>
Cc:     Daniel Vetter <daniel.vetter@...ll.ch>,
        Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org,
        Christoph Hellwig <hch@...radead.org>,
        Peter Zijlstra <peterz@...radead.org>,
        Jani Nikula <jani.nikula@...ux.intel.com>,
        Mauro Carvalho Chehab <mchehab@...pensource.com>,
        Daniel Vetter <daniel.vetter@...el.com>
Subject: [PATCH] doc: Explain light-handed markup preference a bit better

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 <corbet@....net>
Cc: linux-doc@...r.kernel.org
Cc: Christoph Hellwig <hch@...radead.org>
Cc: Peter Zijlstra <peterz@...radead.org>
Cc: Jani Nikula <jani.nikula@...ux.intel.com>
Cc: Mauro Carvalho Chehab <mchehab@...pensource.com>
Signed-off-by: Daniel Vetter <daniel.vetter@...el.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.
 
 * Please stick to this order of heading adornments:
 
-- 
2.10.2