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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20190612144015.033247db@coco.lan>
Date:   Wed, 12 Jun 2019 14:40:15 -0300
From:   Mauro Carvalho Chehab <mchehab+samsung@...nel.org>
To:     Jonathan Corbet <corbet@....net>
Cc:     Daniel Vetter <daniel@...ll.ch>,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Mauro Carvalho Chehab <mchehab@...radead.org>,
        linux-kernel@...r.kernel.org,
        Maarten Lankhorst <maarten.lankhorst@...ux.intel.com>,
        Maxime Ripard <maxime.ripard@...tlin.com>,
        Sean Paul <sean@...rly.run>, David Airlie <airlied@...ux.ie>,
        dri-devel@...ts.freedesktop.org
Subject: Re: [PATCH v3 33/33] docs: EDID/HOWTO.txt: convert it and rename to
 howto.rst

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

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