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