[PATCH v3 33/33] docs: EDID/HOWTO.txt: convert it and rename to howto.rst

[Mauro Carvalho Chehab]

Em Tue, 11 Jun 2019 09:37:01 -0600
Jonathan Corbet <corbet at lwn.net> escreveu:

> On Tue, 11 Jun 2019 06:02:15 -0300
> Mauro Carvalho Chehab <mchehab+samsung at kernel.org> 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.

> 
> > Btw, that's one of the reasons[1] 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
docs.

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:

	https://linuxtv.org/downloads/v4l-dvb-apis-new/uapi/v4l/open.html#device-naming

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.

Thanks,
Mauro