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

From: Daniel Vetter <daniel@ffwll.ch>
To: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Cc: Jonathan Corbet <corbet@lwn.net>,
	Linux Doc Mailing List <linux-doc@vger.kernel.org>,
	Mauro Carvalho Chehab <mchehab@infradead.org>,
	Linux Kernel Mailing List <linux-kernel@vger.kernel.org>,
	Maarten Lankhorst <maarten.lankhorst@linux.intel.com>,
	Maxime Ripard <maxime.ripard@bootlin.com>,
	Sean Paul <sean@poorly.run>, David Airlie <airlied@linux.ie>,
	dri-devel <dri-devel@lists.freedesktop.org>
Subject: Re: [PATCH v3 33/33] docs: EDID/HOWTO.txt: convert it and rename to howto.rst
Date: Wed, 12 Jun 2019 21:45:15 +0200	[thread overview]
Message-ID: <CAKMK7uFhPKbpQj1Y2+C1zW0SdRcezHYDA4h=Ri_eV2xB7HtVig@mail.gmail.com> (raw)
In-Reply-To: <20190612144015.033247db@coco.lan>

On Wed, Jun 12, 2019 at 7:40 PM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> Em Tue, 11 Jun 2019 09:37:01 -0600
> Jonathan Corbet <corbet@lwn.net> escreveu:
>
> > On Tue, 11 Jun 2019 06:02:15 -0300
> > Mauro Carvalho Chehab <mchehab+samsung@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.

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

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

> 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

-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch