summaryrefslogtreecommitdiffstats
path: root/Documentation/doc-guide
diff options
context:
space:
mode:
authorDaniel Vetter <daniel.vetter@ffwll.ch>2017-03-02 16:16:33 +0100
committerJonathan Corbet <corbet@lwn.net>2017-03-09 02:44:44 -0700
commitc3c53600f62b5fa92acf3a7f5eb71bacb25f6b01 (patch)
tree54dd60d1a770929617fc8979d10dbe717a21eaff /Documentation/doc-guide
parent54f5d13b708a64177d4437a2b23fb05035f90716 (diff)
downloadlinux-c3c53600f62b5fa92acf3a7f5eb71bacb25f6b01.tar.bz2
doc: Explain light-handed markup preference a bit better
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: 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> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'Documentation/doc-guide')
-rw-r--r--Documentation/doc-guide/sphinx.rst17
1 files changed, 16 insertions, 1 deletions
diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index 96fe7ccb2c67..532d65b70500 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -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
+ documentation.
* 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
------------