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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <20161128155121.31b7b689@vento.lan>
Date:   Mon, 28 Nov 2016 15:51:21 -0200
From:   Mauro Carvalho Chehab <mchehab@...pensource.com>
To:     Daniel Vetter <daniel.vetter@...ll.ch>
Cc:     LKML <linux-kernel@...r.kernel.org>,
        Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org,
        Christoph Hellwig <hch@...radead.org>,
        Peter Zijlstra <peterz@...radead.org>,
        Jani Nikula <jani.nikula@...ux.intel.com>,
        Daniel Vetter <daniel.vetter@...el.com>
Subject: Re: [PATCH] doc: Explain light-handed markup preference a bit
 better

Em Mon, 28 Nov 2016 17:16:22 +0100
Daniel Vetter <daniel.vetter@...ll.ch> escreveu:

> 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.

Good idea! Please see below for some suggestions.

> 
> Cc: Jonathan Corbet <corbet@....net>
> Cc: linux-doc@...r.kernel.org
> Cc: Christoph Hellwig <hch@...radead.org>
> Cc: Peter Zijlstra <peterz@...radead.org>
> Cc: Jani Nikula <jani.nikula@...ux.intel.com>
> Cc: Mauro Carvalho Chehab <mchehab@...pensource.com>
> Signed-off-by: Daniel Vetter <daniel.vetter@...el.com>
> ---
>  Documentation/kernel-documentation.rst | 11 ++++++++++-
>  1 file changed, 10 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst
> index 0dd17069bc0b..ceb17d428278 100644
> --- a/Documentation/kernel-documentation.rst
> +++ b/Documentation/kernel-documentation.rst
> @@ -77,7 +77,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. A lot
> +  of core kernel developers prefer plain text, with a big emphasis on plain. And
> +  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.
> +
> +  Be especially considerate when converting existing .txt 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.

Looks good to me.

>  * Please stick to this order of heading adornments:

I would actually relax the heading adornments order. IMHO, if a
document to be converted has already some adornments order, the
best is to just keep using them.

So, IMHO, I would be changing the above to:

	* Please stick to the heading adornments that are already
	  present on a document, if you're converting it to ReST. If you're
	  writing it from scratch, please prefer this order of heading adornments:

I would also mention to prefer using "::" over ".. code-block::" when
converting existing documents.

Thanks,
Mauro