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
> Cc: linux-doc@vger.kernel.org
> Cc: Christoph Hellwig
> Cc: Peter Zijlstra
> Cc: Jani Nikula
> Cc: Mauro Carvalho Chehab
> Signed-off-by: Daniel Vetter
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:: `` for longer code blocks that benefit
> + from highlighting.
> +
>
> the C domain
>
> --
> 2.11.0
>
--
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html