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

[Mauro Carvalho Chehab]

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 :-)

Regards,
Mauro