Messages in this thread | | | Date | Mon, 28 Nov 2016 15:51:21 -0200 | From | Mauro Carvalho Chehab <> | 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@ffwll.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@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> > --- > 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
| |