Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932513AbcLGP5h (ORCPT ); Wed, 7 Dec 2016 10:57:37 -0500 Received: from mail-wm0-f66.google.com ([74.125.82.66]:33209 "EHLO mail-wm0-f66.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S932371AbcLGP5f (ORCPT ); Wed, 7 Dec 2016 10:57:35 -0500 From: Daniel Vetter To: LKML Cc: Daniel Vetter , Jonathan Corbet , linux-doc@vger.kernel.org, Christoph Hellwig , Peter Zijlstra , Jani Nikula , Mauro Carvalho Chehab , Daniel Vetter Subject: [PATCH] doc: Explain light-handed markup preference a bit better Date: Wed, 7 Dec 2016 16:42:58 +0100 Message-Id: <20161207154258.23333-1-daniel.vetter@ffwll.ch> X-Mailer: git-send-email 2.10.2 Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 3490 Lines: 79 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. v2: - Mention that existing headings should be kept when converting existing .txt files (Mauro). - Explain that we prefer :: for quoting code, it's easier on the eyes (Mauro). - Explain that blindly converting outdated docs is harmful. Motived by comments Peter did in our discussion. v3: Make the explanations around fixed-width quoting more concise (Jani). Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Cc: Christoph Hellwig Cc: Peter Zijlstra Cc: Jani Nikula Cc: Mauro Carvalho Chehab Signed-off-by: Daniel Vetter --- Documentation/kernel-documentation.rst | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst index 0dd17069bc0b..5bffe5a418aa 100644 --- a/Documentation/kernel-documentation.rst +++ b/Documentation/kernel-documentation.rst @@ -77,9 +77,27 @@ 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. 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. -* Please stick to this order of heading adornments: + Be especially considerate when converting existing 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. + +* Don't just blindly convert documents, also carefully review them and fix up + any issues in the text itself. Updated docs might trick readers into believing + they're accurately reflecting current best practice, which would be rather + harmful if the text itself is entirely outdated. + +* When converting existing documents, please try to retain the existing heading + styles as much as possible. Sphinx accept almost anything, as long as it's + consistent and headings all start in column 1. + + For new documents please stick to this order of heading adornments: 1. ``=`` with overline for document title:: @@ -107,6 +125,12 @@ Here are some specific guidelines for the kernel documentation: the order as encountered."), having the higher levels the same overall makes it easier to follow the documents. +* For inserting fixed width text blocks (for code examples, use case + examples, etc.), use ``::`` for anything that doesn't really benefit + from syntax highlighting, especially short snippets. Use + ``.. code-block:: `` for longer code blocks that benefit + from highlighting. + the C domain ------------ -- 2.10.2