linux-kernel - Re: [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree

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 for Android: free password hash cracker in your pocket

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

Message-ID: <20190405024350.rbwbiaxjybrmqea6@mail.google.com>
Date:   Fri, 5 Apr 2019 10:44:35 +0800
From:   Changbin Du <changbin.du@...il.com>
To:     Jonathan Corbet <corbet@....net>
Cc:     "Rafael J. Wysocki" <rafael@...nel.org>,
        Changbin Du <changbin.du@...il.com>,
        "Rafael J. Wysocki" <rjw@...ysocki.net>,
        Len Brown <lenb@...nel.org>,
        Bjorn Helgaas <helgaas@...nel.org>,
        ACPI Devel Maling List <linux-acpi@...r.kernel.org>,
        Linux Kernel Mailing List <linux-kernel@...r.kernel.org>,
        "open list:DOCUMENTATION" <linux-doc@...r.kernel.org>
Subject: Re: [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree

+ Bjorn

On Wed, Apr 03, 2019 at 01:36:13PM -0600, Jonathan Corbet wrote:
> On Tue, 2 Apr 2019 10:25:23 +0200
> "Rafael J. Wysocki" <rafael@...nel.org> wrote:
> 
> > There are ACPI-related documents currently in Documentation/acpi/ that
> > don't clearly fall under either driver-api or admin-guide.  For
> > example, some of them describe various aspects of the ACPI support
> > subsystem operation and some document expectations with respect to the
> > ACPI tables provided by the firmware etc.
> > 
> > Where would you recommend to put them after converting to .rst?
> 
> OK, I've done some pondering on this.  Maybe what we need is a new
> top-level "hardware guide" book meant to hold information on how the
> hardware works and what the kernel's expectations are.  Architecture
> information could maybe go there too.  Would this make sense?
> 
> If so, I could see a division like this:
> 
> Hardware guide
> 	acpi-lid
> 	aml-debugger (or maybe driver api?)
> 	debug (ditto)
> 	DSD-properties-rules
> 	gpio-properties
> 	i2c-muxes
> 
> Admin guide
> 	cppc_sysfs
> 	initrd_table_override
> 
> Driver-API
> 	enumeration
> 	scan_handlers
> 
> other:
> 	dsdt-override: find another home for those five lines
>
Then, should we create dedicated sub-directories for these new charpters and
move documents to coresspoding one? Now we have 'admin-guide' and all admin-guid
docs are under it, otherwise we will have reference across different folders.
For example, the 'admin-guide/index.rst' will have:
    ...
    ../acpi/osi
    ...
Which seems not good.

> ...and so on.  I've probably gotten at least one of those wrong, but that's
> the idea.
> 
> Of course, then it would be nice to better integrate those documents so
> that they fit into a single coherent whole...a guy can dream...:)
>
I am not an adminstrator, so I don't know how adminstrators use this kernel
documentation. But as a kernel developer, I prefer all related documents
integrated into one charpter. Because I probably miss some useful sections
if the documents are distributed into several charpters. And this is usually
how a book is written (One charpter focus on one topic and has sub-sections
such as overview, backgroud knowledge, implemenation details..),
but a book mostly target on hypothetical readers...

> Thanks,
> 
> jon

-- 
Cheers,
Changbin Du