linux-kernel - Re: [PATCH v2 2/2] Documentation/sphinx: link dma-buf rsts

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: <20160823081633.123ae938@lwn.net>
Date:   Tue, 23 Aug 2016 08:16:33 -0600
From:   Jonathan Corbet <corbet@....net>
To:     Daniel Vetter <daniel@...ll.ch>
Cc:     Mauro Carvalho Chehab <mchehab@...pensource.com>,
        Sumit Semwal <sumit.semwal@...aro.org>,
        Markus Heiser <markus.heiser@...marit.de>,
        linux-doc@...r.kernel.org,
        Linux Kernel Mailing List <linux-kernel@...r.kernel.org>,
        dri-devel <dri-devel@...ts.freedesktop.org>,
        "linaro-mm-sig@...ts.linaro.org" <linaro-mm-sig@...ts.linaro.org>,
        "linux-media@...r.kernel.org" <linux-media@...r.kernel.org>
Subject: Re: [PATCH v2 2/2] Documentation/sphinx: link dma-buf rsts

On Tue, 23 Aug 2016 15:28:55 +0200
Daniel Vetter <daniel@...ll.ch> wrote:

> I think the more interesting story is, what's your plan with all the
> other driver related subsystem? Especially the ones which already have
> full directories of their own, like e.g. Documentation/gpio/. I think
> those should be really part of the infrastructure section (or
> something equally high-level), together with other awesome servies
> like pwm, regman, irqchip, ... And then there's also the large-scale
> subsystems like media or gpu. What's the plan to tie them all
> together? Personally I'm leaning towards keeping the existing
> directories (where they exist already), but inserting links into the
> overall driver-api section.

To say I have a plan is to overstate things somewhat...

One objective I do have, though, is to declutter Documentation/.
Presenting people looking for docs with a 270-file directory is
unfriendly to say the least.  We don't organize the code that way; the
average in the kernel is <... find | wc -l ... > about 15
files/directory, which is rather more manageable.  Someday I'd like
Documentation/ to look a lot more like the top-level directory.

It seems to me that we have a few basic types of stuff here:

 - Driver API documentation, obviously, is a lot of it, and I would like
   to organize it better and to move it out of the top-level directory.

 - Hardware usage information - module parameters, sysfs files, supported
   hardware information, graphic descriptions of the ancestry of hardware
   engineers, etc.  The readership for this stuff is quite different, and
   I think it should be separate; often it's intertwined with API
   information at the moment.

 - Other usage information - a lot of what's under filesystems/ for
   example, and more.

 - Core API documentation.

 - Kernel development tools - the stuff I started pulling together into
   the dev-tools/ subdirectory.

 - How to deal with this unruly mob - SubmittingPatches, CodingStyle,
   development-process, etc.  There's process stuff, and general
   development documents like volatile-considered-harmful.txt or
   memory-barriers.txt

We can go a long way by organizing this stuff within the formatted
documentation, but I really think we need to organize the directory
structure as well.  I see that as a slow-moving process that will take
years, but I do think it's a direction we should go.

jon