Re: [PATCH v3 33/33] docs: EDID/HOWTO.txt: convert it and rename to howto.rst
From: Daniel Vetter
Date: Wed Jun 12 2019 - 15:50:09 EST
On Wed, Jun 12, 2019 at 7:40 PM Mauro Carvalho Chehab
> Em Tue, 11 Jun 2019 09:37:01 -0600
> Jonathan Corbet <corbet@xxxxxxx> escreveu:
> > On Tue, 11 Jun 2019 06:02:15 -0300
> > Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx> wrote:
> > > Jon, please correct me if I' wrong, bu I guess the plan is to place them
> > > somewhere under Documentation/admin-guide/.
> > That makes sense to me.
> > > If so, perhaps creating a Documentation/admin-guide/drm dir there and
> > > place docs like EDID/HOWTO.txt, svga.txt, etc would work.
> > Maybe "graphics" or "display" rather than "drm", which may not entirely
> > applicable to all of those docs or as familiar to all admins?
> It is up to Daniel/David to decide. Personally, I agree with you that
> either "graphics" or "display" would be better at the admin guide.
We use Documentation/gpu already for the developer guide, I think
going with "gpu" on the admin guide for consistency would be good. I
do personally think that splitting out the admin guide makes sense, we
could also put some recommendations about access rights for drm device
nodes and stuff like that in there.
> > > Btw, that's one of the reasons why I opted to keep the files where they
> > > are: properly organizing the converted documents call for such kind
> > > of discussions. On my experience, discussing names and directory locations
> > > can generate warm discussions and take a lot of time to reach consensus.
> > Moving docs is a pain; my life would certainly be easier if I were happy
> > to just let everything lie where it fell :) But it's far from the hardest
> > problem we solve in kernel development, I assume we can figure it out.
> Yeah, it is doable. I'm happy to write the rename patches and even try
> to split some documents at the places I'm more familiar with, but, IMHO,
> we should do some discussions before some of such renames.
> For example, Daniel said that:
> > > > Yeah atm we're doing a bad job of keeping the kapi and uapi parts
> > > > separate. But the plan at least is to move all the gpu related uapi stuff
> > > > into Documentation/gpu/drm-uapi.rst. Not sure there's value in moving that
> > > > out of the gpu folder ...
> From the conversions I've made so far, almost all driver subsystems
> put everything under Documentation/<subsystem: kAPI, uAPI, admin info,
> driver-specific technical info.
> It should be doable to place kAPI and uAPI on different books, but there
> will be lots of cross-reference links between them, on properly-written
I'm not sure it makes sense to split out the kapi and uapi sides of
the docs complete. For the admin guide I think one overall book
covering all subsystems is good. But someone creating a drm/kms
compositor is not going to be interested much into some special
options for networking protocol I think. For those I think focusing
more on the specific subsystem makes more sense (and easier to share
common concepts/diagrams between uapi and kapi of a given subsystem).
I do think for a given subsystem the uapi side should be clearly split
out (otherwise it's impossible to find for non-kernel people). And
currently drm falls short really badly on this. So maybe a good
argument for a uapi kernel directory would be to force that, but not
sure that's good enough of a reason.
> However, other admin-guide stuff under drivers are usually in the middle
> of the documents. For example, on media, we have some at the uAPI guide,
> like the Device Naming item:
> But splitting it from uAPI guide is not an easy task.
> At the driver's specific documentation is even messier.
> Ok, splitting is doable, but require lots of dedication, and I'm not
> convinced if it would make much difference in practice.
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch