Em Mon, 28 Nov 2016 17:16:22 +0100 Daniel Vetter <daniel.vetter@xxxxxxxx> 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@xxxxxxx> > Cc: linux-doc@xxxxxxxxxxxxxxx > Cc: Christoph Hellwig <hch@xxxxxxxxxxxxx> > Cc: Peter Zijlstra <peterz@xxxxxxxxxxxxx> > Cc: Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> > Cc: Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx> > Signed-off-by: Daniel Vetter <daniel.vetter@xxxxxxxxx> > --- > 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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
