Re: [PATCH] doc: Explain light-handed markup preference a bit better
From: Mauro Carvalho Chehab
Date: Mon Dec 12 2016 - 12:47:33 EST
Em Thu, 8 Dec 2016 23:06:57 +0100
Daniel Vetter <daniel.vetter@xxxxxxxx> escreveu:
> On Thu, Dec 8, 2016 at 10:10 AM, Mauro Carvalho Chehab
> <mchehab@xxxxxxxxxxxxxxxx> wrote:
> > Em Wed, 7 Dec 2016 12:39:24 -0700
> > Jonathan Corbet <corbet@xxxxxxx> escreveu:
> >> On Wed, 7 Dec 2016 16:42:58 +0100
> >> Daniel Vetter <daniel.vetter@xxxxxxxx> 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.
> >> I do think we should put something in to guide people in the right
> >> direction. And yes, it should, itself, be light-handed and minimal.
> >> [...]
> >> > Documentation/kernel-documentation.rst | 28 ++++++++++++++++++++++++++--
> >> > 1 file changed, 26 insertions(+), 2 deletions(-)
> >> I do, however, also believe that it should apply to relatively recent
> >> docs-next :)
> >> > diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst
> >> > index 0dd17069bc0b..5bffe5a418aa 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.
> >> I think this is about where I figured out why I'm not 100% ready to jump on
> >> this. What we're doing here is mixing two things: information on how to
> >> write documents, and information on how to convert existing documents.
> >> I'm not really opposed to applying the patch as-is, but I do wonder if what
> >> we really need is a new section aimed specifically at people doing
> >> conversions? The concerns *are* a bit different, and there's more
> >> information we could put into a conversion section that isn't relevant to
> >> others. Plus we could remove it some day far in the future when
> >> everything's converted :)
> > Yeah, a "conversion guide" section seems interesting. In the case of
> > media, for example, we prefer to use as much as ReST provides, as nobody
> > cares that the doc source would be as readable as the html/pdf output.
> > So, we want to be sure that the enriched text output would look better
> > to the ones using the documentation.
> > In that case, I would go for something close to the text I wrote to Peter
> > sometime ago:
> Hm yeah, separate conversion section makes sense. In that case I'll
> adopt Jani's suggestion for more terseness in overview document, and
> we can merge Mauro's proposal (or something like it) on top. And I'll
> try to rebase onto latest doc-next too ;-)
> Does that sound like a plan, before I head of and respin v4?
Sounds like a plan to me :-)