[PATCH 1/6] doc: Explain light-handed markup preference a bit better

[Daniel Vetter]

On Thu, Mar 02, 2017 at 04:16:33PM +0100, Daniel Vetter wrote:
> 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).
> 
> v4:
> - 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 at lwn.net>
> Cc: linux-doc at vger.kernel.org
> Cc: Christoph Hellwig <hch at infradead.org>
> Cc: Peter Zijlstra <peterz at infradead.org>
> Cc: Jani Nikula <jani.nikula at linux.intel.com>
> Cc: Mauro Carvalho Chehab <mchehab at s-opensource.com>
> Signed-off-by: Daniel Vetter <daniel.vetter at intel.com>

Jon, can you pls pick this one up, or want me to resend stand-alone?

Thanks, Daniel
> ---
>  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
> --- 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
>  ------------
> -- 
> 2.11.0
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch