Em Mon, 12 Sep 2016 10:40:41 -0600
Jonathan Corbet <cor...@lwn.net> escreveu:
> On Mon, 12 Sep 2016 11:47:51 -0300
> Mauro Carvalho Chehab <mche...@s-opensource.com> wrote:
>
> > There are several documents related to Kernel development, where the
> > HOWTO working like an index to most of them.
> >
> > Convert the documents mentioned at HOWTO (including it) to ReST and add them
> > at the Sphinx build.
>
> Some preliminary thoughts from seat 10A somewhere over New York state at
> the moment, seemingly...
>
> - I only got parts of this in my inbox, cover letter not included; that
> made it a bit hard to figure out what was going on.
I pushed the patches on my experimental repository:
https://git.linuxtv.org//mchehab/experimental.git/log/?h=docs-next
(the last one is unrelated with this series)
>
> - I like the general idea; it's the sort of thing I've been wanting to
> do.
>
> - We should think about naming and organization a bit. I would have
> called this collection something like development-process, since it's
> really focused on the process side of things.
OK. I'll rename the dir to "development-process".
> Oh, and I would have
> included the existing development-process document :)
:)
Well, I'm pretty sure there are lots of other documents to add there.
I'll take a look on the existing documents and add it on a next
patch series.
> In a sense, much of what's in Documentation/ is "kernel development",
> so the name may be a bit vague for a subset of the docs.
True.
> In the end, I suspect we'll end up with sub-books on process, internal
> APIs, tools,
> etc. It's probably silly to think that we can come up with the ideal
> organization from the outset, but it may be worth a try anyway.
Yeah, I suspect that we'll end by having sub-books there. I opted to
start with the "HOWTO" groupe because it privided inside it a list of
documents that include, IMHO, the absolute minimum for someone to start:
SendingPatches, SendingDrivers and CodingStyle.
So, it sounded a good start ;)
> - Some of this will need wider exposure for a different reason: I suspect
> there will be resistance to renaming well-known documents like
> SubmittingPatches. Everybody knows it's there and directs people to
> it; simply moving it out will create lots of dangling mental links, and
> I think people will grumble. I don't really know how to solve that one.
Yeah, I noticed that the minute after I sent the patch series: I should
have c/c LKML.
I'll do that on the next version.
Yeah, I suspect that people may not welcome too much such rename,
but I guess it is unavoidable, if we want to better organize the
documentation.
> - Speaking of dangling links, it's important to fix up references to
> documents from elsewhere in the docs tree when we move them. It's an
> easy thing to forget.
Ah, true! I'll double check those links on the next version.
>
> Anyway, mostly due to the known filename issues, I don't want to rush
> into this one in particular, so my inclination is to defer it past 4.9.
> Hopefully you don't object too strongly to that idea...?
That's fine for me. There's no rush on merging it ASAP, except that
perhaps we might have some conflicts if we delay it too much.
In general, I like the idea of merging such patches just after a
merge window (perhaps at -rc1 or -rc2, if Linus allows).
Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
