Re: [PATCH] doc: Explain light-handed markup preference a bit better

[Daniel Vetter <daniel@ffwll.ch>]

Hi Peter,

On Tue, Nov 29, 2016 at 10:23:14AM +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.
> 
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: linux-doc@vger.kernel.org
> 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>

Since this was motivated by a discussion you've (re)started, does this
sufficiently address your concerns for conversion from plain text .txt to
plain text .rst of existing documents? Anything you'd want to see changed?

Thanks, Daniel

> ---
>  Documentation/kernel-documentation.rst | 44 ++++++++++++++++++++++++++++++++--
>  1 file changed, 42 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst
> index 0dd17069bc0b..d04cecdb498d 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::
>  
> @@ -136,6 +154,28 @@ changed to ``VIDIOC_LOG_STATUS`` and the function can now referenced by:
>       :c:func:`VIDIOC_LOG_STATUS`
>  
>  
> +For inserting code examples and use-cases use the simple fixed-width quoting
> +style ``::`` which can either be on a line of it's own, or at the end of a
> +preceeding paragraph. If there's no space before the double-colon it will be
> +converted to a normal ``:``, which makes the overall text flow fairly reasonable
> +
> +.. code-block:: rst
> +
> +     Some text explaing what you need to do::
> +
> +        code_example()
> +
> +     More text explaining the next step::
> +
> +        if (condition)
> +                more_function_calls();
> +
> +
> +Sphinx also supports ``.. code-block::`` annotations, which also allow you to
> +specify the language used for hightlight. But that should only be used when
> +really necessary.
> +
> +
>  list tables
>  -----------
>  
> -- 
> 2.10.2
> 

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