[PATCH] doc: Explain light-handed markup preference a bit better
From: Daniel Vetter
Date: Wed Dec 14 2016 - 08:47:25 EST
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.
- 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
- 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
- Rebase onto docs-4.10.
- Go with the more terse recommendation from Jani, defer to the much
more detailed conversion guide Mauro is working on for details.
Cc: Jonathan Corbet <corbet@xxxxxxx>
Cc: Christoph Hellwig <hch@xxxxxxxxxxxxx>
Cc: Peter Zijlstra <peterz@xxxxxxxxxxxxx>
Cc: Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx>
Cc: Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>
Signed-off-by: Daniel Vetter <daniel.vetter@xxxxxxxxx>
Documentation/doc-guide/sphinx.rst | 17 ++++++++++++++++-
1 file changed, 16 insertions(+), 1 deletion(-)
diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index 96fe7ccb2c67..532d65b70500 100644
@@ -73,7 +73,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. For the most part the documentation should be plain text with
+ just enough consistency in formatting that it can be converted to
+ other formats.
+* Please keep the formatting changes minimal when converting existing
+ documentation to reStructuredText.
+* Also update the content, not just the formatting, when converting
* Please stick to this order of heading adornments:
@@ -103,6 +112,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:: <language>`` for longer code blocks that benefit
+ from highlighting.
the C domain