(unknown)
Bcc:
Subject: Re: [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree Reply-To:
In-Reply-To: <[email protected]>
+ Bjorn
Quoted 30 lines · Jonathan Corbet
Quoted 7 lines · On Tue, 2 Apr 2019 10:25:23 +0200 "Rafael J. Wysocki" <[email protected]> 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-muxesAdmin guide
cppc_sysfs
initrd_table_override
Quoted 7 lines
Driver-API
enumeration
scan_handlersother:
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.
Quoted 6 lines
...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...
Quoted 3 lines
Thanks,
jon
Signature · 2 lines
Cheers, Changbin Du